# spec — Spec-Driven Development Skill for Claude Code
An [oh-my-claudecode](https://github.com/oh-my-claudecode/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:
```bash
# 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:
```yaml
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`](examples/user-auth-flow.md) for a completed
example showing what the generated output looks like.
---
## Requirements
- [Claude Code](https://claude.ai/code)
- [oh-my-claudecode](https://github.com/oh-my-claudecode/oh-my-claudecode) v4.0+
---
## Testing
Run the structural validator before every commit:
```bash
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/`](tests/scenarios/).
See [`tests/README.md`](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](LICENSE).