# Sdd Lifecycle

> Spec-Driven Development lifecycle conventions — phases, artifacts, gates, task numbering, and workflow rules shared across all SDD agents. Use when running any /sdd-* command, creating tasks, or routing work through SDD phases.

- Skill: `manu-arrieta/sdd-lifecycle` (Agent Skill)
- Install (CLI): `npx skillmds@latest add manu-arrieta/sdd-lifecycle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manu-arrieta/sdd-lifecycle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Manu-Arrieta (https://skillmd.com/u/manu-arrieta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/manu-arrieta/sdd-lifecycle

---


# SDD Lifecycle — Conventions & Rules

Every agent in the AOI ecosystem follows these lifecycle rules. This skill is the single source of truth for SDD mechanics — it describes HOW the lifecycle works, not what any specific agent does.

## Task Numbering (TASK-YYYY-NNN)

Every task gets a unique ID: `TASK-{year}-{sequential}`

```
.tasks/{feature-name}/TASK-2026-001/
├── proposal.md         # Explore phase output
├── spec.md             # Specify phase output
├── design.md           # Plan phase output
├── tasks.md            # Task breakdown
├── implementation-plan.md  # Cross-agent assignment map
├── iterations/         # Implement phase artifacts
├── verify-report.md    # QA & verification output
├── archive-report.md   # Closure & documentation
└── functional-docs.md  # Generated user-facing docs
```

## Phase Gates — MANDATORY

| Gate                | From → To            | Who Approves | What Must Exist                                           |
| ------------------- | -------------------- | ------------ | --------------------------------------------------------- |
| Intent Gate         | Pre-Flight → Explore | Owner        | BIC calibrated; invariants + oracle persisted as O(1) facts |
| Proposal Gate       | Explore → Specify    | Owner        | `proposal.md` with acceptance criteria                    |
| Design Gate         | Specify → Plan     | Owner        | `spec.md` approved, no ambiguity                          |
| Implementation Gate | Plan → Implement   | Owner        | `design.md` + `tasks.md` complete                         |
| TDD Gate            | During Implement   | Agent        | RED (failing test) → GREEN (min code) → REFACTOR per task |
| UX Gate             | During Implement   | @ux-designer | UI component review before any new UI                     |
| Invariant Gate      | During Verify      | Automatic    | Every BIC `never`/`oracle` tag asserted by a test (`invariant-gate.mjs`, 0 tokens) |
| Verify Gate         | Implement → Verify | Automatic    | All tasks marked done                                     |
| Archive Gate        | Verify → Archive   | Owner        | `verify-report.md` with PASS/FAIL                         |

> **Note on Design Gate**: The Design Gate (Specify→Plan, Owner approval) is satisfied jointly with the Implementation Gate at the end of `/sdd-ff`. The Supervisor's `/sdd-ff` command bundles Specify → Plan → Tasks into a single workflow with one Owner approval checkpoint, which serves as both the Design Gate and Implementation Gate. This is a deliberate optimization, not a violation.

## Entrada al ciclo

`/sdd-frame` cuando la intención llega en lenguaje natural y hay que destilar invariantes;
`/sdd-new` cuando el requerimiento ya está acotado. Detalle en la skill `sdd-entry`.

## Handling Bugs, Adjustments & Definition Gaps

No todo problema requiere un BIC nuevo ni una tarea `/sdd-new`. El diagnóstico detallado de
los tres escenarios vive en `@triage-specialist`, que carga exactamente cuando hace falta.
Lo que se necesita en cualquier fase es saber a dónde enrutar:

### Decision Rule
- *Broken behavior against existing rules?* ➔ `@triage-specialist` (diagnosis & TDD fix).
- *Need to add or modify a business rule/invariant?* ➔ `/sdd-frame` (calibrate intent in natural language).
- *Parameter, static copy, or trivial tweak?* ➔ Direct fix with test / ICM Fact (zero overhead).

## Rules ALL Agents Must Follow

### Before Starting Any Phase

1. Recall ICM context for the phase: `icm_memory_recall(query: "pending tasks", topic: "sdd-{WORKSPACE}")`
2. Check feedback for past mistakes: `icm_feedback_search(query: "{phase}")`
3. Read the constitution: `.specify/memory/constitution.md`

### During Work

- Every 3-5 tool calls or sub-tasks → store a checkpoint in ICM
- Architecture decisions → BOTH `icm_memory_store` (episodic) AND `icm_memoir_add_concept` (graph)
- Errors encountered → `icm_feedback_record` immediately

### After Completing a Phase

- `icm_memory_store(topic: "sdd-{WORKSPACE}-{FEATURE}-TASK-YYYY-NNN", importance: "high")`
- If topic has 7+ entries → `icm_memory_consolidate(topic)` immediately

## Scaffold Mirror Rule

Any change to agents, skills, instructions, or prompts in `.github/` MUST be mirrored to `scaffold/.github/` in the same commit. The `verify-report.md` checks this automatically.

## ICM Topics Per Phase

| Phase      | Topic                              | What to Store                                         |
| ---------- | ---------------------------------- | ----------------------------------------------------- |
| Pre-Flight | —                                  | Zero-Task Footprint (efímero en diálogo socrático)    |
| Explore    | `sdd-{WS}-{FEATURE}-TASK-YYYY-NNN` | User intent, constraints, service discovery           |
| Specify   | same                               | Formal specs, acceptance criteria                     |
| Plan      | same + `{WS}-architecture`         | Design decisions, tradeoffs, component graph          |
| Implement | same                               | Progress checkpoints, error resolutions               |
| Verify    | same + `{WS}-errors-resolved`      | QA findings, spec drift, health audit                 |
| Archive   | same + `{WS}-session-summaries`    | Final decisions, what was excluded, closure rationale |