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:

Read the phase description carefully
Look for "⚠️ Check for [TODO-INFRASTRUCTURE-*]" warnings
If any [TODO-INFRASTRUCTURE-*] markers exist from previous phases:
- STOP
- Review what they mean
- Resolve them in TDD cycles BEFORE proceeding
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:

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

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

project-workflow-build-system