implement-spec

name	implement-spec
description	Implements a feature based on a provided technical specification, ensuring build stability and strict adherence to the spec through a sub-agent code review. Creates a feature branch, commits changes, and raises a PR on completion.

Implement Spec Skill

All paths are relative to the skill's base directory provided when you load the skill.

This skill guides you through implementing a feature defined in a Technical Specification file (usually in specs/). It mandates a strict workflow of Worktree Setup -> Analysis & Planning -> Implementation -> Verification -> Code Review -> QA Validation -> PR Creation.

Workflow

0. Worktree Setup

Invoke the /setup-worktree skill to create an isolated worktree for this task. After the worktree is created, proceed to Analysis & Planning.

1a. Analysis & Planning

1. Read the Spec: Use the tool available to you for reading files to read the target technical specification artifact (e.g., specs/feature-name.md).

2. Understand Guardrails: Pay close attention to the "Goals", "Non-Goals", and "API Design" sections. These are your acceptance criteria.

3. Determine implementation approach:

   • TDD — if backend service files or utility functions are implemented. Follow TDD guide.
   • Figma-to-Code — if the spec has a Figma References section. Follow Figma-to-Code guide.

   These are not mutually exclusive — a full-stack change follows both, each for its part of the work.

1b. Task List Creation

After reading the spec, use whatever task/todo tool you have available to create todos combining skill workflow steps and feature work items. Create every todo before writing any code. They must cover both:

1. Skill workflow items: Branch Setup, Analysis & Planning, Task List Creation, Implementation (TDD gate, Figma-to-Code gate, shared deps, parallelisation), Verification, Code Review, QA Validation (if a QA test plan exists), PR Creation.
2. Feature work items: endpoints, services, models, DTOs, components, pages — drawn from the spec's API Design, Goals, and architecture sections.

2. Implementation

Parallelisation

Only frontend work is suitable for parallelisation. Backend work (services, repositories, modules) must be implemented sequentially by the main agent following the TDD workflow.

Before writing any code, read the spec and identify independent work streams — frontend components, pages, hooks that don't depend on each other at compile time.

Shared dependencies first: any file that other streams will import (DTOs, types, base components, constants) must be implemented in the main session before parallel work begins.

Once shared dependencies exist, delegate frontend streams to subagents — up to a maximum of 2. Do not always spin up 2; use as many as the work genuinely calls for. Parallelise only if there are 2+ independent frontend work streams. If unsure or the spec is small, stick with sequential implementation.

For each subagent, provide:

• The path to the spec file so it can read the full context itself
• The specific files it is responsible for
• A brief note on its role in the overall implementation (e.g. "you are implementing the dashboard page and its components")

Do not commit during subagent work. Subagents implement and return results. Review their output, apply any corrections, then commit everything together after verification.

Implementation Gate

Before moving to Step 3, confirm:

• If service files or utility functions were implemented: did I follow the TDD workflow? references/tdd.md
• If the spec has a Figma References section: did I follow the Figma-to-Code workflow? references/figma-to-code.md

3. Verification (The "Build" Check)

CRITICAL: You must ensure the application builds successfully after your changes.

1. Determine the build command: Check package.json scripts first. Look for build, type-check, or typecheck in that order. Use the first one found. Only fall back to running tsc directly if none exist.
2. Run it: Execute the command found above.
3. Fix Errors: If the build fails, you MUST fix the errors immediately. Do not proceed until the build is clean.
4. Fix Lints: For lint fixes, fix them manually — do not run npm lint --fix or similar automation. This ensures only files in the spec are touched.

4. Code Review (The "Guardrails" Check)

Before communicating completion to the user, delegate code reviews to two sub-agents in parallel — one for feature correctness, one for code quality. Using sub-agents avoids bias from the implementing agent reviewing its own work.

Pass both sub-agents the list of files changed and the spec content. They return reports. Using the combined reports, ask yourself:

1. Completeness: Did I implement every endpoint defined in "API Design"?
2. Compliance: Did I meet all "Goals"? Did I avoid all "Non-Goals"?
3. Quality: Are there any linting errors or obvious bugs?
4. Consistency: Does the code match the "Proposed Architecture"?

