Lifecycle

The six phases

Guild Stack work moves through six phases: init → ideate → plan → build → qa → ops. Each phase has one command and one assembler skill. You can enter at any phase. /guild:guild [brief] detects the phase for you and asks you to confirm.

Init

Init is cheap by default. It builds the wiki and, for an existing repo, a cheap-scan CodebaseMap (an inventory of the repo) plus a confidence-tagged architecture-map stub. The deep knowledge graph and the guided tour are not built at Init. Add --learn (or set defaults.auto_learn) to run the full learn pipeline.

Ideate

guild-brainstorm asks clustered questions until the spec covers seven planning-contract fields: goal, audience, success criteria, non-goals, constraints, autonomy policy, and known risks and rollback. It also rolls up assumptions against blocking unknowns. The clarify loop runs when the resolved loops include spec: by default at --rigor=standard and deep; quick skips it.

Plan

guild-plan runs team composition first (see Teams and specialists). Then it writes one lane per approved worker. (Approved advisors, challengers, and reviewers are not lanes; they act at their own gates.) A lane carries task-id, owner, depends-on:, scope, success-criteria, autonomy-policy, and a seed complexity_score and tier. The tier is re-scored at dispatch. The execution backend is resolved once at intake, not per phase.

Build

guild-execute-plan runs each lane as an ephemeral cell: spawn at its resolved tier, work, emit a guild.handoff.v2 receipt, dismiss. depends-on: decides which lanes run in parallel. Before dispatch it assembles the lane's context bundle and scores its tier (Cost and tiering). After the lanes, guild-review checks the receipts in two stages: spec compliance, then quality. It writes .guild/runs/<run-id>/review.md.

QA

QA runs only after a passing .guild/runs/<run-id>/verify.md. With no passing verify, Guild Stack routes you back to Build; going on anyway is your decision, and the quality report records it. guild-quality scans signals, shows you the selected checks, runs them under the run sandbox and budget, and computes the release gate. QA is opt-in: it is never auto-entered and never silently skipped. A BLOCK override stays human-gated even under --auto-approve=all.

Ops

/guild:ops [runbook] picks one of five runbook classes: release, monitoring, incident, rollback, maintenance. Four safety rails always hold:

1. Incident and rollback are never autonomous.
2. The first run is always interactive.
3. Always-ask is unconditional for risky or destructive steps.
4. The pre-flight dry-run is mandatory.

Auto-approve and rigor

--auto-approve[=spec,plan,build,qa,all] skips the named approval gates. It never skips the team decision gate, and it never overrides a QA BLOCK. --rigor=quick|standard|deep selects which loops run. For example, quick skips the spec clarify loop.

The product loop and intake routing

When you describe work, Guild Stack first decides what kind of work it is. A vague product idea ("I have an idea for an app that tracks plants") enters the product loop. A bug fix, a review or a deploy does not.

Try it

Run the classifier on a prompt to see its verdict and the signals behind it:

echo "I have an idea for a budgeting app" | node "${GUILD_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$HOME/.local/share/guild/dist/claude-code}}/runtime/scripts/classify-intake.js"

The output is JSON with intake (product_loop or other), a score, and every matched signals[] entry. Routing reads intake only, never the raw score.

The intake classifier

The classifier is deterministic. The same prompt always gives the same result. It uses signals and a threshold, not model judgment. It does no I/O and never throws. An empty or non-string prompt returns other.

It is tuned for precision over recall. A missed product idea costs you one question. A hijacked engineering prompt sends a run down the wrong path. The code states a design target of precision at or above 0.9 and recall at or above 0.8 over its fixture.

Signals fall in four categories:

The verdict is product_loop only when both conditions hold:

1. The net score (product weights minus veto weights) is at least 1.0.
2. Either a strong-idea signal is present, or an opener appears together with a specificity signal.

A bare opener scores 0.6 and can never route on its own. A single veto weighs 1.5 and sinks even a strong idea. "I have an idea to refactor the auth module" routes to other.

When the verdict is product_loop, the next skill is guild:product-explore. Otherwise the normal lifecycle continues.

Workflow classes

Bare /guild:guild widens the product check to a six-way verdict: product, research, debug, ops, init, or other. Each class has one authored workflow graph under src/surfaces/graphs/. other means the classifier is not confident, and Guild Stack asks you instead of guessing.

How the class is bound

The class is chosen in this order. The first match wins, and the classifier only fills silence.

1. A typed verb. init, ops, research and debug bind their own class. ideate, plan, build and qa bind product.
2. --class=product|research|debug|ops|init.
3. The classifier. It scores each class. A class needs a score of at least 1.0, and a tie resolves to other.

An unknown verb or an unknown --class= value is not downgraded to the classifier. Guild Stack asks you. research and debug are sub-verbs of /guild:guild, not separate command files.

/guild:guild debug
/guild:guild --class=ops

A graph can hand off to another class mid-run with a change_class edge. For example, a debug run can move to product when "this is a feature, not a bug".

Product path: explore, then define

In the product graph, intake leads to product.explore, then product.define, then the spec.

