spec — Spec-Driven Development Skill for Claude Code

An oh-my-claudecode skill that enforces a spec-first workflow for AI-assisted development:

interview → spec → tasks → implement → verify

No source files are created or modified until the user has approved a written spec. The spec file persists as a decision log and enables interrupted sessions to be resumed exactly where they left off.

Why spec-first?

AI agents that jump straight to coding often produce solutions that solve the wrong problem, miss edge cases, or require expensive rewrites. A short structured spec aligns understanding before any code is written, giving you a checkpoint to catch misunderstandings early and a record of the decisions made.

Installation

Copy SKILL.md into your oh-my-claudecode skills directory:

# Global installation (available in all projects)
cp SKILL.md ~/.claude/skills/spec.md

# Project-local installation
cp SKILL.md .claude/skills/spec.md

Restart Claude Code. The skill is now available as /spec.

Usage

/spec user-auth-flow       # start a spec for a named feature
/spec                      # interactive — asks for feature name first
/spec list                 # show all specs and their statuses

The skill also activates automatically when you say:

• "write a spec for …"
• "let's plan first"
• "spec-driven approach"
• "spec first, then implement"
• "create a plan before coding"

Workflow

Phase 1 — Interview

Claude asks up to five questions (What, Why, Scope, Constraints, Definition of Done). Questions already answered in your message are filled in automatically.

Phase 2 — Spec Generation

A structured spec file is written to .claude/specs/<feature-name>.md and shown to you for approval. You can reply yes, edit <changes>, or stop.

Phase 3 — Task List

The ## Tasks section of the spec is expanded into an ordered, atomic checklist.

Phase 4 — Implementation

Tasks are executed one at a time. Each completed task is marked [x] in the spec. Commit checkpoints are offered at logical milestones.

Phase 5 — Verification

Test and lint commands are read from .claude/spec-config.yml if already saved, or auto-detected (npm, make, cargo, pytest, composer, go, CI workflow files). Discovered commands are written back to config so future runs skip detection. Results are reported and the spec status is updated to Implemented or Partial.

Configuration

Create .claude/spec-config.yml in your project root to customise behaviour:

specs_dir: docs/specs        # default: .claude/specs
test_command: npm test       # default: auto-detected
lint_command: npm run lint   # default: auto-detected

All keys are optional. The skill writes test_command and lint_command automatically after the first successful detection.

Spec file location

Specs are written to the configured specs_dir (default: .claude/specs/). Spec files are never deleted — they are a permanent decision log.

Example spec

See examples/user-auth-flow.md for a completed example showing what the generated output looks like.

Requirements

• Claude Code
• oh-my-claudecode v4.0+

Testing

Run the structural validator before every commit:

bash tests/validate.sh

This checks that SKILL.md has valid frontmatter, all required sections, and all guardrail phrases intact. Requires only bash.

For behavioural testing, use the manual scenarios in tests/scenarios/. See tests/README.md for full instructions.

Contributing

1. Fork the repository.
2. Make your changes to SKILL.md.
3. Test by invoking /spec in a project with OMC installed and walking through the full five-phase workflow.
4. Open a pull request with a description of what you changed and why.

Improvements are welcome, especially around tool detection in Phase 5 and handling of edge cases not yet covered.

License

MIT — see LICENSE.