AI Coding Agents

AI Coding Agents

Once a PRD is locked, SpecGraph generates a team of AI coding agents — configured AI personas that work together to architect, plan, implement, and validate your project. These agents are designed to work with Claude Code through SpecGraph's MCP server, which feeds them the right context at each stage of development.

Two Tiers of Agents

SpecGraph uses a two-tier agent architecture. Each tier serves a different purpose in the development workflow.

Tier 1 — Workflow Agents

Workflow agents are always generated for every project. There are four fixed roles that represent the full development lifecycle:

Architect Reads the full locked PRD and project context (tech stack, design system, security requirements) and designs the system architecture. The Architect runs first, before any code is written, and produces the architectural decisions that all other agents follow.

Scrum Master Reads the PRD, all accepted wishes, and acceptance criteria, then breaks the project into implementation stories — small, self-contained units of work. Each story is stored in SpecGraph and becomes the unit of work for the Developer agent. The Scrum Master ensures stories are properly sequenced and scoped.

Developer Implements one story at a time using a test-driven development loop. The Developer reads a single story with its full context (requirements, acceptance criteria, related PRD sections), writes failing tests, implements the code to make them pass, and reports completion. The Developer works with strict scope boundaries — it never makes architectural decisions or modifies code outside the current story.

QA Engineer Validates each story's implementation against its acceptance criteria. The QA agent reviews code, checks that the behaviour matches the Given/When/Then criteria, and either passes the story or flags it for rework.

Tier 2 — Specialist Agents

Specialist agents are generated by AI from your specific PRD. The number and focus areas vary by project. Common examples include:

• Frontend Specialist — component patterns, design system usage, accessibility standards
• Backend Specialist — API design, data model conventions, service layer patterns
• Database Specialist — schema design, query patterns, migration conventions
• Security Specialist — authentication, authorization, data handling requirements
• DevOps Specialist — deployment, CI/CD, infrastructure patterns

Specialist agents act as reference resources for the Developer agent. When implementing a story that involves the frontend, the Developer loads the Frontend Specialist's instructions to get domain-specific guidance tailored to your project's stack and conventions.

How Agents Connect to Claude Code via MCP

SpecGraph includes an MCP (Model Context Protocol) server that connects directly to Claude Code. Instead of exporting files into your project folder, the MCP server makes your PRD, agents, stories, and context available to Claude Code as live tool calls.

The principle: SpecGraph is the brain. Claude Code is the hands. MCP is the nerve system.

When you start a Claude Code session in your project directory, it connects to the SpecGraph MCP server and can:

• Read the full PRD and any section on demand.
• Load an agent's instructions to "become" that agent.
• Fetch a single story with fully self-contained context (no need to load the whole spec).
• Report story completion and blocker status back to SpecGraph.

This means the SpecGraph web UI shows live implementation progress — which stories are in progress, which are done, and which are blocked — updated in real time as Claude Code works.

The MCP Workflow

The development workflow with MCP follows a clear sequence:

1. Initialize the Project

Run init_project once in your codebase directory. This writes an .mcp.json file (which configures the MCP connection) and a minimal CLAUDE.md that tells Claude Code to use the SpecGraph MCP tools. No spec files are copied into your project — everything stays in SpecGraph's database.

2. Architect Phase

Load the Architect agent prompt via MCP. The Architect calls get_prd, get_project_context, and get_control_manifest to read the full specification and constraints, then designs the system architecture. When complete, it calls update_project_phase and the project advances in SpecGraph's web UI.

3. Story Sharding Phase

Load the Scrum Master prompt. The Scrum Master calls get_wishes and get_acceptance_criteria to understand all requirements, then breaks the work into stories using create_stories. Stories appear immediately in SpecGraph's Implementation Dashboard.

4. Development Loop

Load the Developer prompt. For each story:

1. Call get_story to fetch the story's self-contained context package.
2. Write failing tests from the acceptance criteria.
3. Implement the code to make tests pass.
4. Call complete_story to report completion, including which files were changed.
5. If stuck on an ambiguity or conflict, call report_blocker instead — this halts work on that story and creates a visible blocker in the SpecGraph web UI for a human to resolve.

5. QA Phase

Load the QA prompt. For each completed story, the QA agent calls get_story for the acceptance criteria, reviews the implementation, and calls update_story_status to pass or flag the story.

Viewing Agents in SpecGraph

Navigate to the Agents page of any project (available after PRD is locked). You'll see:

• Workflow Agents displayed in tier order (Architect → Scrum Master → Developer → QA).
• Specialist Agents listed by domain.
• Full instructions for each agent, viewable inline.
• A Copy Instructions button for each agent — for users who want to paste instructions manually into an AI tool without using MCP.

Setting Up the MCP Connection

See the Export & MCP Connection page for step-by-step instructions on connecting Claude Code to SpecGraph via MCP.