agent-guild 1.0.0__tar.gz

agent_guild-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: tests (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]   # the lowest supported and the newest
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv run pytest -q
+
+  install-smoke:
+    name: clean install of the built wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv build
+      - name: Install the wheel into an empty venv and run the CLI away from the checkout
+        run: |
+          uv venv --python 3.12 "$RUNNER_TEMP/venv"
+          uv pip install --python "$RUNNER_TEMP/venv/bin/python" dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/venv/bin/agent-guild" --help

agent_guild-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+# Manual on purpose: run it (Actions -> Release -> Run workflow, with the tag, e.g. v1.0.0) after CI is
+# green on main, the tag is pushed, the PyPI trusted publisher exists for this repo and the GitHub
+# environment "pypi" is set up.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish, e.g. v1.0.0
+        required: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write   # to create the GitHub release
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ inputs.tag }}
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: The tag must match the package version
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          v=$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$v" = "$TAG" || { echo "tag $TAG != version $v"; exit 1; }
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+      - name: Create the GitHub release with the CHANGELOG notes and the built files
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          python3 scripts/release_notes.py "$TAG" > release-notes.md
+          gh release create "$TAG" dist/* --title "$TAG" --notes-file release-notes.md --verify-tag

agent_guild-1.0.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Claude Code local state
+.claude/settings.local.json
+CLAUDE.local.md
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

agent_guild-1.0.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.0.0] - 2026-10-21
+
+First release.
+
+- Multi-agent setup for Claude Code: a Sonnet orchestrator that delegates to `architect`, `coder`, `code-grader` and
+  `utility` subagents, with the routing, briefs and memory protocol in `development-workflow.md`.
+- Memory in two layers: memory-bank (current state, in a git-tracked `memory/` folder) and jev-mem (long-term facts,
+  recalled by relevance through an MCP server and hooks).
+- Spec-Driven Development with approval gates via sdd-feature, opt-in per project.
+- `agent-guild` installer: copies the agents, workflow rules and skills into a project, merges `CLAUDE.md`, `.mcp.json`
+  and `.claude/settings.json`, and is safe to re-run. `--without`, `--model`, `--dry-run`, `--force` and more.

agent_guild-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Illescas Romero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_guild-1.0.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.5
+Name: agent-guild
+Version: 1.0.0
+Summary: A multi-agent setup for Claude Code (orchestrator + architect, coder, grader, utility subagents) with memory-bank, jevmem and Spec-Driven Development wired in, installed into a project with one command.
+Project-URL: Homepage, https://github.com/illescasDaniel/agent-guild
+Project-URL: Issues, https://github.com/illescasDaniel/agent-guild/issues
+Author-email: Daniel Illescas Romero <illescas.daniel@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,memory,multi-agent,orchestrator,sdd,spec-driven-development,subagents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# agent-guild
+
+A ready-made **multi-agent setup for [Claude Code](https://claude.com/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](development-workflow.md).
+- **Memory**, in two layers, so context survives between sessions:
+  - [memory-bank](https://github.com/illescasDaniel/memory-bank): *current state* (what's being worked on, decisions,
+    progress), in a git-tracked `memory/` folder.
+  - [jev-mem](https://github.com/illescasDaniel/jev-mem): *long-term facts*, recalled by relevance through an MCP
+    server and session hooks.
+- **Spec-Driven Development (SDD)**, via [sdd-feature](https://github.com/illescasDaniel/sdd-feature-skill): specs,
+  design, interfaces, implementation and grading, with approval gates between phases. Opt-in per project.
+
+```bash
+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
+
+| File | Install to | Role |
+|---|---|---|
+| [development-workflow.md](development-workflow.md) | imported from `~/.claude/CLAUDE.md` | Orchestrator rules: knowledge layers, routing, SDD phase → agent map, briefs, memory protocol |
+| [agents/architect.md](agents/architect.md) | `~/.claude/agents/` | Opus, read-only. Plans, SDD Phase 1 design decisions, Phase 2 interfaces, root causes |
+| [agents/coder.md](agents/coder.md) | `~/.claude/agents/` | Sonnet. Scoped implementation; parallel-safe |
+| [agents/code-grader.md](agents/code-grader.md) | `~/.claude/agents/` | Opus, read-only. SDD Phase 5. Body identical to the sdd-feature skill's grader; only the frontmatter differs |
+| [agents/utility.md](agents/utility.md) | `~/.claude/agents/` | Haiku. Checks, git, moves, bulk edits |
+
+## 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.
+- **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.
+
+## 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`.
+
+```bash
+uvx agent-guild /path/to/project --dry-run
+```
+
+```bash
+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`.
+
+| Flag | Effect |
+|---|---|
+| `--without sdd` / `memory-bank` / `jevmem` | Leave a component out. `sdd` also drops `code-grader` and the gate section; `jevmem` drops its skill, server, hooks and the auto-memory switch |
+| `--model ALIAS` | Project main-session model; default `sonnet` (the per-project alternative to the global setting below), `none` leaves it unset |
+| `--import-cursor-skills` | Also copy the project's `.cursor/skills/*` into `.claude/skills/`; skills that already exist are kept |
+| `--personal-settings` | Put `--model` and `autoMemoryEnabled` in the git-ignored `.claude/settings.local.json` |
+| `--import-auto-memory` | First import the project's existing auto-memory notes into jevmem |
+| `--keep-auto-memory` | Don't switch auto-memory off |
+| `--sources-dir DIR` | Use local clones named `memory-bank/`, `jev-mem/`, `sdd-feature-skill/` instead of GitHub |
+| `--git-exclude` | List the files this run *creates* in `.git/info/exclude` (local to your clone, never committed), so you can try the setup without it showing in `git status`. Off by default: files are added normally and your git settings apply. Edits to files git already tracks (e.g. an existing `.mcp.json`) can't be hidden; the tool warns about them |
+| `--force`, `--dry-run` | Overwrite edited copies; show the plan without writing |
+
+Still per machine, once: `uvx jevmem config init` and `uvx --from jevmem jevmem warmup`.
+
+The manual steps below do the same thing by hand, and also cover the per-machine variant.
+
+### Manual install
+
+Two parts:
+
+1. **Agents and orchestrator rules**: always per machine. They're how you work, not part of any one project.
+2. **Memory and skills** (jevmem MCP server and hooks, auto-memory switch, skills): **per project (recommended)** or
+   per machine. Pick one per project, not both. Doing both injects jevmem notes twice and registers the server twice.
+
+### 1. Agents and orchestrator rules (per machine)
+
+```bash
+mkdir -p ~/.claude/agents && ln -s /path/to/agent-guild/agents/*.md ~/.claude/agents/
+```
+
+```bash
+printf '\n@/path/to/agent-guild/development-workflow.md\n' >> ~/.claude/CLAUDE.md
+```
+
+Orchestrator model: either globally, in `~/.claude/settings.json`, replace `"model": "opusplan"` with
+`"model": "sonnet"`; or only for a project, with `"model": "sonnet"` in its `.claude/settings.json` (or
+`.claude/settings.local.json` to keep it personal). The installer does the latter by default.
+
+jevmem's own settings (API key or local model, `~/.jevmem/config.jsonc`) and its embedding model are per machine
+either way:
+
+```bash
+uvx jevmem config init
+```
+
+```bash
+uvx --from jevmem jevmem warmup
+```
+
+### 2a. Memory and skills per project (recommended)
+
+Everything lives in the repo and is committed. Worktrees, branches and other contributors get the same setup, and
+nothing leaks into projects that don't use it.
+
+Run these from the project's root.
+
+**Skills**, into `.claude/skills/`:
+
+```bash
+npx skills add illescasDaniel/memory-bank -a claude-code -y
+```
+
+```bash
+npx skills add illescasDaniel/sdd-feature-skill -a claude-code -y
+```
+
+The `jev-memory` skill isn't packaged for `npx skills`. Copy it from a clone of jev-mem:
+
+```bash
+cp -r jev-mem/.claude/skills/jev-memory .claude/skills/
+```
+
+**jevmem MCP server**, in the project's `.mcp.json`, pinned:
+
+```bash
+claude mcp add --scope project jevmem -- uvx --from "jevmem>=0.4.0,<0.5" jevmem-mcp
+```
+
+If you already registered jevmem at user scope (`claude mcp add --scope user jevmem …`), that works too. The server
+only provides tools and injects nothing, and notes are stored per project (`project:<repo name>`) either way. Keep
+just one registration, so the server isn't listed twice.
+
+**Hooks and auto-memory switch**, in the project's `.claude/settings.json`:
+
+```json
+{
+  "autoMemoryEnabled": false,
+  "hooks": {
+    "SessionStart": [{"hooks": [{"type": "command", "command": "uvx --from \"jevmem>=0.4.0,<0.5\" jevmem hook session-start", "timeout": 15}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "uvx --from \"jevmem>=0.4.0,<0.5\" jevmem hook user-prompt", "timeout": 20}]}]
+  }
+}
+```
+
+Before setting `autoMemoryEnabled: false`, import the project's existing auto-memory notes (see
+[Importing auto-memory](#importing-auto-memory)). To turn auto-memory off only for yourself, without committing the
+change, put that key in `.claude/settings.local.json` instead.
+
+**Rules**, in the project's `AGENTS.md` / `CLAUDE.md`:
+
+- **Memory bank**: the snippet from the [memory-bank README](https://github.com/illescasDaniel/memory-bank#use-it),
+  then ask the agent to "set up the memory bank".
+- **SDD, if wanted**: the Phase Gate Protocol snippet from the
+  [sdd-feature README](https://github.com/illescasDaniel/sdd-feature-skill#add-this-to-your-agentsmd--claudemd),
+  adjusted to the project's paths. Leave it out to keep SDD manual: the skill still works when you ask for it.
+- **Quality gate command, test conventions, code-navigation MCPs**: the agents look for these there.
+
+### 2b. Memory and skills per machine
+
+For when you want the same setup in every project without touching repos. Don't combine it with 2a in the same
+project.
+
+```bash
+npx skills add illescasDaniel/memory-bank -a claude-code -g -y
+```
+
+```bash
+npx skills add illescasDaniel/sdd-feature-skill -a claude-code -g -y
+```
+
+```bash
+cp -r jev-mem/.claude/skills/jev-memory ~/.claude/skills/
+```
+
+```bash
+claude mcp add --scope user jevmem -- uvx --from "jevmem>=0.4.0,<0.5" jevmem-mcp
+```
+
+In `~/.claude/settings.json`, add `"autoMemoryEnabled": false` at the top level. Then merge these hooks into the
+existing `hooks` block, next to the `PreToolUse` one:
+
+```json
+"SessionStart": [{"hooks": [{"type": "command", "command": "uvx --from \"jevmem>=0.4.0,<0.5\" jevmem hook session-start", "timeout": 15}]}],
+"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "uvx --from \"jevmem>=0.4.0,<0.5\" jevmem hook user-prompt", "timeout": 20}]}]
+```
+
+Then remove the same hooks, server and skills from any project that already defines them.
+
+The per-project rules in `AGENTS.md` / `CLAUDE.md` (memory bank snippet, optional SDD snippet, quality gate) are still
+added per project.
+
+### Importing auto-memory
+
+Claude Code's built-in auto-memory (`~/.claude/projects/<encoded-path>/memory/*.md`) is a second fact store that
+overlaps with jevmem. Before switching it off for a project, import its notes. Run this from the project's root, so
+the notes land in the same `project:<name>` scope that the hooks and MCP server use. Point `--root` at that project's
+folder only, because the default imports every project's memory at once:
+
+```bash
+uvx jevmem import-claude-memory --root ~/.claude/projects/<encoded-project-path>
+```
+
+- **Folder name:** the project's absolute path with `/` replaced by `-`.
+- **Jev must be configured.** Writes are screened by Jev, so the key or local model must be set up, or the notes are
+  queued unscreened and hidden from recall.
+- **Check the result** with `uvx jevmem list`, and `memory_forget` anything stale.
+
+After the switch, the old files stay on disk, but Claude no longer reads or writes them. To turn auto-memory off for a
+single shell instead, set the environment variable `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.
+
+## Development
+
+```bash
+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.
+
+## License
+
+[MIT](LICENSE)