Command Reference
All Guild commands follow the flat /guild:<verb> pattern. The main entry point is /guild:guild [brief] — it runs the full lifecycle from whatever phase your project is currently at.
The : plugin namespace is a Claude Code requirement and stays in v2; the redundant guild- prefix from v1 is dropped (e.g., /guild:guild-wiki → /guild:wiki). Sub-verbs (wiki ingest, config init, learn map) are positional arguments to the command, never separate command files or nested namespaces.
Skills (guild:brainstorm, guild:plan, etc.) are model-invoked, never typed by the user. The command /guild:<token> and the skill guild:<token> share a stem but are distinct surfaces.
Main lifecycle command
| Command | Description |
|---|---|
/guild:guild [brief] | Run the full lifecycle from the current phase. Proposes a phase and asks before proceeding — never silent. Accepts an optional brief as a quoted string. |
Phase detection: bare /guild:guild surfaces a phase-detection prompt. To start at
a specific phase, use a phase subcommand (see below) or pass --rigor=quick|standard|deep.
Phase subcommands
Each phase command is a thin entrypoint that invokes its skill(s) in order. See the phase-to-skill dispatch table for the exact skill chain.
| Command | Phase | What it does |
|---|---|---|
/guild:init | Init | Bootstrap the project wiki, CodebaseMap stub, and architecture-map. Full learn-* pipeline only under --learn or defaults.auto_learn: true. |
/guild:ideate | Brainstorm | Generate the spec. With --rigor=deep, wraps in guild:loop-clarify. |
/guild:plan | Plan | Compose the team and write the plan. With --rigor=deep, + guild:loop-plan-review. Team composition is a sub-step here (not a separate command). |
/guild:build | Build | Execute per-lane: context-assemble → execute-plan → review. With --rigor=deep, + guild:loop-implement. |
/guild:qa | Quality | Run the full guild:quality skill — auto-selects and executes E2E/smoke/a11y/perf/integration checks from CodebaseMap + plan signals. |
/guild:ops | Operations | Run the full guild:operations skill — executes release/monitoring/incident/rollback/maintenance runbooks under a split autonomy posture with four safety rails. |
Learn command
| Command | Sub-verb | What it does |
|---|---|---|
/guild:learn | (required) | The understand-everything pipeline. Sub-verbs are positional arguments. |
/guild:learn map | map | Build a brownfield CodebaseMap. |
/guild:learn graph | graph | Build the deep knowledge-graph. |
/guild:learn onboard | onboard | Generate an onboarding document for new contributors. |
/guild:learn diff | diff | Explain recent changes from the git diff. |
/guild:learn explain | explain | Explain a specified component or file in depth. |
/guild:learn is the same pipeline as /guild:init --learn — one implementation, two
entry points.
Status and session commands
| Command | Description |
|---|---|
/guild:status | Show the active run’s state: current phase, team composition, last gate outcome. Replaces the v1 /guild:guild-team show. |
/guild:resume | Resume a paused or interrupted run. Use --restart to force a fresh loop from the current phase. |
Wiki commands
| Command | Description |
|---|---|
/guild:wiki ingest | Ingest a source document into the project wiki at .guild/wiki/. Applies the anomaly gate (models.ingestSimilarityGate) before writing. |
/guild:wiki query | BM25 search over the wiki. Returns matching pages ranked by relevance. |
/guild:wiki lint | Validate wiki pages for structure, missing fields, and expired entries. |
Config commands
| Command | Description |
|---|---|
/guild:config init | Scaffold .guild/settings.json with all keys and a self-documenting _help block. |
/guild:config show | Print the resolved config — merged defaults + file + CLI flags. |
/guild:config validate | Validate settings.json against the closed-key set; exit non-zero on violation. |
/guild:config update-mcp-hashes | Re-pin MCP tool description hashes in mcp.tool_description_hashes. |
See the Configuration Reference for the full settings.json key set.
Initiative commands
Initiatives are opt-in durable work scopes. One-off runs remain first-class; an initiative attaches only on explicit request.
| Command | Description |
|---|---|
/guild:initiative new | Create a new named initiative and attach the current session to it. |
/guild:initiative status | Show the active initiative’s state, spec, and plan. |
/guild:initiative resume | Resume the current or a named initiative. |
/guild:initiative update | Update the initiative’s definition ledger. |
/guild:initiative close | Close the current initiative and archive its artifacts. |
Maintenance commands
| Command | Description |
|---|---|
/guild:fix [run-id | "symptom"] | Diagnose and fix a failed or stuck run. Pass a run-id or a symptom description. Use --review=cross to engage the Codex adversarial broker. (Renamed from v1 /guild:guild-diagnose.) |
/guild:evolve [skill] [--auto] | Run the skill evolution pipeline for a named skill. --auto skips the confirmation gate. See self-evolving skills. |
/guild:rollback <skill> [n] | Roll back a skill to a previous version. n specifies how many versions back (default: 1). |
/guild:stats | Print run stats: lane counts, model tier distribution, skill usage. |
/guild:audit | Run static boundary-check and hook registration audit. Flags any Guild-owned files written outside .guild/. |
Global flags
These flags apply to the main /guild:guild command and most phase subcommands.
| Flag | Values | Description |
|---|---|---|
--rigor | quick | standard | deep | Expand into loop/cap/review settings. deep = loops=all, cap=16, review=cross. Supersedes the v1 --loops, --loop-cap, --codex-cap flags. |
--model-tier | cheap | mid | powerful | Pin the model tier for this run. Top of the cost-tiering precedence ladder. |
--review | local | cross | off | Review broker mode. cross = Claude↔Codex adversarial review at G-spec, G-plan, and G-lane gates. |
--auto-approve | spec,plan,build,all | Comma-separated list of gates to skip the user-approval pause. Destructive, network, spend, and Quality BLOCK-override actions always prompt. No qa or ops token — Quality/Operations auto-pass only under all. |
--agent-mode | team | agent | subagent | auto | Pin the execution backend for this run. |
--team-size | integer | Override the team size cap (default: 4; hard max: 6). |
--learn | (flag) | Run the full learn-* pipeline during /guild:init. Equivalent to defaults.auto_learn: true. |
--dry-run | (flag) | Simulate the run without writing artifacts or executing code. |
--statusline | (flag) | Enable the status-line output for this run. |
--initiative | string | Attach this run to a named initiative. |
Phase-to-skill dispatch
Each phase command invokes its skills in order. Skills are model-invoked — the user never types them directly.
| Phase command | Skills invoked (in order) | Output artifacts |
|---|---|---|
/guild:init | guild:init (cheap by default: wiki + brownfield cheap-scan CodebaseMap + architecture-map stub) — full learn-* pipeline ONLY under --learn / defaults.auto_learn | .guild/init/<slug>.md, .guild/wiki/**, codebase-map.json + architecture-map.md stub |
/guild:ideate | guild:brainstorm (deep: wrapped by guild:loop-clarify) | .guild/spec/<slug>.md |
/guild:plan | guild:team-compose → guild:plan (deep: + guild:loop-plan-review) | .guild/team/<slug>.yaml, .guild/prd/<slug>.md, .guild/plan/<slug>.md |
/guild:build | per lane: guild:context-assemble → guild:execute-plan → guild:review (deep: + guild:loop-implement) | handoff receipts, assumptions.md, review.md |
/guild:qa | guild:quality | .guild/runs/<run-id>/quality/<run-id>.md |
/guild:ops | guild:operations | .guild/runs/<run-id>/ops/<run-id>.md |
/guild:learn | guild:learn-map / learn-graph / learn-onboard / learn-diff / learn-explain (sub-verb selects) | deep knowledge-graph + onboarding / diff / explain artifacts |
Codex adversarial review gates
Cross-host review (--review=cross) runs at three gates:
| Gate | Timing |
|---|---|
| G-spec | After guild:brainstorm writes the spec, before guild:team-compose. |
| G-plan | After guild:plan writes the plan, before the user-approval gate. |
| G-lane | After each lane’s handoff receipt is written, before the next lane dispatches. |
Loop cap: 5 rounds (configurable via --codex-cap=N or settings.json key codex_cap). On round 6, prompts with: force-pass / extend-cap / rework.
If Codex is unavailable, the gate emits a warning and proceeds — no hard-block on Codex outages.
v1 redirect stubs (v2.0.x only)
These v1 command names print a redirect message and exit non-zero. They run nothing. Redirect stubs are deleted at v2.1.0.
| v1 command | v2 replacement | Redirect behavior |
|---|---|---|
/guild:guild-wiki | /guild:wiki <ingest|query|lint> | Prints rename notice + prefix-drop explanation. |
/guild:guild-evolve | /guild:evolve [skill] [--auto] | Prints rename notice. |
/guild:guild-rollback | /guild:rollback <skill> [n] | Prints rename notice. |
/guild:guild-stats | /guild:stats | Prints rename notice. |
/guild:guild-audit | /guild:audit | Prints rename notice. |
/guild:guild-diagnose | /guild:fix [run-id | "symptom"] | Prints verb-rename notice (diagnose→fix). |
/guild:guild-team was removed (not renamed). Team composition is now a sub-step of /guild:plan. See the migration guide §2.
Related
- Architecture & Lifecycle — lifecycle phases these commands map to.
- Configuration Reference —
settings.jsonfor persistent flag defaults. - Self-Evolving Skills — how
/guild:evolveworks. - Project Memory & Wiki —
/guild:wikiin depth. - v1 → v2 Migration — complete command rename table.