# Noelserdna Claude Plugin Sdd Task Implementer

> SDD Task Implementer Skill

- Skill: `tomevault-io/noelserdna-claude-plugin-sdd-task-implementer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/noelserdna-claude-plugin-sdd-task-implementer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/noelserdna-claude-plugin-sdd-task-implementer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/noelserdna-claude-plugin-sdd-task-implementer

---


# SDD Task Implementer Skill

> **Principio:** El codigo es un artefacto derivado de las especificaciones — cada linea debe ser trazable a un requisito, cada commit debe ser atomico y reversible.
> La implementacion no inventa: traduce contratos, invariantes y criterios de aceptacion en codigo verificable.

## Purpose

- 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 as `[x]` 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 This Skill

- Task documents exist in `task/TASK-FASE-{N}.md` (generated by `sdd-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

## When NOT to Use This Skill

- To create specs → use `sdd-specifications-engineer`
- To audit specs → use `sdd-spec-auditor`
- To fix spec defects → use `sdd-spec-auditor` (Mode Fix)
- To generate FASE files + plans → use `sdd-plan-architect`
- To generate task documents → use `sdd-task-generator`
- To modify requirements → use `sdd-req-change`
- To audit security → use `sdd-security-auditor`

## Relationship to Other Skills

| Skill | Phase | Relationship |
|-------|-------|-------------|
| `sdd-specifications-engineer` | Creation | **Foundation**: specs are the source of truth |
| `sdd-spec-auditor` | Quality | **Prerequisite**: specs should be audit-clean |
| `sdd-spec-auditor` (Mode Fix) | Correction | **Prerequisite**: audit findings resolved |
| `sdd-plan-architect` | Phases + Planning | **Prerequisite**: FASE files + plan/ artifacts must exist |
| `sdd-task-generator` | Tasks | **Prerequisite**: task/ documents must exist |
| **`sdd-task-implementer`** | **Implementation** | **THIS SKILL**: produces code from tasks |
| `sdd-requirements-engineer` | Requirements | **Lateral/Opcional**: retrofit REQs |
| `sdd-req-change` | Changes | **Lateral/Opcional**: cambios post-facto |
| `sdd-security-auditor` | Security | **Lateral/Opcional**: auditoria de seguridad |

### Pipeline Position

```
Requisitos → sdd-specifications-engineer → sdd-spec-auditor (fix) →
                                                        ↓
                                                 sdd-plan-architect
                                                        ↓
                                                sdd-task-generator
                                                        ↓
                                               sdd-task-implementer ← YOU ARE HERE

Herramientas laterales (opcionales):
  sdd-requirements-engineer        ← retrofit: derivar REQs cuando se empezo por specs
  sdd-req-change        ← gestionar cambios de requisitos post-facto
  sdd-security-auditor  ← auditoria de seguridad complementaria
```

> SWEBOK v4 alignment:
> - Ch04 §1: Software Construction Fundamentals (minimize complexity, construct for verification)
> - Ch04 §2: Managing Construction (planning, dependencies)
> - Ch04 §3: Practical Considerations (coding, testing, quality, integration)
> - Ch04 §4.4: Assertions, Design by Contract, Defensive Programming
> - Ch04 §4.16: Test-First Programming (TDD)
> - Ch04 §4.17: Feedback Loop for Construction
> - Ch03 §1.4: Software Design Principles (abstraction, SoC, coupling, cohesion)
> - Ch12 §1: Software Quality Fundamentals (error → defect → failure chain)

---

## Core Principles

### 1. Spec-Driven Construction

```
WRONG: "Voy a implementar esta feature como creo que deberia funcionar"
WRONG: "Agrego este campo extra que podria ser util"
WRONG: Implementar comportamiento no documentado en specs

RIGHT: "Implemento exactamente lo que dice UC-005 flujo principal paso 3"
RIGHT: "El contrato API-matching.md define el response schema — lo sigo al pie"
RIGHT: Cada linea de codigo trazable a UC, ADR, INV o REQ
```

### 2. One Task = One Commit

```
WRONG: Implementar 3 tasks en un solo commit "implement matching"
WRONG: Dejar cambios uncommitted entre tasks
WRONG: Commits que tocan archivos no mencionados en la task

RIGHT: Task TASK-F0-001 → implementacion → tests verdes → commit atomico
RIGHT: Commit message exacto del campo **Commit** de la task
RIGHT: Solo los archivos listados en la task se modifican
```

### 3. Test-First Construction (TDD)

```
WRONG: Escribir implementacion y luego los tests
WRONG: Escribir tests que siempre pasan (test sin assertions reales)
WRONG: Saltarse los tests "porque es solo configuracion"

RIGHT: Escribir test → verificar que FALLA → implementar → verificar que PASA
RIGHT: Tests cubren cada criterio de aceptacion de la task
RIGHT: Tests de config verifican que la configuracion es correcta y funcional
```

### 4. Pause on Ambiguity

