Guild

A Guild Stack plugin for AI coding hosts that gives you self-evolving teams of specialist agents.

Guild turns a single coding session into a disciplined guild: /guild "<task>" runs intake, binds a workflow class, composes a team, writes per-specialist plans, assembles tight context bundles, dispatches specialists, reviews, verifies, and reflects. Every significant question becomes a structured decision. Every skill edit replaces a named span and keeps a compact history for rollback. Harvest is the only automatic writer; everything else waits for a gate.

What v2 ships

• 15 specialist templates + 4 machinery agents — 15 domain type templates across three groups (engineering: architect, researcher, backend, frontend, devops, qa, mobile, security; content & communication: copywriter, doc-writer, technical-writer, social-media, seo; commercial: marketing, sales), one templates/specialists/*.md per role, minted on demand into your project's .guild/agents/ by team composition — plus the 4 machinery agents the plugin registers directly (advisor, context-manager, developer, team-lead; one agents/*.md each).
• 76 skills, of which 17 are indexed — the host's catalog is exactly 17 assembler skills (using-guild, init, brainstorm, plan, team-compose, execute-plan, quality, operations, learn, wiki, initiative, review, diagnose, evolve, create-skill, create-specialist, reflect). Everything else still ships but stays off the index: L3 chapters live in their parent assembler's references/, the 58 specialist starter recipes live under skills/specialists/, and the dashboard launcher lives under skills/playbooks/dashboard/.
• 13 dispatching command files — bare /guild [brief], the phase verbs /guild:init|ideate|plan|build|qa|ops, /guild:learn, the nouns /guild:wiki|initiative, /guild:status, /guild:config, and /guild:maintain. Sub-verbs are arguments, never files. The dropped v2.6 command files (adopt, audit, dashboard, evolve, fix, goal, migrate, models, resume, rollback, stats) are print-only aliases that name the new spelling. The : plugin namespace stays (Claude Code requires it); every command is /guild:<verb> (v1→v2: https://guildstack.dev/docs/migration-v1-to-v2).
• One runtime shape — bare /guild is the T0 orchestrator session: with no verb it runs intake and binds one of five class graphs (product · research · debug · ops · init); research, debug, and --class= bind the class directly. Work runs in three tiers (T0 → a Team Lead per TaskCell → specialists) that report only through guild.goal_status.v1 and guild.handoff.v2. Each cell runs one inner loop (recall → research-on-miss → implement → verify → harvest) under an enforced budget (advisorRounds, optional token/usd caps). The critic is the advisor machinery agent; product qa is the one review gate.
• Two context sizes — a specialist's on-disk bundle is at most 6k tokens; a parent sees only the lane bundle of at most 1,200 tokens of citations, of which matching .guild/wiki/glossary.md terms take at most 200. The full glossary is never always-on.
• One promotion law — harvest promotes decision-shaped verdicts to this cwd's wiki and span-replaces project playbooks through scrubbedWrite, and never commits. wiki.autopromote defaults on; false makes the root candidates-only. Specialists never write the wiki. The per-phase checkpoint is a domain function that only classifies. Wiki labels.concern uses the shipped enum: architecture · security · performance · reliability · data · api · ux · build · ops.
• 16 supported hosts, one adapter contract — Guild runs across 16 canonical hosts (Claude Code CLI/Desktop/Web, Codex CLI/app, Pi, Antigravity, Cursor, GitHub Copilot, opencode, Rovo Dev, Kiro/Qoder/Trae via AGENTS-file, and the Claude.ai connector) through a single host-adapter contract. Support is described with an honest two-field model — the presentation Support label (Supported / Supported (beta) / Supported (app) / Supported (connector)) is kept separate from the receipt-derived Public State; no host is ever claimed beyond its verified evidence. Missing capabilities degrade to a lesser substrate — the phase still runs and the degradation is written to disk. See the Guild docs site → https://guildstack.dev/hosts.
• 10 hook events wired — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStop, Stop, TaskCreated, TaskCompleted, TeammateIdle.
• Tooling scripts — evolution, rollback, telemetry summary, audit-log summary, Codex review-trail validation, and the opt-in tmux agent-team launcher live under scripts/.
• 2 optional MCP servers — guild-memory (BM25 over the wiki once it crosses ~200 pages) and guild-telemetry (structured trace query), two ids of one compiled runtime/guild-mcp.js built from src/runtime/mcp/. Both stdio-only, no network. Guild runs without them.
• Three execution backends (D5 agent_mode ladder) — tmux visible panes (in-session or detached); InProcessTeamBackend (implemented: orchestrator consumes a declarative dispatchPlan, each specialist runs as an independent Agent-tool call, no tmux required); remote cross-host SSH dispatch; SUBAGENT last resort for CI / fresh installs. See the Guild docs site → https://guildstack.dev/docs/architecture.
• Cost-aware model tiering — cheap / mid / powerful, auto-scored per lane from deterministic signals, with advisor escalation for uncertainty. Zero-config stable. See the Guild docs site → https://guildstack.dev/docs/configuration (models.*).
• Recall — recall.backend: bm25 | hybrid (default bm25). Embeddings are cache only; a missing embedding model fails open to BM25. A lazy SQLite read-through cache sits on platform state, off the repo (index: "auto", default; disable with index: "off").
• Policy-only config, session-bound hosts — durable config holds policy keys only. The host family and the models bind per session on the run record; an unknown host never defaults to Claude.
• O-3 short-output advisor — fires when a lane's output token count falls below calibrated p10 floors (models.shortOutputThreshold). Calibrate with the calibrate-o3-cli tool in the separate guild-benchmark repo. See the Guild docs site → https://guildstack.dev/docs/configuration.
• Security + observability — security.bypass_permissions_policy (capability-scope enforcement), 3-stage secrets redaction (secrets_policy.*), and structured trace cost rollup via the guild-telemetry MCP (trace_cost_rollup). See the Guild docs site → https://guildstack.dev/docs/configuration.

Getting Started

Install

The quickest path is the installer script (install.sh at this repo's root — detects your AI coding hosts, runs the marketplace commands below, never uses sudo, never edits shell profiles):

curl -fsSL https://guildstack.dev/install.sh | bash

Domain unavailable? The same script ships in this repo:

curl -fsSL https://raw.githubusercontent.com/lookatitude/guild/main/install.sh | bash

Preview host-specific install paths without changing anything:

curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host claude-code-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host codex-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host pi-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host antigravity-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host agents-file

Installing manually into Claude Code does exactly the same thing:

claude plugin marketplace add lookatitude/guild
claude plugin marketplace update guild
claude plugin install guild@guild

Release channels — stable vs beta

Branches are distribution channels: main is stable (released versions — what the commands above install) and next is beta — merged work still being tested ahead of the next release. To follow the beta channel:

# Claude Code — pin the marketplace to the next branch:
claude plugin marketplace add lookatitude/guild@next
# marketplace update keeps tracking the pinned next ref:
claude plugin marketplace update guild
claude plugin install guild@guild

# install.sh (any supported host) — same selector:
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel beta

Switch back to stable by re-adding the marketplace without the @next pin (or --channel stable). Beta may contain unreleased behavior; release notes only cover what has reached main.

Staying up to date

Guild detects updates per channel and never phones home during session start: a SessionStart hook reads a machine-level cache (refreshed in the background at most once per defaults.update.cadence_hours, default 24) and prints a one-line signal with the exact update command when your channel has moved — new release tag on stable, new next commit on beta. defaults.update.mode controls it: notify (default), auto (stages the update headlessly; applies next session), or off. Dev checkouts are never touched.

Applying updates per host — the full 16-host registry:

# claude-code-cli (marketplace-managed):
claude plugin marketplace update guild && claude plugin update guild@guild

# Wrapper-package hosts — pi-cli, antigravity-cli, cursor, github-copilot,
# opencode, rovo-dev (installer-managed; needs the receipt):
guild-run update

# codex-cli — Codex OWNS its installed plugin cache, so Guild never swaps it
# (guild-run update refuses and names this instead). Receipted installs
# re-render; host-native installs are detected and told the precise codex
# command for their registered source type:
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update

# File-surface hosts — agents-file, kiro, qoder, trae (snapshot copies):
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update
# …then re-copy the refreshed dist/agents tree into the project.

# Everything with an install receipt, in one go (any host mix):
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update

The four app/connector surfaces (claude-code-app, claude-code-web, codex-app, claude-ai-connector) take no install and therefore no update command; codex-app follows whatever its shared Codex CLI registration does.

Each install writes a guild.install_receipt.v1 (host, channel, ref, commit) under ~/.guild/receipts/ — that receipt is what --update and guild-run update re-render from, keeping every host on the channel it was installed from. A host-native install (e.g. a hand-run codex plugin add) writes no machine receipt: --update will detect it and name that host's real command. The session-start update check mints a package-local receipt for IDENTIFICATION — its channel field is an assumed default, marked as such, and nothing ever clones from it.

Installing manually into Codex CLI uses Codex's plugin manager:

npx tsx scripts/build-host-packages.ts --root . --out dist --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
codex plugin marketplace remove guild || true
codex plugin marketplace add ./dist/codex-marketplace
codex plugin add guild@guild

Restart Claude Code after installation so commands, skills, agents, hooks, and MCP servers are loaded into the next session.

Local development:

git clone https://github.com/lookatitude/guild.git
cd guild
(cd scripts && npm ci && npm run sync:claude-install)
claude plugin marketplace add ./dist/claude-code
claude plugin marketplace update guild
claude plugin install guild@guild --scope project

Use the generated Claude package for development sessions. A dependency-populated checkout contains ignored executable files and is intentionally not accepted as an exact runtime package. Re-run npm run sync:claude-install after changing plugin source so the generated package and its complete identity stay aligned.

Restart Claude Code before running /guild from the project. Claude Code loads plugin commands, agents, skills, hooks, and optional MCP entries at session startup; a newly installed or edited plugin is not fully visible until the next session.

First run

Run /guild with a brief, or with no arguments. A verb is optional: bare /guild runs intake, classifies the work, and proposes the next step for you to confirm:

/guild "Build a Stripe subscription flow, add tests, update the docs, draft a launch email."
/guild

The first visible sign that the plugin loaded is the SessionStart bootstrap card: it lists the Guild version, slash commands, optional MCP servers, and doc entry points. In a Guild root the bootstrap always loads; if the root's .guild/ layout is older, the first write-capable entry upgrades it. The lifecycle starts when you invoke /guild.

The first /guild run writes durable state under .guild/: spec, team, plan, context bundles, run handoffs, review, verification, telemetry, and reflections. You confirm after brainstorm, team-compose, and plan; the later phases run from the approved plan with minimal interruption.

To verify hooks and audit logs are firing after restart:

1. Start a fresh Claude Code session in a project where Guild is installed.
2. Confirm the bootstrap card appears.
3. Run a small /guild "..." task, or use any workflow that dispatches tools.
4. Check for .guild/runs/<run-id>/events.ndjson.
5. For v1.4 audit logging, check .guild/runs/<run-id>/logs/v1.4-events.jsonl for hook_event and, after tool use, tool_call rows.

Older Claude Code hosts may skip newer hook events such as PreToolUse and PreCompact; the handlers are designed to fall through without breaking the session. If the bootstrap card appears but no .guild/runs/ files are written, run /guild:maintain audit and inspect hooks/hooks.json in the installed plugin. If a Guild run failed or telemetry looks inconsistent, run /guild:maintain fix with the run id or a short symptom; it reads recent .guild/runs evidence, writes a diagnosis/fix plan, and asks before applying any edits.

Environment variables

Variable	Default	Meaning
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	unset	Set to 1 to allow Guild's experimental tmux agent-team backend. Subagents via Agent remain the default.
GUILD_LOOP_CAP	unset	Display/override signal for the per-lane adversarial-loop cap. The authoritative cap is the loop_cap key in .guild/settings.json (default 16, clamped to [1, 256]); CLI --loop-cap overrides per run.
GUILD_ENABLE_DEVTEAM_REFLECT	unset/off	Developer-team reflection gate for hooks/maybe-reflect.ts. Set to 1 only when working on Guild's own dev-team reflection workflow.

The agent-team backend is experimental. Enable it only when teammates need to coordinate directly:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Benchmark live runs live in the separate guild-benchmark repo, which owns its own safety gate for spawning the real claude CLI (dry-run first). See that repo for setup, and /guild:status dashboard to launch the benchmark UI against the live project. The plugin only produces the data that UI reads (inventory and run traces); it ships no UI pages of its own.

Optional MCP servers

guild-memory and guild-telemetry ship as stdio MCP servers under mcp-servers/ but are optional — Guild works end-to-end without them. Both ship pre-bundled in runtime/guild-mcp.js, so they cold-start under plain node with no npm install step on first use.

Use guild-memory when the wiki crosses ~200 pages (ripgrep gets slow); use guild-telemetry for structured trace queries over .guild/runs/.

Quickstart

/guild "Build a Stripe subscription flow, add tests, update the docs, draft a launch email."

The session will:

1. Brainstorm the spec and ask blocking questions.
2. Propose a team — gaps become auto-create / skip / substitute / from-scratch prompts.
3. Write per-specialist lanes with depends-on:.
4. Assemble one context bundle per specialist under .guild/context/<run-id>/.
5. Dispatch through the Agent tool (or, with approval, an agent-team tmux session).
6. Review (spec match → quality), verify (tests / scope / success criteria).
7. Reflect on skill gaps; queue evolution proposals.

You confirm after brainstorm, team-compose, and plan. Post-plan runs with minimal interruption.

If you register a new specialist with guild:create-specialist, restart or reload the plugin before expecting /guild:plan (team is composed as a plan sub-step) or future /guild runs to route to it. Claude Code snapshots plugin agent and skill manifests at session startup.

Codex adversarial review is a Guild development discipline, not a default consumer /guild loop. Review trails live under .guild/runs/<run-id>/codex-review/*.md and can be checked with npx tsx scripts/verify-codex-review-trail.ts <codex-review-dir>. The validator currently requires each file's frontmatter to include final_status: satisfied or final_status: skipped-codex-unavailable.

Commands

Every command is /guild:<verb> (the : plugin namespace is required by Claude Code). There are 13 dispatching command files plus 11 print-only aliases; sub-verbs are positional arguments.

Command	Purpose
/guild [brief] [research|debug] [--class=…]	T0 orchestrator session. No verb runs intake and proposes the class and phase for you to confirm; research, debug, and --class= bind the class
/guild:init [--learn] | adopt …	Initialize Guild in a repo (wiki + brownfield cheap-scan map; --learn runs the full learn pipeline); adopt localizes shipped capability
/guild:ideate	Socratic spec — brainstorm the task into .guild/spec/<slug>.md
/guild:plan | goal …	Compose the per-phase team + write per-specialist lane plans; goal emits guild.goal.v1 goals from the spec
/guild:build	Assemble per-specialist context, dispatch the lanes, review handoffs
/guild:qa	The one review gate over the run
/guild:ops	Operations phase — release, monitoring, incident, rollback, maintenance runbooks
/guild:learn [map|graph|knowledge|onboard|diff|explain]	Understand-everything engine; explicit Stage-2 runs extract-structural.ts
/guild:status [resume|stats|dashboard]	Read-only run state; resume continues a run, stats reports usage, dashboard launches the benchmark UI
/guild:wiki <ingest <path>|query "..."|lint>	Project knowledge over .guild/knowledge/sources/ and .guild/wiki/
/guild:initiative <new|status|list|resume|update|archive|restore|close>	Durable multi-run work (opt-in; a one-off /guild never creates one)
/guild:config <init|reconcile|show|set|role|ui|validate|providers|models|migrate>	Policy config; config set rejects host family, host id, and concrete model names
/guild:maintain <evolve|rollback|audit|fix|gc|wiki revert>	Self-heal and RSI; rollback walks a skill back through its compact history

Documentation

Documentation: https://guildstack.dev/docs

The canonical docs live at the Guild docs site (https://guildstack.dev).

• https://guildstack.dev/docs/getting-started — install, first run, and basic configuration.
• https://guildstack.dev/docs/architecture — shipped plugin architecture, directory layout, the v2 single-verb lifecycle phases, hook inventory, backend options.
• https://guildstack.dev/docs/specialist-roster — the 15 domain specialist templates + the 4 machinery agents (advisor, context-manager, developer, team-lead), their triggers, DO NOT TRIGGER boundaries, and owned skills.
• https://guildstack.dev/docs/context-assembly — three-layer context contract, role mapping, ambient-context caveat.
• https://guildstack.dev/docs/wiki-pattern — categorized project memory, sources vs synthesized, decision capture, scale transition.
• https://guildstack.dev/docs/self-evolution — the triggers, the evolve pipeline, promotion gate, compact history + rollback.
• https://guildstack.dev/docs/configuration — the policy config reference: agent_mode, model tiering, SQLite index, security / secrets policy, O-3 calibration, cross-host dispatch.

Architecture at a glance

Four layers: the orchestrator session, the installed plugin (skills, machinery agents, specialist templates, commands, hooks, scripts, MCPs), the composed specialist team in worktree isolation, and project-local state under .guild/ (including the minted specialist instances).

Diagrams and the full walkthroughs — lifecycle, skill taxonomy, project memory, context assembly, team composition, self-evolution, and specialist creation — live on the docs site: https://guildstack.dev/docs.

Runtime state

All project-created Guild state lives under the active root's .guild/ (never committed by Guild itself):

.guild/
├── guild.yaml            # root identity: workspace or project
├── config/project.json   # durable policy only; host and models bind per session
├── settings.json         # reconcile-owned settings surface (/guild:config)
├── agents/               # project-created specialists (files = source of truth)
├── skills/               # project-created skills
├── workflows/            # derived index; the five class graphs are the workflow runtime
├── loops/                # derived index; not authored truth
├── wiki/                 # synthesized knowledge, decisions, standards
├── knowledge/            # graph, indexes, sources/ (ingested blobs), candidates
├── memory/               # summaries, lessons, recall index
├── initiatives/          # initiative registry, active, archived
├── teams/                # reusable team definitions
├── artifacts/            # reports, audits, handoffs, generated outputs
├── indexes/              # codebase map + compatibility indexes
├── runs/                 # run traces, handoff receipts, review, verification
├── spec/                 # approved specs
├── plan/                 # per-task plans
├── team/                 # resolved specialist teams (<slug>.<phase>.yaml)
├── context/              # per-run specialist context bundles
├── reflections/          # proposed learnings and improvements
└── evolve/               # shadow-mode eval runs and reports

Files here are latest-only. Evolve replaces the wrong span and keeps a compact history on platform state, so there is no skill-versions/ tree. Caches and scratch live off the repo.

Principles

Every Guild specialist inherits the same operating prelude, folded into the using-guild skill:

1. Think before doing.
2. Simplicity first.
3. Surgical changes.
4. Goal-driven execution.
5. Evidence over claims.

License

MIT