product-explore turns the idea into .guild/explore/<slug>.json, schema guild.explore.v1. It has five required, non-empty fields:

• assumptions
• evidence_needs
• comparables
• risks
• recommended_next_step

It validates with validateExploreV1, which fails closed on a missing field, an empty field or an unknown key. If the idea is too thin, it asks one to three clarifying questions rather than inventing content.

product-define takes a validated explore artifact and writes .guild/define/<slug>.json, schema guild.define.v1. This is the PRD nucleus. Its fields are:

• acceptance_criteria, a list of {id, text}
• user_stories
• non_goals
• risks
• affected_surfaces
• test_implications

Every acceptance criterion gets a stable, unique id (AC-1, AC-2). Those ids are the traceability tokens. A plan lane, a build receipt, a QA check and a release gate all resolve to them. validateDefineV1 fails closed on a duplicate or empty id. If the explore artifact is missing or invalid, define sends you back to explore.

The PRD and the approval gate

The plan always includes a PRD. By default it is an inline ## PRD section in .guild/plan/<slug>.md. It becomes a standalone .guild/prd/<slug>.md when any trigger fires:

• The plan covers more than one feature.
• The run is attached to an initiative.
• The spec has more than five success criteria.

On promotion, the plan keeps a one-line pointer to the standalone file.

There is no separate G-prd gate. The PRD is approved at the existing plan and PRD approval gate. The user-facing gates remain spec, team and plan.

The product graph

src/surfaces/graphs/product.yaml is the plugin default (guild.workflow_graph.v1, graph id product.default). A project overlay at .guild/graphs/product.yaml may reorder nodes or omit nodes marked required: false. It cannot drop a node marked required: true.

Three nodes are required: d5 (team compose), product.qa and d8 (initiative close). ideate and product.release can be skipped by the operator.

Edges include replan (plan back to spec, build back to plan, qa back to build) and escalate (build to d5). In the product graph, product.qa is the one review gate.

QA in depth

/guild:qa is the quality phase. On the engineering lifecycle it is opt-in: it is never entered on its own and never skipped silently. On the product class graph it is required: product.qa must pass before the product release step. It picks which checks apply, runs the ones your repo already has, and computes a release recommendation. For the six-phase overview see Lifecycle in depth.

The flow has five stages: SignalScan, SelectMatrix, RunChecks, G-quality, ReleaseGate.

Try it

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

Requires a passing verify

QA runs after a passing .guild/runs/<run-id>/verify.md, never instead of it. If verify.md is missing or failing, Guild Stack routes you back to Development and says so. You may proceed anyway, but that is an operator decision. Your name and reason are recorded in the quality report.

Team gate first

Before any participant is dispatched, the qa team is composed and approved. No dispatch happens without a current approve decision. A stale or missing decision fails closed. --auto-approve does not cover team approval. Selection and the check run itself happen in the orchestrator session, so they can proceed while the gate is pending.

Selection: SignalScan and the matrix

SignalScan reads signals on disk. It does not guess with a model. It decides each of five classes:

No class is skipped silently. Guild Stack then shows the matrix and the estimated budget, and asks:

• [proceed] runs the matrix as shown.
• [edit-selection] lets you change it. The report records override: user.
• [explain-signals] shows which signals led to each choice.

There is no --classes= flag. Selection is derived from signals, then you can override it.

Running the checks

QA runs only harnesses it discovers. It never writes or installs a test framework. Authoring a harness belongs to the qa-* specialists.

Sandbox. Checks run inside the run's task_run permission envelope. On top of that, an always-ask hard set fires prompts inline, even under --auto-approve. The set is release, security, ops and destructive.

Budget. Time per class and in total comes from defaults.quality.budget.

When a class runs out of budget, its result is inconclusive: budget exhausted. It is never a silent pass.

G-quality: the advisory panel

G-quality is advisory. It never blocks on its own. It has two parts:

1. In-phase panel. Producer qa-test-strategy. Challengers are security (always present) and architect (only when the multi_component signal fired). Each finding is closed by a rerun, an added check, or a named owner-accepted risk.
2. Cross-host review. A different host family critiques the report through the review broker. It fires only on risk >= high, review: cross / --review=cross, or when config requires it. Otherwise it is skipped. If it returns rework, resolve the findings before the release gate. See Adversarial review.

ReleaseGate: computed, not asked

The recommendation is computed from the results. Each class ends as pass, fail, inconclusive, not_applicable or gap.

You choose [release], [block] or [abort]. Choosing [release] on a BLOCK is a human-only force-pass. Your name and rationale are recorded.

--auto-approve accepts spec, plan, build, qa and all. There is no ops token. qa and all auto-pass a RELEASE-READY verdict only. A BLOCK override is never auto-passed under any token, and Guild Stack prints that asymmetry.

What it writes

The report is .guild/runs/<run-id>/quality/<run-id>.md. It holds four blocks: selection, results, challenger_trail and release_decision.

Ops runbooks read this report. A release or rollback refuses to run on a BLOCK unless a human force-pass is recorded.