```
WRONG: "No estoy seguro de como manejar este caso, voy a adivinar"
WRONG: Implementar una solucion cuando el spec tiene un [DECISION PENDIENTE]
WRONG: Ignorar contradicciones entre spec y plan

RIGHT: "PAUSE: El spec UC-015 no define el comportamiento para estado frozen"
RIGHT: "PAUSE: [DECISION PENDIENTE] encontrada en ADR-025 — necesito respuesta"
RIGHT: "PAUSE: plan/PLAN-FASE-3.md contradice spec/contracts/API-matching.md en..."
```

### 5. Incremental Integration

```
WRONG: Implementar todas las tasks de un FASE y luego integrar
WRONG: No verificar build/tests entre tasks
WRONG: Saltarse rollback checkpoints

RIGHT: Despues de cada task → build → tests → commit
RIGHT: Despues de cada phase interna → checkpoint tag
RIGHT: Integracion incremental: cada commit deja el sistema en estado funcional
```

### 6. Defensive Construction

```
WRONG: Confiar en inputs externos sin validacion
WRONG: Ignorar manejo de errores "ya lo hare despues"
WRONG: Log que expone PII o credenciales

RIGHT: Validar inputs en fronteras del sistema (SWEBOK v4 Ch03, Practical Considerations)
RIGHT: Error handling en cada punto definido por UC exception flows
RIGHT: Logging que sigue el ADR de error-handling sin exponer datos sensibles
```

---

## Invocation

### Mode 1: Per-FASE (default)

```
/sdd-task-implementer --fase 0
```

Implementa todas las tasks de FASE-0 en orden, respetando dependencias y marcadores [P].

### Mode 2: Single Task

```
/sdd-task-implementer --task TASK-F0-005
```

Implementa una task especifica. Verifica que sus dependencias esten completas.

### Mode 3: Continue

```
/sdd-task-implementer --continue
```

Resume desde la ultima task incompleta del FASE activo. Detecta el punto de continuacion leyendo los marcadores `[x]` en task documents.

### Mode 4: Verify

```
/sdd-task-implementer --verify --fase 0
```

Solo lectura. Verifica que la implementacion existente cumple los criterios de aceptacion de las tasks sin escribir codigo.

### Mode 5: Checkpoint

```
/sdd-task-implementer --checkpoint --fase 0
```

Crea un rollback checkpoint tag en el punto actual sin implementar mas tasks.

### Mode 6: New Tasks Only (Cascade)

```
/sdd-task-implementer --fase 1 --new-tasks-only
```

Implementa unicamente las tasks generadas por un cascade de `sdd-req-change`.

- Cuando se proporciona `--new-tasks-only`, solo se implementan tasks que contengan el marcador `Source: CASCADE-{id}` en su definicion.
- Las tasks ya marcadas como completadas (`[x]`) se omiten automaticamente.
- Se sigue el mismo proceso test-first y commit atomico de los modos normales (Phases 3-8).
- Este modo es invocado tipicamente por `sdd-req-change` Phase 9 (Pipeline Cascade) cuando se ejecuta con `--cascade=auto`. El flujo completo es: `sdd-req-change` detecta cambios → genera nuevas tasks con marcador CASCADE → invoca `sdd-task-implementer --fase {N} --new-tasks-only` para implementarlas.

---

## Output Artifacts

```
src/                          ← Codigo de implementacion (estructura segun plan/)
tests/                        ← Tests unitarios, integracion, BDD
task/TASK-FASE-{N}.md         ← Checkboxes actualizados [x]
feedback/IMPL-FEEDBACK-FASE-{N}.md  ← Feedback de issues spec-level (para sdd-req-change)
```

### What This Skill Modifies

| Artifact | Action | Notes |
|----------|--------|-------|
| `src/**/*` | CREATE/MODIFY | Codigo de implementacion |
| `tests/**/*` | CREATE/MODIFY | Tests unitarios e integracion |
| `task/TASK-FASE-{N}.md` | MODIFY (checkboxes only) | `- [ ]` → `- [x]` — included in same atomic commit |
| `feedback/IMPL-FEEDBACK-FASE-{N}.md` | CREATE/APPEND | Spec-level issues found during implementation |
| Git tags | CREATE | Rollback checkpoint tags |
| Git commits | CREATE | Un commit atomico por task |

### What This Skill NEVER Modifies

- `spec/` — cualquier archivo
- `plan/` — cualquier archivo
- `task/TASK-INDEX.md` — indice global
- `task/TASK-ORDER.md` — grafo de dependencias
- `audits/` — informes de auditoria
- `.env`, credenciales, secretos

---

## Execution Phases

### Phase 0: Context Loading & Inventory

**Goal:** Cargar todo el contexto necesario para implementar con precision.

