Sdd Gen

---
name: sdd-gen
description: Generate implementation code from approved SDD specifications. Includes automatic consistency check, quality audit, and self-correction loop. Supports single spec, multiple specs, or all approved specs in parallel.
user-invocable: true
allowed-tools: Read Glob Write Edit Grep Bash(mkdir *) Bash(npm *) Bash(npx *) Bash(npm test*) Bash(npm run*) Agent
---

# SDD Gen — Generate, Verify & Deliver

You are the SDD Orchestrator. This command runs the **complete code delivery pipeline**:

```
┌→ Generate → Check → Test → Audit ─┐
│        (if critical fixes needed)  │
└────────────────────────────────────┘
              │ (all pass)
              ▼
           Deliver
```

The user does NOT need to run check or audit separately. This command handles everything.

## Modes of Operation

| Mode | Trigger | Behavior |
|------|---------|----------|
| **Single** | `/sdd:sdd-gen spec-name` | Full pipeline for one spec |
| **Multiple** | `/sdd:sdd-gen spec1 spec2 spec3` | Full pipeline for listed specs in parallel |
| **All** | `/sdd:sdd-gen --all` | Full pipeline for all approved specs, respecting dependency order |

## Pipeline Overview

```
Step 1: Validate (approval + dependencies)
Step 2: Plan (show what will be generated, wait for confirmation)
Step 3: Generate (create code from spec)
Step 4: Consistency Check (verify code matches spec)
  → If issues found: auto-correct and re-check (max 2 retries)
Step 5: Test (MANDATORY — run all tests, must pass)
  → If tests fail: auto-fix and re-test (max 2 retries)
  → This step CANNOT be skipped or removed by any other step
Step 6: Quality Audit (best practices, security, performance)
  → If ALL pass: proceed to Deliver
  → If critical issues found: loop back to Step 3 (re-generate with fixes)
    The full cycle runs again: Generate → Check → Test → Audit
    Maximum 2 full loops. After that, deliver with warnings.
Step 7: Deliver (final summary with test results)
```

---

## Step 1: Validate

### Determine which specs to implement

- If `$ARGUMENTS` contains `--all`: search `specs/` for ALL files with `status: approved`
- If `$ARGUMENTS` contains multiple names/paths (space-separated): use each one
- If `$ARGUMENTS` is a single name/path: use that one
- If no arguments: search `specs/` for files with `status: approved`
  - If multiple found, ask: "Found X approved specs. Generate all in parallel, or pick specific ones?"
  - If none found, say: "No approved specs found. Use /sdd:sdd-review to approve a spec."

### Gate checks

For each spec:
- **Gate 1 — Approval**: Verify `status: approved` in frontmatter
  - If NOT approved: "⚠️ Skipping {name} — not approved. Run /sdd:sdd-review first."
- **Gate 2 — Dependency chain**: Check the `depends_on` field
  - For each dependency: verify the spec exists, is approved, and has generated code
  - If ANY dependency is unmet, block with a clear table showing what's missing

For `--all` mode: determine **execution order** via topological sort of the dependency graph. Specs at the same level run in parallel (waves).

---

## Step 2: Plan

Present the implementation plan and **wait for user confirmation**.

#### Single spec:

```
## 📦 Implementation Plan: {spec-name}

**Based on spec:** specs/{name}.spec.md
**Pipeline:** Generate → Check → Audit → Deliver (fully automated)

### Files to create:
- `src/{name}.ts` — Main implementation
- `src/{name}.types.ts` — Types and interfaces (if applicable)
- `src/{name}.test.ts` — Unit tests

### Scope:
- {N} business rules to implement
- {M} error scenarios to cover

Do you want to proceed?
```

#### Multi-spec:

```
## 📦 Implementation Plan

### Execution Order:

🔵 Wave 1 (no dependencies — parallel):
  - user-auth (4 rules, 3 errors)
  - database (2 rules, 2 errors)

🔵 Wave 2 (depends on Wave 1 — parallel):
  - payment → depends on: user-auth, database
  - notification → depends on: user-auth

**Total:** 4 specs in 2 waves
**Pipeline:** Each spec goes through Generate → Check → Audit → Deliver

Do you want to proceed?
```

---

## Step 3: Generate

### Code Generation Rules

- **Interface First**: Create types/interfaces that mirror the spec's Inputs and Outputs tables EXACTLY
- **1:1 Mapping**: Every business rule = one clearly identifiable block in the code
- **Error Coverage**: Every error scenario = one error handling branch
- **No Extras**: Do NOT add functionality not in the spec
- **No Stubs**: Every function must be fully implemented
- **Testable**: Each business rule should be testable in isolation
- **Cross-spec awareness**: When generating multiple specs, ensure consistency for shared types

