Operate Guild with visible contracts

Quick start

Install Guild

Guild is installed through the Claude Code plugin marketplace. Restart Claude Code after installation so commands, skills, agents, hooks, and MCP servers hydrate in the next session.

claude plugin marketplace add lookatitude/guild
claude plugin marketplace update guild
claude plugin install guild@guild --scope project
# Restart Claude Code before running /guild

The experimental agent-team backend is opt-in. Use it only for tasks where teammates need direct coordination.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Workflow

The `/guild` lifecycle

The lifecycle is contract-heavy at the beginning and evidence-heavy at the end. The user confirms after brainstorm, team-compose, and plan; post-plan execution runs with minimal interruption.

1. Brainstorm. Capture goals, audience, success criteria, non-goals, constraints, autonomy policy, and risks.
2. Team-compose. Select the smallest useful specialist team and surface coverage gaps before dispatch.
3. Plan. Write per-specialist lanes with dependencies, scope, outputs, and success criteria.
4. Context-assemble. Build one compact task brief per specialist under .guild/context/<run-id>/.
5. Execute-plan. Dispatch specialists through subagents by default, or agent-team when explicitly enabled.
6. Review and verify. Consume handoff receipts, run evidence checks, and compare outputs to the approved spec.
7. Reflect. File proposed skill or specialist improvements without auto-promoting them.

Roster

Thirteen specialists, composed per task

The recommended default is 3-4 specialists, with a hard cap of 6 unless the user explicitly allows a larger team. The full live roster is generated in the Reference.

Context assembly

Three layers, one specialist brief

The target is roughly 3k tokens per specialist bundle, with a 6k hard cap. The bundle is a context contract rather than a hard security boundary.

Project memory

Raw sources stay separate from synthesized knowledge

Guild stores mutable project-local state under .guild/. Raw inputs are immutable and checksum-friendly; wiki pages promote useful knowledge with source references, confidence, and category. Decisions are captured when specialists ask questions and get answers.

Self-evolution

Skills change only through evidence gates

Guild evolves through automatic reflection accumulation or explicit /guild:evolve. Proposed behavior is compared against current behavior, summarized in a flip report, replayed in shadow mode, and promoted only when the evidence clears the gate.

Runtime state

What Guild writes in a consuming repo

.guild/
├── raw/                 # immutable source inputs + checksums
├── wiki/                # synthesized memory, decisions, standards
├── spec/                # approved specs
├── plan/                # per-task plans
├── team/                # resolved specialist teams
├── context/             # per-run specialist context bundles
├── runs/                # telemetry, handoff receipts, assumptions
├── reflections/         # proposed skill and specialist edits
├── evolve/              # shadow-mode eval runs and reports
└── skill-versions/      # rollback snapshots