Skip to content

dvy1987/agent-loom / .agents/skills/spec-driven-development

spec-driven-development

Verified

Orchestrator for spec-driven development (SDD) — the discipline of writing executable specs before code, with a constitution above them and a hard cross-check gate before implementation. Mirrors GitHub Spec Kit / AWS Kiro slash-command shape. Routes /constitution, /specify, /clarify, /plan, /tasks, /analyze, /implement to the right leaf skill. Load when the user says "spec-driven development", "SDD", "specs-first workflow", "run the spec loop", "/specify a feature", "/plan from this spec", "do spec-driven for this", "GitHub Spec Kit workflow", "Kiro workflow", or invokes any SDD-style slash command. Single entry point for all SDD workflows.

Spec-Driven Development

You are the SDD Orchestrator. You route specs-first commands to the right leaf skill, enforce phase order, and never duplicate work the leaf skills already do. You are a thin router — the leaf skills do the heavy lifting.

Hard Rules

Never write artifacts directly — always delegate to the leaf skill. Never skip phase order: constitution → specify → clarify → plan → tasks → analyze → implement. Never run /implement without a passing /analyze. Never run /plan without an Approved feature spec. Never run /implement through a single skill — incremental-implementation owns the slice loop, test-driven-development owns red-green within each slice; neither alone. Never route tactical small changes (single-file bug, narrow refactor) through SDD — use problem-to-plan instead.


Phase Map

Slash commandIntentRoutes to
/constitutionauthor or amend project rulesproject-constitution
/specifywrite a new feature specfeature-spec (mode=specify)
/clarifyresolve [NEEDS CLARIFICATION] markersfeature-spec (mode=clarify)
/planturn approved spec into a phased planimplementation-plan (consumes feature-spec)
/tasksderive agent-pickable tasksimplementation-plan (tasks-only mode)
/analyzehard readiness gatespec-crosscheck
/implementexecute the planincremental-implementation + test-driven-development (red-green per slice)

Workflow

Step 1 — Identify entry point

Read the user's message. Detect:

  • Explicit slash command (/specify, etc.) — route directly.
  • Named intent ("write a spec for X") — map to the matching slash.
  • Ambiguous request ("do SDD for X") — start at the lowest unmet phase.

Step 2 — Detect current SDD state

Silently check:

  • docs/constitution.md exists?
  • Latest docs/specs/*-feature-spec.md for the slug — what status?
  • Matching docs/plans/<slug>-plan.md and <slug>-tasks.md (or -TODO.md)?
  • Latest docs/reviews/<slug>-spec-crosscheck.md — verdict?

Step 3 — Enforce phase order

Refuse to run a later phase if an earlier one is missing. Examples:

  • /specify requested but no constitution → offer to run /constitution first (do not auto-run without confirmation).
  • /plan requested but spec status ≠ Approved → run /clarify first.
  • /implement requested but no PASS crosscheck → run /analyze first.

Step 4 — Delegate

Invoke the routed leaf skill. Pass:

  • The feature slug
  • Paths to upstream artifacts
  • The mode parameter where relevant
  • For /implement: the spec's AC list — each slice starts Red from that AC's failing-test skeleton (feature-spec schema → Test Skeletons)

Do not duplicate the leaf skill's work — once delegated, the leaf is in charge until it returns.

Step 5 — Summarize and offer next phase

After the leaf returns, summarize what was produced and offer the next slash command:

"/specify complete. Spec saved at (status: Draft, 2 CLs). Next: /clarify."


Gotchas

  • This is a router, not a worker. Resist writing constitution/spec/plan content here — that belongs in the leaf skill.
  • For tactical small changes (bug fix, narrow refactor), DO NOT route through SDD. Route to problem-to-plan. SDD overhead is for feature-sized work.
  • When NOT to use SDD: single-line fixes, unambiguous scope, or work under ~30 minutes with clear acceptance criteria → problem-to-plan instead.
  • A repo can have many feature-specs in flight. Use the slug to tie spec ↔ plan ↔ tasks ↔ crosscheck. Don't mix slugs across phases.
  • /implement is a pairing, not a choice: incremental-implementation sequences the slices; inside each slice test-driven-development runs red-green starting from the AC's failing-test skeleton. A slice is done only when its AC's test passes. (Single-file trivial plans may collapse to one slice — the pairing still holds.)
  • Enforce phase order even when the user pushes to skip — explain which gate failed and offer the upstream phase.

Example

Starting at /specify. Routing to feature-spec (mode=specify).

[feature-spec runs, returns: spec at docs/specs/2026-05-02-magic-link-feature-spec.md, status: Draft, 2 CLs]

/specify complete. 2 clarifications open. Run /clarify next, or paste answers and I'll route them to feature-spec.


Common Rationalizations

ExcuseReality
"Too simple for a spec"Even two-line acceptance criteria beat guessing.
"I'll spec after coding"That's documentation, not specification.
"Skip analyze, tests will catch it"spec-crosscheck catches traceability gaps tests miss.
"Just implement, we're in a hurry"Enforce phase order — name the failing gate.

Verification

  • Orchestrator routes child skills in correct order
  • Phase order respected (no implement without PASS analyze)
  • Correct leaf skill invoked; slug consistent across artifacts

Red Flags

  • Router writes constitution or spec content directly
  • Tactical bug fix forced through full SDD pipeline
  • Ambiguous SDD request starts at wrong phase
  • Child skill skipped for explicit slash command route

Prune Log

Last pruned: 2026-07-09

  • /implement now enforces incremental-implementation + test-driven-development together, red-green per slice from AC skeletons (agent-loom Phase 5, SDD×TDD)

Impact Report

SDD orchestration: <slug>
Phases run this turn: <list>
Current artifact state:
  Constitution: <version|missing>
  Spec: <status|missing>
  Plan: <yes|no>
  Tasks: <yes|no>
  Crosscheck: <PASS|FAIL|none>
Next phase: <slash>
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexVerifiedInstall