Agile Studio

A full specialist team for Claude Code.

A planning and build harness for domain experts who are building serious software with AI — using standard agile methodology, with a named team of specialists who know exactly what they're doing.

What this is

Agile Studio gives Claude Code a complete delivery team: a Business Analyst, a Product Manager, a UX Expert, an Architect, and a Product Owner — each a named specialist with their own domain expertise, their own way of working, and their own deliverables. You don't need to understand their techniques. You need to understand your domain. They handle the rest.

You don't write code. You work with your team.

"The AI is the most capable junior engineer who ever lived. It can build anything you describe correctly. It will build exactly what you describe. The role of the team is to make sure what you describe is the right thing to build — before any code is written."

Agile Studio implements the BMAD method (Business Methodology for Agile Delivery) inside Claude Code, enhanced with ruflo swarm builds, cross-session memory, safety hooks, and a definition-of-done enforcement layer.

Install

Install inside the project folder to ensure you have the latest version:

npx agile-studio init

Or globally (needs to be rerun on updates):

npm install -g agile-studio

That's it. This single command:

• Scaffolds your project structure (docs/, .agile/, CLAUDE.md)
• Installs the /agile skill into Claude Code
• Installs six safety hooks into your Claude Code settings
• Initialises git with an initial commit
• Prints your next steps

Then:

Inside your project folder in Claude Code, type:

/agile

What happens when you type /agile

Claude Code loads the Agile Studio orchestrator. It checks whether you have an existing project in progress (via .agile/state.json and ruflo memory) and either:

• New project: Introduces your team, explains the process, and hands you to Mary to begin discovery.
• Returning project: Shows you exactly where you left off — which documents are approved, which stories are done, which sprint is active — and resumes from there.

The team

Each specialist handles their own domain. They stay in character, probe your assumptions, and produce documents the next specialist builds from.

Mary — Business Analyst
  Researches your market. Challenges your assumptions.
  Runs structured brainstorming. Produces the Project Brief.
  Output: docs/prd/brief.md

John — Product Manager
  Turns Mary's brief into a PRD: what to build, for whom, by when.
  Defines the MVP. Documents what must not be built yet.
  Output: docs/prd/prd.md

Sally — UX Expert
  Designs the user experience. Produces front-end specifications.
  Can generate prompts for v0 and Lovable.
  Output: docs/ui/frontend-spec.md

Winston — Architect
  Designs the technical foundation. Documents every structural decision.
  Chooses the stack based on what your product actually needs.
  Output: docs/architecture/architecture.md

Sarah — Product Owner
  Breaks the PRD and architecture into stories with acceptance criteria.
  Manages the backlog. Plans sprints. Owns the definition of done.
  Output: docs/stories/ and docs/sprints/sprint-[n].md

Max (the orchestrator) routes between them. When you type *plan, Max brings in the right specialist for the current stage. When you type *agent winston, Winston takes over directly.

The six stages

Agile Studio guides you through six stages. Each specialist hands off to the next. You approve each document before the next one begins.

Stage 1 — Discovery (Mary)
  Who is this for? What problem does it solve? What exists already?
  Output: Project Brief

Stage 2 — Product Definition (John)
  What does this product do? What are the goals, constraints, and MVP?
  Output: PRD

Stage 3 — Architecture (Winston)
  What technical foundation does this product need?
  Output: Architecture Document

Stage 4 — UX Specification (Sally)
  What does every screen look like and how does every interaction work?
  Output: Front-end Specification

Stage 5 — Backlog (Sarah)
  What are the specific, testable pieces of work? In what order?
  Output: Stories + Sprint Plans

Stage 6 — Build
  Direct Claude Code to build story by story, verify each one,
  and integrate them into a working system.
  Powered by: ruflo swarm (parallel specialist agents)

At every stage, the relevant specialist explains why their work matters before they begin.

The safety layer

Agile Studio installs six hooks into Claude Code that run automatically throughout your build:

| Hook | When | What it does | |------|------|-------------| | agile-git-safety | Before any bash command | Blocks force-push and hard-reset with uncommitted story work | | agile-destructive-guard | Before any bash command | Blocks rm -rf on project docs and database drops without warning | | agile-pre-build | Before npm run build or deploy | Warns on uncommitted changes; flags stories missing acceptance criteria | | agile-story-guard | After writing to docs/stories/ | Checks that every story has acceptance criteria before saving | | agile-definition-of-done | After editing source files | Surfaces the DoD checklist for the active story | | agile-session-save | After git commit | Saves project state to .agile/state.json for session continuity |

