Core concepts

You can use Guild Stack well with a handful of ideas. This page teaches them in plain words first. The Power layer is the full glossary; the Architect layer shows how the pieces are built.

Guild Stack adds commands to your AI coding tool

Guild Stack runs inside the AI coding tool you already use. The 3.0.0 release was tested on two: Claude Code and Codex. Guild Stack v3 gives you 13 commands. They all start with /guild:.

You only need three to start:

Command	What it does
`/guild:init`	Learns your project and sets up the `.guild/` folder.
`/guild:guild`	The front door. Tell it what you want; it suggests where to start.
`/guild:status`	Shows where your current task is and what comes next.

Work moves through steps

Guild Stack does not jump straight to code. A task moves through steps:

Ideate: write down what you want, what "done" means, and what is out of scope.
Plan: split the work into pieces and decide who does each piece.
Build: do the pieces.
QA (quality check): test the work and write down the result.

Each step has its own command, so you can stop, look, and continue.

A team does the work

For bigger tasks, Guild Stack splits the work into pieces called lanes. Each lane goes to a specialist: an AI helper with one focused job. A lane can wait for another lane to finish first.

When a specialist finishes, it writes a short receipt: what it did and which files it changed. You can read every receipt.

Work gets checked

After the build, Guild Stack reviews the work and writes review.md. Then a final check confirms the change is really on disk and writes verify.md. If the check fails, the task is not done.

Your project gets notes

Guild Stack keeps notes about your project in .guild/wiki/. You can add your own documents to the notes and ask questions later:

/guild:wiki ingest NOTES.md
/guild:wiki query "retry backoff"

Glossary

Short definitions of the words you will meet in Guild Stack. Each entry links to a deeper page.

Advisor. A helper that answers one hard sub-question at the powerful tier. It sees only the draft and the question, not your whole project. See Cost and tiering.

Alias. An old command name kept for a short time. It prints the new name and exits. See Commands.

Candidate. A piece of new knowledge waiting for approval. It lands in .guild/knowledge/candidates/ and is not part of the wiki yet. See Reading what Guild Stack wrote.

Capability row. A record of what one host (AI tool) can do natively, such as run a shell or load skills. Guild Stack reads it instead of guessing from the tool's name. See Host adapters.

Channel. The line of releases you follow: stable (the main branch) or beta (the next branch). See Updates.

CodebaseMap. An inventory of your repo made by a cheap scan. /guild:init builds it. See Knowledge.

Context bundle. The small, bounded set of facts Guild Stack hands to one lane before it starts. See Context assembly.

D8. The gate that runs when you close an initiative. It refuses to close if its check fails or cited evidence is missing. See Initiatives.

Gate. A point where Guild Stack stops for a check or for your approval. The named gates:

Spec approval: you approve the written spec before planning.
G-plan: a review of the plan. It runs inside planning, when policy asks for it.
G-lane: a review of one lane's receipt during build. It is the only gate shown at the command level.
G-quality: a challenger review of the QA report. It does not block by itself; the release gate does.
G-diagnose: a review of a diagnosis report before any fix is applied.
G-spec: a review of the spec, when policy asks for it.
G-prd: not a separate gate. The PRD is approved with the plan.
G-knowledge: only a non-blocking binding step in ideation. It marks a missing init.

See Lifecycle and Adversarial review and gates.

Handoff receipt. See receipt.

Harvest. The step that turns a finished run's decisions into wiki pages. It is the only automatic writer to the wiki, and you can turn it off with wiki.autopromote: false. See Knowledge.

Host. The AI coding tool Guild Stack runs inside, such as Claude Code or Codex. See Install.

Initiative. Work that spans more than one run. You opt in to it. See Initiatives.

Intake class. The kind of request, set with --class: product, research, debug, ops, or init. See Commands.

KnowledgeGraph. A deep map of how the ideas in your project connect. It is slower to build than a CodebaseMap. Init does not build it by default. /guild:init --learn, or the setting defaults.auto_learn: true, runs the full pipeline that builds it. See Knowledge.

Lane. One piece of a plan, given to one specialist. A lane can wait for another lane. See Core ideas.

Machinery agent. A helper that runs Guild Stack itself, such as the advisor, rather than a domain role. See Teams and specialists.

Receipt. The short note a specialist writes when a lane is done: what it did and which files it changed. They live under .guild/runs/<run-id>/handoffs/. Install receipts are a different thing: see Updates.

