{ "markdown": "

\n \"Guild\n

\n\n# Guild\n\nA Guild Stack plugin for AI coding hosts that gives you self-evolving teams of specialist agents.\n\nGuild turns a single coding session into a disciplined guild: `/guild \"\"`\nruns brainstorm, composes a team, writes per-specialist plans, assembles tight\ncontext bundles, dispatches specialists, reviews, verifies, and reflects. Every\nsignificant question becomes a structured decision. Every skill edit is a\nversioned artifact with rollback. Nothing durable is written without passing a\ngate.\n\n## What v2 ships\n\n- **15 specialist templates + 3 machinery agents** — 15 domain type templates\n across three groups (engineering: architect, researcher, backend, frontend,\n devops, qa, mobile, security; content & communication: copywriter, doc-writer,\n technical-writer, social-media, seo; commercial: marketing, sales), one\n `templates/specialists/*.md` per role, minted on demand into your project's\n `.guild/agents/` by team composition — plus the 3 machinery agents the plugin\n registers directly (advisor, developer; one `agents/*.md` each).\n- **111 skills** across six tiers — 1 core (`guild-principles`), 39 meta\n (the workflow spine + decisions + reflect + evolve + create-specialist +\n rollback + audit + diagnose + v1.4 loop/review helpers), 11 knowledge\n (wiki ingest / query / lint + the `learn-*` family), 58 specialist skills\n (2–5 per specialist), and the `guild-operations` + `guild-quality` gate skills.\n- **The v2 command surface** — `/guild:guild [brief]` plus the phase verbs\n `/guild:init|ideate|plan|build|qa|ops`, helpers `/guild:status|resume`,\n nouns `/guild:wiki|initiative`, and maintenance\n `/guild:evolve|rollback|stats|audit|fix|migrate`. The `:` plugin namespace\n **stays** (Claude Code requires it) — v2 drops only the redundant `guild-`\n command prefix (v1 `/guild:guild-wiki` → v2 `/guild:wiki`); every command is\n `/guild:` (v1→v2: `https://guildstack.dev/docs/migration-v1-to-v2`).\n- **16 supported hosts, one adapter contract** — Guild runs across 16 canonical\n hosts (Claude Code CLI/Desktop/Web, Codex CLI/app, Pi, Antigravity, Cursor,\n GitHub Copilot, opencode, Rovo Dev, Kiro/Qoder/Trae via AGENTS-file, and the\n Claude.ai connector) through a single host-adapter contract. Support is\n described with an **honest two-field model** — the presentation *Support* label\n (`Supported` / `Supported (beta)` / `Supported (app)` / `Supported (connector)`)\n is kept separate from the receipt-derived *Public State*; no host is ever\n claimed beyond its verified evidence. Missing capabilities **degrade** to a\n lesser substrate — the phase still runs and the degradation is written to disk.\n See the Guild docs site → `https://guildstack.dev/hosts`.\n- **10 hook events wired** — `SessionStart`, `UserPromptSubmit`, `PreToolUse`,\n `PostToolUse`, `PreCompact`, `SubagentStop`, `Stop`, `TaskCreated`,\n `TaskCompleted`, `TeammateIdle`.\n- **Tooling scripts** — evolution, rollback, telemetry summary, audit-log\n summary, Codex review-trail validation, and the opt-in tmux agent-team\n launcher live under `scripts/`.\n- **2 optional MCP servers** — `mcp-servers/guild-memory/` (BM25 over the wiki\n once it crosses ~200 pages) and `mcp-servers/guild-telemetry/` (structured\n trace query). Both stdio-only, no network. Guild runs without them.\n- **Three execution backends** (D5 `agent_mode` ladder) — tmux visible panes\n (in-session or detached); `InProcessTeamBackend` (implemented: orchestrator\n consumes a declarative `dispatchPlan`, each specialist runs as an independent\n Agent-tool call, no tmux required); remote cross-host SSH dispatch; `SUBAGENT`\n last resort for CI / fresh installs. See the Guild docs site → `https://guildstack.dev/docs/architecture`.\n- **Cost-aware model tiering** — cheap / mid / powerful, auto-scored per lane\n from deterministic signals, with advisor escalation for uncertainty.\n Zero-config stable. See the Guild docs site → `https://guildstack.dev/docs/configuration` (`models.*`).\n- **SQLite read-through wiki cache** — lazy-build, opt-in (`index: \"auto\"`,\n default). Direct-parse below threshold; disable with `index: \"off\"`.\n See the Guild docs site → `https://guildstack.dev/docs/configuration` (`defaults.index.*`).\n- **O-3 short-output advisor** — fires when a lane's output token count falls\n below calibrated p10 floors (`models.shortOutputThreshold`). Calibrate with\n the `calibrate-o3-cli` tool in the separate `guild-benchmark` repo.\n See the Guild docs site → `https://guildstack.dev/docs/configuration`.\n- **Security + observability** — `security.bypass_permissions_policy`\n (capability-scope enforcement), 3-stage secrets redaction\n (`secrets_policy.*`), and structured trace cost rollup via the\n `guild-telemetry` MCP (`trace_cost_rollup`).\n See the Guild docs site → `https://guildstack.dev/docs/configuration`.\n\n## Getting Started\n\n### Install\n\nThe quickest path is the installer script (`install.sh` at this repo's root —\ndetects your AI coding hosts, runs the marketplace commands below, never uses\n`sudo`, never edits shell profiles):\n\n```bash\ncurl -fsSL https://guildstack.dev/install.sh | bash\n```\n\nDomain unavailable? The same script ships in this repo:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/lookatitude/guild/main/install.sh | bash\n```\n\nPreview host-specific install paths without changing anything:\n\n```bash\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host claude-code-cli\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host codex-cli\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host pi-cli\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host antigravity-cli\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host agents-file\n```\n\nInstalling manually into Claude Code does exactly the same thing:\n\n```bash\nclaude plugin marketplace add lookatitude/guild\nclaude plugin marketplace update guild\nclaude plugin install guild@guild\n```\n\n### Release channels — stable vs beta\n\nBranches are distribution channels: **`main` is stable** (released versions —\nwhat the commands above install) and **`next` is beta** — merged work still\nbeing tested ahead of the next release. To follow the beta channel:\n\n```bash\n# Claude Code — pin the marketplace to the next branch:\nclaude plugin marketplace add lookatitude/guild@next\n# marketplace update keeps tracking the pinned next ref:\nclaude plugin marketplace update guild\nclaude plugin install guild@guild\n\n# install.sh (any supported host) — same selector:\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel beta\n```\n\nSwitch back to stable by re-adding the marketplace without the `@next` pin (or\n`--channel stable`). Beta may contain unreleased behavior; release notes only\ncover what has reached `main`.\n\n### Staying up to date\n\nGuild detects updates per channel and never phones home during session start:\na SessionStart hook reads a machine-level cache (refreshed in the background at\nmost once per `defaults.update.cadence_hours`, default 24) and prints a one-line\nsignal with the exact update command when your channel has moved — new release\ntag on stable, new `next` commit on beta. `defaults.update.mode` controls it:\n`notify` (default), `auto` (stages the update headlessly; applies next\nsession), or `off`. Dev checkouts are never touched.\n\nApplying updates per host — the full 16-host registry:\n\n```bash\n# claude-code-cli (marketplace-managed):\nclaude plugin marketplace update guild && claude plugin update guild@guild\n\n# Wrapper-package hosts — pi-cli, antigravity-cli, cursor, github-copilot,\n# opencode, rovo-dev (installer-managed; needs the receipt):\nguild-run update\n\n# codex-cli — Codex OWNS its installed plugin cache, so Guild never swaps it\n# (guild-run update refuses and names this instead). Receipted installs\n# re-render; host-native installs are detected and told the precise codex\n# command for their registered source type:\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --update\n\n# File-surface hosts — agents-file, kiro, qoder, trae (snapshot copies):\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --update\n# …then re-copy the refreshed dist/agents tree into the project.\n\n# Everything with an install receipt, in one go (any host mix):\ncurl -fsSL https://guildstack.dev/install.sh | bash -s -- --update\n```\n\nThe four app/connector surfaces (`claude-code-app`, `claude-code-web`,\n`codex-app`, `claude-ai-connector`) take no install and therefore no update\ncommand; `codex-app` follows whatever its shared Codex CLI registration does.\n\nEach install writes a `guild.install_receipt.v1` (host, channel, ref, commit)\nunder `~/.guild/receipts/` — that receipt is what `--update` and `guild-run\nupdate` re-render from, keeping every host on the channel it was installed\nfrom. A **host-native** install (e.g. a hand-run `codex plugin add`) writes no\nmachine receipt: `--update` will detect it and name that host's real command.\nThe session-start update check mints a package-local receipt for\nIDENTIFICATION — its channel field is an assumed default, marked as such, and\nnothing ever clones from it.\n\nInstalling manually into Codex CLI uses Codex's plugin manager:\n\n```bash\nnpx tsx scripts/build-host-packages.ts --root . --out dist --generated-at \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"\ncodex plugin marketplace remove guild || true\ncodex plugin marketplace add ./dist/codex-marketplace\ncodex plugin add guild@guild\n```\n\nRestart Claude Code after installation so commands, skills, agents, hooks, and\nMCP servers are loaded into the next session.\n\nLocal development:\n\n```bash\ngit clone https://github.com/lookatitude/guild.git\ncd guild\n(cd scripts && npm ci && npm run sync:claude-install)\nclaude plugin marketplace add ./dist/claude-code\nclaude plugin marketplace update guild\nclaude plugin install guild@guild --scope project\n```\n\nUse the generated Claude package for development sessions. A dependency-populated\ncheckout contains ignored executable files and is intentionally not accepted as an\nexact runtime package. Re-run `npm run sync:claude-install` after changing plugin\nsource so the generated package and its complete identity stay aligned.\n\nRestart Claude Code before running `/guild` from the project. Claude Code loads\nplugin commands, agents, skills, hooks, and optional MCP entries at session\nstartup; a newly installed or edited plugin is not fully visible until the next\nsession.\n\n### First run\n\nRun `/guild` with a brief, or run it with no arguments and let the brainstorm\nskill prompt for the task:\n\n```text\n/guild \"Build a Stripe subscription flow, add tests, update the docs, draft a launch email.\"\n/guild\n```\n\nThe first visible sign that the plugin loaded is the SessionStart bootstrap card:\nit lists the Guild version, slash commands, optional MCP servers, and doc entry\npoints. The card is informational only. The lifecycle starts when you invoke\n`/guild`.\n\nThe first `/guild` run writes durable state under `.guild/`: spec, team, plan,\ncontext bundles, run handoffs, review, verification, telemetry, and reflections.\nYou confirm after brainstorm, team-compose, and plan; the later phases run from\nthe approved plan with minimal interruption.\n\nTo verify hooks and audit logs are firing after restart:\n\n1. Start a fresh Claude Code session in a project where Guild is installed.\n2. Confirm the bootstrap card appears.\n3. Run a small `/guild \"...\"` task, or use any workflow that dispatches tools.\n4. Check for `.guild/runs//events.ndjson`.\n5. For v1.4 audit logging, check `.guild/runs//logs/v1.4-events.jsonl`\n for `hook_event` and, after tool use, `tool_call` rows.\n\nOlder Claude Code hosts may skip newer hook events such as `PreToolUse` and\n`PreCompact`; the handlers are designed to fall through without breaking the\nsession. If the bootstrap card appears but no `.guild/runs/` files are written,\nrun `/guild:audit` and inspect `hooks/hooks.json` in the installed plugin.\nIf a Guild run failed or telemetry looks inconsistent, run `/guild:fix`\nwith the run id or a short symptom; it reads recent `.guild/runs` evidence,\nwrites a diagnosis/fix plan, and asks before applying any edits.\n\n### Environment variables\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | unset | Set to `1` to allow Guild's experimental tmux agent-team backend. Subagents via `Agent` remain the default. |\n| `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. |\n| `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. |\n\nThe agent-team backend is experimental. Enable it only when teammates need to\ncoordinate directly:\n\n```bash\nexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\n```\n\nBenchmark live runs live in the separate `guild-benchmark` repo, which owns its\nown safety gate for spawning the real `claude` CLI (dry-run first). See that\nrepo for setup, and `/guild:dashboard` to launch the benchmark UI against the\nlive project.\n\n### Optional MCP servers\n\n`guild-memory` and `guild-telemetry` ship as stdio MCP servers under\n`mcp-servers/` but are **optional** — Guild works end-to-end without them.\nBoth ship pre-bundled (`dist/index.js`), so they cold-start under plain\n`node` with no `npm install` step on first use.\n\nUse `guild-memory` when the wiki crosses ~200 pages (ripgrep gets slow);\nuse `guild-telemetry` for structured trace queries over `.guild/runs/`.\n\n## Quickstart\n\n```text\n/guild \"Build a Stripe subscription flow, add tests, update the docs, draft a launch email.\"\n```\n\nThe session will:\n\n1. Brainstorm the spec and ask blocking questions.\n2. Propose a team — gaps become auto-create / skip / substitute / from-scratch prompts.\n3. Write per-specialist lanes with `depends-on:`.\n4. Assemble one context bundle per specialist under `.guild/context//`.\n5. Dispatch through the Agent tool (or, with approval, an agent-team tmux session).\n6. Review (spec match → quality), verify (tests / scope / success criteria).\n7. Reflect on skill gaps; queue evolution proposals.\n\nYou confirm after brainstorm, team-compose, and plan. Post-plan runs with\nminimal interruption.\n\nIf you register a new specialist with `guild:create-specialist`, restart or\nreload the plugin before expecting `/guild:plan` (team is composed as a plan sub-step) or future `/guild` runs to\nroute to it. Claude Code snapshots plugin agent and skill manifests at session\nstartup.\n\nCodex adversarial review is a Guild development discipline, not a default\nconsumer `/guild` loop. Review trails live under\n`.guild/runs//codex-review/*.md` and can be checked with\n`npx tsx scripts/verify-codex-review-trail.ts `. The validator\ncurrently requires each file's frontmatter to include `final_status: satisfied` or\n`final_status: skipped-codex-unavailable`.\n\n## Commands\n\nEvery command is `/guild:` (the `:` plugin namespace is required by Claude\nCode). The bare `/guild [brief]` is the smart entry point; the phase verbs, nouns,\nand maintenance verbs are separate commands.\n\n| Command | Purpose |\n|---|---|\n| `/guild [brief]` | Bare entry — smart **phase detection**: inspects `.guild/` state and proposes the next lifecycle phase (init · ideate · plan · build · qa · ops), always confirmed, never silent |\n| `/guild:init` | Initialize Guild in a repo (wiki + brownfield cheap-scan map; `--learn` runs the full learn pipeline) |\n| `/guild:ideate` | Socratic spec — brainstorm the task into `.guild/spec/.md` |\n| `/guild:plan` | Compose the team + write per-specialist lane plans; `--team-size=N` lifts the 6-specialist cap |\n| `/guild:build` | Assemble per-specialist context, dispatch the lanes, review handoffs |\n| `/guild:qa` | Quality gate over the run |\n| `/guild:ops` | Operations phase — release, monitoring, incident, rollback runbooks |\n| `/guild:learn [map\\|graph\\|onboard\\|diff\\|explain]` | Understand-everything engine — codebase map, deep knowledge graph, onboarding tour, diff/blast-radius, file/module explain |\n| `/guild:status` | Read-only: current phase, next gate, blockers, resume hint |\n| `/guild:resume` | Resume an interrupted run from its furthest phase |\n| `/guild:wiki \\|query \"...\"\\|lint>` | Project knowledge over `.guild/raw/` and `.guild/wiki/` |\n| `/guild:initiative ` | Durable multi-run work (opt-in; a one-off `/guild` never creates one) |\n| `/guild:goal` | Create/inspect P.O.V.E.R. goals + host-portable task groups |\n| `/guild:config ` | Manage the `.guild/settings.json` config surface |\n| `/guild:evolve [] [--auto] [--to-template=vN]` | Run a skill through the evolve pipeline (paired evals → flip report → shadow mode → promotion gate) |\n| `/guild:rollback [n]` | Walk a skill back `n` versions from `.guild/skill-versions/` |\n| `/guild:stats` | Usage, success rates, flip counts, top-used skills, top-requested specialists |\n| `/guild:audit` | Security audit of installed scripts, hooks, permissions |\n| `/guild:fix [run-id \\| \"symptom\"] [--review=cross]` | Diagnose Guild runtime failures from telemetry and propose a gated self-fix plan |\n| `/guild:migrate` | v1→v2 `.guild/` converter (dry-run by default) |\n| `/guild:dashboard` | Launch the observability / benchmark dashboard |\n\n## Documentation\n\n**Documentation: https://guildstack.dev/docs**\n\nThe canonical docs live at the **Guild docs site** (`https://guildstack.dev`).\n\n- `https://guildstack.dev/docs/getting-started` — install, first run, and basic configuration.\n- `https://guildstack.dev/docs/architecture` — shipped plugin architecture, directory layout, the v2 single-verb lifecycle phases, hook inventory, backend options.\n- `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.\n- `https://guildstack.dev/docs/context-assembly` — three-layer context contract, role mapping, ambient-context caveat.\n- `https://guildstack.dev/docs/wiki-pattern` — categorized project memory, raw vs synthesized, decision capture, scale transition.\n- `https://guildstack.dev/docs/self-evolution` — the two triggers, the 10-step pipeline, promotion gate, versioning + rollback.\n- `https://guildstack.dev/docs/configuration` — complete `settings.json` reference: `agent_mode`, model tiering, SQLite index, security / secrets policy, O-3 calibration, cross-host dispatch.\n\n## Architecture at a glance\n\nFour layers: the orchestrator session, the installed plugin (skills, machinery\nagents, specialist templates, commands, hooks, scripts, MCPs), the composed\nspecialist team in worktree isolation, and project-local state under `.guild/`\n(including the minted specialist instances).\n\nDiagrams and the full walkthroughs — lifecycle, skill taxonomy, project memory,\ncontext assembly, team composition, self-evolution, and specialist creation —\nlive on the docs site: **https://guildstack.dev/docs**.\n\n## Runtime state\n\nAll project-created Guild state lives under the active root's `.guild/` (never\ncommitted by Guild itself):\n\n```text\n.guild/\n├── guild.yaml # root identity: workspace or project\n├── settings.json # project/workspace behavior (the config surface)\n├── agents/ # project-created specialists (files = source of truth)\n├── skills/ # project-created skills\n├── workflows/ # reusable workflows\n├── loops/ # custom review/build/learning loops\n├── wiki/ # synthesized knowledge, decisions, standards\n├── knowledge/ # graph, indexes, sources, promotion candidates\n├── memory/ # summaries, lessons, recall index\n├── initiatives/ # initiative registry, active, archived\n├── teams/ # reusable team definitions\n├── artifacts/ # reports, audits, handoffs, generated outputs\n├── raw/ # immutable source inputs + checksums\n├── indexes/ # codebase map + compatibility indexes\n├── runs/ # run traces, handoff receipts, review, verification\n├── spec/ # approved specs\n├── plan/ # per-task plans\n├── team/ # resolved specialist teams (..yaml)\n├── context/ # per-run specialist context bundles\n├── reflections/ # proposed learnings and improvements\n├── evolve/ # shadow-mode eval runs and reports\n└── skill-versions/ # rollback snapshots\n```\n\n## Principles\n\nEvery Guild specialist inherits the same operating prelude (`skills/core/principles/`):\n\n1. Think before doing.\n2. Simplicity first.\n3. Surgical changes.\n4. Goal-driven execution.\n5. Evidence over claims.\n\n## License\n\nMIT\n", "bytes": 21212, "sha": "b59a20aeb5159f103cb227e2becfdcb31d8bbbdd853d372e3e46b65752de0bd1", "repo_slug": "lookatitude/guild", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_lookatitude_guild_guild_2da204cd/readme" }