guild: Instructions file for Claude Code

Guild — repo orientation

Guild is a cross-host plugin that ships 4 machinery agents (advisor, context-manager, developer, team-lead), 15 domain specialist type templates (minted into a project's .guild/agents/ on demand by team composition), and 76 skills — 17 of them indexed — across a brainstorm-plan-execute-review-verify-reflect spine, a categorized wiki with decision capture, and a self-evolution loop with shadow-mode gating.

The runtime shape (bare /guild = T0, three tiers, five class graphs, one review gate, one promotion law, two context sizes) is the Layout laws list below; README carries the user-facing summary.

This AGENTS.md file is the canonical host-neutral instruction file. Claude Code loads CLAUDE.md, but CLAUDE.md must only import this file; all durable directions belong here so Codex, Pi, Antigravity, and AGENTS.md-consuming hosts read the same guidance.

For full architecture and design documentation see https://guildstack.dev/docs.

Where things live

• .claude-plugin/plugin.json, .claude-plugin/marketplace.json — plugin + marketplace manifests.
• skills/ — the skill tree. .claude-plugin/plugin.json indexes exactly the 17 assembler directories (KTD59); everything else ships off-index. An assembler is a three-stage folder: SKILL.md (frontmatter always, body on match) + references/ (L3 chapters, on demand) + scripts/ (compiled, never prompt text). The 58 specialist starter recipes live under skills/specialists/ as copy-on-mint feedstock (KTD13/KTD20) and the dashboard launcher under skills/playbooks/dashboard/; neither is indexed. The former core/ and fallback/ tiers are gone: principles folded into using-guild, and tdd / systematic-debug / worktrees / finish-branch are now chapters of the assembler that invokes them.
• agents/*.md — the 4 machinery agents (advisor, context-manager, developer, team-lead), the only host-registered agents the plugin ships. Populated and authored.
• templates/specialists/*.md — the 15 domain specialist type templates (guild.specialist_template.v1; architect … sales, incl. doc-writer), read-only feedstock minted into a project's .guild/agents/ by roster-resolve.ts mint during team composition.
• commands/*.md — the v2 flat-token command surface (/guild:<verb>; the : plugin namespace stays — Claude Code requires it — v2 only drops the redundant guild- prefix; sub-verbs are positional arguments, never separate files or namespaces).
• hooks/hooks.json — native Claude Code hooks; the .ts sources compile to the committed esbuild bundles under hooks/dist/ (+ hooks/agent-team/dist/) the host actually runs (cd hooks && npm run build after any hook edit — source edits are a no-op until rebuilt). Other hosts consume equivalent behavior through host adapters and graceful fallback.
• src/domains/<id>/ — the twelve domains (KTD1/KTD36): kernel, state, security, config, lifecycle, knowledge, teams, dispatch, review, telemetry, evolve, distribution. Each has ONE public index.ts — nothing outside the domain may reach a sibling file — with internals and colocated tests beside it. The KTD36 fold map is data, at src/domains/distribution/domain-fold.ts, and is recorded in the coverage file.
• src/adapters/ — host family maps and the remaining host-runtime projection (KTD4). Not a thirteenth domain: adapters may read a domain index, a domain must not import adapters.
• src/runtime/mcp/ — the source of the two optional MCP servers; it compiles into the one committed runtime/guild-mcp.js with two D-MCP ids (wiki | trace, KTD3). src/surfaces/ holds only the five class graphs (graphs/*.yaml) and the prompt dialects (prompts/).
• There is no src/modules/ tree: each former module's manifests and code live beside the domain it folded into.
• Host packages are a PROJECTION of the live surface (KTD28): build-host-packages copies straight from commands/, skills/, agents/, hooks/, scripts/. There are no resources/ byte mirrors and no mirror-sync step.
• scripts/ — author-plane CLIs (compile, lint, evolve, telemetry); run under bun, shipped to users as compiled Node under runtime/scripts/.
• mcp-servers/ — tests and fixtures for the two MCP servers; their source is src/runtime/mcp/.
• dist/ — committed per-host packages (claude-code, codex, pi, …) rendered by scripts/build-host-packages.ts; regenerated, never hand-edited.
• tests/ — cross-cutting evals, fixtures, and the Verification Contract (tests/verification-contract/index.json). Every test runs under bun test --isolate; there is no Jest and no layout-laws baseline.
• templates/{skills,agents,products}/ — authoring + product scaffolds (templates/specialists/ is the 15 specialist type templates, described above).
• docs/ — RETIRED as a docs set: holds only a static redirect page to https://guildstack.dev/docs plus the logo asset. The public docs are generated from the umbrella's docs/v2/ + the website; reference knowledge lives in .guild/wiki/. Apart from README.md, CONTRIBUTING.md, and CHANGELOG.md, no documentation lives in this repo.