implement

Delegate to the implementer agent. Tests should fail (red phase).

Prerequisites: Plan approved (or loaded from plan file), worktree created, working inside the worktree directory.

Process

1. Review the approved plan's implementation order
2. Delegate to the implementer agent with instructions to write tests first. Include the planner's file analysis to reduce redundant reads — pass along:
   • The Files to Modify and Files to Create lists from the plan (with the planner's notes on what changes in each)
   • Key architectural context the planner discovered (patterns, conventions, relevant existing code)
   • If hasPlanFile is true: Source all of the above from the plan file's ## Implementation Plan and ## Architectural Context sections instead of conversation memory
   • If attachments included UI mockups, wireframes, or screenshots, pass the file paths (e.g., /tmp/claude/attachments/mockup.png) so the implementer can read them directly and write tests that reflect the expected UI structure and behavior
   • If designSpec was loaded, include the Components table and Design Tokens sections so tests can verify correct component structure and token usage
   • Worktree path: <worktree-path>. First Bash command: cd <worktree-path>. CWD persists — do not cd again.
3. For each item in the plan, write tests that cover:
   • The acceptance criteria from the ticket
   • Edge cases identified during planning
   • Error scenarios and boundary conditions
4. Run the test suite — tests should fail (red phase)
5. Report which tests exist and their failure reasons

Test Priority

Frontend stacks (Angular, React, Vue, Next.js, Svelte):

• Read the testing reference skill's UI Component Classification section
• For each component/page in the plan, use the classification to select test types
• Write E2E tests for critical journeys first, then integration/component tests, then unit tests
• Note visual-sensitive components for post-implementation verification in Phase 4

Backend stacks:

• Integration tests first: Real flows that exercise the actual behavior end-to-end
• Unit tests only for: Complex domain logic (calculations, state machines, validation rules)

Test Quality Rules

Assert behavior and business rules:

• Status codes, response shapes, business state changes
• NOT call counts, NOT hardcoded magic values, NOT values copied from implementation

Tests should be:

• Readable as requirements documentation
• Independent of each other (no shared mutable state)
• Deterministic (no timing dependencies, no random values without seeds)

Output

List of tests written with their current status (all should be failing). If any test passes before implementation, investigate — it may indicate the test isn't testing new behavior.

Error Recovery

If tests can't be written (missing test infrastructure, unclear requirements):

1. Identify exactly what's blocking
2. If it's a missing dependency or configuration, fix it
3. If requirements are unclear, escalate to the user — do not guess

Delegate to the implementer agent. Tests should pass (green phase).

Error recovery: If build or tests fail, the implementer retries up to 3 times. If still failing after 3 attempts, stop and ask the user.

Prerequisites: Tests written and failing (red phase complete).

Design Structure Pre-Reading (if pencil.enabled and pencilAvailable)

Before delegating to the implementer, the main agent pre-reads design structure from the .pen file so the implementer subagent receives it as text context (subagents cannot use Pencil tools).

1. Identify relevant screens: From the ticket description and implementation plan, determine which screens (by node ID from designScreenIds) are affected by this ticket.

2. Read design structure and tokens:

   CLI-app mode: Batch all reads into a single invocation:

   pencil interactive -a desktop <<'EOF'
   batch_get({ nodeIds: ["<screen-node-id-1>", "<screen-node-id-2>"], readDepth: 3 })
   get_variables()
   export_nodes({ nodeIds: ["<screen-node-id-1>", "<screen-node-id-2>"], outputDir: "$TMPDIR/design-screenshots", format: "png" })
   EOF
   

   Then Read each exported PNG for visual references to pass to the implementer.

   Editor mode: Call each tool separately via MCP:

   • batch_get(nodeIds: [<screen-node-id>], readDepth: 3) per screen
   • get_variables()
   • get_screenshot(nodeId: <screen-node-id>) per screen

3. Store the results as designStructure (component hierarchy), designTokenValues (tokens), and screenshot references.

If any Pencil call fails, inform the user which calls failed and what data will be missing. Proceed with DESIGN.md text content only — do not block implementation.

Pass to implementer: Include designStructure, designTokenValues, and screenshot references as text context in the implementer delegation prompt. If any data is missing due to failures, note which pieces are absent so the implementer knows the design context is partial. Tell the implementer: "Use this design structure for component hierarchy. Use design token values for spacing, colors, and typography. Compare your implementation visually against the provided screenshots."

Process

1. Delegate to the implementer agent with instructions to make failing tests pass. Carry forward the same planner context provided in Phase 3 (file lists, architectural notes) so the implementer doesn't re-read files it already analyzed. If hasPlanFile is true: Source context from the plan file's ## Implementation Plan and ## Architectural Context sections.
   • If attachments included UI mockups, wireframes, or screenshots, pass the file paths (e.g., /tmp/claude/attachments/mockup.png) so the implementer can read them directly and match the expected visual design
   • If designSpec was loaded, include the full DESIGN.md content — component hierarchy, UI library mappings, CSS custom property references from design tokens. Tell the implementer: "Use the DESIGN.md component mappings and design tokens for implementation. Map design components to framework components as specified in the Components table. Use CSS custom properties from the Design Tokens section."
   • If lspServers in .claude/config.json has any enabled servers, tell the implementer: "LSP diagnostics are active — fix type errors and unused code after each edit"
   • Worktree path: <worktree-path>. First Bash command: cd <worktree-path>. CWD persists — do not cd again.
2. Follow the approved plan's implementation order
3. For each failing test:
   • Write the minimum code to make it pass
   • Run the test to confirm it passes
   • Ensure no previously passing tests have broken
4. Run the full build and test suite after all changes
5. All tests should pass (green phase)

Visual Verification (frontend stacks, when applicable)

After all functional tests pass, if the plan's Test Strategy includes visual components:

1. Playwright Test (primary): If Playwright is configured (playwright.config.* exists), write visual regression tests using toHaveScreenshot() — these run in CI and catch regressions automatically
2. Playwright CLI (interactive checks): Use playwright-cli open <url>, playwright-cli screenshot, playwright-cli snapshot for dev verification — layout inspection, CSS debugging, responsive behavior. Playwright CLI verifications are ephemeral and do NOT replace Playwright Test.
3. If neither available: note in PR description that visual verification was not performed

See the testing skill's "Browser Testing Tools" section for the full decision framework.

Design Comparison (if pencil.enabled and pencilAvailable)

After functional tests pass and standard visual verification is complete:

1. Screenshot comparison: Use the screenshot references captured during Design Structure Pre-Reading. If not available (pre-reading was skipped or failed):

   CLI-app mode:

   pencil interactive -a desktop <<'EOF'
   export_nodes({ nodeIds: ["<screen-node-id>"], outputDir: "$TMPDIR/design-comparison", format: "png" })
   snapshot_layout({ parentId: "<screen-node-id>", problemsOnly: true })
   EOF
   

   Then Read the exported PNG for comparison.

   Editor mode: Call get_screenshot(nodeId: <screen-node-id>) and snapshot_layout(parentId: <screen-node-id>, problemsOnly: true) via MCP.

   Compare side-by-side with the Playwright screenshot of the implemented page. Note any significant visual discrepancies.

2. Layout verification: Review the snapshot_layout output for clipping, overflow, or misalignment issues that might indicate the implementation diverges from the design.

3. If discrepancies are found, list them and delegate fixes to the implementer. Re-run the comparison after fixes. Only proceed to Phase 5 once comparison passes or the user explicitly accepts the remaining gaps.

If Pencil is unavailable (pencilAvailable = false), skip this section and note in the PR description that design comparison was not performed.

Rules

• Follow the approved plan exactly
• Make failing tests pass with the simplest correct implementation
• Follow patterns from .claude/rules/ files
• Follow lessons from .claude/rules/lessons-learned.md
• No premature abstractions — keep it simple
• No dead code, no commented-out code, no TODOs without ticket references

Verification

After implementation:

1. Run the full build — must succeed
2. Run the full test suite — all tests must pass
3. Report the results

Error Recovery

If build or tests fail:

1. Analyze the failure output carefully — identify the root cause, not just the symptom
2. Fix the root cause
3. Re-run build and tests
4. If still failing after 3 attempts, stop and report to the user with:
   • The exact error output
   • What you tried
   • Your best hypothesis for the root cause

Delegate to the implementer agent. Run tests after — must still pass.

Prerequisites: All tests passing (green phase complete).

Process

1. Delegate to the implementer agent with refactoring instructions.
   • If lspServers in .claude/config.json has any enabled servers, tell the implementer: "Use LSP diagnostics to identify unused code during refactoring"
   • Worktree path: <worktree-path>. First Bash command: cd <worktree-path>. CWD persists — do not cd again.
2. Review all changes made in this implementation for:
   • Dead code or unnecessary abstractions — remove them
   • Duplicated logic — consolidate into shared helpers only if used 3+ times
   • Unclear names — rename for clarity
   • Complex conditionals — simplify (extract guard clauses, reduce nesting)
   • Overly clever code — replace with straightforward alternatives
3. Run the full test suite after refactoring — must still pass
4. If any test fails, revert the last refactoring step and try a different approach

Rules

• Refactoring must not change behavior — tests are the safety net
• Keep it as simple as possible — don't introduce new patterns
• Don't refactor code that wasn't touched in this implementation
• Small, incremental changes — don't refactor everything at once

Error Recovery

If tests fail after refactoring:

1. Identify which refactoring step broke the test
2. Revert that specific change
3. Try a simpler refactoring or skip that particular cleanup

These phases are independent read-only operations and MUST run in parallel.

Parallel Execution Pattern

1. Gather shared context ONCE before launching reviewers — batch all git operations into a single Bash call to minimize round-trips:

   echo "===DIFF===" && git diff && echo "===FILES===" && git diff --name-only && echo "===STAT===" && git diff --stat
   

   Parse the output by delimiter to extract: full diff (between ===DIFF=== and ===FILES===), changed file list (between ===FILES=== and ===STAT===), and diff summary stats (after ===STAT===). Also have the original ticket requirements and the approved implementation plan ready from earlier phases — do not re-fetch them. If hasPlanFile is true: Source ticket requirements from the plan file's ## Ticket Details section and the implementation plan from ## Implementation Plan.

2. Launch ALL THREE reviewers as parallel Task tool calls in a SINGLE message:

   • Task 1: security-reviewer agent — pass it the diff output, new/modified file list
   • Task 2: code-reviewer agent — pass it the diff output, ticket requirements, implementation plan
   • Task 3: silent-failure-hunter agent — pass it the diff output, new/modified file list

   All agents receive the pre-gathered diff so none need to run git diff independently.

3. Wait for all to complete, then process results by priority — security-critical findings first:

   • If the security reviewer reports any CRITICAL findings, fix those immediately before processing other review results. Critical security issues (auth bypass, injection, data exposure) take precedence over code quality or style concerns.
   • If no CRITICAL security findings, process all three reviewer outputs together (see phase details below).

Phase 6 — Security Review

Delegate to the security-reviewer agent. If Critical or High findings: fix them (delegate back to implementer), re-run tests, re-review. If fix is unclear, stop and ask the user.

Prerequisites: Tests pass, refactoring complete, shared diff context gathered.

Process

1. Receive the pre-gathered diff output and new/modified file list (do NOT run git diff again)
2. Delegate to the security-reviewer agent with the context above
3. The agent traces data flow from input to storage/output and checks for vulnerabilities
4. Process findings by severity (see Actions below)

Expected Output

The agent returns findings with severity levels (Critical/High/Medium/Low), plus a Passed Checks checklist.

Actions

• Critical or High: Fix immediately. Delegate fixes to the implementer agent. Re-run tests. Re-run security review on the fixes.
• Medium or Low: Note in the PR description as known items.
• If fix is unclear: Stop and ask the user for guidance.

Error Recovery

If the security reviewer identifies an issue but the fix is unclear:

1. Present the finding to the user with full context
2. Ask for guidance on the preferred fix approach
3. Implement the fix and re-run the security review

Phase 7 — Code Review

Delegate to the code-reviewer agent. Fix "Must Fix" issues (confidence >= 90). Note anything needing human decision.

Prerequisites: Tests pass, refactoring complete, shared diff context gathered.

Process

1. Receive the pre-gathered diff output, ticket requirements, and approved implementation plan (do NOT run git diff again)
2. Delegate to the code-reviewer agent with all context above.
   • If lspServers in .claude/config.json has any enabled servers, tell the code-reviewer: "LSP servers are active — unaddressed warnings are high-confidence findings"
3. The agent reviews using confidence scoring (0–100) and only reports issues >= 50 confidence
4. Process the results by confidence tier (see Actions below)

Expected Output

The agent returns issues with confidence scores, categorized as:

• Must Fix (confidence >= 90) — verified bugs, missing error handling, convention violations
• Should Fix (confidence 75–89) — likely issues with strong evidence
• Nitpicks (confidence 50–74) — possible concerns, style suggestions

Plus a Passing Checks checklist and Verdict (APPROVE / APPROVE_WITH_SUGGESTIONS / REQUEST_CHANGES).

Actions

• Must Fix (>= 90): Fix all issues. Re-run tests after fixes.
• Should Fix (75–89): Fix if straightforward. Note in PR description if deferred.
• Nitpicks (50–74): Ignore unless trivial to address.
• Needs human decision: Stop and ask the user.

Error Recovery

If the reviewer returns REQUEST_CHANGES:

1. Delegate fixes to the implementer agent
2. Re-run tests to verify fixes don't break anything
3. Re-run code review on the fixed code
4. If the same issue persists after 2 fix attempts, escalate to the user

Silent Failure Review

Delegate to the silent-failure-hunter agent. This runs in parallel with the security and code reviewers.

Process

1. Receive the pre-gathered diff output and new/modified file list
2. The agent scans for silent failure patterns: empty catch blocks, swallowed errors, missing error propagation, silent fallbacks
3. Findings are merged with the code review results

Actions

• Critical (error swallowed in auth/payment/data-loss paths): Fix immediately
• Warning (empty catch, silent fallback in non-critical paths): Fix if straightforward, note in PR description if deferred
• Info (intentional suppression with comment): No action needed

Skip entirely if no self-corrections occurred and no doc updates are warranted.

Prerequisites: Code review and security review complete, all fixes applied.

Step 8A: Capture Lessons

Delegate to the lessons-collector agent. Skip if no self-corrections occurred during the session.

1. Review the conversation/session for self-corrections:
   • Build errors that required fixes
   • Wrong APIs or patterns used then corrected
   • Test failures with non-obvious causes
   • Incorrect assumptions that led to rework
2. If self-corrections occurred, delegate to the lessons-collector agent
3. The agent appends entries to .claude/rules/lessons-learned.md in the target project

Skip Step 8A if no self-corrections occurred during the session.

Quality Criteria for Lessons

Each lesson must be:

• Specific — "Used findOne instead of findUnique in Prisma" not "Made a mistake"
• Actionable — includes a clear rule to prevent recurrence
• Non-duplicate — check existing entries before adding

Error Recovery

If .claude/rules/lessons-learned.md doesn't exist, create it with a header. If it exceeds 100 entries, suggest consolidating related entries into permanent rules in .claude/rules/<topic>.md.

Step 8B: Update CLAUDE.md (if warranted)

Update when:

• A new architectural pattern was established that future work must follow
• A new integration point or external dependency was introduced with specific usage rules
• A convention was discovered that prevents mistakes if documented at project level

Do NOT update for:

• Routine features following existing patterns
• Lessons already captured in lessons-learned.md
• Implementation details specific to one feature

Process:

1. Read claudeMdLocation from .claude/config.json (default: .claude/CLAUDE.md)
2. Read current CLAUDE.md content
3. Append new rules under ## Critical Rules as bullet points
4. Do not remove or rewrite existing content — only append

Step 8C: Update README.md (if warranted)

Update when:

• New command, API endpoint, or user-visible feature was added
• Configuration options changed
• Setup/installation steps changed
• New prerequisites or dependencies were introduced

Do NOT update for:

• Internal refactoring, bug fixes, test-only changes
• Changes with no user-facing impact

Process:

1. Read README.md at project root
2. Add documentation matching existing style/structure
3. Keep changes minimal

Rebase on latest main, then handle commit, push, and PR creation.

Prerequisites: Code review complete, all Must Fix items resolved, tests pass. Network access required for git fetch.

If hasPlanFile is true: Source ticketId, slug, isChild, isLastChild, and parentId from the plan file's front matter for commit messages, branch names, and PR body references.

Step 1: Rebase on Latest Main (main-agent-only — requires auth)

Fetch and rebase onto the latest main branch to catch conflicts before creating the PR:

git fetch origin main
git rebase origin/main

If rebase succeeds: Re-run the full build and test suite to verify nothing broke.

• If tests pass → proceed to Step 2 (Commit).
• If tests fail → stop the pipeline and report the failures to the user. The rebase introduced incompatibilities that need manual resolution.

If rebase fails (conflicts): Abort the rebase, stop the pipeline, and report to the user:

git rebase --abort

Report the conflicting files and provide manual resolution steps:

1. Run git rebase origin/main manually
2. Resolve conflicts in the listed files
3. git rebase --continue
4. Re-run build and tests
5. Resume the pipeline from Step 2

Step 2: Commit

Stage and commit all changes with conventional commit format:

git add -A
git commit -m "<type>(<scope>): <description>

<body if needed>

<ticket-ref>"

If ticket mode: Include a ticket reference in the commit message: #<id> or Fixes #<id>.

If isLastChild is true, add a second ticket reference line for the parent:

Fixes #<childId>
Fixes #<parentId>

This causes the PR to auto-close both the child and parent on merge. If not last child, just Fixes #<childId> (unchanged).

If ticketless mode: Use a conventional commit with no ticket reference. Omit the <ticket-ref> line.

Step 3: Push

Try to push the branch:

• If ticket mode:

  git push -u origin feature/<ticket-id>-<description>
  

• If ticketless mode:

  git push -u origin feature/<auto-slug>
  

If the push fails (e.g., sandbox network restriction, SSH remote), do the following:

1. Display the exact push command to the user
2. Explain that the sandbox may be blocking the push (SSH remotes don't work with sandbox network filtering — HTTPS remotes are recommended)
3. Ask the user to run the push command manually outside Claude Code
4. Wait for user confirmation that the push succeeded before proceeding to PR creation

Step 4: Create PR

Create the PR using gh pr create.

PR body template

Write the body to a temp file first, then read it back. Do not put the body inline as a single string or use heredocs (they fail in the sandbox).

If ticket mode, include the ## Ticket section in the PR body:

• If isLastChild is true: The Ticket section should contain both child and parent references:

  Fixes #<childId>
  Fixes #<parentId> (parent — all children complete)
  

• If isChild but NOT isLastChild: The Ticket section should contain:

  Fixes #<childId>
  Related to #<parentId> (parent — N siblings still open)
  

  (Use Related to instead of Fixes so the parent is NOT auto-closed.)
• If not a child ticket: Use the standard Fixes #<id> reference.

printf '%s' '## Summary
<1-2 sentences describing the change>

## Ticket
<ticket references as described above>

## Changes
- <change 1>
- <change 2>
- <change 3>

## Testing
<how it was tested — what tests were written, what was verified>

## Checklist
- [x] Tests pass
- [x] Security review done
- [ ] Documentation updated

## Notes
<any Medium/Low security findings or Should Fix items, or "None">' > /tmp/claude/pr-body.md
BODY=$(cat /tmp/claude/pr-body.md)
gh pr create --title "<type>(<scope>): <description>" --body "$BODY"

If ticketless mode, omit the ## Ticket section from the PR body. The template becomes:

printf '%s' '## Summary
<1-2 sentences describing the change>

## Changes
- <change 1>
- <change 2>
- <change 3>

## Testing
<how it was tested — what tests were written, what was verified>

## Checklist
- [x] Tests pass
- [x] Security review done
- [ ] Documentation updated

## Notes
<any Medium/Low security findings or Should Fix items, or "None">' > /tmp/claude/pr-body.md
BODY=$(cat /tmp/claude/pr-body.md)
gh pr create --title "<type>(<scope>): <description>" --body "$BODY"

Step 5: Label Ticket

If ticketless mode: Skip Step 5.

If ticket mode: After PR creation, replace the "Working" label with "Implemented" on the ticket:

gh issue edit <number> --repo <owner>/<repo> --add-label "Implemented" --remove-label "Working"

If isLastChild is true, also label the parent ticket as "Implemented":

gh issue edit <parentId> --repo <owner>/<repo> --add-label "Implemented"

(GitHub auto-closes the parent via Fixes #<parentId> in the PR body on merge.)

Error Recovery

• Rebase conflicts: Abort the rebase (git rebase --abort), report conflicting files, provide manual resolution steps, stop the pipeline
• Post-rebase test failure: Tests passed before rebase but fail after — report failures to the user. The rebase introduced incompatibilities that need manual resolution
• Push fails: Display the push command, explain sandbox limitations, ask user to push manually
• PR creation fails: Check if the branch exists on remote, verify gh auth status, retry once

Step 6: Plan File Cleanup

If hasPlanFile is true: After successful PR creation (Step 4 completes), delete the consumed plan file:

rm .claude/plans/<plan-filename>.md

If the .claude/plans/ directory is now empty, remove it too:

rmdir .claude/plans/ 2>/dev/null

This prevents stale plan files from accumulating. If the pipeline fails before PR creation, the plan file is preserved so the user can retry.