1. Leer `CLAUDE.md` del proyecto para tech stack, convenciones, estructura
2. Leer `spec/domain/01-GLOSSARY.md` para lenguaje ubicuo
3. Leer `spec/domain/02-ENTITIES.md` y `03-VALUE-OBJECTS.md` para modelo de dominio
4. Leer `spec/domain/04-STATES.md` para maquinas de estado
5. Leer `spec/domain/05-INVARIANTS.md` para invariantes aplicables
6. Leer el FASE file correspondiente: `plan/fases/FASE-{N}-*.md`
7. Leer el plan correspondiente: `plan/PLAN-FASE-{N}.md`
8. Leer el task document: `task/TASK-FASE-{N}.md`
9. Identificar todas las specs referenciadas en los campos **Refs** de las tasks
10. Construir el mapa de contexto: que UCs, ADRs, INVs, REQs aplican

**Context Map Output:**

```
FASE-0 Context Map:
├── UCs: UC-001, UC-002, UC-003
├── ADRs: ADR-001 (tech stack), ADR-002 (encryption), ADR-025 (rate limiting)
├── INVs: INV-SYS-001 (multi-tenant), INV-SYS-003 (auth required)
├── REQs: REQ-BOOT-001, REQ-BOOT-002, REQ-BOOT-003
├── Entities: User, Organization, ApiKey
├── VOs: Email, HashedPassword, Role
└── States: UserState (active, suspended, deleted)
```

### Phase 1: Readiness Gates

**Goal:** Verificar que todos los prerequisitos estan listos.

| Gate | Condition | Action if Failed |
|------|-----------|-----------------|
| G-01 | Task document `task/TASK-FASE-{N}.md` exists | HALT: run `sdd-task-generator` |
| G-02 | Plan artifact `plan/PLAN-FASE-{N}.md` exists | HALT: run `sdd-plan-architect` |
| G-03 | FASE file `plan/fases/FASE-{N}-*.md` exists | HALT: run `sdd-plan-architect` |
| G-04 | Glossary `spec/domain/01-GLOSSARY.md` exists | WARN: proceed with caution |
| G-05 | All referenced specs in Refs fields exist | HALT: missing spec files |
| G-06 | Git working tree is clean | WARN: recommend committing pending changes |
| G-07 | Previous FASE tasks complete (if FASE > 0) | WARN: unfinished dependencies |
| G-08 | Tech stack tools available (compiler, test runner) | HALT: install required tools |

### Phase 2: Task Selection & Ordering

**Goal:** Determinar que tasks implementar y en que orden.

1. Parsear `task/TASK-FASE-{N}.md` extrayendo todas las tasks
2. Identificar tasks ya completas (`[x]`) y pendientes (`[ ]`)
3. Leer dependencias del grafo en la seccion Dependencies del task document
4. Construir orden de ejecucion respetando:
   - Dependencias explicitas (task A bloquea task B)
   - Orden de phases internas (Setup → Foundation → Domain → Contracts → Integration → Tests → Verification)
   - Marcadores `[P]` para tasks paralelizables
5. Si mode es `--task TASK-F{N}-{SEQ}`, verificar que dependencias estan completas
6. Si mode es `--continue`, encontrar primera task pendiente cuyas dependencias esten completas

**Output:**

```
Execution Plan:
Phase 1 (Setup):
  → TASK-F0-001 [PENDING] Configure wrangler.toml
  → TASK-F0-002 [PENDING] Initialize TypeScript project

Phase 2 (Foundation):
  → TASK-F0-003 [P] [PENDING] Create auth middleware
  → TASK-F0-004 [P] [PENDING] Create rate limiting middleware
  → TASK-F0-005 [PENDING] Create health endpoint (depends on F0-003, F0-004)
```

### Phase 3: Pre-Implementation Design

**Goal:** Entender el diseno detallado antes de escribir codigo. (SWEBOK §4.3.1)

Para cada task, antes de escribir codigo:

0. **Write breadcrumb**: Create `.sdd/current-task.json` with `{ "taskId": "{TASK-ID}", "fase": {N}, "refs": [{refs from task}], "startedAt": "{ISO-8601}" }` — this enables the trace-map hook (H9) to auto-capture file→task mappings during implementation.
1. **Leer specs referenciadas**: Abrir cada UC, ADR, contrato mencionado en **Refs**
2. **Extraer contratos de entrada/salida**: Request/response schemas, event schemas
3. **Identificar invariantes aplicables**: Que INV-* deben cumplirse en este codigo
4. **Revisar maquinas de estado**: Si la task toca una entidad con estados, leer 04-STATES.md
5. **Analizar integracion**: Como se conecta esta task con las anteriores y posteriores
6. **Detectar ambiguedades**: Si el spec tiene `[DECISION PENDIENTE]` o vaguedad → PAUSE
7. **Planificar la estructura**: Que archivos crear/modificar, que imports, que dependencias

**Design Notes Format (mental, not a file):**

