tt-implement-plan

Contents

• How this differs from /implement-plan
• CRITICAL: Orchestrator pattern (kept from /implement-plan)
• Workflow
  • Step 0: Locate the project + the plan
  • Step 1: Read the principles and requirements (ground the session)
  • Step 2: Read the phase plan
  • Step 3: Resume detection
  • Step 4: Execute one phase
  • Step 5: Between phases — user confirmation
  • Step 6: Final completion
• Handling blockers
• Locked phase body — what to do instead
• Anti-patterns to avoid
• Quality checklist (per phase)
• Quality checklist (final)
• Resources
  • references/
  • Related tasktracker skills
• Key principles

Reference files (open one when a step points to it):

• references/insight-cookbook.md: Insight Cookbook — logDefect / logLearning / logFriction
• references/plan-format.md: How a tasktracker plan is stored

Tasktracker-native orchestrator that executes a plan stored as phase tasks. It runs phases one at a time, honours active-task / locked-body / insight-logging conventions, and delegates the actual code work to /tt-implement-phase (which in turn delegates to subagents).

How this differs from /implement-plan

If the plan came from /create-plan (file-based), use /implement-plan. If the plan lives in tasktracker, use this skill.

CRITICAL: Orchestrator pattern (kept from /implement-plan)

THIS SESSION IS THE ORCHESTRATOR. IT NEVER IMPLEMENTS CODE DIRECTLY — it walks the phases and, for each, follows /tt-implement-phase as the phase lead: it dispatches the role agents, waits for their reports, and keeps TaskTracker accurate. The phase runs in this session because agent reports arrive here; a forked lead can't receive them. Code is written by the implementer agent, or by this session only when no subagent tool exists at all (/tt-implement-phase's in-context mode).

tt-implement-plan (this session — ORCHESTRATOR and PHASE LEAD)
    │
    │   ⛔ NEVER writes code   ⛔ NEVER uses Write/Edit   (while Agent is available)
    │   (creates files only via tasktracker MCP calls)
    │
    └── follows tt-implement-phase for each phase, in this session
            │
            ├── orchestrated mode → implementer / mechanic / reviewer agents do the work;
            │                       their reports arrive here as messages
            └── in-context mode  → only when no subagent tool exists

"Foreground", "no background agents" or "don't poll" in the user's words is about waiting, not about who writes the code: dispatch the role agents and wait for their reports, never polling with sleep loops. Only an explicit "write the code yourself in this session" overrides the orchestrator rule; ask when unsure. (On a Strago run, "do the work in the foreground" was read as permission to write a step in-context, and the user had to correct it.)

If you find yourself about to use Write/Edit/NotebookEdit:

⛔ STOP — you are violating the plan-orchestrator pattern.
✅ Dispatch the implementer agent, as /tt-implement-phase describes. (Only with no
   subagent tool at all does the work happen in-context. Writing code here while
   the Agent tool exists is the bug.)

Workflow

Step 0: Locate the project + the plan

1. tasktracker_listProjects({search: "..."})   # or use argument hint.
   - If user passed a slug or id, use it directly with getProject.
2. tasktracker_getProject({projectId})
3. tasktracker_getProjectReadiness({projectId})
   - The `plan` row should read satisfied — meaning concrete phases
     exist beyond the four lifecycle phases. If not, STOP. The user
     probably needs /tt-create-plan first.

If the user gives a phase task id directly ("implement phase X"), skip the readiness gate and treat that single phase as the scope.

Step 1: Read the principles and requirements (ground the session)

tasktracker_getPrinciples({projectId, includeGlobal: true})
tasktracker_listRequirements({projectId, status: "approved"})

Spend a moment reading. Principles are the durable rules; requirements are the contract this work fulfils. The next ~hour of decisions hangs off these.

Step 2: Read the phase plan

tasktracker_listTasks({projectId, type: "phase"})
# Filter out the four lifecycle phases (metadata.lifecycleSlug ∈
# {brainstorm, requirements, architecture, plan}) — those are done.
# What remains is the implementation plan.

# For each implementation phase, in dependency order:
tasktracker_getTask({taskId})                  # body, status, version
tasktracker_getChildTasks({taskId})            # sub-tasks
tasktracker_listAcceptanceCriteria({requirementId})   # per linked requirement

Note the order: phase tasks are intended to be executed in the order they were created (or per blockedBy if explicit). Identify the first non-completed phase — that's the resume point.

Step 3: Resume detection

For each implementation phase, in order:
  - status == "completed" → skip
  - status == "in_progress" → resume from here
  - status == "pending" → first incomplete; resume from here
  - Stop at the first pending/in_progress one.

