scosman/vibe-crafting/skill

Spec-Driven Development

A structured process for building software projects with specifications. You (the human) focus on decisions and review; AI agents handle drafting and building.

How It Works

Every batch of work ("project") gets a spec folder under /specs/projects/PROJECT_NAME/. The skill guides you through:

1. Planning: Project overview → functional spec → architecture → implementation plan
2. Building: Implement phases autonomously, with code review built into each phase
3. Reviewing: Spec-aware code review that verifies implementation matches design

The skill is project-agnostic. It provides the process; your project-specific conventions (test commands, linting, style) come from your system prompt configuration.

If This Conversation Was Compacted

The command references below hold the role definitions, process gates and prompt templates for each command. Compaction restores only this file — not them. If this conversation has been compacted part-way through a command, re-read that command's reference file before your next action.

When compacting, preserve: this instruction, which /spec command is running, which phase and step it is on, and the handles of any sub-agents you hold — the coding agent's agent ID in particular, since you resume it for review feedback and commit.

During /spec implement, /spec task and /spec pr you are a manager: you spawn and resume sub-agents, triage review findings, run git, and print progress blocks. You do not write code, run tests, review code, or commit. Every coding round — including one that addresses review feedback — is code-reviewed before commit.

Command Reference

/spec setup

One-time (or incremental) setup for using the skill in a repo. Adds .specs_skill_state/ to gitignore, creates /specs/projects/ directories, detects monorepo layout, and checks for commonly-needed configuration.

→ Read setup command reference

/spec new_project or /spec new

Create a new project from scratch. Walks through planning steps: project overview, functional spec, architecture (with optional component designs), and implementation plan. Sets this as your active project.

→ Read new project command reference

/spec continue or /spec cont

Resume work on the active project. Shows current state and routes to the next logical action — continue speccing, implement next phase, or review code.

→ Read continue command reference

/spec implement or /spec impl

Implement the active project. Routes to phase-specific or full implementation. Use /spec implement next for one phase, /spec implement all for all remaining, or /spec implement phase N for a specific phase.

→ Read implement command reference

/spec task

Implement a one-off task without a full spec. Describe what you want inline and get the same implement loop (coding agent, code review, commit) without planning artifacts.

→ Read task command reference

/spec research

Research a topic on the web. Splits the topic into subtopics, runs a research sub-agent on each, and writes a tree of research docs under a single summary. Requires web search and web fetch tools. Runs standalone, or embedded in /spec new_project when a spec depends on knowledge you don't have yet.

→ Read research command reference

/spec pr

Address review feedback from a GitHub pull request. Finds the PR for the current branch, fetches unresolved comments, spawns a coding agent to address them, runs the standard code review and triage, commits, pushes, and replies to each comment thread on GitHub.

→ Read PR feedback command reference

/spec cr or /spec code_review

Structured, spec-aware code review. Reviews git diff by default, or a specified scope. Always runs as a sub-agent with clean context.

→ Read code review command reference

/spec deep cr or /spec deep review

Multi-phase agentic code review. Compares current branch against its fork point, designs review phases tailored to the diff, runs focused sub-agents per phase, and produces persistent review artifacts.

→ Read deep code review command reference

/spec design crit or /spec crit

Multi-phase agentic review of spec/design documents. Identifies design concerns, runs focused sub-agents per concern area, produces persistent review artifacts, and offers an interactive resolution phase to triage and fix issues found.

→ Read design crit command reference

Bare /spec — Router

Reads current state (active project, artifact statuses) and presents relevant options. Never requires routing — direct commands always work. Can also interpret open-ended requests.

To check state: read .specs_skill_state/current_project.md and scan artifact frontmatter. Always show /spec task as an available option. If no project exists, suggest new_project, task, or setup. If project in progress, show state and suggest the next action.

If the request is about learning or understanding something rather than building it — "what's the current state of the OpenEnv standard?", "how does Stripe's webhook retry work?", "which library should we use for Z?" — route to /spec research. Also suggest it when a user's project idea depends on an external standard, API, or library that neither of you can describe accurately from memory.

Not a command: shared/backlog_phase.md — an interactive process for deciding a queue of open questions with the user. Written for the Backlog phase of /spec implement; reusable wherever a flow needs a batch of decisions.

Project Structure

Every project lives under /specs/projects/PROJECT_NAME/:

Research Folders

Research output lives in a folder per topic, with a research_summary.md at its root linking to per-subtopic summaries, which link to deep docs:

Research folders have no frontmatter status and are outside the artifact dependency chain — they're inputs to speccing, not spec artifacts.

Artifact Conventions

All spec files use YAML frontmatter with a status field:

---
status: draft
---

Valid statuses: draft, complete.

• Artifacts start as draft when created
• Mark complete after user confirmation
• If a completed artifact is edited, downstream artifacts cascade to draft (if they may be affected)

Dependency chain: project_overview → functional_spec → architecture → components → implementation_plan

Phase plans are outside the cascade — generated fresh during implementation.

Modes

The skill operates in two modes:

• Project mode: Full spec planning → phased implementation. Use for anything that benefits from upfront design — new features, complex changes, multi-phase work.
• Task mode: Inline description → single-pass implementation. Use for well-understood, small-to-medium changes — bug fixes, small features, refactors.

Both modes use the same implement loop (coding agent → code review → commit). Task mode skips the spec planning steps.

State Management

The file .specs_skill_state/current_project.md (git-ignored) tracks your active work:

Current Project: /specs/projects/project_name

or for tasks:

Current Task: tasks/task-slug

Task files live at .specs_skill_state/tasks/[slug].md.

This file is per-worktree (git-ignored), so you can have parallel worktrees with different active work.

Monorepo Support

For monorepos (multiple sub-projects in one repo):

• /spec setup discovers sub-projects by scanning for root markers (pyproject.toml, package.json, etc.)
• Each sub-project gets its own /specs/projects/ directory
• /specs/monorepo.md at repo root describes the layout
• Cross-project work lives at root /specs/projects/

→ See /spec setup for discovery and setup.

Extensibility

The skill provides the process. Project-specific details come from your environment:

From the skill: The workflow, general guidance ("run automated checks"), persona-driven quality standards

From your system prompt: Test commands, lint/format commands, code style, CR standards, project-specific constraints

The skill references these generically: "run the project's automated checks" not "run uv run ./checks.sh."

→ See /spec setup for help configuring external knowledge.