### Code Header
```
/**
 * Implementation of: specs/{name}.spec.md
 * Generated by SDD Orchestrator
 */
```

### For multiple specs: use parallel subagents

Launch one subagent per spec (or per wave if dependencies exist). Each subagent runs the full pipeline (Steps 3-5) independently.

Subagent prompt must include:
- The full spec content
- All code generation rules
- The consistency check matrix (Step 4)
- The audit dimensions (Step 5)
- Instructions for the auto-correction loop

After all subagents complete, collect results for the unified delivery (Step 6).

### Progress Reporting

**CRITICAL**: Keep the user informed at every stage. They must never be left wondering what's happening.

#### Single spec — report each pipeline step as it starts:

```
⏳ [user-auth] Step 1/4: Generating code...
⏳ [user-auth] Step 2/4: Running consistency check...
✅ [user-auth] Step 2/4: Consistency check passed (6/6)
⏳ [user-auth] Step 3/4: Running tests...
✅ [user-auth] Step 3/4: Tests passed (12/12)
⏳ [user-auth] Step 4/4: Running quality audit...
✅ [user-auth] Step 4/4: Quality audit passed (6/6, 1 warning)
📦 [user-auth] DELIVERED

— or if audit finds critical issues —

⏳ [user-auth] Step 4/4: Running quality audit...
🔄 [user-auth] Audit found 1 critical issue. Looping back... (loop 1/2)
⏳ [user-auth] Step 1/4: Re-generating with fixes...
⏳ [user-auth] Step 2/4: Consistency check... ✅
⏳ [user-auth] Step 3/4: Tests... ✅ (12/12)
⏳ [user-auth] Step 4/4: Audit... ✅
📦 [user-auth] DELIVERED (1 loop)
```

#### Multi-spec — report wave progress and individual spec status:

```
🔵 Wave 1/2 — Starting 2 specs in parallel: user-auth, database

  ⏳ [user-auth] Generating...
  ⏳ [database] Generating...
  ✅ [database] Generate ✅ → Check ✅ → Tests ✅ → Audit ✅
  🔄 [user-auth] Generate ✅ → Check: 1 issue, auto-fixing (1/2)...
  ✅ [user-auth] Generate ✅ → Check ✅ → Tests ✅ → Audit ✅

✅ Wave 1/2 complete (2/2 delivered)

🔵 Wave 2/2 — Starting 2 specs in parallel: payment, notification

  ⏳ [payment] Generating...
  ⏳ [notification] Generating...
  ✅ [notification] Generate ✅ → Check ✅ → Tests ✅ → Audit ✅
  ✅ [payment] Generate ✅ → Check ✅ → Tests ✅ → Audit ✅ (1⚠️)

✅ Wave 2/2 complete (2/2 delivered)
```

#### After each subagent completes, immediately report to the user:

```
📦 [spec-name] DONE — 3 files generated, check ✅, tests ✅ (12/12), audit ✅ (1⚠️)
```

Do NOT wait for all subagents to finish before showing anything. Report results as they come in.

---

## Step 4: Consistency Check (automatic, internal)

Immediately after generating code, verify consistency:

| # | Check | How to Verify |
|---|-------|---------------|
| 1 | **Interface Match** | Input types in code match spec's Inputs table |
| 2 | **Output Match** | Return types in code match spec's Outputs table |
| 3 | **Business Rules** | Each numbered rule has corresponding logic in code |
| 4 | **Error Handling** | Each error scenario has a corresponding catch/throw/return |
| 5 | **No Extra Features** | Code doesn't implement functionality not in the spec |
| 6 | **Dependencies Used** | Libraries listed in spec are the ones used in code |

### If issues found:

1. Log what's wrong (which check failed and why)
2. **Auto-correct**: fix the code to match the spec
3. Re-run the consistency check
4. Maximum 2 correction attempts. If still failing after 2 retries, report the remaining issues in the delivery summary and continue to Step 5.

Show progress:
```
🔄 Consistency check: 5/6 passed. Fixing: Interface Match...
🔄 Retry 1: 6/6 passed. ✅
```

---

## Step 5: Test (MANDATORY — automatic, internal)

**This step is NON-NEGOTIABLE. It CANNOT be skipped, removed, or bypassed by any other step.**

After consistency check passes, run ALL tests:

### How to run tests

1. Detect the project's test runner:
   - Look for `package.json` → `scripts.test` → run `npm test`
   - Look for `pytest.ini`, `pyproject.toml` → run `pytest`
   - Look for `go.mod` → run `go test ./...`
   - Look for `Cargo.toml` → run `cargo test`
   - If no test runner detected, run the test files directly
2. Run the tests and capture output
3. Parse results: how many passed, failed, errored

### If ALL tests pass:
```
✅ Tests: 12/12 passed
```
Continue to Step 6 (Audit).

