Architecture & Lifecycle

Every /guild:guild invocation runs the same 7-step lifecycle: brainstorm, team-compose, plan, context-assemble, execute, review, verify. Understanding the architecture tells you where your project state lives, how specialists stay isolated, and why runs are reproducible.

Four layers

Guild’s runtime has four layers:

Orchestrator session (main Claude Code session)
  ↓ dispatches through Agent tool or agent-team backend
Plugin (installed in this repo)
  skills/   agents/   commands/   hooks/   scripts/   mcp-servers/
  ↓ spawns
14 Specialist subagents (worktree-isolated)
  each receives a context bundle as its authoritative task brief
  ↓ writes to
Project-local state (.guild/)
  spec/  plan/  team/  context/  runs/  wiki/  reflections/  evolve/

Why this matters for your runs: Specialists operate in isolation — each receives only the context relevant to its lane. When an output is wrong, you can diff .guild/context/<run-id>/ to see exactly what that specialist was working from.

The context bundle written by guild:context-assemble is a strong context contract, not a hard isolation boundary — Claude Code still loads the consuming repo’s CLAUDE.md, plugin skills, and MCP servers. Specialists are instructed to privilege the bundle; when ambient context contradicts it, the bundle wins and the contradiction surfaces in the handoff receipt. See Context Assembly for details.

Specialist teams

Guild ships 14 specialists across three groups — the team for each run is assembled from this roster. See the Specialist Roster for triggers, boundaries, and default tiers.

Directory layout

guild/
├── .claude-plugin/plugin.json          # plugin manifest
├── .mcp.json                           # optional MCPs: guild-memory, guild-telemetry
├── skills/                             # 77 skills across 5 tiers
│   ├── core/principles/                # T1 · 1 skill
│   ├── meta/                           # T2 · 18 skills (workflow spine)
│   ├── knowledge/                      # T3 · 3 skills: wiki-ingest, query, lint
│   ├── fallback/                       # T4 · 5 skills (forked from superpowers MIT)
│   └── specialists/                    # T5 · 50 authored specialist skills
├── agents/                             # 14 specialist definitions (.md)
├── commands/                           # 8 slash commands (.md)
├── hooks/                              # hooks.json + 10 event handlers
├── scripts/                            # 7 tooling scripts (tsx, stdlib-only)
└── mcp-servers/                        # 2 bundled MCPs: guild-memory, guild-telemetry

Skill taxonomy (77 total):

The 7-step lifecycle

Implemented in commands/guild.md. Each phase delegates to one or more T2 skills:

User intent
 → guild:brainstorm       spec     → .guild/spec/<slug>.md
 → guild:team-compose     team     → .guild/team/<slug>.yaml
 → guild:plan             lanes    → .guild/plan/<slug>.md
 → guild:context-assemble bundles  → .guild/context/<run-id>/<specialist>-<task-id>.md
 → guild:execute-plan     dispatch → backend (tmux / InProcess / subagent)
 → guild:review           2-stage  → spec match, then quality
 → guild:verify-done      gates    → tests · scope · success-criteria
 → guild:reflect          proposals → .guild/reflections/ (post-Stop hook)

Confirmation gates: after brainstorm (spec), after team-compose (team), and after plan (plan). Post-plan phases run with minimal interruption.

Parallelism rules:

• Architect runs first when present — its output feeds all other lanes.
• Backend → QA sequential (integration tests need the implementation).
• DevOps → QA sequential (staging environment setup).
• Content and commercial specialists run in parallel with engineering when they only need the spec.

Execution backends — the D5 dispatch ladder

agent_mode: team | agent | subagent | auto in .guild/settings.json governs every /guild:guild run. On auto, the orchestrator resolves in order:

All named backends share the TeamBackend interface (spawn / sendTask / readState / dismiss / teardown). Pinning team on a tmux-less host is rejected with an error.

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is required for tmux-based team spawning. The launcher refuses without it.

Cost-aware model tiering

Three stable tiers map to concrete models via settings.json models.tiers:

The orchestrator auto-scores each lane from deterministic signals and prints the score + resolved tier at dispatch. See Cost-Aware Model Tiering for the full scoring signals and advisor protocol.

Hook inventory (10 events)

PreToolUse and PreCompact are newer hook surfaces — older Claude Code hosts may never dispatch them. Handlers exit cleanly on missing input; the run continues with fewer audit rows.

Project-local state layout

Runtime artifacts live under .guild/ at the consuming repo’s root. Guild never commits them:

.guild/
├── raw/               # immutable source inputs + checksums
├── wiki/              # synthesized project memory, decisions, standards
├── spec/              # approved specs
├── plan/              # per-task plans
├── team/              # resolved specialist teams
├── context/           # per-run specialist context bundles
├── runs/              # telemetry, handoff receipts, assumptions
├── reflections/       # proposed skill and specialist edits
├── evolve/            # shadow-mode eval runs and reports
└── skill-versions/    # rollback snapshots

See Project Memory & Wiki Pattern for the wiki category structure and write path.

Cross-host orchestration

Cross-host execution is off by default (defaults.cross_host.enabled: false). When enabled, each specialist in team.yaml may declare host: <host-id> to route work to a specific host.

Capability routing is deterministic — a three-axis function (mode × tier × host) selects (host, model) per task by filtering guild.host_capability.v1 manifests. The function must return in < 5 ms with no network call. A ranked fallback chain fires on manifest absence, auth failure, or rate-limit — never silently downgrading tier.

See Configuration reference for defaults.cross_host.* keys.

SQLite read-through recall

.guild/index.sqlite is a rebuildable derived cache — never the system of record. Delete it for zero data loss (only speed loss).

The index is dark until measured-slowness thresholds fire (defaults: 500 wiki files, 2 000 knowledge-graph nodes, 20 runs). Below every threshold, all reads use direct file parse or the guild-memory BM25 path. The wiki_fts table (FTS5, bm25() ranking) is populated exclusively by guild:wiki-ingest and guild:decisions. See Context Assembly for the two-path recall implementation.

Observability

Guild writes structured trace events to .guild/runs/<run-id>/logs/v1.4-events.jsonl. The optional guild-telemetry MCP server provides read-only structured query tools:

• trace_list_runs — list run IDs
• trace_summary — phase + specialist breakdown per run
• trace_cost_rollup — token and cost aggregates by tier, specialist, or phase

The guild-telemetry MCP is optional — Guild works without it.

Security posture

Capability-scope enforcement. Agent definitions may carry a capability_scope: frontmatter block (op-class allowlist, network flag, write scope). The PreToolUse hook enforces it — violations block the tool call and emit a security event to runs/<run-id>/logs/security-events.jsonl.

Secrets policy. A scrubber (redact-log.ts) runs over all .guild/ artifact writes. Durable artifacts (handoff, wiki, review) are fail-closed on scrub failure. Local telemetry is fail-open with a warning.

Untrusted-content defense. guild:context-assemble wraps recalled chunks in trust markers: operator (skill bodies — no wrapper), reviewed (human-promoted wiki pages), synthesized (auto-generated candidates — trusted=false). A BM25 anomaly gate prevents silent semantic displacement at ingest.

See also

• How Guild Works — phase-by-phase user guide for /guild:guild runs.
• Context Assembly — the three-layer context bundle contract.
• Cost-Aware Model Tiering — auto-score signals, advisor protocol.
• Self-Evolving Skills — the evolution pipeline and rollback.
• Project Memory & Wiki Pattern — the knowledge layer.
• Configuration reference — all settings.json keys.