How Guild Works

You approve three gates — spec, team, and plan. The remaining phases run with minimal interruption. When the run completes, Guild proposes skill improvements and memory updates for your review; nothing auto-promotes.

Guild's 7-step lifecycle: brainstorm → team-compose → plan → context-assemble → execute → review → verify — Three approval gates keep you in control; the build, review, and verify phases run automatically.

The phase pipeline

/guild:guild [brief]
  ↓
init          → .guild/init/<slug>.md, wiki stubs, codebase-map.json
  ↓
ideate        → .guild/spec/<slug>.md              [gate: you approve spec]
  ↓
plan          → .guild/team/<slug>.yaml             [gate: you approve team]
              → .guild/plan/<slug>.md               [gate: you approve plan]
  ↓
build         → .guild/context/<run-id>/            (one bundle per specialist)
              → handoff receipts, assumptions.md, review.md
  ↓
qa            → .guild/runs/<run-id>/quality/
  ↓
ops           → .guild/runs/<run-id>/ops/
  ↓
reflect       → .guild/reflections/<skill>/         (proposals only — nothing auto-promotes)

Phase-by-phase

init

What you get: A lightweight context map of your project — wiki stubs, a codebase-map.json summary, and an architecture-map.md stub. Run once per project; re-run when the codebase changes significantly. The full knowledge-graph pipeline runs only under --learn.

/guild:init

Output: .guild/init/<slug>.md, initial wiki pages under .guild/wiki/, codebase-map.json.

ideate

What you get: A structured task specification you review and approve before any work starts. Guild drafts the spec, asks blocking questions, and waits for your answers. Nothing proceeds until you approve.

Gate: You approve the spec before the plan phase starts.

plan

What you get: A concrete team of specialists and a sequenced plan — you see exactly who will work on what before anyone starts.

Two sub-steps run sequentially:

Team-compose — Guild proposes which specialists to dispatch, with gap-handling options (auto-create, skip, substitute, or draft-from-scratch) for any capability gaps. Writes .guild/team/<slug>.yaml.
Plan — Per-specialist lanes with depends-on: ordering for sequenced work. Writes .guild/plan/<slug>.md.

Gate: You approve the team, then the plan.

/guild:plan

Respond with [edit] at the plan gate to revise before approving. The --team-size=N flag lifts the default 6-specialist cap.

build

What you get: All specialists execute their approved lanes. Each specialist receives a tight context bundle — only the skills and wiki pages it needs — then delivers a structured handoff receipt.

Per lane, in order:

guild:context-assemble — builds a context bundle capped at 6 k tokens.
guild:execute-plan — dispatches the specialist via the execution backend.
guild:review — 2-stage review: spec match, then quality.

Output: Handoff receipts under .guild/runs/<run-id>/, assumptions.md, review.md.

Parallelism: architect runs first (its output is a common dependency); backend + QA run sequentially; content and commercial specialists run in parallel with engineering when they only need the spec.

qa

What you get: A cross-cutting quality gate across all lane outputs — test coverage, scope adherence, and success-criteria satisfaction checked in one pass.

/guild:qa

Output: .guild/runs/<run-id>/quality/<run-id>.md.

ops

What you get: An operational readiness check — deployment, observability, and runbook coverage assessed before you ship.

/guild:ops

Output: .guild/runs/<run-id>/ops/<run-id>.md.

reflect

What you get: Proposed skill improvements and memory updates queued for your review. The Stop hook fires guild:reflect when the completion heuristic passes (≥1 specialist dispatched, ≥1 file edited, no error).

Nothing auto-promotes. Proposals accumulate; you gate promotion via /guild:evolve and /guild:wiki ingest.

Resuming a partial run

/guild:resume
/guild:status

/guild:status reads .guild/ state and surfaces the furthest completed phase, the next gate, and any blockers. /guild:resume re-enters the lifecycle from where it left off.

Execution backends

The build phase dispatches specialists through one of three backends, selected by the agent_mode setting in .guild/settings.json (default: auto):

Mode	When	What you see
`team`	Inside tmux or tmux available	One pane per specialist, visible in terminal
`agent`	No tmux, host supports independent agents	`InProcessTeamBackend` — Agent tool dispatch
`subagent`	Fallback (CI, fresh installs)	Direct Agent tool calls via `guild:execute-plan`

See Architecture & Lifecycle for the full dispatch ladder and backend details.

Decisions captured mid-run

Any time a specialist reaches genuine uncertainty, it invokes guild:decisions rather than guessing. The skill writes a structured decision record to .guild/wiki/decisions/<slug>.md in ADR-lite format (context → options → decision → consequences), then proceeds.

Medium/high-significance decisions are captured; trivial Q&A stays in the run transcript.