Bts Implement

Resume Protocol

If tasks.json exists in the recipe directory:

1. Stale check: Compare tasks.json updated_at with final.md modification time. If final.md is newer → use AskUserQuestion:

   • "Re-decompose tasks from updated spec" → go to Step 1 (fresh decomposition)
   • "Resume with existing tasks" → resume below

2. Task status recovery: Read tasks.json and find resume point:

   • in_progress tasks → the last session was interrupted mid-task. Read the actual file to assess how much was written. Complete or rewrite as needed.
   • pending tasks → start from the first pending task
   • All done/skipped → skip to Step 4

3. Retry count preservation: Each task's retry_count persists across sessions. Resume from the saved count, not from 0. If a task has retry_count=4 and max is 5, it gets ONE more attempt before being blocked.

Step 1: Task Decomposition

1. Read .bts/specs/recipes/{id}/final.md

2. Extract file-level tasks: each file to create or modify becomes a task

3. Determine dependency order (shared types first, then modules, then integration)

4. Save task list to .bts/specs/recipes/{id}/tasks.json:

   {
     "recipe_id": "{id}",
     "started_at": "ISO8601",
     "updated_at": "ISO8601",
     "tasks": [
       {
         "id": "t-001",
         "file": "src/auth/types.ts",
         "action": "create",
         "status": "pending",
         "description": "Auth type definitions — see final.md Section 3.1",
         "depends_on": [],
         "retry_count": 0,
         "last_error": ""
       }
     ]
   }
   

5. Update phase and log:

   bts recipe log {id} --phase implement --action implement --output tasks.json --based-on final.md --result "N tasks decomposed"
   

6. Validate:

   bts validate
   

Step 2: Scaffolding

1. Create directories for all new files
2. Install dependencies if needed:
   • Node.js: npm install / yarn add
   • Go: go mod tidy
   • Python: pip install / poetry add
3. Create empty files or boilerplate as needed

Environment check: Run the build command once before writing any code. If it fails with "command not found" or similar environment error → stop immediately and report: "Build tool not available. Install [tool] before proceeding." Do NOT proceed to task implementation if the build environment is broken.

Step 3: Implementation Loop

Reservations check: If .bts/specs/recipes/{id}/reservations.md exists, read it before starting. When implementing a file listed in the "Affected Files" section, warn: "[RESERVATION] This area has unresolved concerns from debate: {concern}. Proceed with extra caution."

For each task in dependency order:

Dependency check: If a task's depends_on includes a blocked or skipped task, auto-skip it with status "skipped" and last_error "dependency blocked: {id}".

ASSESS

• Read the task from tasks.json
• If status is in_progress → file may be partially written. Read the actual file and decide: complete the remaining parts, or rewrite from scratch.
• If status is pending → fresh start for this task
• Set status to in_progress and save tasks.json immediately

IMPLEMENT

• Write the code exactly as specified in final.md
• Follow function signatures, types, error handling from the spec
• Preserve existing code when modifying files

VERIFY

Run the project's build command:

# Detect and run appropriate build
# TypeScript: npx tsc --noEmit
# Go: go build ./...
# Rust: cargo check
# Python: python -m py_compile

If build fails:

1. Increment retry_count in tasks.json and save last_error
2. Stagnation check: Compare current error with last_error. If the error message is substantially the same as the previous attempt → try a fundamentally different approach (different algorithm, different API, etc.) Do NOT repeat the same fix.
3. Rebuild (check retry_count < implement.max_build_retries from settings, default: 5)
4. If retry_count reaches the limit → mark task as blocked, save error, move to next task

If build passes:

• Update task status to done, clear last_error
• Update tasks.json updated_at
• Move to next task

Crash safety: tasks.json is the source of truth for implementation progress. It is written to disk (via Write tool) after every task status change. If the session crashes, the next resume reads tasks.json and knows exactly where to continue. No separate work-state save is needed during the loop — tasks.json IS the checkpoint.

Log Each Task

bts recipe log {id} --action implement --result "task {task-id} done"

Step 4: Checkpoint

Review task status:

• All done or skipped → continue to Step 5
• Any blocked → use AskUserQuestion ("N task(s) blocked. How to proceed?"):
  • "Skip blocked and continue" → mark blocked as skipped, continue
  • "Retry blocked tasks" → reset retry_count to 0, set status to pending, go back to Step 3
  • "Stop and review" → stop and report blocked task details

Checkpoint: Implementation tasks complete. Proceed directly to testing. Do NOT /clear — test/simulate/review steps need implementation context.

Step 5: Test

Update phase and run tests:

bts recipe log {id} --phase test

Use Skill("bts-test") with arguments: {id} The test skill will read final.md for test scenarios and tasks.json for the list of implemented files.

If tests fail (bts-test does not output <bts>TESTS PASS</bts>):

• Do NOT proceed to review. Stop here.
• Report: "Tests failed. Fix implementation and re-run /implement {id} to retry from Step 5."
• The recipe stays in phase "test" for resume.

Step 5.3: Simulate

Use Skill("bts-simulate") with arguments: "code" to verify all code paths are covered.

This reads tasks.json for implemented files and final.md for expected scenarios, then walks through each scenario against the actual code.

If simulation finds GAPs or ISSUEs:

• Fix the code to address each finding
• Add tests for any COVERAGE GAPs (missing test scenarios)
• Re-run tests: use Skill("bts-test") with arguments: {id} (bts-test skips generation, re-runs tests, updates test-results.json)
• If tests fail → fix and let bts-test retry loop handle it
• Do NOT re-run simulation (runs once per implementation)

If no gaps → proceed to Step 5.5 (Review).

bts recipe log {id} --action simulate --result "N scenarios, N gaps"

Step 5.5: Review

Update phase:

bts recipe log {id} --phase review

Use Skill("bts-review") (full mode, no arguments — uses tasks.json for scope).

After review.md is generated, read it and fix all [ACTIONABLE] critical and major items:

• For each [ACTIONABLE] finding, modify the code to address it
• After all fixes, re-run tests: use Skill("bts-test") with arguments: {id} (bts-test skips generation, re-runs tests, updates test-results.json)
• If tests fail → fix and let bts-test retry loop handle it
• Do NOT re-run /review after fixes (review runs once per implementation)

If no actionable items → proceed directly to Step 6.

bts recipe log {id} --action review --output review.md --result "N critical, N major (N actionable)"

Step 6: Sync

Always run sync (even if deviation.md exists from a previous run — code may have changed since then, and sync is idempotent).

After tests pass, update phase and sync:

bts recipe log {id} --phase sync

Use Skill("bts-sync") with arguments: {id}

Step 7: Status

After sync:

bts recipe log {id} --phase status

Use Skill("bts-status") with arguments: {id}

Completion

When all steps are done:

• Verify tasks.json shows all tasks as done or skipped
• Verify no blocked tasks remain (all resolved or skipped)
• Verify review.md exists (review has run)
• Verify deviation.md exists (sync has run)
• Output <bts>IMPLEMENT DONE</bts>
• Tell the user (plaintext, after the marker):

  Implementation complete — {id} done. Check deviation.md for any follow-up items. Next: run /bts-recipe-blueprint to start the next roadmap item, or /bts-recipe-fix for any bugs.

If unresolved blocked tasks remain:

• Report which tasks are blocked and why
• Ask user for guidance