If you find discrepancies: Fix them now. Do not ask the user for permission to fix bugs you introduced. Once fixes are applied, send changes back to the sub-agent that flagged them — independently. Do not send correctness fixes to the code quality reviewer or vice versa. Use the same sub-agent instance, not a new one. If issues persist after this second pass, escalate to the user rather than looping further.

5. QA Validation (After Clean Code Review)

Determine which QA agents to spawn based on what the spec contains:

Spec contains	Agent to spawn	Mode
Figma References section	UI validation sub-agent	UI validation only
QA Test Plan section	Test plan execution sub-agent	Test plan execution only
Both	Both sub-agents	In parallel
Neither	—	Skip this step entirely, go to PR Creation

If neither condition is met, skip this step and proceed directly to PR Creation.

Spawning the UI validation sub-agent

Provide:

• The spec file path so it can read the Figma references (fileKey and nodeId)
• The local URL where the implemented page or component is running
• The feature-slug used during implementation (for cached Figma screenshots in /tmp/<feature-slug>/)
• The Figma frame dimensions (width × height) from the design context
• Explicit instruction: validate UI fidelity only — do not execute any test plan

Spawning the test plan execution sub-agent

Provide:

• The spec file path so it can read the QA Test Plan section in full
• The app URL (local dev server or staging)
• Any auth context needed (credentials, auth method, environment)
• Explicit instruction: execute the test plan scenarios only — do not perform UI pixel comparison

After QA agents return

Review each agent's report:

• Failures: fix the issues in code, then send the changes back to the same sub-agent instance that reported them — do not spawn a new one. Send UI validation fixes back to the UI validation sub-agent; send test plan failures back to the test plan execution sub-agent. Do not cross-send between the two.
• Once all sub-agents return a full pass, proceed to PR Creation.

If fixes require a second round of code review: only send the changed files back to the relevant code review sub-agent — not a full re-run of all agents.

---

6. PR Creation (After QA Passes)

Only once the build is clean, the code review passes, and QA validation passes (or was skipped):

1. Commit following Conventional Commits format. The type must match the branch prefix:

   git add -A
   git commit -m "<type>: <short imperative description>"
   

   Examples: feat: add contractor onboarding flow, fix: correct invoice rounding logic

2. Push branch:

   git push -u origin <branch-name>
   

3. Check if a PR already exists for this branch:

   gh pr view <branch-name> --json url -q .url
   

   • If a PR exists: skip creation. The new commit is already on the branch and the existing PR is updated. Capture the existing PR URL.
   • If no PR exists: create one using the GitHub CLI. The body must include the spec summary, a list of files changed, the code review report, and the test plan (if present in the spec):

   gh pr create \
     --base <base-branch> \
     --title "<type>(<optional scope>): <short description>" \
     --body "$(cat <<'EOF'
   ## Summary
   <Goals from the spec>
   
   ## Changes Made
   <Bullet list of files/modules touched>
   
   ## Code Review Report
   <Combined output from both code review sub-agents>
   
   ## Test Plan
   <From the spec's verification section, if present>
   EOF
   )"
   

   Examples of PR titles: feat(onboarding): add contractor onboarding flow, fix(invoice): correct invoice rounding logic, docs: update API usage guide

4. Capture the PR URL from the output.

5. Fallback: If gh CLI is not available, warn the user, skip PR creation, and provide the branch name so they can open a PR manually.

7. Completion

Only when you are confident that:

1. The code is implemented.
2. The app builds without errors.
3. The implementation matches the Spec.
4. A sub-agent has conducted a code review.
5. QA validation has passed (or was skipped because neither Figma References nor a QA Test Plan exist in the spec).
6. A PR has been raised (or the user has been notified of the branch if gh is unavailable).

Then notify the user with:

• The code review report (findings + what was fixed).
• The QA validation report (if QA ran — pass/fail per criterion, any fixes applied).
• The PR URL for them to review.
• Which base branch the PR targets.