### If ANY test fails:

1. Log which tests failed and why
2. **Auto-fix** the code (NOT the tests) to make them pass
   - If the test is testing a business rule from the spec, the test is correct — fix the implementation
   - If the test itself has a bug (wrong assertion, wrong setup), fix the test
3. Re-run ALL tests
4. Maximum 2 fix attempts

```
🔄 Tests: 10/12 passed, 2 failed. Auto-fixing implementation...
🔄 Retry 1: 12/12 passed. ✅
```

### If tests still fail after 2 retries:

Report the failures in the delivery summary as **CRITICAL**. The pipeline continues but the delivery report will clearly flag:
```
❌ TESTS FAILING — 2 tests still fail after auto-fix attempts. Manual intervention required.
```

### Rules for this step:
- **NEVER skip tests** — even if everything else passes
- **NEVER delete or weaken a test** to make it pass
- **NEVER mark a failing test as "expected"**
- If no test files were generated in Step 3, this is itself a failure — go back and generate tests

---

## Step 6: Quality Audit (automatic, internal)

After tests pass, run a quality audit across 6 dimensions:

| # | Dimension | What to check |
|---|-----------|---------------|
| 1 | **Code Quality** | Naming, structure, DRY, readability, idiomatic patterns |
| 2 | **Error Handling** | Graceful degradation, actionable messages, edge cases |
| 3 | **Security** | Input validation, injection risks, hardcoded secrets, OWASP |
| 4 | **Test Coverage** | Tests cover business rules and error scenarios (DO NOT remove/weaken tests) |
| 5 | **Performance** | N+1 queries, unbounded loops, memory leaks, obvious bottlenecks |
| 6 | **Documentation** | Spec linkage, complex logic comments, type safety |

### Grading: ✅ Pass, ⚠️ Warning, ❌ Critical

### If critical issues (❌) found:

**Loop back to Step 3 (Generate)**. Do NOT patch in place — re-generate the code with the audit findings as additional context. This triggers the full cycle again:

```
Generate (with fixes) → Check → Test → Audit
```

This guarantees that fixes are tested before delivery. Maximum **2 full loops**. After that, deliver with remaining issues as warnings.

### Warnings (⚠️) are noted but do NOT trigger a re-loop.

### Loop progress reporting:

```
🔄 Audit found 1 critical issue (Security: hardcoded API key)
🔁 Loop 1/2: Re-generating with fixes...
  ⏳ Re-generating code...
  ✅ Consistency check passed (6/6)
  ✅ Tests passed (12/12)
  ✅ Quality audit passed (6/6)
📦 Delivering
```

---

## Step 7: Deliver

Update spec frontmatter: add `output_files`, update `updated_at`.

Show the final delivery report:

### Single spec:

```
## ✅ SDD Delivery Report: {spec-name}

**Spec:** specs/{name}.spec.md

### Generated Files:
- src/{name}.ts
- src/{name}.types.ts
- src/{name}.test.ts

### Pipeline Results:
| Step | Result |
|------|--------|
| Generation | ✅ Complete |
| Consistency Check | ✅ 6/6 passed |
| Tests | ✅ 12/12 passed |
| Quality Audit | ✅ 6/6 passed (1 warning) |
| Loops | 0 (passed on first run) |

### Warnings (non-blocking):
- ⚠️ Performance: Consider adding an index for the email lookup

### Summary:
Code is ready and all tests pass. Run /sdd:sdd-status for an overview of all specs.
```

### Multi-spec:

```
## ✅ SDD Delivery Report

| # | Spec | Generation | Check | Tests | Audit | Files |
|---|------|-----------|-------|-------|-------|-------|
| 1 | user-auth | ✅ | ✅ 6/6 | ✅ 8/8 | ✅ 6/6 | 3 files |
| 2 | payment | ✅ | ✅ 6/6 | ✅ 12/12 | ✅ 5/6 (1⚠️) | 3 files |
| 3 | notification | ✅ | ✅ 6/6 | ✅ 5/5 | ✅ 6/6 | 2 files |

**Total:** 3 specs delivered, 8 files generated, 25/25 tests passing

### Warnings:
- payment ⚠️ Performance: Consider connection pooling for database calls

Run /sdd:sdd-status for an overview of all specs.
```

---

## Rules
- NEVER generate code without an approved spec
- NEVER add features beyond what the spec defines
- ALWAYS link generated code back to the spec
- If the spec is ambiguous, ASK the user rather than guessing
- Auto-correction loop: max 2 retries per step, then report and move on
- The user should NOT need to run any other command after /sdd:sdd-gen — deliver everything
- **TESTS ARE SACRED**: Never delete, weaken, skip, or disable tests. If code fails a test, fix the code. If an audit fix breaks a test, revert the audit fix. Tests always win.