implement

Implement Track

Execute a track's plan using Superpowers' execution engine (subagent-driven or inline), with track progress management and phase checkpoints. Small issues can skip the track entirely: pass an issue file path to use Direct Issue Mode.

Progress Checklist

Copy this checklist and track your progress:

Implementation Progress:
- [ ] Pre-flight: verify project initialized
- [ ] Track selection (argument or interactive)
- [ ] Context loading
- [ ] Track status → in-progress
- [ ] Execution mode selection
- [ ] Per-task loop: RED → GREEN → REFACTOR → commit → mark complete
- [ ] Phase review: code simplifier → code reviewer → auto-fix → INBOX
- [ ] Phase checkpoint → user approval
- [ ] (repeat tasks/phases)
- [ ] Track completion: final verification + status update

Pre-flight

0. If the argument is a path to an existing .md file under issues/, go straight to Direct Issue Mode — it has its own pre-flight and does not require conductor/.
1. Verify project is initialized (conductor/workflow.md exists). If conductor/workflow.md does not exist, inform the user and stop (suggest setup).
2. Load workflow config: TDD strictness, commit strategy, verification rules

Track Selection

If the argument is a path to an existing .md file under issues/: skip the track flow entirely and follow Direct Issue Mode below.

If argument provided (track ID): validate conductor/tracks/{argument}/plan.md exists.

If no argument: read conductor/tracks.md, show incomplete tracks:

Select a track to implement:

In Progress:
1. [~] auth_20260403 - User Authentication (Phase 2, Task 3)

Pending:
2. [ ] nav-fix_20260402 - Navigation Bug Fix

Enter number or track ID:

Context Loading

Read all relevant context:

• conductor/tracks/{trackId}/spec.md — requirements
• conductor/tracks/{trackId}/plan.md — task list
• conductor/tracks/{trackId}/metadata.json — progress state
• conductor/product.md — product context
• conductor/tech-stack.md — technical constraints
• conductor/workflow.md — process rules
• conductor/code_styleguides/ — language conventions

Track Status Update

Mark track as in-progress:

• In conductor/tracks.md: change [ ] to [~]
• In metadata.json: set status: "in_progress", update timestamp

Execution Mode Selection

Detect subagent-driven-development and executing-plans using the detection procedure (check, in order: the available-skills list for the prefixed or bare name; .claude/settings.json enabledPlugins; a .claude/skills/<name>/ or .agents/skills/<name>/ directory). Check both plugin-prefixed and bare forms, and use whichever invocation form was found.

If Superpowers is available, offer the choice:

How should this track be implemented?

1. Subagent-driven (recommended) — fresh subagent per task with two-stage review
2. Inline execution — single session, batch checkpoints every 3 tasks

Subagent-Driven Execution (via Superpowers)

Invoke the subagent-driven-development skill using the detected form, passing the track's plan from conductor/tracks/{trackId}/plan.md.

Superpowers handles:

• Fresh subagent per task (implementer → spec-reviewer → code-quality-reviewer)
• TDD enforcement (red → green → refactor)
• Per-task commits
• Final code review across entire implementation

Our wrapper responsibilities (before/after Superpowers runs each task):

Before dispatching each task's subagent, update metadata.json: set current_task to this task's ID (e.g., "2.3") and current_phase to the containing phase number. This ensures resume state is accurate even if the session is interrupted mid-task.

After each task completes, update track metadata:

• Mark task [x] in conductor/tracks/{trackId}/plan.md
• Increment tasks.completed in metadata.json
• Set current_task to the next incomplete task ID
• Check for phase completion

Superpowers output control: When invoking the skill, instruct it that all artifacts belong in conductor/tracks/{trackId}/ — not docs/superpowers/. If Superpowers writes artifacts outside the track directory despite the instruction, move them in. If Superpowers invokes finishing-a-development-branch at the end, defer to our own Track Completion flow below instead — we manage the track lifecycle, not Superpowers.

Inline Execution (via Superpowers)

Detect executing-plans using the detection procedure (check, in order: the available-skills list for the prefixed or bare name; .claude/settings.json enabledPlugins; a .claude/skills/<name>/ or .agents/skills/<name>/ directory). If no signal is positive, fall back to the no-Superpowers path below.

Invoke the executing-plans skill using the detected form, passing the track's plan.

Same metadata lifecycle: write current_task before each task starts, update counters after each task completes. Same output control: instruct Superpowers to write to the track directory, redirect anything that escapes, and handle completion via our Track Completion flow.

