Guild

Guild makes Claude Code think before it builds.

Guild is a spec-driven development CLI for Claude Code. It installs structured design and development workflows as .claude/ markdown files in any project. Before code is written, features are evaluated, debated by independent AI perspectives, and specified in a design doc. Everything is markdown, tracked by git, works offline, zero infrastructure.

The Problem

Without structure, Claude Code:

• Writes code before understanding the problem
• Has no design phase and no review gate
• Loses decisions between sessions
• Produces results that vary with every conversation

How Guild Solves It

• Spec before code: every feature starts with a design doc
• Structured deliberation: /council runs parallel independent analysis -- multiple perspectives evaluate independently, then synthesize
• Decisions that persist: design docs, session state, and project context live in git-tracked markdown
• Zero infrastructure: no servers, no APIs, just markdown files and Claude Code

Quick Start

npm install -g guild-agents
guild init

Then use skills as slash commands in Claude Code:

/guild-specialize        # Learn your codebase, enrich CLAUDE.md
/council "Add JWT auth"  # Spec a feature through structured deliberation
/build-feature           # Implement from spec through the full pipeline

The Pipeline

You ──> /council "Add JWT auth"
         │
         ▼
    ┌──────────┐     ┌──────────────┐     ┌──────────┐
    │ Evaluate │────>│  Design Doc  │────>│  Build   │
    │ debate   │     │  spec        │     │ implement│
    └──────────┘     └──────────────┘     └────┬─────┘
                                               │
                                         ┌─────┴─────┐
                                         ▼           ▼
                                   ┌──────────┐┌──────────┐
                                   │  Review  ││    QA    │
                                   └──────────┘└──────────┘

Six phases: evaluate, specify, plan, implement, review, validate. Phases 1-3 happen before any code is written.

Skills Reference

All 15 skills, grouped by function:

| Skill | Group | Description | | --- | --- | --- | | /build-feature | Pipeline | Full pipeline: evaluate, spec, implement, review, QA | | /new-feature | Pipeline | Create branch and scaffold for a new feature | | /create-pr | Pipeline | Create a structured pull request from current branch | | /council | Decision | Multi-perspective deliberation on a decision or feature | | /review | Quality | Code review on the current diff | | /qa-cycle | Quality | QA and bugfix loop until clean | | /tdd | Discipline | TDD red-green-refactor cycle | | /debug | Discipline | Systematic 4-phase debugging | | /verify | Discipline | Evidence-before-claims verification | | /guild-specialize | Context | Explore codebase, enrich CLAUDE.md with real conventions | | /re-specialize | Context | Incremental update of auto-generated CLAUDE.md zones | | /session-start | Context | Load context and resume work | | /session-end | Context | Save state to SESSION.md | | /status | Context | Project and session state overview | | /dev-flow | Context | Show current pipeline phase and next step |

CLI Commands

guild init              # Interactive project onboarding
guild new-agent <name>  # Create a custom agent
guild status            # Show project status
guild doctor            # Diagnose setup
guild list              # List agents and skills
guild run <skill>       # Preview a skill's execution plan (dry-run)
guild logs              # View execution traces
guild logs clean        # Remove old traces (--days N, --all)
guild workspace init <name> <members...>  # Create a workspace
guild workspace add <path>                # Add a member repo
guild workspace status                    # Show workspace state

Under the Hood

Guild coordinates 10 specialized agents through the pipeline. Each agent handles one phase.

| Agent | Role | | --- | --- | | advisor | Evaluates ideas and provides strategic direction | | product-owner | Turns approved ideas into concrete tasks | | tech-lead | Defines technical approach and architecture | | developer | Implements features following project conventions | | code-reviewer | Reviews quality, patterns, and technical debt | | qa | Testing, edge cases, regression validation | | bugfix | Bug diagnosis and resolution | | db-migration | Schema changes and safe migrations | | platform-expert | Diagnoses Claude Code integration issues | | learnings-extractor | Extracts compound learnings from pipeline executions |

Agents are flat .md files with identity and expertise. Skills orchestrate agents through structured pipelines. Everything lives in .claude/, readable by humans, tracked by git.

Guild Builds Itself

Every feature in Guild goes through the same spec-first pipeline that Guild installs in your project. Guild's own design decisions live in docs/specs/.

Requirements

• Node.js >= 20
• Claude Code
• gh CLI (optional, for GitHub integration)

Contributing

See CONTRIBUTING.md for setup, branching, and contribution guidelines.

License

MIT -- see LICENSE.