How it works.
SpecGraph turns a product idea into an agent-ready specification through four governed phases. Each phase has a department owner. When the spec is complete, AI coding agents pick up stories over MCP and implement them in a review-gated loop.
Phase 1 — Discoverybrownfield only
Skip this entirely for new projects. For existing codebases, the discovery skill ingests the repo — reading files, routes, schemas, and tests — and auto-drafts every spec phase. The team then reviews and corrects each section before moving forward.
Phase 2 — Specification
Three phases run in sequence, each owned by a different department:
- Vision & Scope (Business) — strategic rationale, primary users, KPIs, risks, and what is explicitly out of scope.
- Features & Stories (Product) — numbered functional requirements (FR-001, FR-002, …) each with Given/When/Then acceptance criteria.
- Product Brief (Product) — a locked narrative that consolidates the above into a single source of truth. Downstream phases trust this brief; unlocking it invalidates anything that depends on it.
If the project has a UI, a Design & UX phase (Design) runs before Architecture. It captures design tokens, screen inventory, component specs, and testable UX requirements.
Phase 3 — Architecture & Quality
Four specialist phases converge here:
- Technical Architecture (Engineering) — ADRs, data model, API contracts, folder structure.
- Quality & Testing (QA) — test strategy, coverage targets, NFRs, smoke suite, and performance benchmarks.
- Security & DevOps (Security) — auth model, RBAC matrix, OWASP checklist, CI/CD pipeline.
- Handoff Readiness (System) — validates every upstream phase is complete. Nothing generates until this check is green.
On approval, the Handoff Pack is generated: spec.md, CLAUDE.md, epics.md, stories/, and sprint-status.yaml. The MCP Server exposes this pack to coding agents — they pull stories, implement them, and push status updates back over the same connection.
Phase 4 — Implementation
Coding agents (Claude Code, Cursor, Cline, …) connect to the MCP Server and enter the Story Loop:
- Agent pulls the next
ready-for-devstory, readsspec.md+CLAUDE.mdfor context. - Agent implements all tasks in the story and reports files modified and test results back over MCP.
- A different LLM reviews the diff against the story's acceptance criteria.
- If the review fails, the story loops back to development with the reviewer's notes.
- If the review passes, the story is marked done and the next story in the epic begins.
- When all stories in an epic are done, a Retrospective captures learnings before the next epic starts.
The live Progress board (P-09) shows each connected agent, its current story, files touched, and test results in real time — without leaving the SpecGraph UI.