```
TASK-F0-003: Create auth middleware
├── Input: JWT token in Authorization header (ADR-003)
├── Output: Authenticated context with user_id, org_id, role
├── Invariants: INV-SYS-001 (tenant isolation), INV-SYS-003 (auth required)
├── Error cases: UC-002 exception flow (invalid token → 401)
├── Integration: Used by ALL subsequent endpoints
├── Files: src/middleware/auth.ts, tests/middleware/auth.test.ts
└── State machines: N/A
```

### Phase 4: Test-First Construction

**Goal:** Escribir tests que FALLAN antes de la implementacion. (SWEBOK §4.4.16)

Para cada task que tiene componente testeable:

1. **Crear archivo de test** en la ubicacion correcta segun plan/
2. **Escribir tests para cada criterio de aceptacion** del campo **Acceptance**
3. **Escribir tests para exception flows** de los UCs referenciados
4. **Escribir tests para invariantes** que aplican (INV-*)
5. **Ejecutar tests** → Verificar que FALLAN (RED phase)
6. Si tests pasan sin implementacion → los tests estan mal escritos → corregir

**Test Naming Convention:**

```typescript
describe('AuthMiddleware', () => {
  it('should extract user context from valid JWT', () => { ... });
  it('should return 401 when token is missing', () => { ... });
  it('should return 401 when token is expired', () => { ... });
  it('should enforce tenant isolation (INV-SYS-001)', () => { ... });
});
```

**Tasks sin tests:** Algunas tasks (config, wrangler.toml, env setup) no requieren tests unitarios. En estos casos, Phase 4 define una **verificacion manual** en lugar de tests automatizados:

```
Verification: wrangler.toml parses correctly → `npx wrangler dev` starts without errors
```

### Phase 5: Implementation

**Goal:** Escribir el codigo que hace pasar los tests. (SWEBOK §4.3.3)

1. **Implementar la solucion minima** que satisface los criterios de aceptacion
2. **Seguir los contratos exactamente**: schemas, tipos, rutas, HTTP methods del spec
3. **Aplicar invariantes** como validaciones en el codigo
4. **Manejar errores** segun los exception flows de los UCs
5. **Usar lenguaje ubicuo** del glosario en nombres de variables, funciones, clases
6. **Ejecutar tests** → Verificar que PASAN (GREEN phase)
7. **Refactorizar** si es necesario manteniendo tests verdes (REFACTOR phase)

**Construction Rules (SWEBOK §4.1):**

- **Minimizar complejidad**: Codigo simple y legible, no clever code
- **Construir para verificacion**: Codigo que facilita testing y debugging
- **Reutilizar assets**: Usar frameworks, librerias y patrones del plan/
- **Aplicar standards**: Seguir coding standards del proyecto (linting, formatting)
- **Defensive programming**: Validar inputs en fronteras del sistema

**Coding Checklist:**

```
[ ] Nombres siguen glosario (domain/01-GLOSSARY.md)
[ ] Tipos match entity specs (domain/02-ENTITIES.md)
[ ] Validaciones match invariants (domain/05-INVARIANTS.md)
[ ] Error handling match UC exception flows
[ ] HTTP routes match contracts (contracts/*.md)
[ ] Request/Response schemas match contracts
[ ] Rate limits match ADR-025 / nfr/LIMITS.md
[ ] Auth required per INV-SYS-003
[ ] Tenant isolation per INV-SYS-001
[ ] No PII in logs
[ ] No secrets in code
```

### Phase 6: Quality Verification

**Goal:** Ejecutar el review checklist de la task antes de commitear. (SWEBOK §4.3.6)

1. **Ejecutar el Review checklist** del campo **Review** de la task
2. **Ejecutar tests completos** (no solo los de esta task, sino la suite completa)
3. **Verificar build** — el proyecto compila sin errores
4. **Verificar lint/format** — sin warnings relevantes
5. **Cross-check contra spec** — la implementacion cumple cada criterio de aceptacion

**Review Execution Protocol:**

Para cada item `- [ ]` del campo **Review** de la task:
- Verificar el item
- Si PASA → marcar mentalmente como verificado
- Si FALLA → corregir la implementacion y re-verificar
- Si NO APLICA → documentar por que

**Quality Metrics (SWEBOK §4.2.3):**

```
Task Quality Report:
├── Tests: 5/5 passing
├── Build: Clean (0 errors, 0 warnings)
├── Lint: Clean
├── Review Checklist: 7/7 verified
├── Acceptance Criteria: 3/3 satisfied
└── Invariants: INV-SYS-001 ✓, INV-SYS-003 ✓
```

### Phase 7: Atomic Commit & SHA Capture

**Goal:** Crear el commit atomico con el mensaje exacto de la task y capturar su SHA para trazabilidad.

> **IMPORTANTE — Checkbox-first:** El marcado `[x]` se realiza ANTES del commit y se incluye en el mismo commit atomico. Esto garantiza que si el contexto se desborda o la sesion se interrumpe despues del commit, el checkbox ya esta persistido. Nunca marcar el checkbox en un paso posterior al commit.

