How Guild Stack works

After this page you can read a Guild Stack run: which phase it is in, what approval comes next, where the receipt lives, and why the same task may look different across hosts without changing the lifecycle.

Guild Stack turns one product or software task into a traceable run. The same state machine runs whether you start with one prompt, jump straight to a phase, or attach work to an opt-in initiative. Every run writes durable evidence under .guild/, so the path from spec to plan to handoff receipts stays inspectable later.

For installation, start with Get Started with Guild Stack. For adapter contracts, dispatch backends, and module internals, read Architecture & Lifecycle.

Lifecycle · three entries

map / active

Different entry lenses, one state machine

Linear

/guild:guildnext phaserun receipt

Phase

/guild:<phase>resolve prerequisitesame receipt

Initiative

opt-in attachone or more runsprogress evidence

1. 01Init
2. 02Ideation
3. 03Planning
4. 04Development
5. 05Quality
6. 06Operations

The run storyboard

One run is easiest to understand as a sequence of visible artifacts:

/guild:guild "your task"
  -> spec proposal        .guild/spec/<slug>.md
  -> team proposal        .guild/team/<slug>.<phase>.yaml
  -> lane plan            .guild/plan/<slug>.md
  -> lane work            .guild/context/<run-id>/...
  -> handoff receipts     .guild/runs/<run-id>/handoffs/...
  -> review and verify    .guild/runs/<run-id>/review.md, verify.md
  -> optional qa/ops      .guild/runs/<run-id>/quality/... or ops/...

The important idea is not that Guild Stack runs unattended. It keeps moving only after the next contract is clear. A one-off run produces evidence; an initiative, when you explicitly attach one, owns progress across multiple runs.

The gate receipt idea

Guild Stack uses two kinds of gate:

Gate kind	What it does	What you can inspect
User gate	Pauses for a human decision, such as spec, team, plan, Quality release, or risky Operations work.	The proposed artifact and the recorded decision.
Adversarial gate	Challenges an artifact at a phase boundary. Cross-host review is strongest; same-host or skipped review is recorded as weaker.	Review packet, verdict, findings, and follow-up trail.

Planning normally asks for three approvals before implementation:

spec approval -> team approval -> plan approval -> dispatch

Destructive, network, spend, and production-sensitive work still asks even under --auto-approve=all. Quality can auto-proceed only on a computed PASS with --auto-approve=qa or all; overriding a BLOCK remains human-gated. Operations has no auto-approve token.

Three ways in

Guild Stack has three entry lenses. They differ in where you enter and who owns progress; they do not create competing workflows.

Lens	Use it when	What happens
Linear	You want Guild Stack to take a brief and move forward.	/guild:guild "your task" proposes the next phase and walks Ideation, Planning, Development, then optional Quality.
Phase	You know exactly where the work belongs.	/guild:<phase> jumps to init, ideate, plan, build, qa, or ops; missing prerequisites are rebuilt minimally, routed backward, or surfaced for a decision.
Initiative	The goal spans sessions, features, or projects.	/guild:initiative or --initiative=<id> attaches runs to a durable wrapper. One-off runs remain first-class and never attach silently.

The phase pipeline for power users

/guild:guild [brief]
  |
  v