Fallback (no Superpowers)

Execute tasks directly following TDD workflow from conductor/workflow.md:

For each incomplete task ([ ] in plan.md):

1. Mark in-progress: change [ ] to [~] in plan.md
2. Update metadata.json: set current_task to this task's ID (e.g., "2.3"), set current_phase to the containing phase number
3. RED: write failing test, verify it fails
4. GREEN: implement minimal code to pass, verify pass
5. REFACTOR: clean up, verify still passing
6. Commit: following commit strategy from workflow.md
7. Mark complete: change [~] to [x] in plan.md, increment tasks.completed in metadata.json

Phase Checkpoints

After all tasks in a phase are [x]:

1. Determine Phase File Scope

Build the list of files this phase touched:

Primary method: Collect all "files to modify" entries from the phase's tasks in plan.md.

Fallback (always run as supplement): The plan.md list misses new files created during tasks and files touched incidentally. Always supplement with git:

• Find the phase's first task commit in git log (match by task ID or commit message convention from workflow.md)
• Get its parent SHA with git rev-parse {first-task-commit}^
• Diff from its parent: git diff --name-only {parent-sha}..HEAD
• If no task commit is found, skip the git supplement and use the plan.md file list only
• Union with any files found in plan.md

This is the phase file list — all review and fixes are scoped to ONLY these files.

2. Phase Code Review

Launch Agent 1 first, then Agent 2 after it finishes. Running sequentially avoids edit conflicts when both agents fix the same file.

Agent 1 — Code Simplifier: Detect the simplify skill using the multi-signal procedure (check, in order: the available-skills list for the prefixed or bare name; .claude/settings.json enabledPlugins; a .claude/skills/<name>/ or .agents/skills/<name>/ directory). If found via any signal, invoke it with the phase file list. Otherwise, launch a general-purpose agent:

Review ONLY the following files from this phase: [phase file list]. Check for: unnecessary complexity, duplicated logic across the phase's files, dead code introduced by this phase, inconsistent patterns between tasks in this phase. For each issue found: state the file, line, and a concrete fix. Apply all fixes directly — do not ask for approval. If you discover issues in files outside the phase file list during your review, do NOT fix them. Return them as a separate out-of-scope list.

Agent 2 — Code Reviewer: Launch after Agent 1 completes so it reviews the already-simplified code:

Review ONLY the following files from this phase: [phase file list]. Check for:

• Security issues (injection, XSS, unvalidated input at boundaries)
• Performance regressions (N+1 queries, unnecessary re-renders, missing indexes)
• Correctness bugs (off-by-one, null handling, race conditions)
• Missing error handling at system boundaries
• Style and cosmetic issues (naming, formatting, dead imports)

For each issue found: state the file, line, severity (critical/warning/nit), and fix.

• In-scope (file is in the phase file list): Apply the fix directly, regardless of severity. Fix everything — critical, warning, and nit.
• Out-of-scope (file is NOT in the phase file list but you noticed an issue while reviewing code that calls into it): Do NOT fix. Return as a separate out-of-scope list.

If your harness cannot spawn subagents (e.g. Gemini CLI, Copilot CLI, or plain chat), do this work yourself sequentially, using each agent's brief above as a checklist.

After both agents finish:

1. If either agent made changes, commit following the commit strategy in workflow.md (e.g., refactor: phase {N} code review fixes). If neither agent made changes, skip the commit.
2. Collect out-of-scope issues from both agents. If any, append each as a bullet to issues/INBOX.md:

   - {description} in {file}:{line} ({severity}). Source: phase {N} review of {trackId}.
   

   If issues/INBOX.md does not exist, create it first with this content, then append the bullet under ## Inbox:

   # Issue Inbox
   
   Add issues as bullet points below. Run `/triage` in Claude Code or `$triage` in Codex to process them.
   
   ## Inbox
   

   Also create issues/archived/{tracked,implemented,deferred,wont-fix,duplicate}/.

3. Run Verification

1. Run phase verification steps listed in plan.md
2. Run full test suite
3. If review fixes broke tests: fix the regression inline (do not re-launch review agents), amend the review fixes commit, re-run tests to confirm

4. Report and Wait for Approval

Phase {N} complete.

Results:
- All phase tasks: complete
- Code review: {X} in-scope fixes applied, {Y} out-of-scope issues filed to INBOX
- Tests: passing
- Verification: pass