Display the resume point to the user:

● Plan Status: <project name>

  ✓ Phase 1 — Database schema (completed)
  ✓ Phase 2 — Auth service (completed)
  ◻ Phase 3 — API endpoints (in_progress)   ← resume here
  ◻ Phase 4 — Tests (pending, blocked by 3)
  ◻ Phase 5 — Docs (pending, blocked by 4)

Resuming Phase 3.

Multi-session note: the MCP persists activeTask to ~/.config/tasktracker-mcp/active-task across restarts. You usually do not need CLAUDE_CODE_TASK_LIST_ID=... — opening a new session sees the same active task.

Step 4: Execute one phase

For each phase, in order:

4a. Activate

tasktracker_setActiveTask({taskId: <phase-task-id>})
# Unless the phase is already in_progress (a resume):
tasktracker_updateTaskStatus({taskId: <phase-task-id>, status: "in_progress", version: <from getTask>})

setActiveTask returns a digest containing principles, the phase body, acceptance criteria, and (if present) the directional-work block. Read this carefully — it's the ground truth for the phase scope. Do not re-derive scope from the original brainstorm; the phase body is the locked contract.

Time comes from heartbeats, not timers. Tasktracker books time only while tasktracker MCP calls keep arriving for the active task; a segment closes after ~5 minutes without one. While role agents work, they keep the time segment open (getCurrentTimer at least every ~4 minutes, confirmed by a HEARTBEAT: line in each report); this session can't heartbeat while it waits for them. Don't call startTimer — started timers create lease-less rows that absorb other sessions' cost (one phase read 12h18m against 3h16m of real work) — and don't switch or pause the active task while agents are working.

4b. Announce

═══════════════════════════════════════════════════════════════
● STARTING PHASE N: <Phase Name>
═══════════════════════════════════════════════════════════════

Objective: <from phase body>
Verification approach: <from phase body>
Requirements: <list of REQ-... this phase implements>
Sub-tasks: <count> seeded
Principles in play: <any directly relevant>

Delegating to /tt-implement-phase...

4c. Run the phase with /tt-implement-phase

Skill(skill="tt-implement-phase", args=<the block below>)

Execute Phase N.
Caller: tt-implement-plan
Project: <project name + id>
Phase task id: <id>
Phase title: <title>
Sub-tasks: <list from getChildTasks>
Requirements: <list of (id, title, criteria) from listAcceptanceCriteria>
Principles: <surfaced from setActiveTask digest>
Checkpoints: <per-unit when the user wants a report after each step>

Execute all quality gates. Update each sub-task's status as it
completes. Finish with PHASE_RESULT.

CRITICAL: do NOT update the phase description — it is locked
once sub-tasks exist (HTTP 422). Any design rationale or new
finding goes to the "Design + decision note" sub-task (or a
new sub-task if that one is already closed).

The Skill call loads /tt-implement-phase's procedure into this session, and you follow it as the phase lead: dispatching the work by role (a Sonnet implementer, a Haiku mechanic checking every unit, an Opus reviewer), sub-task setActiveTask/updateTaskStatus discipline, exit-condition verification via /verification-loop, integration testing, code review via /devflow:code-review, ADR compliance, task-tree synchronization and insight logging. The code itself comes from the implementer agent.

Agent reports arrive later, as messages. Each Agent call returns at once; when nothing else is left to do, end the turn with one line naming what you're waiting for, and the agent's report resumes you. Don't poll with sleep loops, and don't write the code yourself while an agent is on it. When the user asked for a report after each step, pass Checkpoints: per-unit: the phase then prints a three-line checkpoint after every unit's independent check and carries on.

The phase ends with its PHASE_RESULT (preflight, sub_tasks, evidence, insights_logged) written in this conversation. Use it for the Step 5 block; don't restate more than that.

4d. Insight logging (during, not after)

/tt-implement-phase Step 7 captures phase-level insights. At the plan-orchestrator level, ALSO log anything that surfaces as a cross-phase concern (e.g., a defect that affects future phases, a friction with the plan itself). Don't bury it in chat.

If a principle should be added based on this phase's experience, propose it to the user — don't silently add. Principles are a charter, not a backlog.

4e. Pause before any user wait

Before any message that ends with a question, tasktracker_pauseActiveTask. The user's thinking time is not work time — pauseActiveTask closes the running time segment for exactly the wait, and the next tool call opens a fresh one. Never pause while role agents are working: pausing would cut the segment their heartbeats keep open.

4f. Phase done

Read the PHASE_RESULT the phase procedure wrote. It leaves the active task on the phase so the writes below are attributed.

On status: PASS:

1. tasktracker_getTask({taskId: <phase-task-id>}). The procedure normally completed the phase in its Step 8 (phase_status: completed or completed_with_caveat) — then there is nothing to write. If the phase isn't completed, check that every sub-task is completed (or archived, with a one-line reason logged), then tasktracker_updateTaskStatus({taskId: <phase-task-id>, status: "completed", version}).
2. tasktracker_clearActiveTask() — Step 8 of the phase left the pointer on the phase for you.
3. Show the user the result block (Step 5).

On status: FAILED (or BLOCKED, which only an unattended run returns), stop. Put it to the user (see "Handling blockers" below). Do not auto-proceed.

If the phase was completed with a caveat (phase_status: completed_with_caveat), the procedure called completeWithCaveat itself — just propagate the caveat in the user-facing summary.

Step 5: Between phases — user confirmation

By default, show this block and wait for the user before the next phase. If the user asked to run the whole plan or to run unattended, show the block without the confirmation line and start the next phase straight away; collect any manual-verification items for the closing summary. BLOCKED and FAILED still stop the run either way.

═══════════════════════════════════════════════════════════════
● PHASE N COMPLETE: <Phase Name>
═══════════════════════════════════════════════════════════════

Results from /tt-implement-phase:
  ✅ Implementation: <N> files created, <M> modified
  ✅ Exit Conditions: all passed
  ✅ Code Review: PASS (notes: <from PHASE_RESULT, or "none">)
  ✅ ADR Compliance: passed
  ✅ Sub-tasks: <X>/<X> completed

Insights logged this phase:
  • Defect: <id> — <summary>
  • Learning: <id> — <summary>
  • Friction: <id> — <summary>

Manual verification required:
  - [ ] <user-observable check from PHASE_RESULT>

───────────────────────────────────────────────────────────────
Please confirm the manual verification, then say "go" to start
Phase N+1: <Next Phase Name>.
═══════════════════════════════════════════════════════════════

4f already cleared the active task, so nothing is booked while the user reads this.

Step 6: Final completion

When all implementation phases are completed:

tasktracker_getProjectReadiness({projectId})
# Verify all four lifecycle rows still satisfied; verify plan row.

# ── Definition-of-Done gate (Phase 115) ──────────────────────────
# THE authoritative "is the build actually done" check. Server-side,
# all-pillars: every phase completed, zero unsatisfied ACs on linked
# approved requirements, zero open defects, zero architecture drift.
tasktracker_getProjectDoneness({projectId})
# If done:false — DO NOT declare the build complete. Surface each
# blocker, resolve it (or open a follow-up phase), and re-run. A
# "green" completion with open defects / unsatisfied ACs / drift is
# exactly what this gate exists to stop. readiness=plan formed;
# doneness=work correct — both must pass before the closing summary.

tasktracker_getDefectStats({projectId})
tasktracker_getImprovementMetrics({projectId})

tasktracker_clearActiveTask()

Closing summary:

═══════════════════════════════════════════════════════════════
● PLAN COMPLETE: <Project Name>
═══════════════════════════════════════════════════════════════

Implementation phases completed: <N>/<N>

Insights this run:
  Defects logged: <count>   (open: <count>)
  Learnings:      <count>
  Frictions:      <count>

Final verification:
  - [ ] E2E run: <command>
  - [ ] Documentation updated (if applicable)
  - [ ] Security checklist (if security-sensitive)

Active task cleared. Ready for review.
═══════════════════════════════════════════════════════════════

Handling blockers

A blocker found mid-phase is put to the user by the phase procedure itself (its blocker protocol: persist it, pause, ask, continue from the blocked step). The steps below are for a phase that ended FAILED, or BLOCKED in an unattended run:

1. STOP further phase execution.
2. PAUSE — tasktracker_pauseActiveTask(). The pointer is still on the phase; the user's thinking time isn't work.
3. ASK with AskUserQuestion: the blocker, the options from PHASE_RESULT.blocked.options, and your recommendation. A FAILED result has no options — offer retrying the failed step, a follow-up phase, or abort.
4. RESUME or ABORT based on the answer:
   • Resume → run /tt-implement-phase again as in 4c, adding Resume From Step: <blocked.step>, the user's decision, and the earlier PHASE_RESULT verbatim, then continue at 4f with the new result.
   • Abort → tasktracker_clearActiveTask(). The phase keeps its blocked sub-task, whose blockedReason records why.

Don't auto-fix. Don't auto-revise the plan. Don't auto-edit the phase body (it's locked anyway). The user owns the call.

⛔ PHASE N BLOCKED

Issue: <from PHASE_RESULT.blocked — step, kind, details, needs>

