/implement - Implementation Agent

Token Efficiency

Mode	How it works	Token cost
Auto	Orchestrator stays alive, spawns workers in background. Workers output a 4-line signal + write details to task doc. Orchestrator accumulates only signals (~50 tokens each).	Very low
Manual + `/clear`	Run each skill in a fresh session. Same token benefit, you stay in control.	Low
Manual without `/clear`	History compounds across all stages.	High (avoid)

Manual mode tip: After each skill completes, run /clear before invoking the next one.

Workflow

/implement [auto] {ID}
       ↓
0. Read LEARNINGS.md (if exists) — avoid known mistakes
1. Parse arguments: detect "auto" flag, "--model" override, task ID
2. Resolve task ID → find docs/task/{ID}-{name}.md
3. Read task document — this is the ONLY codebase context needed
   └── Only read source files explicitly listed in task doc's "File Changes"
   └── Do NOT explore directories, grep broadly, or read files not in the plan
4. Enter worktree isolation: EnterWorktree({ name: "task-{ID}" })
   └── Creates .claude/worktrees/task-{ID}/ on a new branch
   └── All edits, commits, and pushes happen inside the worktree
   └── User's working directory stays on main — never switches branch
5. If "auto" flag → set Automation: auto in task doc
6. Move task to "## In Progress" in TASKS.md
7. Invoke specialized skills if relevant (see Step 3 below)
8. Implement following task document steps
9. Commit with [task-{ID}] prefix for traceability
10. Push branch to origin (git push -u origin {branch})
11. Update status to "TESTING" when complete
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
Notify user              Enter Orchestrator Mode
Ready for /simplify      (drives pipeline, stays alive)

Pre-Implementation Checklist

0. Read Project Learnings

Read LEARNINGS.md entirely if it exists (~200 tokens, saves thousands)
Focus on: Common Mistakes to Avoid, Established Coding Patterns, Architecture & Decisions, Tech Stack Notes
The task doc contains all codebase research you need — only open source files explicitly listed in ## File Changes; do NOT explore directories or read unlisted files

0.5. Parse Arguments

auto → set automation mode
--model {haiku|sonnet|opus} → model override (takes precedence over task doc recommendation)
Natural language hint (e.g., "use sonnet", "force haiku") → treat as model override
Remaining arg → task ID

Model override resolution (priority order):

--model flag or inline natural language hint → use this, ignore task doc
Recommended Model field in task document → use this
Default fallback → haiku

Acknowledge override:

Model: sonnet (override — task recommended: haiku)

Or when using task recommendation:

Model: haiku (recommended by task)

If auto detected, update task document header:

> **Automation:** auto

1. Resolve Task ID

Read TASKS.md
Find row with matching ID in first column
Get task doc path from that row
Verify file exists in docs/task/

1.5. Enter Worktree Isolation

Before any file edits or git operations:

EnterWorktree({ name: "task-{ID}" })

Creates .claude/worktrees/task-{ID}/ on a new branch
User's working directory stays on main for the entire implementation
Multiple agents can run in parallel with zero branch conflicts

2. Read the Task Document — Then Stop Exploring

✅ ALWAYS READ:
   - docs/task/{ID}-{task-name}.md          (your primary source)
   - LEARNINGS.md                            (already done in Step 0)
   - Files listed in ## File Changes         (only these, nothing else)

❌ DO NOT READ unless the task doc explicitly names them:
   - package.json / tsconfig.json / .env
   - Any config file not in ## File Changes
   - Files in directories not mentioned in the task doc
   - Adjacent files "for context"

❌ DO NOT RUN:
   - find . -type f       (directory sweeps)
   - ls -R / ls -la       (directory listing)
   - cat on unlisted files
   - Any grep to "understand patterns" — patterns are in ## Code Context

If a file isn't in the task doc and you think you need it: check ## Code Context first. If it genuinely isn't there, use a targeted Grep for the specific symbol — not a directory sweep.

Understand from the task doc:

Task ID (for commit messages)
Recommended Model — advisory, not a blocker; note if different but proceed
Requirements, proposed solution, architecture
File changes — your complete reading list
Implementation steps — follow them in order

3. Invoke Specialized Skills

Before writing any code, check whether platform-specific skills are installed and relevant:

Skill	Invoke When
`/vercel-react-best-practices`	Task involves React, Next.js, or TypeScript
`/supabase-postgres-best-practices`	Task involves database queries, RLS, schema, or Supabase

If a relevant skill is available, invoke it before writing code. If you realize partway through you skipped one, invoke it then review your code before continuing.

4. Update TASKS.md

Move task from "Planned" to "In Progress" with started date and status.

5. Verify Dependencies

Required API endpoints exist
Required types/interfaces exist
Required packages installed
No blocking tasks

Commit Convention

All commits must include the task ID prefix.

[task-{ID}] {type}: {description}

{optional body}

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

