agent-guild

A ready-made multi-agent setup for Claude Code, installed into a project with one command. A Sonnet orchestrator delegates to specialist subagents (Opus architect and grader, Sonnet coders, Haiku utility), and three features come wired in:

• Multiple agents: architect, coder (parallel-safe), code-grader and utility, plus the orchestrator rules that decide who does what: routing, briefs and reports. See development-workflow.md.
• Memory, in two layers, so context survives between sessions:
  • memory-bank: current state (what's being worked on, decisions, progress), in a git-tracked memory/ folder.
  • jev-mem: long-term facts, recalled by relevance through an MCP server and session hooks.
• Spec-Driven Development (SDD), via sdd-feature: specs, design, interfaces, implementation and grading, with approval gates between phases. Opt-in per project.

uvx agent-guild /path/to/project

                         user
                          │  approvals (chat only)
                          ▼
              ┌──────────────────────┐   reads/writes   memory/ (state, gate status)
              │ orchestrator (Sonnet)│ ───────────────▶ jevmem (facts)      ← single writer
              └──────────────────────┘                  specs/, wireframes/
        plans │      chunks │       grade │      chores │
              ▼             ▼             ▼             ▼
        architect        coder ×N     code-grader     utility
        (Opus, RO)      (Sonnet)      (Opus, RO)      (Haiku)
              └── all read specs/, memory/, jevmem recall; report memory candidates + friction ──┘

Not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

Files

Install

Quick: the installer (per project)

agent-guild copies everything into a project (plain copies, not links, so the project can edit them) and is safe to re-run: files that differ from the shipped version are skipped unless you pass --force.

uvx agent-guild /path/to/project --dry-run

uvx agent-guild /path/to/project

It does, in the project:

• copies agents/*.md and development-workflow.md into .claude/;
• copies the memory-bank, jev-memory and sdd-feature skills into .claude/skills/ (cloned from GitHub, or from local clones with --sources-dir DIR);
• adds three removable sections to CLAUDE.md: Agents and delegation, Memory bank and Phase Gate Protocol. They live in CLAUDE.md, not AGENTS.md, because they are rules for Claude Code and its subagents; AGENTS.md stays tool-neutral. If the project has an AGENTS.md, CLAUDE.md starts with @AGENTS.md. A section that CLAUDE.md or AGENTS.md already has is not added again;
• adds the pinned jevmem server to .mcp.json and the jevmem hooks to .claude/settings.json, merging into existing files;
• sets autoMemoryEnabled: false and the project's model to sonnet.

Still per machine, once: uvx jevmem config init and uvx --from jevmem jevmem warmup.

Prefer to do it by hand, or want the per-machine variant (agents and memory in ~/.claude for every project)? See docs/manual_installation.md.

Development

git clone https://github.com/illescasDaniel/agent-guild && cd agent-guild
uv run pytest
uv run agent-guild /path/to/project --dry-run

From a checkout, the CLI reads agents/, templates/ and development-workflow.md at the repo root; the published wheel bundles them.

Adding it to a project that already has its own setup

The installer never overwrites a file that differs from the shipped one (and skips CLAUDE.md sections that AGENTS.md or CLAUDE.md already has), so it is safe to run on a project with its own agents, skills and rules. After it runs:

• Skipped files are yours. Anything the log marks skipped ... differs keeps your version. If it is an older or customised copy of a shipped one (the sdd-feature skill, code-grader, jev-memory), diff it against the shipped file and merge what you want by hand. --force replaces it instead.
• New files can land next to yours. A skill folder you already have keeps its SKILL.md, but the shipped files that are missing (templates, scripts) are added beside it. If .claude/skills is a symlink to .cursor/skills, the log says so, and the skills are written there.
• Cursor reads .claude/agents/ too. The agents installed here work in Cursor without copies in .cursor/agents/ (.cursor/agents/ wins on a name clash). Cursor ignores tools, disallowedTools and effort, so the read-only agents are not read-only there. If your project has a test that requires every .claude/agents/*.md to have a .cursor/agents/ twin, relax it to require the twin only for the Cursor agents.
• Skip what you already have with --without memory-bank / jevmem / sdd, for example when your own memory-bank skill has a different name.

Design choices

• The orchestrator is the only writer of memory. Parallel coders writing memory/ would conflict, and someone has to decide what is worth remembering. Subagents can read memory, including jevmem recall, and return Memory candidates and Friction sections in their reports.
• Subagents don't get the jevmem hooks. The SessionStart and UserPromptSubmit hooks fire in the main session only. So the agents that need history (architect, coder, grader) can call memory_recall themselves.
• The files on disk are the hand-off. Once a wireframe, SPEC.md or interfaces exist, briefs point to them instead of restating them. That solves the cold-start problem without long prompts.
• disallowedTools instead of a tools allowlist for architect, coder and grader. They inherit project MCP servers (e.g. code-navigation MCPs) without per-project edits, while jevmem writes and file edits stay blocked where needed. utility keeps a plain allowlist.
• Language coders are separate, opt-in agents with an allowlist. A generic coder only inherits the project's navigation MCPs; in practice it still reached for grep and sed, because the MCP tools arrive deferred (name only) and the brief or its own habits point elsewhere. coder-python, coder-swift and coder-typescript (--with) are generated from coder.md plus a navigation section that names the MCP's tools, and list those tools in tools: so they load up front. A CLAUDE.md rule routes that language's work to them. Without --with, nothing changes.
• The grader runs on Opus. The code it grades was written by Sonnet coders, so a different, stronger model gives a more independent review.
• SDD is opt-in. The global workflow uses SDD only when a project's AGENTS.md / CLAUDE.md adopts the Phase Gate Protocol, or when you ask for the sdd-feature skill directly. Projects that don't want gates just leave the rule out.
• Gates and gate status. SDD gates stay between the orchestrator and the user. The gate status is recorded in memory/activeContext.md, so a new session resumes at the right gate.

License

MIT