1. **Marcar la task como completa** en `task/TASK-FASE-{N}.md`: `- [ ]` → `- [x]` — ANTES de hacer commit
2. **Stage los archivos de la task + el task document** — nunca `git add -A`
3. **Usar el mensaje del campo Commit** de la task, verbatim
4. **Agregar footer** con Refs y Task ID del task document
5. **Verificar** que el commit contiene exactamente los archivos esperados + el task document actualizado
6. **Capturar SHA del commit**:
   ```bash
   COMMIT_SHA=$(git rev-parse --short HEAD)
   ```
7. **Almacenar mapping** en memoria de sesión: `TASK-F{N}-{SEQ} → {SHA}`
8. **Clear breadcrumb**: Remove `.sdd/current-task.json` (`rm -f .sdd/current-task.json`) — prevents stale task context from leaking into the next task's trace mappings.

**Commit Format:**

```
{type}({scope}): {description}

{body — optional, from task context}

Refs: {FASE-N}, {UC-XXX}, {ADR-XXX}, {INV-XXX-XXX}
Task: {TASK-ID}
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
```

**Git Commands:**

```bash
# 1. Mark task as complete BEFORE committing
# Edit task/TASK-FASE-0.md: change "- [ ] TASK-F0-003" to "- [x] TASK-F0-003"

# 2. Stage implementation files + updated task document
git add src/middleware/auth.ts tests/middleware/auth.test.ts task/TASK-FASE-0.md

# 3. Commit with exact message from task
git commit -m "$(cat <<'EOF'
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 <noreply@anthropic.com>
EOF
)"

# 4. Capture SHA for traceability
COMMIT_SHA=$(git rev-parse --short HEAD)
# Store: TASK-F0-003 → $COMMIT_SHA
```

### Phase 8: Progress Tracking & Task Loop

**Goal:** Reportar progreso y continuar con la siguiente task.

1. **Reportar progreso** al usuario (incluir SHA del commit):

```
✓ TASK-F0-003 completed (3/12 tasks, 25%) → commit abc1234
  Next: TASK-F0-004 [P] Create rate limiting middleware
  Parallel available: TASK-F0-004, TASK-F0-005 (both [P])
```

2. **Evaluar siguiente task**:
   - Si hay tasks pendientes cuyas dependencias estan completas → continuar
   - Si hay tasks bloqueadas → reportar que dependencias faltan
   - Si todas las tasks del phase interno estan completas → colocar checkpoint
   - Si todas las tasks del FASE estan completas → ir a Phase 9

3. **Loop**: Volver a Phase 3 para la siguiente task

### Phase 9: FASE Checkpoint & Verification

**Goal:** Verificar que el FASE completo cumple sus Criterios de Exito.

1. **Crear rollback checkpoint tag**:
   ```bash
   git tag -a fase-{N}-verified -m "FASE-{N} implementation complete and verified"
   ```

2. **Verificar Criterios de Exito** del FASE file (`plan/fases/FASE-{N}-*.md`):
   - Leer seccion "Criterios de Exito"
   - Para cada criterio, verificar que la implementacion lo cumple
   - Documentar evidencia para cada criterio

3. **Ejecutar suite completa de tests**

4. **Verificar coverage per-file** (si el plan incluye Coverage Map §7.4):
   ```bash
   npx vitest run --coverage
   ```
   - Para cada source file en Coverage Map §7.4, verificar que tiene coverage > 0%
   - Para cada source file con tipo `logic`/`entity`/`service`/`state-machine`, verificar coverage >= 80% lines
   - Si un archivo tiene 0% y NO esta en Exclusions → **FAIL** — crear test task pendiente
   - Si un archivo tiene <80% y es lógica de dominio → **WARN** — reportar en completion

5. **Reportar completion** (incluir commit log):

```
FASE-0 Implementation Complete
================================
Total tasks: 12
Completed: 12 (100%)
Tests: 45 passing, 0 failing
Coverage: 92% lines (threshold: 80%)
  - Files below 80%: {list or "none"}
  - Files at 0% (not excluded): {list or "none"}
Criterios de Exito: 5/5 verified
Checkpoint: git tag fase-0-verified

Commit Log:
| Task | SHA | Message | Refs |
|------|-----|---------|------|
| TASK-F0-001 | abc1234 | chore(bootstrap): configure wrangler.toml | FASE-0 |
| TASK-F0-002 | def5678 | feat(bootstrap): initialize TypeScript project | FASE-0, ADR-001 |
| TASK-F0-003 | ghi9012 | feat(auth): add JWT authentication middleware | FASE-0, UC-002, ADR-003, INV-SYS-001 |
| ... | ... | ... | ... |

Commits: 12 atomic (abc1234..xyz9012)
```

---

## Internal Phase Checkpoints

Checkpoints se crean automaticamente al completar todas las tasks de un phase interno:

| After Phase | Tag | Verification |
|------------|-----|-------------|
| Setup complete | `fase-{N}-setup` | Project builds |
| Foundation complete | `fase-{N}-foundation` | Smoke tests pass |
| Domain complete | `fase-{N}-domain` | Domain unit tests pass |
| Contracts complete | `fase-{N}-contracts` | Contract tests pass |
| Integration complete | `fase-{N}-integration` | Integration tests pass |
| Tests complete | `fase-{N}-tests` | Full test suite green |
| Verification complete | `fase-{N}-verified` | All FASE criteria met |

---

## Multi-Agent Strategy

Para tasks marcadas con `[P]` (paralelizables), se pueden lanzar agentes paralelos.

| Agent | Scope | Reads | Writes |
|-------|-------|-------|--------|
| Task-agent-A | TASK-F{N}-{X} | spec/, plan/, task/ | `src/{path-A}`, `tests/{path-A}` |
| Task-agent-B | TASK-F{N}-{Y} | spec/, plan/, task/ | `src/{path-B}`, `tests/{path-B}` |

### Parallel Execution Rules

1. Solo tasks marcadas `[P]` pueden ejecutarse en paralelo
2. Tasks paralelas NUNCA tocan los mismos archivos (garantizado por sdd-task-generator)
3. Cada agente ejecuta Phases 3-7 completas para su task
4. Cada agente marca su checkbox en Phase 7 (incluido en su commit atomico)
5. Si un agente falla, los demas continuan — el fallo se reporta al final
6. Los commits se crean secuencialmente (git no soporta commits paralelos)

### Agent Instructions Template

```
You are a TASK IMPLEMENTER agent for sdd-task-implementer.

Your task: Implement {TASK-ID} from task/TASK-FASE-{N}.md

## Context
Read these files before coding:
- task/TASK-FASE-{N}.md (find your task entry)
- plan/PLAN-FASE-{N}.md (architecture decisions)
- {list of spec files from Refs field}
- spec/domain/01-GLOSSARY.md (ubiquitous language)

## Your Task
{Full task entry from task document}

## Process
1. Read acceptance criteria
2. Write failing tests
3. Implement code to pass tests
4. Run review checklist
5. Report results (do NOT commit — main agent commits)

## Constraints
- ONLY modify files listed in task entry
- ONLY implement what acceptance criteria require
- PAUSE if you find ambiguity or [DECISION PENDIENTE]
- Use ubiquitous language from glossary
```

---

## Handling Pause Conditions

El implementer DEBE pausar y reportar al usuario en estas situaciones:

### PAUSE: Ambiguity

```
PAUSE: Ambiguity in TASK-F0-005
  Spec ref: UC-005 paso 4
  Problem: "El sistema valida el formato" — no especifica que formatos son validos
  Options:
    A) Implementar validacion basica (extension + MIME type)
    B) Implementar validacion estricta (magic bytes + content inspection)
  Recommendation: A (sufficient per RN-181 timeout constraints)
  Action needed: User decision before continuing
```

### PAUSE: Decision Pending

```
PAUSE: [DECISION PENDIENTE] found
  Location: spec/adr/ADR-025-rate-limiting.md line 45
  Content: "[DECISION PENDIENTE] Algoritmo de rate limiting: token bucket vs sliding window"
  Impact: TASK-F0-004 cannot be implemented without this decision
  Action needed: Resolve decision in spec before continuing
```

### PAUSE: Spec-Implementation Conflict

```
PAUSE: Conflict detected
  Task: TASK-F0-008
  Spec says: "POST /api/v1/extractions" (contracts/API-extraction.md)
  Plan says: "POST /api/v1/extract" (plan/PLAN-FASE-1.md)
  Action needed: Resolve conflict — spec takes precedence
```

### PAUSE: Build Failure

```
PAUSE: Build failure after TASK-F0-006
  Error: Type 'string' is not assignable to type 'Email'
  Cause: Missing value object implementation (TASK-F0-005 dependency)
  Action needed: Verify TASK-F0-005 is complete
```

### PAUSE: Test Failure Unexpected

```
PAUSE: Test regression after TASK-F0-009
  Failing test: tests/middleware/auth.test.ts:42
  Test was passing after TASK-F0-003
  Cause: TASK-F0-009 modified shared middleware chain
  Action needed: Review integration between F0-003 and F0-009
```

---

## Implementation Feedback Protocol

> **Principle:** "Code reveals specification flaws the same way testing reveals bugs" (spec-kit).
> The implementer NEVER modifies `spec/`, but it CAN generate structured feedback for `sdd-req-change` to process.

When a PAUSE condition reveals a **spec-level issue** (ambiguity, conflict, missing behavior, incorrect contract), the implementer generates a feedback file instead of only halting:

### Feedback File: `feedback/IMPL-FEEDBACK-FASE-{N}.md`

One file per FASE, appended as issues are discovered during implementation.