git commit -m "[task-1] feat: Add JWT authentication middleware

Implements token validation and refresh logic.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"

Completion Checklist

Category	Checks
Code quality	Compiles without errors, no TypeScript errors, follows existing patterns
Functionality	All "Must Have" requirements implemented, happy/loading/error/empty states handled
Task document	Requirements checked off, deviations documented, notes for tester added

Update Status to TESTING

When implementation is complete:

1. Update TASKS.md — move to "Testing" section with test report pending.

2. Update task document:

> **Status:** TESTING
> **Completed:** {Date}
> **Implementation Notes:** {Any important notes for tester}

3. Update CLAUDE.md (Structural Changes)

Scan what was built and update CLAUDE.md immediately — don't wait for /document.

What you built	What to update in CLAUDE.md
New directory created	`## Project Structure`
File moved or renamed	`## Important File Locations`
Database migration added	`## Stack` (schema note) + `## Important File Locations`
New edge function / API route	`## Important File Locations` or `## Key Conventions`
New env variable required	`## Stack` (note the var and purpose)
New package installed	`## Stack`
New pattern established (used 2+ times)	`## Key Conventions`
Old pattern replaced	Remove old entry, add new one

Read existing CLAUDE.md before touching it — prune stale entries first
Never just append — if a directory was renamed, update the old entry
If none of the above apply (pure logic change, styling tweak) → skip

4. Push branch to origin:

git push -u origin {branch-name}

5. Pre-Completion Verification:

React/Next.js task? → Invoked /vercel-react-best-practices (if installed)?
Database/Supabase task? → Invoked /supabase-postgres-best-practices (if installed)?
If skipped, invoke now and review code before proceeding.

6. Inform User / Chain to Next Skill:

Check Automation: auto field in task document.

Manual Mode:

Output: completion summary with files changed, commits made, recommended model, and next step (/simplify {ID})

Run /clear before invoking /simplify — it only needs the task doc, not this history.

Auto Mode: Enter Orchestrator Mode below.

Orchestrator Mode

Only entered when Automation: auto is set. This session stays alive as the pipeline coordinator. Workers run in background, write results to the task document, and return a 4-line signal. You read the signal and decide what happens next — never the worker.

Shared memory: docs/task/{ID}-{task-name}.md — every worker reads and writes to it.

retry_count = 0
max_retries = 3

Stage 1 — Quality Gate

Assign simplify worker:

Task({ subagent_type: "general-purpose", model: "sonnet", prompt: "/simplify {ID}", run_in_background: true })

Wait for SIGNAL. Route:

Signal	Action
`STATUS: PASS`	Proceed to Stage 2
`STATUS: FAIL`	retry_count++. If retry_count > max_retries → STOP, notify user. Otherwise: assign implement-fix worker (see Fix Worker below), then return to Stage 1

Stage 2 — Testing

Assign test worker:

Task({ subagent_type: "general-purpose", model: "haiku", prompt: "/test {ID}", run_in_background: true })

Wait for SIGNAL. Route:

Signal	Action
`STATUS: PASS`	Proceed to Stage 3
`STATUS: FAIL`	retry_count++. If retry_count > max_retries → STOP, notify user. Otherwise: assign implement-fix worker referencing `REFERENCE` from signal, then return to Stage 1

Stage 3 — Documentation

Assign document worker:

Task({ subagent_type: "general-purpose", model: "haiku", prompt: "/document {ID}", run_in_background: true })

Wait for STATUS: DONE signal → proceed to Stage 4.

Stage 4 — Ship

Assign ship worker:

Task({ subagent_type: "general-purpose", model: "haiku", prompt: "/ship {ID}", run_in_background: true })

Wait for STATUS: DONE signal → pipeline complete.

Pipeline Complete

Report to user:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PIPELINE COMPLETE: #{ID} - {Task Title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ implement   code written & committed
✓ simplify    quality gate passed
✓ test        {N} criteria verified
✓ document    feature doc created
✓ ship        PR ready for review

PR: {url from ship signal}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Fix Worker (when simplify or test fails)

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "/implement {ID} — Fix required. See REFERENCE path in task doc for details.",
  run_in_background: true
})

The worker reads the task document fresh — all context is in ## Implementation Notes or the test report path. Pass only the reference path, not the full failure details.

Stop Conditions

Stop the pipeline and notify the user when:

retry_count > max_retries (3 cycles without PASS)
Any worker returns STATUS: BLOCKED
Ship worker returns a build/lint failure

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PIPELINE STOPPED: #{ID} - {Task Title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stopped at: {stage}
Reason: {signal summary}
Details: {REFERENCE path from signal}

Action needed from you before pipeline can continue.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specialized Skills (Install Separately)

vercel-react-best-practices — install from vercel-labs/agent-skills; invoke for React/Next.js/TypeScript code
supabase-postgres-best-practices — install from supabase/agent-skills; invoke for database queries, RLS, schema, Supabase code

implement