The SpecGraph Workflow
A complete overview of how a project moves through every phase in SpecGraph, from document upload to deployment.
The SpecGraph Workflow
Every project in SpecGraph follows the same end-to-end workflow. Each phase has a clear purpose and gates the next, ensuring nothing is skipped and the final specification reflects genuine cross-department input. The workflow has two halves: specification building (phases 1–11, in the web UI) and MCP-driven development (phases 12–16, via Claude Code).
The Full Flow
── SPECIFICATION ────────────────────────────────
1. Create Project
↓
2. Upload Documents
↓
3. Generate PRD (AI)
↓
4. Open Department Surveys
↓
5. Departments Submit Wishes
↓
6. Detect Conflicts (AI)
↓
7. Resolve Conflicts (Team)
↓
8. Unify PRD (AI)
↓
9. Stakeholder Approvals
↓
10. Lock PRD
↓
11. Generate Coding Agents (AI)
── MCP DEVELOPMENT ──────────────────────────────
↓
12. Architect (MCP — Claude Code)
↓
13. Story Sharding (MCP — Claude Code)
↓
14. Export Specification
↓
15. In Development (MCP — Claude Code)
↓
16. Deployed → ClosedEach step is covered in detail in the pages below. Use the sidebar to navigate to the specific phase you're working on.
Phase Summary
| Phase | Who Acts | What Happens |
|---|---|---|
| Creating a Project | Project Lead | Defines the project name, description, and template |
| Uploading Documents | Project Lead | Uploads source docs for AI to read |
| PRD Generation | AI + Project Lead | AI generates the initial structured PRD |
| Collecting Wishes | All Departments | Departments fill surveys and submit requirements |
| Resolving Conflicts | All Teams | Teams discuss and vote on conflicting requirements |
| Unification | AI + Project Lead | AI produces the final unified specification |
| Approvals | Stakeholders | Formal sign-offs from designated approvers |
| Export | Project Lead | Locked PRD exported as AI-ready markdown |
| MCP Connection | Claude Code | Architect designs system, Scrum Master shards stories, Developer implements |
MCP Development Phases
After the PRD is locked and coding agents are generated, the project enters the MCP-driven development cycle. These phases are driven by Claude Code using the SpecGraph MCP server — not the web UI.
| Phase | MCP Prompt | What Happens |
|---|---|---|
architecting | architect | Architect agent reads PRD + context, designs system architecture, documents decisions |
story_sharding | scrum-master | Scrum Master agent breaks architecture into ordered implementation stories |
exported | — | Specification exported; stories visible in Implementation Dashboard |
in_development | developer / qa | Developer implements stories one by one; QA verifies each against acceptance criteria |
deployed | — | Application is live |
closed | — | Project archived |
Important Rules
- Phases are sequential. You cannot skip ahead. For example, you cannot run conflict detection before surveys are submitted, and you cannot lock the PRD before all required approvals are received.
- Critical conflicts block progress. All Critical and High severity conflicts must be resolved before unification can begin.
- PRD locking is permanent. Once a PRD is locked, it cannot be edited. This is intentional — the locked PRD is the authoritative record of what was agreed upon.
- MCP phases require a live connection. The
architecting,story_sharding, andin_developmentphases are driven by Claude Code via the SpecGraph MCP server. See MCP Connection for setup. - Exports are for AI tools. The final export is structured specifically to be used with AI coding tools, not as a human-readable report (though it is readable).