```markdown
# Implementation Feedback — FASE-{N}

> Generated by: sdd-task-implementer
> Date: YYYY-MM-DD
> Status: PENDING | PARTIALLY-RESOLVED | RESOLVED

## Issues

### 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 — e.g., "UC-005 should define valid formats as PDF, DOCX, TXT"}

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

---
```

### Feedback Workflow

1. **On PAUSE** — evaluate if the issue is spec-level or implementation-level
2. **If spec-level** — append entry to `feedback/IMPL-FEEDBACK-FASE-{N}.md` (create file if first issue)
3. **If BLOCKER** — mark the 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. **Resolution** — user runs `sdd-req-change --file feedback/IMPL-FEEDBACK-FASE-{N}.md` to process spec corrections

### Output Artifacts (additions)

| Artifact | Action | Notes |
|----------|--------|-------|
| `feedback/IMPL-FEEDBACK-FASE-{N}.md` | CREATE/APPEND | Spec-level issues found during implementation |

> **SWEBOK v4 §4.4.17 — Feedback Loop for Construction:**
> Implementation discoveries feed back into specifications through a formal, traceable channel.
> The implementer documents; the change manager resolves. Separation of concerns preserved.

---

## Verification Protocol (Mode: --verify)

Cuando se invoca con `--verify`, ejecuta verificacion sin escribir codigo:

### Dimension 1: Completeness

Para cada task con `[x]`:
- Verificar que los archivos listados existen
- Verificar que el commit referenciado existe en git log
- Contar tasks completas vs totales

### Dimension 2: Correctness

Para cada task completa:
- Verificar que cada criterio de aceptacion se cumple en el codigo
- Verificar que los tests existen y pasan
- Verificar que los invariantes referenciados estan implementados

### Dimension 3: Coherence

- Verificar que el codigo sigue la arquitectura del plan/
- Verificar que los naming conventions siguen el glosario
- Verificar que no hay code smells obvios (archivos >500 lineas, funciones >50 lineas)

**Verification Report:**

```
FASE-0 Verification Report
===========================
Completeness: 10/12 tasks implemented (83%)
  Missing: TASK-F0-011, TASK-F0-012

Correctness: 10/10 implemented tasks pass verification
  TASK-F0-001: 3/3 acceptance criteria ✓
  TASK-F0-002: 2/2 acceptance criteria ✓
  ...

Coherence: 2 observations
  - src/middleware/auth.ts:45 — function 32 lines (OK, under 50)
  - src/services/extraction.ts — uses "job" instead of "Extraction" (glossary violation)

Overall: 83% complete, 1 coherence issue to fix
```

---

## Revert & Recovery Strategies

### Reverting a Single Task

Lee el campo **Revert** de la task:

| Category | Action |
|----------|--------|
| `SAFE` | `git revert <sha>` — sin efectos secundarios |
| `COUPLED` | Revertir tasks acopladas en orden inverso |
| `MIGRATION` | Ejecutar down migration, luego revertir |
| `CONFIG` | Revertir, luego redeploy |

### Rollback to Checkpoint

```bash
# Rollback entire phase to last checkpoint
git revert --no-commit HEAD..fase-{N}-{phase}
git commit -m "revert: rollback to FASE-{N} {phase} checkpoint"
```

### Handling Failed Implementation

Si una task no puede implementarse:
1. Revertir los cambios parciales de esta task
2. Marcar la task con `[!]` (blocked) en el task document
3. Documentar la razon del bloqueo
4. Continuar con la siguiente task no dependiente

---

## Important Constraints

