System architecture

Guild Stack is one lifecycle rendered onto host-specific surfaces. The public contract is stable: a run moves through approved phases, specialists work from scoped context, every lane returns a receipt, review and verification read files, and durable evidence lands under the consuming repo’s .guild/ tree.

The implementation reference below is split into two layers:

• Architecture spine: the small model you need before reading code.
• Reference map: the module/file contracts that prove where the behavior lives.

Architecture Spine

The one-sentence architecture from docs/v2 is:

Guild Stack v2 is one state machine, six phase entrypoints, three lenses, rendered onto any host through one adapter contract, and made durable by one connected knowledge model.

That sentence expands into four contracts:

Contract	What stays stable	Primary artifacts
Operating model	Workspace federates projects; project owns knowledge; initiative optionally owns progress; run produces evidence.	.guild/workspace.json, .guild/wiki/**, .guild/initiatives/**, .guild/runs/<run-id>/
Lifecycle	Init, Ideation, Planning, Development, Quality, and Operations are one state machine, not separate workflows.	.guild/spec/, .guild/team/, .guild/plan/, .guild/context/, .guild/runs/**
Host adapter	Hosts render the same phase, dispatch, receipt, review, and trace contracts with recorded degradation when a capability is missing.	.guild/hosts/<host-id>/capability.json, handoff receipt host blocks, trace degradation rows
Knowledge model	Filesystem state is canonical; indexes and caches are rebuildable projections.	.guild/wiki/**, .guild/indexes/**, .guild/index.sqlite

The important boundary is not “which host is best.” The boundary is whether the run still writes the required artifacts and records any loss. Guild Stack does not promise parity across hosts.

Host adaptationsplit_adapter_degradation_ladders

Operational mapChoose the strongest path. Record every drop.

01Execution substrate

1. 01tmux teamparallel lanes
2. 02host-nativenative delegation
3. 03subagentbounded delegation
4. 04serial classavailable, not wired

02Adapter surface

1. 01nativefull primitive
2. 02wrappedverified wrapper
3. 03bridgedtranslated capability
4. 04emulatedrecorded substitute
5. 05degradedexplicit loss

Host, substrate, and reviewer remain separate axes. The selected lower rung becomes a receipt.

Module Map

The plugin is built as 30 ownership-scoped modules under plugin/src/modules/<module>/. Each module has a manifest, a public index.ts, workflow code, and owned resources projected into host-facing folders.

plugin/src/modules/<module>/
  module.manifest.json   # id, kind, depends_on, owned inventory
  index.ts               # public cross-module import surface
  workflows/*.ts         # implementation logic
  resources/             # owned commands, skills, hooks, scripts, MCP declarations

The public docs should read the graph as four layers:

Layer	Modules	What they own
substrate	kernel, state, communication, config, security, host-runtime, dispatch, prompting, context, loops, capability, workspace, templates	Host-neutral primitives: module manifests, .guild/ paths, file bus, settings, security gates, host adapters, dispatch, prompt/context assembly.
capability	knowledge, learning, lifecycle, review, teams, specialists, initiatives, intake, evolution, operations, quality	Product behavior: phases, learning, review, teams, initiatives, gated evolution, QA, and runbooks.
operator	telemetry, dashboard, evals, docs-sync, migrations	Traces, local dashboard, eval artifacts, docs-sync gates, and .guild/ migrations.
build	distribution	Host package rendering and installer output.

The source map is:

Need	Start here
Full module index	docs/v2/architecture/README.md
Layered dependency graph	docs/v2/architecture/architecture-spine.md
Module detail	docs/v2/architecture/modules/<module>.md
Runtime path examples	docs/v2/architecture/runtime-flows.md
Live implementation root	plugin/src/modules/<module>/

Module Index

Every row below is a real plugin/src/modules/<module>/ directory, matched to its docs/v2/architecture/modules/<module>.md reference.

30 modules

Harness module index

Module Owned surface Contract Source doc Plugin path

capability Resolves lane tier, dispatch mode, and per-run capability routing. substrate docs/v2/architecture/modules/capability.md plugin/src/modules/capability/

communication File-bus messaging contract between agents and lanes. substrate docs/v2/architecture/modules/communication.md plugin/src/modules/communication/

config Owns .guild/settings.json, the closed-key config surface, and resolution. substrate docs/v2/architecture/modules/config.md plugin/src/modules/config/

context Builds bounded per-specialist context bundles (Universal + Role + Task). substrate docs/v2/architecture/modules/context.md plugin/src/modules/context/

dashboard Operator read surface over .guild/ runs and knowledge (local, read-only). operator docs/v2/architecture/modules/dashboard.md plugin/src/modules/dashboard/

dispatch Transports an approved lane to a running agent via the agent_mode ladder. substrate docs/v2/architecture/modules/dispatch.md plugin/src/modules/dispatch/

distribution Renders host packages and installer output; the only build-kind module. build docs/v2/architecture/modules/distribution.md plugin/src/modules/distribution/

docs-sync Enforces documentation hygiene and docs-sync gates. operator docs/v2/architecture/modules/docs-sync.md plugin/src/modules/docs-sync/

evals Fail-closed schema validators and pure verification primitives. operator docs/v2/architecture/modules/evals.md plugin/src/modules/evals/

evolution Self-improvement loop: post-task reflection, shadow eval, promotion gate. capability docs/v2/architecture/modules/evolution.md plugin/src/modules/evolution/

host-runtime Host registry, adapters, and the capability/degradation substrate. substrate docs/v2/architecture/modules/host-runtime.md plugin/src/modules/host-runtime/

initiatives Opt-in durable-goal lens and the D8 close gate. capability docs/v2/architecture/modules/initiatives.md plugin/src/modules/initiatives/

intake Classifies a user's verbatim prompt and routes it to a lifecycle phase. capability docs/v2/architecture/modules/intake.md plugin/src/modules/intake/

kernel Dependency root of the module graph; owns the cross-module import boundary. substrate docs/v2/architecture/modules/kernel.md plugin/src/modules/kernel/

knowledge Durable memory surface: canonical wiki plus derived indexes. capability docs/v2/architecture/modules/knowledge.md plugin/src/modules/knowledge/

learning Learn engine: deterministic plus LLM-seamed codebase-understanding pipeline. capability docs/v2/architecture/modules/learning.md plugin/src/modules/learning/

lifecycle Owns the phase command spine (init -> ideate -> plan -> build -> qa -> ops). capability docs/v2/architecture/modules/lifecycle.md plugin/src/modules/lifecycle/

loops Guild Stack's adversarial loop wrappers with fixed-cap bounded iteration. substrate docs/v2/architecture/modules/loops.md plugin/src/modules/loops/

migrations Forward-migration surfaces, including .guild/ schema migrations. operator docs/v2/architecture/modules/migrations.md plugin/src/modules/migrations/

operations Realizes the Operations phase (/guild:ops): release, incident, runbooks. capability docs/v2/architecture/modules/operations.md plugin/src/modules/operations/

prompting Owns Guild Stack team prompt wording for the orchestrator and teammates. substrate docs/v2/architecture/modules/prompting.md plugin/src/modules/prompting/

quality Owns the Quality phase producer behavior and release-readiness gate. capability docs/v2/architecture/modules/quality.md plugin/src/modules/quality/

review Guild Stack's adversarial-review surface: cross-host/same-host verdicts and loop control. capability docs/v2/architecture/modules/review.md plugin/src/modules/review/

security Runtime trust boundary: PreToolUse gate, durable-write policy, sandboxing. substrate docs/v2/architecture/modules/security.md plugin/src/modules/security/

specialists Machinery agent definitions, the specialist type template library, and roster resolution. capability docs/v2/architecture/modules/specialists.md plugin/src/modules/specialists/

state Resolves the active .guild/ root and durable run/lane state. substrate docs/v2/architecture/modules/state.md plugin/src/modules/state/

teams Phase-aware team composition matching a spec's domains to specialists. capability docs/v2/architecture/modules/teams.md plugin/src/modules/teams/

telemetry Recorder plus read surface for Guild Stack's observability/trace spine. operator docs/v2/architecture/modules/telemetry.md plugin/src/modules/telemetry/

templates Owns the guild.template.v1 product-template contract and validator. substrate docs/v2/architecture/modules/templates.md plugin/src/modules/templates/

workspace Detects monorepo-of-repos layouts and writes the guild.workspace.v1 manifest. substrate docs/v2/architecture/modules/workspace.md plugin/src/modules/workspace/

Commands Hold No Business Logic

The command surface is a dispatch surface, not the product logic layer.

Proof map:

Surface	Proof
User commands	docs/v2/config-surfaces.md defines flat /guild:<verb> commands and says skills are model-invoked, not user-typed.
Phase command ownership	docs/v2/architecture/modules/lifecycle.md lists init, ideate, plan, build, qa, ops, guild, resume, and status as lifecycle-owned command shells.
Actual phase work	The same lifecycle module owns producer skills such as guild-brainstorm, guild-plan, guild-execute-plan, and guild-verify-done; quality and operations own their phase producers.
Module-resource enforcement	docs/v2/architecture/README.md describes module.manifest.json plus SHA-256-pinned resources/module-resources.json; package generation fails closed on resource drift.
Cross-module boundary	kernel validates ownership and public-only imports through each module’s index.ts.

In practice, a command file declares intent and invokes the phase spine. Business behavior lives in model-invoked skills and the ownership-scoped module workflows/scripts those skills call. That is why adding or changing a command must update the owning module manifest and the docs-sync targets, not just a Markdown command file.

Runtime Flow

A normal run follows this artifact path:

/guild:guild "task"
  -> run-start preflight
  -> resolved settings snapshot
  -> phase entry and user gates
  -> team and lane plan
  -> context bundles
  -> task_run files
  -> specialist dispatch
  -> handoff receipts
  -> review and verification
  -> trace, provenance, and optional quality/ops records

The corresponding files are:

Step	Contract	Path
Run start	guild.run.v1	.guild/runs/<run-id>/run.yaml
Resolved settings	guild.resolved_settings.v1	.guild/runs/<run-id>/resolved-settings.json
Dispatch attempt	guild.task_run.v1	.guild/runs/<run-id>/task-runs/<task-id>.yaml
Pane assignment	guild.task_assignment.v1	.guild/runs/<run-id>/tasks/<specialist>.json
Lane output	guild.handoff_receipt.v1 with guild.handoff.v2	.guild/runs/<run-id>/handoffs/<specialist>-<task-id>.md
Trace	guild.trace_event.v1 / additive trace families	.guild/runs/<run-id>/logs/v1.4-events.jsonl
Run close	guild.provenance.v1	.guild/runs/<run-id>/provenance.json

resolved-settings.json is frozen for the run. Mid-run edits to .guild/settings.json do not change that run’s behavior.

Host And Dispatch Boundaries

Guild Stack separates three choices:

Axis	Question	Where to read
Host	Who orchestrates or receives work?	host-runtime, docs/v2/host-adversarial-adaptability.md
Substrate	How do specialists run?	dispatch, docs/v2/dispatch-execution.md
Reviewer	Who challenges the output?	review, docs/v2/adversarial-review.md

The strongest posture is a different-family reviewer with a result adapter. Same-host review and skipped review are weaker states and must be recorded as such. Host gaps degrade through receipts, run state, approval records, or trace rows; they do not remove the phase contract.

Public Extension Points

These are the surfaces a project or host integrator can work with deliberately:

Extension point	Public-safe boundary
Project specialists	.guild/agents/*.md, minted deterministically from the shipped template library or promoted through the gated specialist creation path.
Project skills	.guild/skills/**, promoted/evolved through gated skill workflows.
Settings	.guild/settings.json, edited through /guild:config or closed-key JSON.
Host adapters	Host registry rows, capability manifests, adapter operations, package renderers.
Knowledge	.guild/wiki/** via human-gated decisions and wiki-ingest paths.
Run artifacts	.guild/runs/<run-id>/** receipts, traces, reviews, and provenance.

These are internals, not extension points:

Internal	Why
plugin/src/modules/*/resources/module-resources.json	Generated/pinned ownership metadata; edit the module source and re-sync.
Top-level projected commands/, skills/, hooks/, scripts/ copies	Host-facing projections; the module resources are the source layer.
Derived indexes and SQLite cache	Rebuildable acceleration, not canonical product memory.
Host chat messages	Liveness pointers only; the file bus and receipts are the contract.

See Also

• How Guild Stack Works for the phase-by-phase user path.
• Agent Communications for the handoff bus.
• Configuration Reference for settings inheritance and closed-key validation.
• Project Memory & Wiki Pattern for canonical knowledge state.
• Adversarial Review for review strength and loop control.