Review fixes committed: {commit SHA or "none — code was clean"}
INBOX items added: {Y}

Approve to continue to Phase {N+1}?
1. Yes, continue
2. No, there are issues to fix
3. Pause implementation

CRITICAL: Never proceed to the next phase without user approval.

Update metadata.json: increment phases.completed.

Error Handling

• Tool failure: HALT, present options (retry / skip / pause / revert)
• Test failure: HALT, show failures, offer fix / rollback / pause
• Git failure: HALT, show git status, suggest resolution

Resumption

If resuming a paused track:

1. Load metadata.json for current state
2. Find current task:
   • If current_task field exists in metadata.json, use it
   • Otherwise, fall back to scanning plan.md: first task marked [~] (in-progress), or if none, first task marked [ ] (pending)
3. Ask: continue from here / restart current task / show progress

Track Completion

When all phases and tasks are [x]:

1. Run final verification (full test suite + acceptance criteria from spec.md)
2. Update track status to complete:
   • In conductor/tracks.md: change [~] to [x]
   • In metadata.json: set status: "complete"
3. Offer cleanup: archive / keep as-is
4. Display summary:

Track Complete: {title}

Phases: {N}/{N}
Tasks: {M}/{M}
Commits: {count}
Tests: all passing

Next: Run /uat-create in Claude Code or $uat-create in Codex to generate an acceptance testing checklist.

Direct Issue Mode

Implement a small issue straight from its file — no spec, no plan, no track. The issue file is the spec; its Acceptance Criteria are the verification contract.

1. Read and validate the issue

• If the file does not exist: tell the user and stop.
• Read frontmatter. Eligible statuses: reviewed (preferred) or triaged. For triaged, tell the user the issue hasn't been through issue-review, and base your sizing on whatever Technical Context actually contains — it may be empty or incomplete.
• Any other status (tracked, implemented, wont-fix, deferred, duplicate): tell the user the issue already left the pipeline and stop.
• Malformed or missing frontmatter: show what's wrong, offer to fix it or stop.

2. Simplicity gate

Assess the issue against all four criteria and present a one-line verdict for each:

1. Testable — acceptance criteria are concrete and verifiable as written
2. Small — expected change surface is ~3 files or fewer (count the actual files in Technical Context's Affected Files, expanding any globs; if absent, scan the codebase)
3. No design decisions — no new architecture, schema/API changes, or new dependencies
4. Single session — completable in one sitting

Then ask the user:

Recommendation: {implement directly | advance to a track}

1. Implement directly
2. Advance to a track instead (/issue-advance in Claude Code, $issue-advance in Codex)
3. Cancel

Failing any criterion flips the recommendation to "advance" — but the user decides; honor an override in either direction.

3. Execute with TDD

• If conductor/workflow.md exists, load TDD strictness and commit strategy from it. Otherwise use defaults — strict TDD, single commit — and say so.
• Run the RED → GREEN → REFACTOR loop from Fallback (no Superpowers) above, driven by the acceptance criteria instead of plan tasks: write a failing test per criterion, make it pass, refactor. Skip that section's plan.md and metadata.json bookkeeping — there is no track.
• If the project has no test suite, say so and verify each acceptance criterion by inspection instead.
• If the test suite fails before you change anything: HALT and show the failures — do not build on a broken baseline.
• Scope escalation: if the work exceeds the assessed size (more files than expected, a design decision surfaces), stop and present: continue anyway / escalate to issue-advance / pause. Escalation does not carry work-in-progress.
• Out-of-scope findings discovered along the way: append to issues/INBOX.md as bullets, creating the file with a ## Inbox heading if missing.
• Commit once, following the commit strategy; reference the issue file path in the message (e.g., fix: honor track status on restore (issues/2026-06-09-manage-restore-status.md)).

4. Final gate

Present before archiving:

Issue implemented: {title}

Acceptance criteria: {checklist with pass/fail}
Tests: {results}
Changes: {git diff --stat summary}
Commit: {sha}

Approve to archive the issue?
1. Yes, archive
2. No — fix something first
3. No — revert the work

If the user wants changes: fix, re-present. On revert: undo the commit, leave the issue file untouched.

5. Archive as implemented

On approval:

• Get today's date by running date +%Y-%m-%d — do not assume you know it.
• Update frontmatter: status: implemented, add implemented: YYYY-MM-DD and commit: <sha>.
• Move the file to issues/archived/implemented/ (create the directory if missing).
• Confirm: issue title, commit SHA, and archive location.