ReleaseGate. The release recommendation QA computes from its results. Guild Stack works it out; it does not ask. A BLOCK stays under human control even with --auto-approve=all. See Lifecycle.

Rigor. How many review loops a run uses: --rigor=quick, standard, or deep. See Lifecycle.

Run. One pass of Guild Stack on a task. Its records live under .guild/runs/<run-id>/. See Reading what Guild Stack wrote.

Specialist. An AI helper with one focused job, such as a backend or a QA role. See Teams and specialists.

Spec. The written description of what you want, what "done" means, and what is out of scope. It is saved as .guild/spec/<slug>.md. See Lifecycle.

Tier. The size of model a lane runs on: cheap, mid, or powerful. Guild Stack picks the lowest tier that fits. See Cost and tiering.

verify.md. The final check's report, at .guild/runs/<run-id>/verify.md. If it fails, the task is not done. See Core ideas.

Wiki. Your project notes, kept in .guild/wiki/. See Knowledge.

Workspace. A folder that holds several repos, each with its own .guild/. See Workspaces.

System architecture

Guild Stack is a plugin that runs inside a host (Claude Code, Codex, and others). It is a thin command surface over a set of skills, backed by deterministic scripts. Models make judgments. Scripts and hooks enforce the rules.

Layered view of the Guild Stack harness: commands call assembler skills, assemblers call scripts and domain code, hooks observe and gate tool use, and two optional MCP servers read the wiki and run traces. All state lands under .guild/. — Open full size

The layers

Layer	Where	What it does
Commands	`commands/*.md`	13 thin entrypoints, `/guild:<verb>`. Sub-verbs are arguments, never separate files. Each command invokes its producer skill.
Assemblers	`skills/`	76 skills ship. Exactly 17 are indexed by the host: the assemblers. Everything else is off-index.
Scripts and domain code	`scripts/`, `src/domains/`	Deterministic logic: scoring, validation, launchers, run lifecycle. Authored in TypeScript, shipped to users as compiled Node under `runtime/scripts/`.
Hooks	`hooks/hooks.json`	Native Claude Code hooks on 10 events. Other hosts get equivalent behavior through host adapters and graceful fallback.
MCP servers	`mcp-servers/`	Two optional read-only servers, `guild-memory` (wiki) and `guild-telemetry` (run traces).

The 10 hook events are SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStop, Stop, TaskCreated, TaskCompleted, and TeammateIdle. Hook sources are TypeScript that compile to committed bundles under hooks/dist/. Editing the source without rebuilding changes nothing at runtime.

The assembler model

An assembler is a three-stage folder:

SKILL.md. Frontmatter is always loaded. The body loads when the skill matches.
references/. Chapters loaded on demand.
scripts/. Compiled code, never prompt text.

The host catalog lists only the 17 assemblers: using-guild, init, brainstorm, plan, team-compose, execute-plan, quality, operations, learn, wiki, initiative, review, diagnose, evolve, create-skill, create-specialist, reflect. Skills the host never lists live as chapters inside their parent assembler. The 58 specialist starter recipes live under skills/specialists/ as copy-on-mint feedstock.

Each phase command hands off to its assembler:

Command	Skills invoked, in order
`/guild:init`	`guild:init`
`/guild:ideate`	`guild:brainstorm`
`/guild:plan`	`guild:team-compose`, then `guild:plan`
`/guild:build`	`guild:execute-plan` (per lane: context assembly, dispatch, then `guild:review`)
`/guild:qa`	`guild:quality`
`/guild:ops`	`guild:operations`
`/guild:learn`	`guild:learn`

Dispatch and handoffs are covered in Dispatch and execution and Agent communications.

Domain code

Under src/domains/ there are twelve domains: kernel, state, security, config, lifecycle, knowledge, teams, dispatch, review, telemetry, evolve, distribution. Each has one public index.ts. Nothing outside a domain may reach a sibling file. Host adapters live in src/adapters/ and are not a thirteenth domain: adapters may read a domain index, a domain must not import adapters. The files in scripts/lib/ are mostly backward-compatible re-exports of these domains.

Host packages are a projection of the live surface. build-host-packages copies straight from commands/, skills/, agents/, hooks/, and scripts/. See Host adapters.

Four machinery agents