init     -> .guild/init/<slug>.md, .guild/wiki/**, codebase-map.json
  |
  v
ideate   -> .guild/spec/<slug>.md
            user gate: approve the spec
  |
  v
plan     -> .guild/team/<slug>.<phase>.yaml
            user gate: approve the team
         -> .guild/plan/<slug>.md
            user gate: approve the plan
  |
  v
build    -> .guild/context/<run-id>/...
         -> .guild/runs/<run-id>/handoffs/...
         -> assumptions.md, review.md, verify.md
  |
  v
qa       -> .guild/runs/<run-id>/quality/<run-id>.md
  |
  v
ops      -> .guild/runs/<run-id>/ops/<run-id>.md
  |
  v
reflect  -> .guild/reflections/<run-id>.md
            proposals only; promotion stays human-gated

The station spine

The six phases are the public mental model. Inside Planning and Development, Guild Stack reuses the station spine as implementation steps: brainstorm, team-compose, plan, context-assemble, execute-plan, review, verify, and reflect.

Station	Where it lives now	Output
Brainstorm	Ideation	Draft spec and blocking questions.
Team-compose	Planning	Phase-scoped team file.
Plan	Planning	Lane plan and autonomy contract.
Context-assemble	Development	Focused bundle per lane.
Execute-plan	Development	Specialist handoff receipts.
Review	Development and phase gates	Findings, verdict, and strength record.
Verify	Development close	Evidence that the run satisfied the approved criteria.
Reflect	Cross-phase	Proposed improvements only; promotion stays human-gated.

The station spine is lower-level reference. As a beginner, follow the phase names and the gate prompts; as a power user, inspect the station artifacts when you need to understand why a run moved or paused.

Phase contracts

Init (/guild:init)

Init gives Guild Stack enough project context to work without guessing. On a brownfield repo it builds a lightweight codebase map, wiki stubs, and an architecture-map stub. The deeper learn pipeline runs only when you ask for it with --learn or configure defaults.auto_learn.

/guild:init
/guild:init --learn

Primary evidence: .guild/init/<slug>.md, .guild/wiki/**, codebase-map.json, and architecture-map.md.

Ideation (/guild:ideate)

Ideation turns a brief into a spec. If project knowledge is missing, the resolver builds a minimal baseline or routes back; it does not fabricate a fully grounded spec. Under standard and deep rigor, the clarify loop asks only the questions needed to unblock the spec.

/guild:ideate "add Stripe subscriptions"

Primary evidence: .guild/spec/<slug>.md. User gate: spec approval.

Planning (/guild:plan)

Planning composes a phase-specific team, writes a right-sized PRD section when needed, and produces the lane plan. The team file is phase-scoped: a Development team and a Quality team for the same goal can be different. Composition matches spec domains against your project’s specialist instances in .guild/agents/ plus the shipped template library; a template-covered domain with no instance yet is minted deterministically into the project, while a genuinely novel domain goes through the gated specialist-creation flow.

/guild:plan
/guild:plan --team-size=5

Primary evidence: .guild/team/<slug>.<phase>.yaml, .guild/plan/<slug>.md, and, for larger work, goal or task-group artifacts from /guild:goal. User gates: team approval, then plan approval.

Development (/guild:build)

Development assembles focused context bundles, dispatches specialists through the resolved execution backend, reviews lane output, and verifies done. Backend selection comes from the run-start snapshot; phases do not re-select it mid-run.

/guild:build
/guild:build lane-backend-001

Primary evidence: .guild/context/<run-id>/..., handoff receipts under .guild/runs/<run-id>/handoffs/, assumptions.md, review.md, and verify.md.

Quality (/guild:qa)

Quality checks whether the product is releasable against goals and user journeys. It derives a matrix from project signals: E2E, smoke, accessibility, performance, and integration. The matrix is shown before execution, and missing harnesses record a gap rather than passing silently.

/guild:qa
/guild:qa <run-id>

Primary evidence: .guild/runs/<run-id>/quality/<run-id>.md. The release recommendation is computed, not guessed.

Operations (/guild:ops)

Operations executes approved runbooks for release, monitoring, incident, rollback, or maintenance. It starts with a dry-run preflight that prints steps, blast radius, and rollback path. Incident and rollback runbooks are always interactive.

/guild:ops release
/guild:ops incident

Primary evidence: .guild/runs/<run-id>/ops/<run-id>.md. Production-sensitive actions remain human-gated.

Reflection

Reflection runs after qualifying work and proposes skill, specialist, and memory improvements. It does not promote knowledge, edit policy, or change runtime permissions on its own. Learning proposes; promotion remains human-gated through the existing wiki-ingest, decisions, and evolution paths.

Primary evidence: .guild/reflections/<run-id>.md.

Resume and inspect

/guild:status
/guild:resume

/guild:status reads .guild/ state and reports the active phase, next gate, and blockers. /guild:resume continues from the next pending gate or phase checkpoint. Resume reads filesystem state, not host memory, so the same .guild/ tree is the durable boundary.

What changes across hosts

The lifecycle, artifacts, and gates stay the same across Guild Stack’s host targets. What changes is the execution substrate: visible tmux teams, wrapped host CLI panes, host-native agents, or serial fallback. When a host cannot express a capability, Guild Stack records the degradation on disk instead of implying equal host parity.

The full-featured reference combo is Claude Code CLI with tmux teams and Codex review. Other hosts can still run the same lifecycle with recorded limitations. See Get Started with Guild Stack for public Support labels and Architecture & Lifecycle for the adapter model.

See also

• Command Reference - flat /guild:<verb> command surface and flags.
• Initiatives - opt-in progress tracking across runs.
• Quality & operations - release checks and runbook rails.
• Adversarial review - review strength, weak fallback, and review trails.
• Project Memory & Wiki Pattern - canonical .guild/wiki/** knowledge and derived indexes.