These hooks inform and protect — they don't block legitimate work. The git safety hooks block genuinely destructive operations. Everything else warns and coaches.

The build layer (ruflo)

When you're ready to build, Agile Studio initialises a ruflo swarm — a team of parallel specialist agents that build your stories concurrently within each sprint:

• Coordinator — reads the sprint plan, publishes shared technical context before parallel building begins
• Backend agent — implements data layer and business logic per story acceptance criteria
• UI agent — implements the frontend per Sally's front-end spec and story criteria
• QA agent — verifies acceptance criteria and reports failures in domain language, not technical error messages

Ruflo memory ensures continuity across Claude Code sessions — every agent starts each session knowing the full project state.

Workflows

Agile Studio supports six delivery workflows. Type *workflow to choose, or *plan to let Max route you automatically:

| Workflow | When to use | |----------|-------------| | Greenfield Fullstack | New product, frontend + backend | | Greenfield Service | New backend service or API | | Greenfield UI | New frontend against an existing backend | | Brownfield Fullstack | Adding features to an existing product | | Brownfield Service | Extending an existing backend | | Brownfield UI | Updating the frontend of an existing product |

Each workflow has a fixed specialist sequence. Mary always starts. Sarah always finishes.

Default tech stack

Agile Studio configures a considered default stack that handles 90% of projects well:

| Layer | Technology | Why | |-------|-----------|-----| | Framework | Next.js (App Router) + TypeScript | Server-rendered, fast, well-supported | | Styling | Tailwind CSS v4 | Consistent design without custom CSS | | Components | shadcn/ui | Beautiful, accessible, you own the code | | Database | PostgreSQL via Drizzle | Type-safe, lightweight, build agents know exact data shape | | Testing | Vitest | Fast watch mode, automated acceptance criteria verification | | Auth | NextAuth.js or Clerk | Handles the complexity you don't want to | | Payments | Stripe | The right choice for most use cases | | Email | Resend | Modern, reliable, developer-friendly | | Deploy | Vercel | Zero-configuration deployment |

Winston proposes the stack based on your PRD and project requirements. You approve it in plain language. If your project needs something different, describe the constraint and Winston will adapt.

Project structure

After agile-studio init, your project looks like this:

my-project/
├── CLAUDE.md                          ← Agile build rules for Claude Code
├── .agile/
│   └── state.json                     ← Project state (updated automatically)
└── docs/
    ├── prd/
    │   ├── brief.md                   ← Project Brief (Mary)
    │   └── prd.md                     ← Product Requirements Document (John)
    ├── architecture/
    │   └── architecture.md            ← Architecture Document (Winston)
    ├── ui/
    │   └── frontend-spec.md           ← Front-end Specification (Sally)
    ├── stories/                       ← One file per story (Sarah)
    ├── sprints/                       ← Sprint plans + session briefs
    └── kb/                            ← Agile Studio knowledge base

Commands inside /agile

*plan             Start or resume planning (routes to the right specialist)
*build            Start or resume building with ruflo swarm
*sprint           Sprint planning and management with Sarah
*status           Show full project state and progress
*research         Research and discovery with Mary
*prd              Product requirements with John
*architect        Architecture and technical design with Winston
*ux               UX and front-end specification with Sally
*story            Story writing and refinement with Sarah
*backlog          View and manage the full story backlog
*agent [name]     Activate a specific specialist (mary, john, sally, winston, sarah)
*workflow         Start or resume a workflow (greenfield/brownfield)
*models           View or change model recommendations per stage
*swarm            Initialise ruflo swarm for parallel story execution
*export           Generate Sprint Session Brief → docs/sprints/session-brief-[n].md
*checklist        Run a quality checklist (PRD, architecture, PO master, story validation)
*party            Roundtable with all specialists on a question
*kb               Load the full Agile Studio knowledge base
*help             Show all commands
*reset            Clear state and start over (asks for confirmation)

Other CLI commands

agile-studio status          # Show current project state
agile-studio install-skill   # Reinstall the /agile skill
agile-studio install-hooks   # Reinstall safety hooks

What you'll learn

By the time you've shipped your first product with Agile Studio, you'll understand:

• Why research before requirements prevents expensive rebuilds
• Why architecture decisions made after the PRD are cheaper than ones made during the build
• What makes a user story testable — and why untestable stories stall sprints
• How to describe acceptance criteria precisely enough that an AI verifies them correctly
• How to direct a build across multiple sessions without losing context
• How to catch problems in words before they become problems in code

These are the skills that make you effective at building with a team — AI or human.

Requirements

• Node.js 18+
• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• ruflo MCP configured in Claude Code (for swarm build features)

License

MIT