spec-driven-dev

A spec-driven development pipeline for Go projects using Claude Code agents, skills, and hooks.

Overview

This project enforces a "spec first" workflow where design documents, API specifications, and test specifications are written and approved before implementation begins. Dedicated Claude Code agents handle each phase of the pipeline:

/write-design-doc ──→ spec-writer agent ──→ specs/design/{feature}.md
/write-api-spec   ──→ spec-writer agent ──→ specs/api/{service}.yaml
/write-test-spec  ──→ spec-writer agent ──→ specs/test/{package}.md
/implement-from-spec ──→ implementer agent ──→ Go source code
/review-against-spec ──→ reviewer agent    ──→ .work/specs/reviews/
/run-spec-tests      ──→ tester agent      ──→ .work/specs/test-results/

Quick Start

1. Clone this repo into your Go project (or copy the .claude/ and specs/ directories):

   git clone https://github.com/abhat/spec-driven-dev.git
   cp -r spec-driven-dev/.claude/ /path/to/your/go-project/.claude/
   cp -r spec-driven-dev/specs/ /path/to/your/go-project/specs/

2. Start with a design doc:

   /write-design-doc my-feature
   

3. Implement from the spec:

   /implement-from-spec specs/design/my-feature.md
   

4. Review the implementation:

   /review-against-spec specs/design/my-feature.md
   

5. Write and run tests:

   /run-spec-tests specs/design/my-feature.md
   

Components

Agents

Agent	Purpose	Mode
spec-writer	Writes design docs, API specs, test specs	Read + Write
implementer	Implements Go code from approved specs	Read + Write
reviewer	Reviews code against specs (read-only)	Read-only
tester	Writes and runs Go tests from test specs	Read + Write

Hooks

All hooks are non-blocking (warnings only). To make them strict, change exit 0 to exit 2 at the end of each script.

Hook	Trigger	Purpose
check-spec-exists.sh	Before Write/Edit	Warns when editing Go files without specs
validate-spec-format.sh	After Write/Edit	Validates spec documents have required sections
run-go-checks.sh	After Write/Edit	Runs go vet and go build after Go changes

Directory Structure

.claude/
  agents/          # Agent definitions
  skills/          # Skill (slash command) definitions
  hooks/           # Hook scripts
  settings.json    # Claude Code configuration
specs/
  design/          # RFC/design documents
  api/             # OpenAPI or Go interface specs
  test/            # Test specifications
.work/specs/       # (gitignored) Review reports, test results

License

MIT