Spec Agents

A hybrid spec-driven development framework for Claude Code. Combines Spec Kit's sequential pipeline with BMAD Method's role-based agent specialization.

The Idea

Instead of one generic AI writing specs, planning, coding, and testing, each phase is handled by a specialized agent with a distinct persona, principles, and domain expertise:

Phase	Command	Agent	Role
1	/specagent.constitution	Diana	Business Analyst — stakeholder discovery, principles
2	/specagent.specify	Marco	Product Manager — PRD, user stories, acceptance criteria
3	/specagent.plan	Winston	System Architect — technical design, NFR mapping, trade-offs
4	/specagent.tasks	Lucia	Scrum Master — task breakdown, story points, dependencies
5	/specagent.implement	Amelia	Senior Developer — TDD, safety protocols, incremental delivery
6	/specagent.verify	Rafael	QA Engineer — acceptance verification, scope creep detection

Each agent only does its job. Marco (PM) never prescribes technical solutions. Winston (Architect) never writes user stories. Amelia (Developer) never redesigns the architecture. Rafael (QA) trusts the spec, not the code.

What Makes This Different

From Spec Kit, we take:

• The sequential pipeline with gates between phases
• Structured templates with inline agent instructions
• Task format with parallel markers and dependency tracking
• Workflow orchestration files

From BMAD Method, we take:

• Named agent personas with deep identity and communication style
• Activation protocols (load context, adopt persona, greet, execute)
• Customizable agents via customize.toml with 3-tier merge (defaults / team / personal)
• Menu-driven sub-actions within each agent
• Safety protocols for implementation (Blast Radius, Reproduction First, Strangler Pattern)

Install

git clone https://github.com/sonoman/spec-agents.git
bash spec-agents/install.sh /path/to/your/project

This installs:

• .claude/skills/specagent.*/ — Agent skills (SKILL.md + customize.toml + templates)
• .spec-agents/workflows/ — Pipeline orchestration
• .spec-agents/custom/ — Project-specific agent overrides
• specs/ — Where all specification artifacts live

Usage

Open Claude Code in your project:

/specagent.constitution    # Diana interviews you about project principles
/specagent.specify         # Marco writes a feature PRD from your description
/specagent.plan            # Winston designs the technical architecture
/specagent.tasks           # Lucia breaks it into ordered, pointed tasks
/specagent.implement       # Amelia executes tasks phase by phase with tests
/specagent.verify          # Rafael verifies everything against the spec

Each agent reads the previous phase's output. Gates prevent skipping ahead.

Customization

Each agent's persona, principles, and behavior can be customized per-project:

# Copy the agent's defaults to your project override
cp .claude/skills/specagent.plan/customize.toml .spec-agents/custom/specagent.plan.toml

# Edit to match your project's needs
# e.g., change principles, add persistent facts, modify menu items

The merge order is: skill defaults < project overrides (.spec-agents/custom/).

Project Structure After Use

your-project/
  .claude/skills/
    specagent.constitution/
      SKILL.md              # Agent definition
      customize.toml        # Default configuration
      templates/            # Document templates
    specagent.specify/
    specagent.plan/
    specagent.tasks/
    specagent.implement/
    specagent.verify/
  .spec-agents/
    workflows/              # Pipeline orchestration
    custom/                 # Project-specific overrides
  specs/
    constitution.md
    001-feature-name/
      spec.md
      plan.md
      tasks.md
      research.md
      checklists/
        spec-checklist.md
      verification-report.md

Workflows

Pre-built workflow compositions in .spec-agents/workflows/:

Workflow	Steps	Use when
00-specagent.all.md	All 6 phases	New project, new feature from scratch
01-specagent.specify-to-plan.md	Specify + Plan	Constitution exists, need to design a feature
02-specagent.plan-to-ship.md	Tasks + Implement + Verify	Spec and plan approved, ready to build

Credits

• Pipeline structure inspired by GitHub Spec Kit
• Agent roles and activation protocol inspired by BMAD Method
• Skill format adapted from Spec Kit Antigravity Skills