The plugin registers four agents with the host. They are the only host-registered agents it ships.

Agent	Model	Role
`team-lead`	sonnet	Owns one TaskCell. Dispatches its specialists, reads their `guild.handoff.v2` receipts, reports upward only as `guild.goal_status.v1`.
`developer`	sonnet	Generic implementer for lanes with no domain home. Escalates to the advisor when above its tier.
`context-manager`	sonnet	Assembles bounded context and run-scoped capability evidence. Writes only under `.guild/context/`, `.guild/artifacts/`, `.guild/runs/**`.
`advisor`	opus	Answers one escalated sub-question per consult. Sees the draft and the question, never the raw project context.

Fifteen domain specialist templates sit in templates/specialists/. Team composition mints them into your project's .guild/agents/ on demand. See Teams and specialists.

The run model

Bare /guild is the T0 orchestrator session. With no verb it runs intake and binds one of five class graphs: product, research, debug, ops, init. Work runs in three tiers: T0, a Team Lead per TaskCell (T1), and specialists (T2). Tiers report upward only through guild.goal_status.v1 and guild.handoff.v2.

Every run gets a directory, .guild/runs/<run-id>/. startRun writes the guild.run.v1 start manifest (run.yaml), a current-run-id sentinel, and an empty logs/ directory. closeRun writes provenance.json (guild.provenance.v1) and flips the status in run.yaml. Starting a run never creates an initiative. An initiative is recorded only as a scalar field.

Other files and folders appear as the run proceeds:

Path under `.guild/runs/<run-id>/`	Written by
`resolved-settings.json`	Run-start preflight. The frozen settings snapshot.
`logs/v1.4-events.jsonl`	Run tracing. The event log the telemetry server reads.
`handoffs/<specialist>-<task-id>.md`	Each lane agent, as its final action.
`in-progress/*.json`	Lane heartbeats.
`agent-team/session.json`	The tmux launcher.
`logs/backend-degradation.jsonl`	The backend-degradation guard.

Phase outputs also land in the run: /guild:qa writes quality/<run-id>.md and /guild:ops writes ops/<run-id>.md. Run records are scrubbed of secrets before they are shared or exported.

The .guild/ layout as a system

All project-created Guild Stack state lives in the active root's .guild/. Nothing Guild Stack generates is written into the plugin install tree. Guild Stack has exactly two state levels: a workspace root and its immediate sub-project roots. There is no third level. A workspace reads sub-project state in place and never copies it.

Path	Holds	Authority
`guild.yaml`	Root identity (workspace or project).	Source
`config/project.json`, `settings.json`	Durable policy only. Host family, host id, and model names bind per session on the run.	Source
`agents/*.md`, `skills/<name>/SKILL.md`	Project-created specialists and skills.	Source
`agents/registry.yaml`, `skills/registry.yaml`, `teams/registry.yaml`, `workflows/`, `loops/`	Indexes.	Derived, never hand-edited
`wiki/`, `knowledge/`, `memory/`	Synthesized knowledge, graph and sources, recall index.	Source
`spec/`, `plan/`, `team/`, `context/`	Approved specs, per-task plans, per-phase team files, per-run context bundles.	Source
`runs/`	One directory per run.	Source
`initiatives/`, `reflections/`, `evolve/`, `artifacts/`	Long-running work, proposed learnings, shadow-mode eval runs, generated output.	Source
`indexes/`	Learn output: `codebase-map.json`, knowledge graph, recall projection.	Derived (rebuilt by `/guild:learn`)

Files are latest-only. Evolve replaces the named span and keeps a compact history on platform state, so there is no skill-versions/ tree. The storage policy classes the SQLite index, the codebase map, and the model catalog as off-repo caches. In v3.0.0 the learn scanner still writes the codebase map to .guild/indexes/codebase-map.json, so treat that file as derived output you can rebuild. See The .guild folder for the beginner view.

MCP servers

Both servers are optional and read-only. Their source is src/runtime/mcp/, compiled into one runtime/guild-mcp.js.

guild-memory: wiki_search (BM25), wiki_get, wiki_list over .guild/wiki/.
guild-telemetry: trace_list_runs, trace_summary, trace_query, trace_cost_rollup over .guild/runs/.

Bundle recall does not go through the memory server. It goes through scripts/lib/recall.ts, so every recalled chunk is protected. See Context assembly.