Skip to main content
The task implementer is the final stage in the SDD pipeline, responsible for implementing code from task documents one task at a time, following test-first development, creating atomic commits, and verifying implementation against acceptance criteria.

​
Purpose

This skill helps you:
  • Implement code from task documents (task/TASK-FASE-{N}.md) one task at a time
  • Follow test-first development: write failing tests, then implementation, then verify
  • Create atomic commits with conventional commit messages from task definitions
  • Track progress by marking completed tasks in task documents
  • Verify implementation satisfies acceptance criteria before committing
  • Enforce spec traceability — every code artifact traces to UC, ADR, INV, REQ
  • Pause on blockers, ambiguities, or design issues instead of guessing

​
When to use

Use this skill when:
  • Task documents exist in task/TASK-FASE-{N}.md (generated by task-generator)
  • You want to implement a specific FASE or specific task(s)
  • You want to resume implementation from the last incomplete task
  • You want to verify that existing implementation matches task acceptance criteria

​
Core principles

​
Spec-driven construction

Implement exactly what the spec says. Each line of code is traceable to UC, ADR, INV, or REQ. 
WRONG: "Implement this feature as I think it should work"
WRONG: "Add this extra field that might be useful"
RIGHT: "Implement exactly what UC-005 main flow step 3 says"
RIGHT: "Follow API-matching.md response schema precisely"

​
One task = one commit

WRONG: Implement 3 tasks in one commit "implement matching"
WRONG: Leave uncommitted changes between tasks
RIGHT: Task TASK-F0-001 → implementation → tests green → atomic commit
RIGHT: Commit message exact from **Commit** field of task
RIGHT: Only files listed in task are modified

​
Test-first construction (TDD)

WRONG: Write implementation and then tests
WRONG: Write tests that always pass
RIGHT: Write test → verify it FAILS → implement → verify it PASSES
RIGHT: Tests cover each acceptance criterion of the task

​
Pause on ambiguity

WRONG: "Not sure how to handle this case, I'll guess"
WRONG: Implement a solution when spec has [DECISION PENDING]
RIGHT: "PAUSE: UC-015 doesn't define behavior for frozen state"
RIGHT: "PAUSE: [DECISION PENDING] found in ADR-025 — need answer"

​
Incremental integration

WRONG: Implement all tasks of a FASE then integrate
WRONG: Not verifying build/tests between tasks
RIGHT: After each task → build → tests → commit
RIGHT: After each internal phase → checkpoint tag

​
Defensive construction

WRONG: Trust external inputs without validation
WRONG: Ignore error handling "I'll do it later"
RIGHT: Validate inputs at system boundaries
RIGHT: Error handling at each point defined by UC exception flows
RIGHT: Logging that follows ADR without exposing sensitive data

​
Execution phases

1

Context loading and inventory

Load all necessary context:
  • Read CLAUDE.md for tech stack, conventions, structure
  • Read spec/domain/01-GLOSSARY.md for ubiquitous language
  • Read domain model: entities, value objects, states, invariants
  • Read FASE file: plan/fases/FASE-{N}-*.md
  • Read plan: plan/PLAN-FASE-{N}.md
  • Read task document: task/TASK-FASE-{N}.md
  • Identify all specs referenced in Refs fields of tasks
  • Build context map: which UCs, ADRs, INVs, REQs apply
2

Readiness gates

Verify prerequisites:
  • Task document exists
  • Plan artifact exists
  • FASE file exists
  • Glossary exists
  • All referenced specs exist
  • Git working tree is clean
  • Previous FASE tasks complete (if FASE > 0)
  • Tech stack tools available
3

Task selection and ordering

Parse task document extracting all tasks. Identify completed ([x]) and pending ([ ]) tasks. Read dependencies from task document. Build execution order respecting dependencies, internal phases, and [P] markers.
4

Pre-implementation design

For each task, before writing code:
  • Read specs referenced in Refs field
  • Extract contracts (request/response schemas, event schemas)
  • Identify applicable invariants (INV-*)
  • Review state machines if task touches stateful entity
  • Analyze integration with previous and subsequent tasks
  • Detect ambiguities (if spec has [DECISION PENDING] → PAUSE)
  • Plan structure: which files to create/modify, imports, dependencies
5

Test-first construction

For each task with testable component:
  • Create test file in correct location
  • Write tests for each acceptance criterion
  • Write tests for exception flows from referenced UCs
  • Write tests for applicable invariants
  • Execute tests → verify they FAIL (RED phase)
  • If tests pass without implementation → tests are wrong → fix
6

Implementation

Write the minimal solution that satisfies acceptance criteria:
  • Follow contracts exactly: schemas, types, routes, HTTP methods
  • Apply invariants as validations in code
  • Handle errors according to UC exception flows
  • Use ubiquitous language from glossary in names
  • Execute tests → verify they PASS (GREEN phase)
  • Refactor if necessary keeping tests green (REFACTOR phase)
Construction rules:
  • Minimize complexity: simple, readable code
  • Construct for verification: facilitate testing and debugging
  • Reuse assets: use frameworks, libraries, patterns from plan
  • Apply standards: follow project coding standards
  • Defensive programming: validate inputs at system boundaries
7

Quality verification

Execute review checklist from task before committing:
  • Run review checklist from Review field
  • Execute complete test suite (not just this task’s tests)
  • Verify build — project compiles without errors
  • Verify lint/format — no relevant warnings
  • Cross-check against spec — implementation meets each acceptance criterion
8

Atomic commit and SHA capture

