sdd

rob-agent-workflow

Spec Driven Development skills for Claude Code — from ambiguous requirement to merged PR.

A set of Claude Code skills implementing Spec Driven Development (SDD) — a methodology that eliminates ambiguity before code gets written. Language and framework agnostic.

---

Why SDD?

AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous.

When you tell an agent "add a feature to manage items from the backoffice," it has to guess: which backoffice, which API contract, which authorization model, which error handling strategy. Each guess is a silent decision. Some are right. Some are wrong.

SDD fixes this by separating what to build from how to build it, then breaking work into self-contained tasks:

Specify → Plan → Tasks → Implement → Review → Ship → Close-loop

By the time the agent writes code, it has everything it needs. No guessing. After merge, a final close-loop phase archives lessons into a per-repo knowledge base so the next feature starts smarter.

---

Skills Overview

Core SDD Pipeline

Phase	Skill	What it does
1	/spec	Functional specification — WHAT to build. Given/When/Then acceptance criteria. Technology-agnostic.
2	/plan	Technical plan — HOW to build it. Reads the codebase. Architecture decisions, testing strategy.
3	/tasks	Task breakdown — DIVIDE. Small, ordered, self-contained tasks. Creates GitHub issue + branch via gh.
4	/implement	TDD implementation — BUILD. Red → Green → Refactor, one task at a time.
5	/review	Code review — CHECK. Bugs, security, performance, conventions before shipping.
6	/ship	Commit + push + PR — DELIVER. Conventional commits. PR via gh pr create. Optional wiki preliminary ingest.
7	/sdd:wiki-close-loop	Post-merge CLOSE-LOOP. Archive review findings and lessons learned into the repo wiki. Manual by design.

Use /sdd:run to orchestrate phases 1-6 in a single pipeline with quality gates. Phase 7 stays manual — nothing is written to the wiki without explicit confirmation.

/ship is not terminal. The PR is a live artifact until merge. Review feedback, CI failures, and post-review commits are expected between /ship and the actual merge.

sequenceDiagram
    actor User
    participant Spec as /spec
    participant SR as spec-reviewer
    participant Plan as /plan
    participant PR as plan-reviewer
    participant Tasks as /tasks
    participant Impl as /implement
    participant Review as /review
    participant Ship as /ship

    User->>Spec: User story or PRD
    Spec->>User: Functional specification
    User-->>SR: Review spec (optional)
    SR-->>User: Issues / Ready
    rect rgb(255, 245, 230)
        Note over User,Spec: Gate: User approval
    end

    User->>Plan: Approved spec
    Plan->>User: Technical plan
    User-->>PR: Review plan (optional)
    PR-->>User: Issues / Ready
    rect rgb(255, 245, 230)
        Note over User,Plan: Gate: User approval
    end

    User->>Tasks: Approved plan
    Tasks->>User: Task list + GitHub issue + branch
    rect rgb(255, 245, 230)
        Note over User,Tasks: Gate: User approval
    end

    User->>Impl: Task list
    loop Each task
        Impl->>Impl: Red → Green → Refactor
    end
    Impl->>User: All tests passing

    User->>Review: Review changes
    Review->>User: Verdict + issues

    User->>Ship: Ship it
    Ship->>User: Committed + PR created
    Ship-->>User: Ingest spec/plan/tasks to .wiki/? (optional)

    Note over User,Ship: PR is live — review, CI, post-review commits happen here

    User->>User: PR merges
    User-->>User: /sdd:wiki-close-loop (optional, post-merge)

Knowledge Base (Wiki)

A per-repo .wiki/ directory accumulates high-value SDD artifacts so future sessions consult prior work instead of rediscovering context. Everything is opt-in — the wiki is never written without explicit user confirmation.

Skill	What it does
/sdd:wiki-ingest	Write SDD artifacts to .wiki/. --preliminary (spec/plan/tasks) or --final (review findings/lessons). Delegated from /ship and /sdd:wiki-close-loop.
/sdd:wiki-close-loop	Post-merge: gather review comments + post-review commits via gh, then write final pages cross-linked to the preliminary entries.

/spec and /plan automatically consult the wiki before interviewing the user — if a matching prior spec or plan exists, it is surfaced for reuse. Absence of .wiki/ is a graceful no-op. See .claude/rules/wiki-conventions.md for the full schema.

Migration Workflow

Skill	What it does
/migrate	Scan → analyze → migrate files from one pattern to another
/review-migration	Validate completed migrations: residual check, tests, build, quality report

Utility