Options:
A) <option from /tt-implement-phase>
B) <option>
C) Abort and create a follow-up phase

Recommendation: <which option, with rationale>

How should I proceed?

If the resolution is "create a follow-up phase", do that outside the blocked phase — tasktracker_createTask({projectId, type: "phase", title, description, requirementIds: [<same requirements>]}) with a clear title. Do not stuff new scope into the blocked phase's body (which is locked anyway).

Locked phase body — what to do instead

Five common situations where you'd want to edit the phase body, and the right answer:

This is not bureaucracy — it's the audit trail. The phase body shows "what we planned", the sub-tasks show "what actually happened", and the diff is debuggable.

Anti-patterns to avoid

• ❌ Writing code in this session while the Agent tool is available — including when the user asked for "foreground" work. Dispatch the implementer.
• ❌ Skipping setActiveTask before phase work — principles won't surface.
• ❌ Calling startTimer for phase time, or switching/pausing the active task while agents are working. Time comes from heartbeats (4a).
• ❌ Polling agents with sleep/wait loops, or saying "I'll wait for the agent" and then ending the phase. End the turn; the report resumes you.
• ❌ Reporting on a phase as done, or starting the next one, before its PHASE_RESULT is written.
• ❌ Forgetting pauseActiveTask before user-wait messages.
• ❌ Editing a phase description after sub-tasks exist (HTTP 422).
• ❌ Auto-fixing a blocker without user confirmation.
• ❌ Marking a phase completed with sub-tasks still in_progress.
• ❌ Logging defects/learnings in chat-only narrative instead of via logDefect/logLearning.
• ❌ Re-deriving scope from the brainstorm or earlier conversation — the phase body is the locked contract.
• ❌ Using TaskCreate/TaskUpdate (the Claude-Code built-ins) for phase progress — use tasktracker_updateTaskStatus.

Quality checklist (per phase)

• setActiveTask set before the first artifact-producing call.
• No startTimer; the active task was not switched or paused while agents were working.
• Phase body read from the setActiveTask digest (not re-derived).
• Principles surfaced and acknowledged where they constrain the phase.
• The role agents did the code work; this session led the phase per /tt-implement-phase and acted on its PHASE_RESULT.
• Sub-tasks marked completed as each finished.
• No edits to the phase description.
• Defects/learnings/frictions logged via tasktracker insights, not chat.
• pauseActiveTask before every user-wait message.
• Phase marked completed only when all sub-tasks are completed (or archived with a reason); active task cleared after the phase finished.
• User confirmed before moving to the next phase (unless they asked for an unattended run).

Quality checklist (final)

• All implementation phases completed.
• getProjectReadiness shows all four lifecycle rows still satisfied.
• getProjectDoneness returns done:true — the build was NOT declared complete while any blocker stood (open defects / unsatisfied ACs / incomplete phases / architecture drift).
• getDefectStats reviewed; open defects either resolved or have a follow-up task.
• clearActiveTask called.
• Closing summary delivered (in chat, not as a file).

Resources

references/

• plan-format.md — How a tasktracker plan is stored: project → phase tasks → sub-tasks, requirement links, acceptance criteria, dependencies, and the readiness/doneness gates.
• insight-cookbook.md — When and how to use logDefect, logLearning, logFriction. Common patterns.

Related tasktracker skills

• /tt-implement-phase — Per-phase orchestrator. This skill delegates to it for every phase.
• /devflow:code-review — Per-phase quality gate inside /tt-implement-phase (not Claude Code's built-in /code-review).
• /adr — Recording mid-implementation design decisions (the ADR file lives in docs/decisions/; the reference goes to a sub-task).
• /verification-loop — 6-check verification framework used inside /tt-implement-phase.
• tasktracker_getProjectReadiness — Useful at start and end as a sanity check.
• /tt-create-plan — Upstream: the skill that produces the plan this orchestrator runs.

Key principles

1. Lead each phase by /tt-implement-phase — in this session, where the agents' reports arrive.
2. Orchestrate, don't implement — this session coordinates and dispatches; the implementer agent codes.
3. Active-task discipline — setActiveTask / pauseActiveTask / clearActiveTask are not optional; time comes from heartbeats, never startTimer. Leave the pointer alone while agents are working.
4. Locked phase body is sacred — sub-tasks are the right place for mid-implementation notes.
5. Insights belong in tasktracker — logDefect / logLearning / logFriction, not just chat.
6. Pause between phases by default — run them back-to-back only when the user asked to run the whole plan or run unattended.
7. Surface blockers immediately — the user owns the resolution call.
8. Act on the PHASE_RESULT — the structured block the phase procedure ends with.