Create atomic commit with exact message from task:
  • Stage only task files — never git add -A
  • Use message from Commit field verbatim
  • Add footer with Refs and Task ID
  • Verify commit contains exactly expected files
  • Capture SHA: git rev-parse --short HEAD
  • Store mapping: TASK-F- →
  • Mark task as complete in task/TASK-FASE-{N}.md: - [ ] → - [x]
9

Progress tracking and task loop

Update progress and continue:
  • Update checkbox in task document
  • Report progress to user (include SHA)
  • Evaluate next task:
    • If pending tasks with complete dependencies → continue
    • If blocked tasks → report missing dependencies
    • If all internal phase tasks complete → place checkpoint
    • If all FASE tasks complete → go to FASE checkpoint
  • Loop: return to pre-implementation design for next task
10

FASE checkpoint and verification

Verify complete FASE meets success criteria:
  • Create rollback checkpoint tag: git tag -a fase-{N}-verified
  • Verify success criteria from FASE file
  • Execute complete test suite
  • Verify coverage per-file (if plan includes Coverage Map)
  • Report completion with commit log

​
What this stage produces

The task implementer generates:
  • Implementation code in src/ directory following project structure
  • Test code in tests/ directory (unit, integration, BDD)
  • Updated task documents with checkboxes marked [x] for completed tasks
  • Git commits — one atomic commit per task with conventional commit message
  • Git tags — checkpoint tags for each internal phase and complete FASE
  • Implementation feedback (optional) at feedback/IMPL-FEEDBACK-FASE-{N}.md for spec-level issues found during implementation
  • Implementation session report summarizing progress, commits, pauses, and next steps

​
Implementation feedback protocol

When a pause condition reveals a spec-level issue (ambiguity, conflict, missing behavior, incorrect contract), the implementer generates a feedback file:

​
Feedback file: feedback/IMPL-FEEDBACK-FASE-{N}.md

One file per FASE, appended as issues are discovered: 
### IF-{FASE}-{SEQ}: {Short Title}

| Field              | Value |
|--------------------|-------|
| **ID**             | IF-{FASE}-{SEQ} |
| **Severity**       | BLOCKER | WARNING |
| **Task**           | TASK-F{N}-{SEQ} |
| **Affected Specs** | {comma-separated spec file paths} |
| **Category**       | AMBIGUITY | CONFLICT | MISSING-BEHAVIOR | INCORRECT-CONTRACT | STALE-DECISION |
| **Status**         | OPEN | RESOLVED | WONT-FIX |

**Problem:**
> {Detailed description of what the implementer found}

**Evidence:**
> {Code context, test failure, or concrete example showing the issue}

**Suggested Resolution:**
> {Implementer's recommendation}

**Workaround (if WARNING):**
> {How the implementer proceeded despite the issue, or "N/A — BLOCKER"}

​
Feedback workflow

  1. On PAUSE, evaluate if issue is spec-level or implementation-level
  2. If spec-level, append entry to feedback file
  3. If BLOCKER, mark task as [!] (blocked) and skip to next non-dependent task
  4. If WARNING, document workaround, proceed with implementation, flag for later reconciliation
  5. Continue implementing non-blocked tasks while feedback is pending
  6. At session end, include feedback summary in implementation session report
  7. User runs req-change --file feedback/IMPL-FEEDBACK-FASE-{N}.md to process spec corrections

​
Real example

Task execution: 
Task: TASK-F0-003 — Create auth middleware

1. Context: Read UC-002, ADR-003, INV-SYS-001, INV-SYS-003
2. Design: JWT validation → extract user_id, org_id, role → enforce tenant isolation
3. Test-first: Write tests/middleware/auth.test.ts
   - Test: should extract user context from valid JWT → FAIL
   - Test: should return 401 when token is missing → FAIL
   - Test: should return 401 when token is expired → FAIL
   - Test: should enforce tenant isolation (INV-SYS-001) → FAIL
4. Implementation: Write src/middleware/auth.ts
   - Validate JWT using jose library (ADR-003)
   - Extract claims: user_id, org_id, role
   - Attach to request context
   - Return 401 if invalid/missing/expired
5. Verify: Run tests → ALL PASS
6. Review checklist:
   [x] Token validation follows ADR-003
   [x] 401 response includes WWW-Authenticate header
   [x] Tenant isolation maintained (INV-SYS-001)
   [x] No PII in logs
7. Commit:
   git add src/middleware/auth.ts tests/middleware/auth.test.ts
   git commit -m "feat(auth): add JWT authentication middleware
   
   Implement token validation, user context extraction,
   and tenant isolation enforcement.
   
   Refs: FASE-0, UC-002, ADR-003, INV-SYS-001, INV-SYS-003
   Task: TASK-F0-003
   Co-Authored-By: Claude Opus 4.6 <[email protected]>"
8. Capture SHA: abc1234
9. Mark complete: TASK-F0-003 [x] → commit abc1234
10. Next: TASK-F0-004 (parallel with F0-003, can execute concurrently)

​
Pipeline integration

This skill is Step 6 (final) of the SDD pipeline: 
task-generator → task/
        ↓
task-implementer → src/, tests/ (THIS SKILL)
Input: task/TASK-FASE-{N}.md, plan/PLAN-FASE-{N}.md, plan/fases/FASE-{N}-*.md, all specs referenced in task Refs fields Output: Implementation code in src/, test code in tests/, updated task documents with [x] checkboxes, atomic git commits, checkpoint tags, optional feedback files Final step: System is implemented incrementally, FASE by FASE, with each commit traceable to specifications

Build docs developers (and LLMs) love

Get started for freeTalk to us