Tracer Development

Execute the build-validate-review cycle for tracer bullet development.

Locate State Files

Before any flow, find the plan files:

• Search docs/tracers/**/state.json

• If multiple matches, list them and use the ask question tool to ask questions about which feature to work on

• If none, STOP: "Run spec-planner to create docs/specs//SPEC.md, then run /overseer-plan to create executable tasks"

Two files per feature:

• state.json

• Machine state (task passes, commits, current tracer)

• PROGRESS.md

• Human-readable plan and learnings

All state updates go to state.json . Learnings are appended to PROGRESS.md .

Decision Tree

Check state.json: │ ├─ No state.json found │ └─ STOP: "Run spec-planner then /overseer-plan first to create a plan" │ ├─ Current tracer has tasks with passes: false │ └─ → NEXT-TASK FLOW │ ├─ All tasks pass, tracer status != "complete" │ └─ → REVIEW-TRACER FLOW │ ├─ Tracer complete, more tracers remain │ └─ Advance currentTracer → NEXT-TASK FLOW │ └─ All tracers status: "complete" └─ DONE: "Feature complete!"

NEXT-TASK FLOW

Precondition Check

Is lastReviewedTracer == currentTracer - 1? ├─ No → "Complete tracer review first" └─ Yes → Continue

If feature status is planning , update it to in_progress in state.json before starting work.

Proceed immediately to Step 1 without asking for confirmation once preconditions are satisfied.

Step 1: Select Task

Read state.json and find first task with passes: false in the current tracer.

Also read the context block for patterns and key files to guide exploration.

Step 2: Write Micro-Plan

Before ANY code, produce a brief plan:

Micro-Plan: Task X.Y - <name>

Goal: <one sentence>

Implementation (minimal):

1. <step>
2. <step> ...

Validation:

• <how we prove this works>

Not doing (explicit scope):

• <what we're deferring>

Step 3: Implement

Key principles:

• Use EXISTING abstractions before creating new ones

• Minimal code that satisfies the task

• Production bar: types + error handling

• No speculative features

Step 4: Validate

Run ALL verification steps from the task's steps array. Also run project validation (typecheck, tests, lint).

• Detect project scripts (package.json, Makefile) or use the ask question tool to ask questions if unclear

• If a step cannot run, mark SKIPPED with reason

• All steps must pass before proceeding

Step 5: Code Review Gate (BLOCKING)

afplay /System/Library/Sounds/Ping.aiff

Present to user:

Code Review: Task X.Y

Files changed:

• <file> (+X, -Y)

Verification steps:

• <step 1>: PASS
• <step 2>: PASS

Project validation:

• Typecheck: PASS or SKIPPED (reason)
• Tests: PASS or SKIPPED (reason)
• Lint: PASS or SKIPPED (reason)

Request approval inline (do not open question mode): reply "lgtm" to approve, or provide feedback.

WAIT FOR USER RESPONSE

• "lgtm" (exactly) → Continue to commit

• Any other response → Treat as feedback, revise, re-request review

Loop until user says "lgtm".

After "lgtm", proceed immediately to commit, mark the task complete, and start the next task without asking for confirmation.

Step 6: Commit + State Update (Background Agent)

After approval, always commit the task. This ensures the next task's review only shows new changes.

Run the commit and state.json update using a background agent with openrouter/z-ai/glm-4.7-flash .

git add -A && git commit -m "feat(<scope>): <task description>"

Step 7: Mark Task Complete

Update state.json for the task (handled by the background agent):

{ "passes": true, "commit": "<commit-hash>" }

Continue to next task, or if all tasks in current tracer have passes: true → REVIEW-TRACER FLOW.

REVIEW-TRACER FLOW

Precondition

All tasks in current tracer have passes: true in state.json.

Step 1: Definition of Done Audit

Check each criterion from the tracer's proves field:

DoD Audit: Tracer N

proves: "<what this tracer validates>"

Evidence:

• <criterion>: <evidence>
• <criterion>: <evidence>
• <criterion>: MISSING - <what's needed>

If any criterion unmet → Add tasks to state.json (with passes: false ), return to NEXT-TASK FLOW. If tasks are added after a tracer was reviewed, set in state.json:

{ "lastReviewedTracer": N-1, "currentTracer": N }

Step 2: Demo

afplay /System/Library/Sounds/Hero.aiff

Present demo instructions:

Demo: Tracer N

Please run:

<demo command from PROGRESS.md>

Expected result: <expected output from PROGRESS.md>

Request response inline (do not open question mode): run the demo and reply "pass" to continue, or describe what went wrong.

WAIT FOR USER RESPONSE

Continuation Logic

• "pass" → Continue to learnings

• Any other response → Treat as feedback, discuss adjustments, may add tasks

Step 3: Record Learnings

Use the ask question tool to ask questions:

What did we learn from this tracer?

• Decisions made?
• Surprises?
• Things to remember for future tracers?

Update both files:

state.json - Add to tracer's learnings array:

{ "learnings": ["<learning>", "<learning>"] }

PROGRESS.md - Append under the tracer's Learnings section:

Learnings

• <learning>
• <learning>

Step 4: Update Future Tracers

Review remaining tracers in light of learnings:

Future Tracer Review

Based on learnings from Tracer N:

Tracer N+1: <name>

• Still makes sense? [yes/adjust]
• Demo still valid? [yes/adjust]
• New tasks needed? [no/add]

Update PROGRESS.md if any changes needed.

Step 5: Mark Tracer Complete

Update state.json:

{ "lastReviewedTracer": N, "currentTracer": N+1, "tracers": [{ "id": N, "status": "complete", "completed": "<ISO date>" }] }

If this was the final tracer, also set:

{ "status": "complete" }

Step 6: Celebrate

afplay /System/Library/Sounds/Funk.aiff

Tracer N complete!

Progress: N/<total> tracers done Next: Tracer N+1 - <name>

Continuing to the next tracer.