1. **SIEMPRE leer specs antes de implementar** — nunca implementar de memoria o suposicion
2. **SIEMPRE escribir tests antes de implementacion** (cuando aplica) — test-first es obligatorio
3. **SIEMPRE usar el commit message exacto** del campo **Commit** de la task
4. **SIEMPRE ejecutar el review checklist** antes de commitear
5. **NUNCA modificar archivos en spec/** — son la fuente de verdad
6. **NUNCA modificar archivos en plan/** — son artefactos derivados
7. **NUNCA commitear secretos** (.env, API keys, credenciales)
8. **NUNCA implementar features** no descritas en los criterios de aceptacion
9. **NUNCA usar `git add -A`** — stage solo archivos especificos de la task
10. **NUNCA ignorar tests fallidos** — corregir antes de continuar
11. **NUNCA saltarse pause conditions** — ambiguedad, conflictos y decisiones pendientes requieren input del usuario
12. **SIEMPRE mantener el sistema en estado funcional** despues de cada commit (SWEBOK §4.3.7)
13. **SIEMPRE usar lenguaje ubicuo** del glosario en todo el codigo

---

## Error Recovery

| Error | Cause | Recovery |
|-------|-------|---------|
| "Task document not found" | Task generator not run | Run `sdd-task-generator` |
| "Plan artifacts not found" | Plan architect not run | Run `sdd-plan-architect` |
| "Spec file not found" | Referenced spec missing | Check Refs field, verify spec exists |
| "Dependency task incomplete" | Previous task not done | Complete dependency task first |
| "Tests fail after implementation" | Bug in implementation | Debug and fix, re-run tests |
| "Build fails" | Syntax error or missing dependency | Fix compilation error |
| "Merge conflict" | Parallel task touched same file | Tasks marked [P] should not conflict — investigate |
| "Checkpoint tag exists" | Phase already checkpointed | Skip checkpoint or force with `--force` |
| "[DECISION PENDIENTE] found" | Spec has unresolved decision | Pause, ask user, resolve in spec first |
| "Git working tree dirty" | Uncommitted changes | Commit or stash pending changes |

---

## Context Loading Protocol

### What to Read (in order of priority)

| Priority | Source | Information Extracted |
|----------|--------|---------------------|
| P0 | `task/TASK-FASE-{N}.md` | Tasks, acceptance criteria, commit messages, refs |
| P1 | `plan/PLAN-FASE-{N}.md` | Architecture, file structure, dependencies |
| P2 | `plan/fases/FASE-{N}-*.md` | Criterios de Exito, specs a leer, invariantes |
| P3 | `spec/domain/01-GLOSSARY.md` | Ubiquitous language for naming |
| P4 | Spec files from Refs | Detailed behavior (UC flows, API contracts, ADR decisions) |
| P5 | `spec/domain/02-ENTITIES.md` | Entity schemas and relationships |
| P6 | `spec/domain/05-INVARIANTS.md` | Business rules to enforce |
| P7 | `spec/domain/04-STATES.md` | State machine transitions |
| P8 | `CLAUDE.md` | Tech stack, coding conventions, project structure |

### Lazy Loading

No cargar TODOS los specs de golpe. Cargar P0-P3 siempre. Cargar P4-P8 solo cuando la task los referencia.

---

## Integration with Tech Stack

Este skill NO prescribe un tech stack. Lee el stack del proyecto desde `CLAUDE.md` y `plan/ARCHITECTURE.md`.

### Stack Detection

```
IF CLAUDE.md mentions "TypeScript" AND "Cloudflare Workers":
  → Test runner: vitest
  → Build: wrangler
  → Deploy: wrangler deploy
  → DB: D1 (SQLite migrations)
  → Queue: Cloudflare Queues

IF CLAUDE.md mentions "Python":
  → Test runner: pytest
  → Build: pip/poetry
  → Deploy: varies

IF plan/ARCHITECTURE.md exists:
  → Follow its project structure exactly
```

### Common Patterns by Task Type

See `references/construction-protocol.md` for implementation patterns per task type (entity, endpoint, middleware, migration, service, test, config).

---

## Output Format: Implementation Session Report

Al finalizar una sesion de implementacion:

```markdown
## Implementation Session Report

**Date:** {YYYY-MM-DD}
**FASE:** {N}
**Tasks completed:** {list}
**Tasks remaining:** {count}

### Progress

| Task | Status | Tests | SHA | Commit Message |
|------|--------|-------|-----|----------------|
| TASK-F0-001 | ✓ Complete | 3/3 | abc1234 | chore(bootstrap): configure wrangler.toml |
| TASK-F0-002 | ✓ Complete | 5/5 | def5678 | feat(bootstrap): init TypeScript project |
| TASK-F0-003 | ⏸ Paused | 2/4 | — | — |
| TASK-F0-004 | ○ Pending | — | — | — |

### Pauses
- TASK-F0-003: [DECISION PENDIENTE] in ADR-025 line 45

### Next Steps
1. Resolve ADR-025 decision
2. Continue with TASK-F0-003
3. Then TASK-F0-004 (parallel with F0-005)

### Checkpoints
- `fase-0-setup` after TASK-F0-002
```

---

## Persist Summary

After completing a FASE or a batch of tasks, update `pipeline-state.json`:

1. Read `pipeline-state.json` from project root (create if absent with default stage structure)
2. Set `stages["task-implementer"].status` = `"done"` (or `"running"` if more FASEs remain)
3. Set `stages["task-implementer"].lastRun` = current ISO-8601
4. Set `stages["task-implementer"].summary`:
   - `artifacts`: list of key files created/modified in `src/` and `tests/` with labels (e.g., `{"file": "src/extraction/pdf-parser.ts", "label": "PDF Parser"}`)
   - `metrics`: `{ "tasks_completed": N, "tasks_remaining": N, "commits": N, "tests_passed": N, "tests_failed": N }`
   - `highlights`: top 3-5 notable observations (e.g., "FASE-0 complete: 8/8 tasks", "All 24 tests passing")
   - `nextStep`: `"Run /sdd-task-implementer --fase=N"` (next FASE) or `"Pipeline complete"` (if last FASE)
   - `generatedAt`: current ISO-8601
5. Write updated `pipeline-state.json`
6. Display summary table to user (console output)

---
> Source: [noelserdna/claude-plugin-sdd](https://github.com/noelserdna/claude-plugin-sdd) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->