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 brainstorm, 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 is a versioned artifact with rollback. Nothing durable is written without passing a gate.

• 15 specialist templates + 3 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 3 machinery agents the plugin registers directly (advisor, developer; one agents/*.md each).
• 111 skills across six tiers — 1 core (guild-principles), 39 meta (the workflow spine + decisions + reflect + evolve + create-specialist + rollback + audit + diagnose + v1.4 loop/review helpers), 11 knowledge (wiki ingest / query / lint + the learn-* family), 58 specialist skills (2–5 per specialist), and the guild-operations + guild-quality gate skills.
• The v2 command surface — /guild:guild [brief] plus the phase verbs /guild:init|ideate|plan|build|qa|ops, helpers /guild:status|resume, nouns /guild:wiki|initiative, and maintenance /guild:evolve|rollback|stats|audit|fix|migrate. The : plugin namespace stays (Claude Code requires it) — v2 drops only the redundant guild- command prefix (v1 /guild:guild-wiki → v2 /guild:wiki); every command is /guild:<verb> (v1→v2: https://guildstack.dev/docs/migration-v1-to-v2).
• 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 — mcp-servers/guild-memory/ (BM25 over the wiki once it crosses ~200 pages) and mcp-servers/guild-telemetry/ (structured trace query). 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.*).
• SQLite read-through wiki cache — lazy-build, opt-in (index: "auto", default). Direct-parse below threshold; disable with index: "off". See the Guild docs site → https://guildstack.dev/docs/configuration (defaults.index.*).
• 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.

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

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.

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
claude plugin marketplace add .
claude plugin marketplace update guild
claude plugin install guild@guild --scope project

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.

Run /guild with a brief, or run it with no arguments and let the brainstorm skill prompt for the task:

/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. The card is informational only. 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:audit and inspect hooks/hooks.json in the installed plugin. If a Guild run failed or telemetry looks inconsistent, run /guild: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.

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:dashboard to launch the benchmark UI against the live project.

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 (dist/index.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/.

/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.

Every command is /guild:<verb> (the : plugin namespace is required by Claude Code). The bare /guild [brief] is the smart entry point; the phase verbs, nouns, and maintenance verbs are separate commands.

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 3 machinery agents (advisor, context-manager, developer), 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, raw vs synthesized, decision capture, scale transition.
• https://guildstack.dev/docs/self-evolution — the two triggers, the 10-step pipeline, promotion gate, versioning + rollback.
• https://guildstack.dev/docs/configuration — complete settings.json reference: agent_mode, model tiering, SQLite index, security / secrets policy, O-3 calibration, cross-host dispatch.

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.

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
├── settings.json         # project/workspace behavior (the config surface)
├── agents/               # project-created specialists (files = source of truth)
├── skills/               # project-created skills
├── workflows/            # reusable workflows
├── loops/                # custom review/build/learning loops
├── wiki/                 # synthesized knowledge, decisions, standards
├── knowledge/            # graph, indexes, sources, promotion candidates
├── memory/               # summaries, lessons, recall index
├── initiatives/          # initiative registry, active, archived
├── teams/                # reusable team definitions
├── artifacts/            # reports, audits, handoffs, generated outputs
├── raw/                  # immutable source inputs + checksums
├── 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
└── skill-versions/       # rollback snapshots

Every Guild specialist inherits the same operating prelude (skills/core/principles/):

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

MIT