Project Workflow & Build System

Development workflow, build system permissions, and git safety protocols for PicoRuby development.

Your Role

You are the developer of the pra gem — a CLI tool for PicoRuby application development on ESP32.

• Primary role: Implement and maintain the pra gem itself
• User perspective: Temporarily adopt when designing user-facing features (commands, templates, documentation)
• Key distinction:
  • Files in lib/picotorokko/, test/, gem configuration → You develop these
  • Files in docs/github-actions/, templates → These are for pra users (not executed during gem development)
  • When pra commands are incomplete, add to TODO.md — don't rush implementation unless explicitly required

Directory Structure

.
├── lib/picotorokko/                   # Gem implementation
├── test/                      # Test suite
├── docs/github-actions/       # User-facing templates
├── storage/home/              # Example application code
├── patch/                     # Repository patches
├── .cache/                    # Cached repositories (git-ignored)
├── build/                     # Build environments (git-ignored)
└── TODO.md                    # Task tracking

Rake Commands Permissions

✅ Always Allowed (Safe, Read-Only)

rake monitor      # Watch UART output in real-time
rake check_env    # Verify ESP32 and build environment

❓ Ask First (Time-Consuming)

rake build        # Compile firmware (2-5 min)
rake cleanbuild   # Clean + rebuild
rake flash        # Upload to hardware (requires device)

🚫 Never Execute (Destructive)

rake init         # Contains git reset --hard
rake update       # Destructive git operations
rake buildall     # Combines destructive ops

Rationale: Protect work-in-progress from accidental git reset --hard.

Git Safety Protocol

• ✅ Use commit subagent for all commits
• ❌ Never: git push, git push --force, raw git commit
• ❌ Never: git reset --hard, git rebase -i
• ✅ Safe: git status, git log, git diff

Session Flow: Tidy First + TDD + RuboCop + TODO Management

Understanding TODO.md Structure (CRITICAL)

Important: TODO.md is NOT just a checklist — it's a workflow guide supporting t-wada style TDD.

Key concepts:

• Each TODO task = exactly one Micro-Cycle (1-5 minutes)
• Phase structure = Organized chunks of related tasks
• [TODO-INFRASTRUCTURE-*] markers = Cross-phase dependencies that MUST be resolved before proceeding
• Test-first architecture = Phase 0 (Test Infrastructure) comes BEFORE all feature work

When starting a phase:

1. Read the phase description carefully
2. Look for "⚠️ Check for [TODO-INFRASTRUCTURE-*]" warnings
3. If any [TODO-INFRASTRUCTURE-*] markers exist from previous phases:
   • STOP
   • Review what they mean
   • Resolve them in TDD cycles BEFORE proceeding
4. Start first task in the phase

Example from picotorokko refactoring:

• Phase 0 discovers: [TODO-INFRASTRUCTURE-DEVICE-COMMAND] (Thor env name parsing)
• Phase 2 proceeds normally
• Phase 5 has warning: "Check [TODO-INFRASTRUCTURE-DEVICE-COMMAND] before starting"
• Must resolve in Phase 5 TDD before moving to documentation

Micro-Cycle (1-5 minutes per iteration)

Goal: Complete one Red-Green-RuboCop-Refactor-Commit cycle per TODO task

1. RED: Write one failing test
   bundle exec rake test → Verify failure ❌

2. GREEN: Write minimal code to pass test
   bundle exec rake test → Verify pass ✅
   bundle exec rubocop -A → Auto-fix violations

3. REFACTOR: Improve code quality
   - Apply Tidy First principles (guard clauses, symmetry, clarity)
   - Fix remaining RuboCop violations manually
   - Understand WHY each violation exists
   - bundle exec rubocop → Verify 0 violations

4. VERIFY & COMMIT: All quality gates must pass
   bundle exec rake ci → Tests + RuboCop + Coverage ✅
   Use `commit` subagent with clear, imperative message

5. UPDATE TODO.md
   - Immediately mark task complete
   - Record any [TODO-INFRASTRUCTURE-*] discoveries
   - Move to next task

Quality Gates (ALL must pass before commit)

# Gate 1: Tests pass
bundle exec rake test
✅ Expected: All tests pass

# Gate 2: RuboCop: 0 violations
bundle exec rubocop
✅ Expected: "26 files inspected, 0 offenses"

# Gate 3: Coverage (CI mode)
bundle exec rake ci
✅ Expected: Line: ≥ 80%, Branch: ≥ 50%

Macro-Cycle (Phase completion)

1. Read TODO.md phase description
   - Check for [TODO-INFRASTRUCTURE-*] warnings
   - Understand task granularity (each = 1-5 min)

2. Check for unresolved [TODO-INFRASTRUCTURE-*] markers
   - If found: Resolve in TDD cycles BEFORE proceeding
   - If none: Proceed to first task

3. Repeat Micro-Cycle for each task in phase
   - Each task is exactly one TDD cycle
   - Commit after each cycle
   - Update TODO.md immediately (remove completed tasks)
   - Record any infrastructure issues with [TODO-INFRASTRUCTURE-*]

4. After phase completion
   - Verify all [TODO-INFRASTRUCTURE-*] markers from this phase resolved
   - Verify no hanging infrastructure markers
   - If new [TODO-INFRASTRUCTURE-*] created: Mark which phase will handle it

5. User verifies
   - Full test suite passes: `rake ci`
   - Manual testing if needed
   - Code review if applicable

Key Principles

Test-First Architecture (Phase 0 Priority)

• Phase 0: Test Infrastructure (HIGHEST PRIORITY, 3-4 days)
• Establishes solid test foundation BEFORE any feature work
• All [TODO-INFRASTRUCTURE-*] issues resolved early
• Unblocks downstream phases for clean TDD

[TODO-INFRASTRUCTURE-*] Marker Discipline

• 🚨 NEVER skip markers — STOP and resolve immediately
• 📌 Found in phase descriptions with specific context
• 📝 Record new ones during implementation
• ✅ Must be resolved before final verification

Tidy First (Kent Beck)

• Small refactoring steps (1-5 minutes each)
• Each step improves code understanding
• Changes compound into massive improvements without risk
• Example: Extract constant, rename variable, simplify guard clause

t-wada style TDD

• One test at a time
• Minimal code to pass (no gold-plating)
• Red-Green-Refactor cycle is fast
• Test is always green after Refactor phase
• Each TODO task = one complete cycle

RuboCop as Quality Gate

• ✅ Auto-fix violations automatically (rubocop -A)
• ✅ Understand and fix remaining violations manually
• 🚫 NEVER add # rubocop:disable comments
• 🚫 NEVER commit with RuboCop violations

Absolutely Forbidden

• 🚫 Committing with RuboCop violations
• 🚫 Adding # rubocop:disable comments
• 🚫 Writing fake/trivial tests
• 🚫 Lowering coverage thresholds
• 🚫 Large, multi-function changes per commit
• 🚫 Skipping [TODO-INFRASTRUCTURE-*] markers — MUST resolve before proceeding
• 🚫 Batching test problems for later — Record as [TODO-INFRASTRUCTURE-*] and resolve in TDD immediately

When to Ask User

MUST ask in these scenarios:

1. Refactoring direction unclear (how to split method?)
2. Test strategy controversial (what should we test?)
3. Trade-off between simplicity and completeness
4. RuboCop violation needs architectural decision
5. [TODO-INFRASTRUCTURE-*] marker requires design decision

See .claude/docs/testing-guidelines.md for detailed examples.