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.