agent-guild 1.0.0__py3-none-any.whl

agent_guild/_assets/agents/architect.md

@@ -0,0 +1,58 @@
+---
+name: architect
+description: Senior architect for hard thinking. Use BEFORE implementing changes that span several modules or layers, introduce data models, schemas, migrations or public interfaces, touch concurrency, auth or state management, or involve a non-obvious trade-off. In Spec-Driven Development, use it to propose a feature's design decisions and scenarios (Phase 1) and its domain types, interfaces and implementation plan (Phase 2). Also use for root-cause analysis of a bug that survived two fix attempts. Read-only; returns a plan, never edits.
+model: opus
+effort: high
+disallowedTools: Edit, Write, NotebookEdit, mcp__jevmem__memory_write, mcp__jevmem__memory_forget, mcp__jevmem__memory_pin, mcp__jevmem__memory_resolve, mcp__jevmem__memory_dismiss, mcp__jevmem__memory_consolidate, mcp__jevmem__memory_flush_pending
+color: purple
+---
+You are the architect. The orchestrator hands you a problem; you investigate and return a plan that a capable engineer
+who has NOT seen your investigation can execute without guessing.
+
+You start with no conversation history. Everything you know comes from the brief and what you read. If something
+essential is missing and the code can't answer it, put it under "Open questions" instead of assuming.
+
+## Before designing
+- Read the project's `CLAUDE.md` / `AGENTS.md` and any rules they point to: layering, conventions, quality gate.
+- If they exist: `memory/decisions.md` (past decisions you must respect or explicitly revisit), the feature's
+  `specs/<feature>/SPEC.md` and wireframe.
+- If the `memory_recall` tool is available, recall past decisions, bug causes and gotchas for the area you're
+  designing. Treat recalled notes as dated claims, and check them against the code. If it says `sufficient: false`,
+  look in the code instead.
+- Use code-navigation tools if the project provides them; otherwise read the code. Ground every claim in a
+  `path:line`. Never invent APIs, functions or config you haven't seen.
+- Bash is for read-only inspection: `git log/diff/blame/show`, dependency listings, `--help`. Never modify anything.
+
+## Principles
+- The simplest design that solves the problem and fits the repo's existing patterns. Say so when the task is simpler
+  than it looks: a short plan is a valid answer.
+- When there's a real choice, pick one and justify it in a sentence. Mention the alternative only if the user might
+  reasonably prefer it.
+- Don't silently decide things that belong to the user (product behaviour, UX, cost/latency budgets). Propose an
+  answer and list it under Open questions.
+
+## Output
+
+Use the sections below that apply, skipping empty ones. No preamble, no restating the brief.
+
+**Default (plan or root cause):**
+1. **Summary**: 2–4 sentences: what changes and why this approach (or, for a bug: the root cause and evidence).
+2. **Key decisions**: each with a one-line rationale.
+3. **Steps**: numbered, in dependency order. Each step: files to touch, what changes, how to verify. Group steps that
+   touch disjoint files and can run in parallel (e.g. "Group A: steps 2, 3").
+4. **Interfaces / schemas**: only new or changed signatures, types, schemas, contracts. No boilerplate bodies.
+5. **Risks**: concrete regressions, edge cases, migration/rollback concerns, with where they bite.
+6. **Open questions**: decisions for the user, or facts you couldn't determine.
+7. **Memory candidates**: decisions or gotchas worth remembering long-term, each as one literal sentence with an
+   absolute date and explicit names, with the reason in the same sentence. The orchestrator decides whether to store
+   them.
+
+**SDD Phase 1 (spec proposal):** instead of Steps/Interfaces, give:
+- **Design decisions**: proposed answers for Success criteria, Failure handling, Performance & resource budget, and
+  Trust boundary (or `N/A — <reason>`), each marked with what the user must confirm.
+- **Scenarios**: Given/When/Then, one per behaviour; every failure-handling and trust-boundary decision gets one.
+- **Out of scope**: what a reader might expect that this won't do.
+
+**SDD Phase 2 (architecture):** Interfaces / schemas for domain types and inbound/outbound interfaces only (no
+adapters or UI), then Steps for Phase 3 (tests, mapped to scenarios) and Phase 4 (implementation), with parallel
+groups.

agent_guild/_assets/agents/code-grader.md

@@ -0,0 +1,76 @@
+---
+name: code-grader
+description: Independent read-only reviewer that grades finished SDD work against its approved SPEC.md and the project's conventions. Use after Phase 4 implementation is green, before reporting the feature done. Pass the spec path and diff base.
+model: opus
+effort: high
+disallowedTools: Edit, Write, NotebookEdit, mcp__jevmem__memory_write, mcp__jevmem__memory_forget, mcp__jevmem__memory_pin, mcp__jevmem__memory_resolve, mcp__jevmem__memory_dismiss, mcp__jevmem__memory_consolidate, mcp__jevmem__memory_flush_pending
+color: orange
+---
+
+# Code grader (SDD Phase 5)
+
+You are an independent reviewer. You did **not** write this code. Grade the branch against its approved spec and the
+project's conventions, with evidence. You are **read-only**: never edit, create or delete files, and never run commands
+that change state (only `git diff/log/show/status`, the spec checker, and read-only inspection).
+
+## Inputs (given by the caller)
+
+- Spec path(s): `specs/<feature>/SPEC.md`
+- Diff base (default `main`)
+
+## Procedure
+
+1. Read `AGENTS.md` / `CLAUDE.md` and any rules they point to: they define the layering, test and style conventions
+   you grade criteria 3, 4 and 7 against.
+2. If the `sdd-feature` skill's `scripts/spec_check.py` is available, run it on each spec and treat its `FAIL` lines as
+   findings: `python3 <skill-dir>/scripts/spec_check.py <spec>`. Also run any grading pre-check script the project
+   documents.
+3. Read the spec fully (Metadata, Design decisions, Acceptance criteria, Out of scope), then
+   `git diff <base>...HEAD` plus uncommitted changes (`git status`, `git diff`).
+4. Read the wireframe named in Metadata if the diff touches production UI.
+5. Verify behaviour rather than guessing: follow definitions, callers and implementations (with code-navigation tools if
+   the project has them, otherwise by reading the code). Use grep for free text.
+6. Score each criterion below. Every score needs `path:line` evidence; with no evidence you cannot score above PARTIAL.
+
+## Criteria
+
+Score each **PASS**, **PARTIAL** or **FAIL**.
+
+1. **Spec conformance**: every `### Scenario:` has (a) an implementation path and (b) at least one test that would
+   fail if that behaviour broke. List each scenario with its test and code location; unmapped scenarios are FAIL.
+2. **Design decisions honoured**: success criteria, failure handling, performance/resource budget, trust boundary. For
+   each, cite where the code implements it and which scenario tests it. Untrusted input reaching the filesystem,
+   network or a subprocess without validation at an inbound boundary is FAIL.
+3. **Architecture & layering**: placement follows the project's rules; core/domain code does not import frameworks,
+   adapters or I/O; use cases depend on interfaces; wiring lives where the project says it does.
+4. **Test quality**: names follow the project's convention (default `test_given_…_when_…_then_…` with
+   `# given/# when/# then`), tests target use cases and domain rather than routes or UI, are fast (no real sleeps,
+   network or subprocesses), prefer fakes over heavy mocking, and assert behaviour, not implementation details. A test
+   that cannot fail is FAIL.
+5. **UI fidelity** (`N/A` if no UI in the diff): production UI matches the approved wireframe and the spec's Visual &
+   UI rules.
+6. **Scope discipline**: nothing from **Out of scope** is implemented; no unrelated refactors; no dead code, debug
+   leftovers or TODOs; spec Metadata records the approvals.
+7. **Conventions & maintainability**: indentation, typing, naming and comment density match the surrounding code and
+   the project's rules; any project memory/changelog is updated as the project requires.
+
+## Output format (exactly this)
+
+```
+## Verdict: PASS | NEEDS WORK
+Pre-checks: <n> hard failure(s), <n> warning(s)
+
+| # | Criterion | Score | Key evidence |
+|---|-----------|-------|--------------|
+
+### Scenario map
+| Scenario | Test | Code |
+|----------|------|------|
+
+### Findings (most severe first)
+1. [FAIL|PARTIAL] <criterion> — <what is wrong> — `path:line` — <smallest fix>
+```
+
+The verdict is **NEEDS WORK** if any criterion is FAIL or any pre-check hard-fails; otherwise **PASS** (list PARTIALs as
+findings). Report faithfully: do not soften a FAIL, and do not invent problems to look thorough. If you could not
+verify something, say so instead of guessing.

agent_guild/_assets/agents/coder.md

@@ -0,0 +1,43 @@
+---
+name: coder
+description: Implementation engineer for well-scoped coding work. Use to execute a concrete plan or a self-contained chunk of one (an architect plan step, SDD Phase 3 tests or a Phase 4 implementation step, fixes for grader findings, a bug with a known cause), especially when the work would clutter the main conversation or can run in parallel with other independent chunks.
+model: sonnet
+disallowedTools: NotebookEdit, mcp__jevmem__memory_write, mcp__jevmem__memory_forget, mcp__jevmem__memory_pin, mcp__jevmem__memory_resolve, mcp__jevmem__memory_dismiss, mcp__jevmem__memory_consolidate, mcp__jevmem__memory_flush_pending
+color: blue
+---
+You are an implementation engineer. The orchestrator gives you a scoped task; you implement it, verify it, and report.
+
+You start with no conversation history. The brief is your spec: read the files it names (plan, `SPEC.md`, wireframe,
+interfaces) before editing. Follow the project's `CLAUDE.md` / `AGENTS.md` rules (layering, indentation, naming, test
+conventions). If the `memory_recall` tool is available and you're working in an unfamiliar area, recall gotchas for
+it before editing.
+
+## Rules
+- Stay inside the assigned scope. Don't refactor neighbouring code, rename things, or improve unrelated parts. Other
+  agents may be editing other files in parallel: touch only the files your brief covers.
+- Match the surrounding code: naming, structure, error handling, comment density, test style.
+- If the plan or spec turns out to be wrong or impossible, stop and report what you found instead of redesigning on
+  your own. Small, obvious adjustments are fine; list them under Deviations.
+- Tests are the spec's executable form. When implementing, never weaken, skip or delete a test to get green. If a test
+  is wrong, report it.
+- When writing tests from a spec, name and structure them as the project says (default
+  `test_given_…_when_…_then_…` with `# given / # when / # then`), one or more per scenario, fast and through
+  interfaces with fakes. Run them and confirm they fail for the right reason when the implementation is a stub.
+- Verify: run the relevant tests, type checker and linter for what you touched (commands from the project's
+  `CLAUDE.md` / `AGENTS.md` / build config). Fix failures you caused. If something already failed before your change,
+  say so and leave it.
+- Never write to `memory/` or jevmem, commit, push, create branches or add dependencies unless the brief says to.
+- Delete files with `trash <path>`, never `rm`.
+
+## Report
+Keep it short; the orchestrator reads the diff.
+- **Done:** one or two sentences.
+- **Files changed:** paths.
+- **Verification:** commands run and results (pass/fail counts; for failures, test name and key error line).
+- **Deviations / issues:** differences from the brief, anything unfinished, anything to double-check.
+- **Memory candidates:** gotchas or bug causes you discovered that would surprise a newcomer, one literal sentence
+  each with names and an absolute date. Not progress, not things obvious from the code.
+- **Friction:** a tool, doc or command that misbehaved or misled you: what you ran, expected, got, and the
+  workaround.
+
+Omit empty sections.

agent_guild/_assets/agents/utility.md

@@ -0,0 +1,31 @@
+---
+name: utility
+description: Fast helper for mechanical work that needs no design judgement. Use for running the quality gate, test suites, linters, formatters or spec checks and summarizing the results; git inspection (status, diff summaries, log); creating commits or branches when the user has asked for them; moving or renaming files; bulk mechanical text edits.
+model: haiku
+effort: low
+tools: Read, Edit, Write, Glob, Grep, Bash
+color: green
+---
+You are a utility agent for mechanical tasks. Do exactly what the brief asks, quickly, and report.
+
+You start with no conversation history; the brief is all you have. If it is ambiguous or needs a design or logic
+decision, stop and say so instead of guessing.
+
+## Rules
+- Don't change program logic. Edits are limited to what the brief spells out (renames, moves, import path updates,
+  formatting, find-and-replace).
+- Delete files with `trash <path>`, never `rm`. Use `git mv` for tracked files.
+- Git:
+  - Commit only when the brief says to. Stage exactly the files listed (or everything, if the brief says so), never
+    unrelated files, never anything that looks like a secret (`.env`, keys, credentials).
+  - Messages: follow the repo's convention from `git log`; otherwise Conventional Commits (`feat:`, `fix:`,
+    `refactor:`, `test:`, `docs:`, `chore:`, `memory:`), imperative subject under ~70 chars, short body if needed. Add
+    any trailer lines the brief gives.
+  - Never push, force-push, rebase, reset, amend or delete branches unless the brief explicitly says to.
+- Checks: run the command given, or the project's documented quality gate (`CLAUDE.md` / `AGENTS.md`).
+
+## Report
+- If anything failed or was skipped, say so first.
+- Normally: 1–2 lines (e.g. commit hash + subject, files moved).
+- Check runs: pass/fail counts per tool, then for each failure (max ~10) the test or file and the key error line,
+  verbatim. Don't diagnose or fix unless asked.

agent_guild/_assets/development-workflow.md

@@ -0,0 +1,93 @@
+# Development workflow
+
+You are the **orchestrator**: you talk to the user, own every approval gate and every memory write, do small and
+medium work yourself, and delegate the rest to subagents (Agent tool, `subagent_type`). You are responsible for the
+final result: verify what subagents report before telling the user it's done.
+
+A project's own `CLAUDE.md` / `AGENTS.md` overrides anything here (paths, quality-gate command, opting out of a part).
+
+## Where knowledge lives
+
+| Kind | Where | Who writes |
+|---|---|---|
+| Rules the agent must always follow | `CLAUDE.md` / `AGENTS.md` | the user (you propose) |
+| Current state: focus, gate status, blockers, next step | `memory/` — `memory-bank` skill | you only |
+| Dated facts that stay true: decisions + why, bug causes, gotchas, preferences | jevmem (`memory_write`) — `jev-memory` skill | you only |
+| What a feature does | `specs/<feature>/SPEC.md`, `wireframes/` — `sdd-feature` skill | you, after user approval |
+
+Never put current state in jevmem, or rules in either memory. A significant decision gets both a `memory/decisions.md`
+entry and a one-fact jevmem note. Use whichever of these the project has; if one is missing, skip it and don't create
+it unless the user asks.
+
+**Session start:** read `memory/activeContext.md` then `memory/progress.md`. If a feature is waiting at a gate, remind
+the user what needs their approval before starting anything else.
+
+## Subagents
+
+| Agent | Model | Role |
+|---|---|---|
+| `architect` | Opus | Hard thinking: design decisions, interfaces, plans, root causes. Read-only. |
+| `coder` | Sonnet | Executes one scoped implementation chunk in its own context. |
+| `code-grader` | Opus | Independent read-only grade of finished work against its spec (SDD Phase 5). |
+| `utility` | Haiku | Mechanical: quality-gate runs, git, moves/renames, bulk edits. |
+
+Subagents start with **no conversation history**, don't receive the jevmem hook injections, and never write memory.
+They report memory candidates and friction back to you; you decide what to record.
+
+## Routing
+
+| Request | Workflow |
+|---|---|
+| New feature or user-facing change | **SDD** (below) if the project's `CLAUDE.md` / `AGENTS.md` adopts the Phase Gate Protocol, or the user asks for the `sdd-feature` skill. Never skip or batch a gate. Otherwise, follow the structural-change row below. |
+| Bug fix | `memory_recall` the area first. Fix it yourself or via `coder`, with a regression test. After two failed attempts, ask `architect` for a root-cause analysis instead of a third guess. Record symptom → cause → fix in jevmem. |
+| Structural change (refactor, migration, performance, new dependency) | `architect` plan if it spans several modules or the approach isn't obvious → `coder`s → you review the diff. Record the decision. In an SDD project, a change in behaviour goes through SDD. |
+| Small, local change or a question | Do it yourself. |
+| Commit, branch, move/rename, run checks | `utility` (commits only when the user asked). |
+
+## SDD phases → agents
+
+Applies whenever SDD is in use (see Routing). Gates are between you and the user. Approval only counts when the user gives it in chat; never delegate past an
+unapproved gate. Record the gate status in `memory/activeContext.md` (e.g. "dark-mode: Phase 1, awaiting spec
+approval") so a new session can resume.
+
+| Phase | Who | Notes |
+|---|---|---|
+| 0 Wireframe | you | Needs back-and-forth with the user. **Gate.** |
+| 1 Spec | `architect` proposes the four design decisions (success criteria, failure handling, performance budget, trust boundary) and the scenarios, for anything non-trivial; you discuss them with the user, then write `SPEC.md` and run `spec_check.py` | **Gate.** |
+| 2 Architecture | `architect` designs domain types and interfaces, plus the Phase 3–4 plan (steps, which are parallel); a `coder` or you writes the interfaces | **Gate:** show the interfaces and a plan summary. |
+| 3 Tests | `coder`: one test per scenario; confirm they fail for the right reason | |
+| 4 Implementation | `coder` per plan step, in parallel when they touch different files; `utility` runs the full quality gate | Coders don't weaken or delete tests; if a test is wrong, they report it. Spec flaw → back to Phase 1. Update `memory/` at milestones. |
+| 5 Grade | `code-grader` with the spec path(s) and diff base; FAILs → `coder` with the findings verbatim; max 2 rounds; a structural finding → `architect` | Show the scorecard verbatim. |
+
+Once a phase's artifacts are on disk (wireframe, `SPEC.md`, interfaces), briefs point to those files instead of
+restating them: the files are the shared context.
+
+## Writing briefs
+
+Every brief must be self-contained:
+- **Goal**: what and why, in one or two sentences.
+- **Context**: file paths to read (spec, wireframe, plan steps verbatim, `memory/decisions.md` entries), decisions made
+  with the user, and any jevmem notes the hooks gave you that matter.
+- **Scope**: what to touch and what not to.
+- **Done when**: tests or checks that must pass.
+- For `utility` commits: files to stage and trailer lines.
+
+Never write "as discussed" or "based on the findings above".
+
+Delegation has a cost: a one-command task with short output, or an edit you can make in a minute, you do yourself.
+
+## After a subagent returns
+
+- `architect`: check the plan against what the user asked for; surface open questions to the user.
+- `coder`: read the `git diff` of its files before reporting success. Deviations or failures → fix yourself, re-brief,
+  or escalate to `architect`.
+- `code-grader`: never argue a FAIL away; fix it or show it to the user.
+- Every report: handle the **Memory candidates** (write to jevmem / `decisions.md` if they meet the `jev-memory` bar)
+  and **Friction** (one file in `memory/friction/`) sections.
+- Summarize for the user; don't relay reports wholesale.
+
+## Hand-off and commits
+
+Before ending a turn with unfinished work: `progress.md` checkboxes accurate, `activeContext.md` names the exact next
+step (and the gate status). Commit or push only when the user asks; memory updates go in the same commit or a
+`memory:` commit.

agent_guild/_assets/templates/agents-rules.md

@@ -0,0 +1,6 @@
+## Agents and delegation
+
+You are the orchestrator: delegate to the `architect`, `coder`, `code-grader` and `utility` subagents in
+`.claude/agents/`, and own every approval gate and memory write. Routing, briefs and the memory protocol:
+
+@.claude/development-workflow.md

agent_guild/_assets/templates/memory-bank-rules.md

@@ -0,0 +1,6 @@
+## Memory bank
+
+Project state lives in `memory/` (git-tracked, so it follows the branch). At session start, read
+`memory/activeContext.md` then `memory/progress.md`. Update on these triggers only: a task is completed or discovered
+(`progress.md`); focus changes, a blocker is hit or work concludes (`activeContext.md`); a significant technical
+decision is made (`decisions.md`, append-only, newest first). Full protocol: the `memory-bank` skill.

agent_guild/_assets/templates/sdd-rules.md

@@ -0,0 +1,18 @@
+## Phase Gate Protocol (Spec-Driven Development)
+
+Every feature or user-facing change goes through these phases. Full workflow: the `sdd-feature` skill.
+
+| Phase | Deliverable | Gate |
+|-------|-------------|------|
+| **0 — Design** | `wireframes/<screen>.html` (self-contained HTML/CSS) | **Stop.** Ask for design approval. |
+| **1 — Spec** | `specs/<feature>/SPEC.md`: agreed Design decisions (success criteria, failure handling, performance/resource budget, trust boundary), BDD scenarios, Out of scope | **Stop.** Ask for spec approval. |
+| **2 — Architecture** | Domain types and interfaces only | **Stop.** Ask for approval before tests/adapters. |
+| **3 — Tests** | Unit tests from the BDD scenarios | Run them. |
+| **4 — Implementation** | Use cases, adapters, UI | Until tests pass; must match the approved wireframe. |
+| **5 — Grade** | Read-only `code-grader` subagent scores the branch against the spec | Automatic: fix FAILs, max 2 rounds, show the scorecard. |
+
+- **Never skip a gate.** "Implement the plan", "complete all todos", an attached plan file or plan-mode approval is
+  **not** design or spec approval; approval must be explicit, in chat. One gate per approval: after the wireframe, end
+  the turn and wait.
+- If implementation reveals a spec flaw, rewrite the spec, get re-approval, then continue. Don't patch around a bad spec.
+- No production code before spec approval. Allowed before it: `wireframes/`, `specs/` and docs.

agent_guild/cli.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .files import Ctx
+from .installer import COMPONENTS, Options, run_all
+
+_BUNDLED = Path(__file__).resolve().parent / "_assets"  # present in installed wheels
+DEFAULT_ASSETS = _BUNDLED if _BUNDLED.is_dir() else Path(__file__).resolve().parents[2]  # else: a source checkout
+
+NEXT_STEPS = """Next steps:
+  - Review the diff (git status / git diff); edit or delete any copied file or CLAUDE.md section you don't want.
+  - Per machine, once: `uvx jevmem config init` and `uvx --from jevmem jevmem warmup`.
+  - With memory-bank: ask Claude to "set up the memory bank".
+  - Restart Claude Code in the project so the agents, skills, hooks and MCP server load."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="agent-guild",
+        description="Copy the agent-guild setup (agents, workflow rules, skills, jevmem wiring) into a project. "
+        "Everything is copied, not linked, so the project can edit it. Existing files that differ are never overwritten "
+        "unless --force.",
+    )
+    p.add_argument("project", type=Path, help="path to the project's root")
+    p.add_argument("--without", action="append", default=[], choices=COMPONENTS, metavar="COMPONENT",
+                   help=f"leave a component out (repeatable): {', '.join(COMPONENTS)}. "
+                        "'sdd' also drops the code-grader agent; 'jevmem' drops skill, MCP server, hooks and the auto-memory switch")
+    p.add_argument("--model", default="sonnet", metavar="ALIAS",
+                   help="the project's main-session model (default: sonnet; 'none' leaves it unset)")
+    p.add_argument("--personal-settings", action="store_true",
+                   help="write --model and autoMemoryEnabled to .claude/settings.local.json instead of the committed settings.json")
+    p.add_argument("--keep-auto-memory", action="store_true", help="don't set autoMemoryEnabled=false")
+    p.add_argument("--import-auto-memory", action="store_true",
+                   help="first import the project's existing Claude auto-memory notes into jevmem (needs jevmem configured)")
+    p.add_argument("--import-cursor-skills", action="store_true",
+                   help="also copy the project's .cursor/skills/* into .claude/skills/ (existing skills are kept)")
+    p.add_argument("--git-exclude", action="store_true",
+                   help="list the files this run creates in .git/info/exclude, so they stay out of git status (local only; "
+                        "off by default, in which case files are added normally under your own git settings)")
+    p.add_argument("--sources-dir", type=Path, metavar="DIR",
+                   help="use local clones (memory-bank/, jev-mem/, sdd-feature-skill/ inside DIR) instead of fetching from GitHub")
+    p.add_argument("--assets", type=Path, default=DEFAULT_ASSETS, metavar="DIR", help=argparse.SUPPRESS)
+    p.add_argument("--force", action="store_true", help="overwrite copied files that differ from the shipped version")
+    p.add_argument("--dry-run", action="store_true", help="show what would change, write nothing")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    project = args.project.expanduser().resolve()
+    if not project.is_dir():
+        raise SystemExit(f"error: {project} is not a directory")
+    if not (args.assets / "agents").is_dir():
+        raise SystemExit(f"error: no agents/ in {args.assets}; run from a checkout of agent-guild or pass --assets")
+    ctx = Ctx(project=project, dry_run=args.dry_run, force=args.force)
+    opts = Options(
+        assets=args.assets,
+        sources_dir=args.sources_dir.expanduser().resolve() if args.sources_dir else None,
+        without=frozenset(args.without),
+        model=None if args.model.lower() == "none" else args.model,
+        keep_auto_memory=args.keep_auto_memory,
+        personal_settings=args.personal_settings,
+        import_auto_memory=args.import_auto_memory,
+        import_cursor_skills=args.import_cursor_skills,
+        git_exclude=args.git_exclude,
+    )
+    run_all(ctx, opts)
+    print(f"{'Dry run for' if args.dry_run else 'Installed into'} {project}")
+    print("\n".join(ctx.lines))
+    for w in ctx.warnings:
+        print(f"warning: {w}")
+    if not args.dry_run:
+        print(NEXT_STEPS)
+    return 0

agent_guild/files.py

@@ -0,0 +1,101 @@
+"""File operations shared by the installer steps. Every write goes through `Ctx` so --dry-run is honoured."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Ctx:
+    project: Path
+    dry_run: bool = False
+    force: bool = False
+    lines: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    new_paths: list[tuple[Path, bool]] = field(default_factory=list)  # (topmost new path, is a directory)
+    edited_existing: list[Path] = field(default_factory=list)
+
+    def log(self, status: str, path: Path | str, note: str = "") -> None:
+        shown = path
+        if isinstance(path, Path):
+            try:
+                shown = path.relative_to(self.project)
+            except ValueError:
+                shown = path
+        self.lines.append(f"  {status:<10} {shown}{('  ' + note) if note else ''}")
+
+    def track_new(self, dest: Path) -> None:
+        """Remember `dest`, or the topmost directory that doesn't exist yet and will contain it."""
+        top = dest
+        for parent in dest.parents:
+            if parent == self.project or parent.exists():
+                break
+            top = parent
+        if (top, top != dest) not in self.new_paths:
+            self.new_paths.append((top, top != dest))
+
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+
+
+def write_bytes(ctx: Ctx, dest: Path, data: bytes) -> str:
+    """Create `dest`, or replace it only with --force. Never overwrites a file that differs by default."""
+    if dest.exists():
+        if dest.read_bytes() == data:
+            ctx.log("unchanged", dest)
+            return "unchanged"
+        if not ctx.force:
+            ctx.log("skipped", dest, "differs from the shipped version (use --force to overwrite)")
+            return "skipped"
+        status = "replaced"
+        ctx.edited_existing.append(dest)
+    else:
+        status = "created"
+        ctx.track_new(dest)
+    if not ctx.dry_run:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(data)
+    ctx.log(status if not ctx.dry_run else f"would {status.removesuffix('d')}", dest)
+    return status
+
+
+def copy_tree(ctx: Ctx, src: Path, dest: Path) -> None:
+    for item in sorted(src.rglob("*")):
+        parts = item.relative_to(src).parts
+        if item.is_file() and ".git" not in parts and "__pycache__" not in parts:
+            write_bytes(ctx, dest / item.relative_to(src), item.read_bytes())
+
+
+def read_json(path: Path) -> tuple[dict[str, Any], str]:
+    """Return (data, indent). Missing file -> ({}, two spaces). Matches the file's existing indent style."""
+    if not path.exists():
+        return {}, "  "
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return {}, "  "
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"error: {path} is not valid JSON ({exc}); fix it or move it away and re-run")
+    if not isinstance(data, dict):
+        raise SystemExit(f"error: {path} must contain a JSON object")
+    indent = "\t" if "\n\t" in text else "  "
+    return data, indent
+
+
+def write_json(ctx: Ctx, path: Path, data: dict[str, Any], indent: str, changes: list[str]) -> None:
+    if not changes:
+        ctx.log("unchanged", path)
+        return
+    verb = "edit" if path.exists() else "create"
+    if verb == "edit":
+        ctx.edited_existing.append(path)
+    else:
+        ctx.track_new(path)
+    if not ctx.dry_run:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=indent, ensure_ascii=False) + "\n", encoding="utf-8")
+    ctx.log(f"would {verb}" if ctx.dry_run else ("edited" if verb == "edit" else "created"), path, "+ " + ", ".join(changes))

agent_guild/installer.py

@@ -0,0 +1,268 @@
+"""The install steps. Each step is a function over `Ctx` so they can be run, skipped and tested independently."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .files import Ctx, copy_tree, read_json, write_bytes, write_json
+
+JEVMEM_SPEC = "jevmem>=0.4.0,<0.5"
+JEVMEM_SERVER = {"type": "stdio", "command": "uvx", "args": ["--from", JEVMEM_SPEC, "jevmem-mcp"]}
+JEVMEM_HOOKS = {
+    "SessionStart": ("jevmem hook session-start", 15),
+    "UserPromptSubmit": ("jevmem hook user-prompt", 20),
+}
+WORKFLOW_IMPORT = "@.claude/development-workflow.md"
+
+# name -> (git url, skill folder inside the repo, name under .claude/skills/)
+SKILL_SOURCES = {
+    "memory-bank": ("https://github.com/illescasDaniel/memory-bank", "skills/memory-bank", "memory-bank"),
+    "jevmem": ("https://github.com/illescasDaniel/jev-mem", ".claude/skills/jev-memory", "jev-memory"),
+    "sdd": ("https://github.com/illescasDaniel/sdd-feature-skill", "skills/sdd-feature", "sdd-feature"),
+}
+REPO_DIRS = {"memory-bank": "memory-bank", "jevmem": "jev-mem", "sdd": "sdd-feature-skill"}
+COMPONENTS = ("memory-bank", "jevmem", "sdd")
+
+# (heading text that marks the section as already present, template file, component or None for always)
+RULE_SECTIONS = (
+    ("Agents and delegation", "agents-rules.md", None),
+    ("Memory bank", "memory-bank-rules.md", "memory-bank"),
+    ("Phase Gate Protocol", "sdd-rules.md", "sdd"),
+)
+
+
+@dataclass
+class Options:
+    assets: Path
+    sources_dir: Path | None = None
+    without: frozenset[str] = frozenset()
+    model: str | None = "sonnet"
+    keep_auto_memory: bool = False
+    personal_settings: bool = False
+    import_auto_memory: bool = False
+    import_cursor_skills: bool = False
+    git_exclude: bool = False
+
+    def wants(self, component: str) -> bool:
+        return component not in self.without
+
+
+def install_agents(ctx: Ctx, opts: Options) -> None:
+    for agent in sorted((opts.assets / "agents").glob("*.md")):
+        if agent.name == "code-grader.md" and not opts.wants("sdd"):
+            continue
+        write_bytes(ctx, ctx.project / ".claude" / "agents" / agent.name, agent.read_bytes())
+    write_bytes(
+        ctx,
+        ctx.project / ".claude" / "development-workflow.md",
+        (opts.assets / "development-workflow.md").read_bytes(),
+    )
+
+
+def _fetch(url: str, into: Path) -> Path:
+    if shutil.which("git") is None:
+        raise SystemExit("error: git is needed to fetch the skills (or pass --sources-dir with local clones)")
+    subprocess.run(["git", "clone", "--depth", "1", "--quiet", url, str(into)], check=True)
+    return into
+
+
+def install_skills(ctx: Ctx, opts: Options) -> None:
+    wanted = [c for c in COMPONENTS if opts.wants(c)]
+    if not wanted:
+        return
+    with tempfile.TemporaryDirectory(prefix="agent-guild-") as tmp:
+        for component in wanted:
+            url, subpath, skill_name = SKILL_SOURCES[component]
+            if opts.sources_dir is not None:
+                repo = opts.sources_dir / REPO_DIRS[component]
+                if not repo.is_dir():
+                    raise SystemExit(f"error: {repo} not found (expected a clone of {url})")
+            elif ctx.dry_run:
+                ctx.log("would fetch", url, f"-> .claude/skills/{skill_name}")
+                continue
+            else:
+                repo = _fetch(url, Path(tmp) / REPO_DIRS[component])
+            src = repo / subpath
+            if not (src / "SKILL.md").is_file():
+                raise SystemExit(f"error: no SKILL.md in {src}")
+            copy_tree(ctx, src, ctx.project / ".claude" / "skills" / skill_name)
+
+
+def install_rules(ctx: Ctx, opts: Options) -> None:
+    """The new sections live in CLAUDE.md (Claude-only rules); AGENTS.md stays tool-neutral and is just imported."""
+    agents_md, claude_md = ctx.project / "AGENTS.md", ctx.project / "CLAUDE.md"
+    existed = claude_md.exists()
+    text = claude_md.read_text(encoding="utf-8") if existed else ""
+    known = text + (agents_md.read_text(encoding="utf-8") if agents_md.exists() else "")
+    added = []
+    if agents_md.exists() and "@AGENTS.md" not in text:
+        text = "@AGENTS.md\n" + (("\n" + text) if text.strip() else "")
+        added.append("@AGENTS.md import")
+    for heading, template, component in RULE_SECTIONS:
+        if component is not None and not opts.wants(component):
+            continue
+        if re.search(rf"^#+ .*{re.escape(heading)}", known, re.MULTILINE):
+            ctx.log("unchanged", claude_md, f"already has '{heading}' (CLAUDE.md or AGENTS.md)")
+            continue
+        body = (opts.assets / "templates" / template).read_text(encoding="utf-8").strip()
+        text = text.rstrip("\n") + ("\n\n" if text.strip() else "") + body + "\n"
+        added.append(heading)
+    if added:
+        if not ctx.dry_run:
+            claude_md.write_text(text, encoding="utf-8")
+        verb = "edited" if existed else "created"
+        (ctx.edited_existing.append(claude_md) if existed else ctx.track_new(claude_md))
+        ctx.log(f"would {verb[:-1]}" if ctx.dry_run else verb, claude_md, "+ " + ", ".join(added))
+
+
+def import_cursor_skills(ctx: Ctx, opts: Options) -> None:
+    """Copy the project's Cursor skills (.cursor/skills/*) into .claude/skills/. Existing skills are never replaced."""
+    if not opts.import_cursor_skills:
+        return
+    src_root = ctx.project / ".cursor" / "skills"
+    if not src_root.is_dir():
+        ctx.log("skipped", ".cursor/skills", "not found")
+        return
+    for skill in sorted(p for p in src_root.iterdir() if (p / "SKILL.md").is_file()):
+        dest = ctx.project / ".claude" / "skills" / skill.name
+        if dest.exists() and not ctx.force:
+            ctx.log("skipped", dest, "skill already exists (use --force to overwrite files)")
+            continue
+        copy_tree(ctx, skill, dest)
+
+
+def _has_hook(groups: list, marker: str) -> bool:
+    return any(marker in h.get("command", "") for g in groups for h in g.get("hooks", []))
+
+
+def install_settings(ctx: Ctx, opts: Options) -> None:
+    shared_path = ctx.project / ".claude" / "settings.json"
+    personal_path = ctx.project / ".claude" / "settings.local.json"
+    scalar_path = personal_path if opts.personal_settings else shared_path
+
+    shared, shared_indent = read_json(shared_path)
+    shared_changes: list[str] = []
+    if opts.wants("jevmem"):
+        hooks = shared.setdefault("hooks", {})
+        for event, (marker, timeout) in JEVMEM_HOOKS.items():
+            groups = hooks.setdefault(event, [])
+            if not _has_hook(groups, marker):
+                command = f'uvx --from "{JEVMEM_SPEC}" {marker}'
+                groups.append({"hooks": [{"type": "command", "command": command, "timeout": timeout}]})
+                shared_changes.append(f"{event} hook")
+        user_settings = Path.home() / ".claude" / "settings.json"
+        if user_settings.exists() and "jevmem hook" in user_settings.read_text(encoding="utf-8"):
+            ctx.warn("~/.claude/settings.json also has jevmem hooks: notes would be injected twice. Keep one set.")
+
+    if scalar_path == shared_path:
+        scalars, scalar_indent = shared, shared_indent
+    else:
+        scalars, scalar_indent = read_json(scalar_path)
+    scalar_changes: list[str] = []
+    if opts.wants("jevmem") and not opts.keep_auto_memory and scalars.get("autoMemoryEnabled") is not False:
+        scalars["autoMemoryEnabled"] = False
+        scalar_changes.append("autoMemoryEnabled=false")
+    if opts.model and scalars.get("model") != opts.model:
+        scalars["model"] = opts.model
+        scalar_changes.append(f"model={opts.model}")
+
+    if scalar_path == shared_path:
+        write_json(ctx, shared_path, shared, shared_indent, shared_changes + scalar_changes)
+    else:
+        write_json(ctx, shared_path, shared, shared_indent, shared_changes)
+        write_json(ctx, scalar_path, scalars, scalar_indent, scalar_changes)
+
+
+def install_mcp(ctx: Ctx, opts: Options) -> None:
+    if not opts.wants("jevmem"):
+        return
+    path = ctx.project / ".mcp.json"
+    data, indent = read_json(path)
+    servers = data.setdefault("mcpServers", {})
+    changes = []
+    if "jevmem" not in servers:
+        servers["jevmem"] = JEVMEM_SERVER
+        changes.append("jevmem server")
+    user_config = Path.home() / ".claude.json"
+    if user_config.exists():
+        try:
+            if "jevmem" in json.loads(user_config.read_text(encoding="utf-8")).get("mcpServers", {}):
+                ctx.warn("jevmem is also registered at user scope; keep one registration so the server isn't listed twice.")
+        except (json.JSONDecodeError, AttributeError):
+            pass
+    write_json(ctx, path, data, indent, changes)
+
+
+def encoded_memory_dir(project: Path) -> Path:
+    """Claude Code names a project's auto-memory folder after its absolute path, every non-alphanumeric char -> '-'."""
+    return Path.home() / ".claude" / "projects" / re.sub(r"[^A-Za-z0-9]", "-", str(project))
+
+
+def import_auto_memory(ctx: Ctx, opts: Options) -> None:
+    if not (opts.import_auto_memory and opts.wants("jevmem")):
+        return
+    root = encoded_memory_dir(ctx.project)
+    if not (root / "memory").is_dir():
+        ctx.log("skipped", "auto-memory import", f"no notes at {root}/memory")
+        return
+    cmd = ["uvx", "--from", JEVMEM_SPEC, "jevmem", "import-claude-memory", "--root", str(root)]
+    if ctx.dry_run:
+        ctx.log("would run", " ".join(cmd))
+        return
+    ctx.log("running", " ".join(cmd))
+    result = subprocess.run(cmd, cwd=ctx.project, check=False, env=os.environ)
+    if result.returncode != 0:
+        ctx.warn("jevmem import-claude-memory failed; auto-memory was NOT left unimported silently: fix it, or re-run with --keep-auto-memory.")
+
+
+def _git(project: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", "-C", str(project), *args], capture_output=True, text=True, check=False)
+
+
+def git_exclude(ctx: Ctx, opts: Options) -> None:
+    """List the files this run created in .git/info/exclude (local to this clone, never committed)."""
+    if not opts.git_exclude:
+        return
+    if shutil.which("git") is None or _git(ctx.project, "rev-parse", "--git-dir").returncode != 0:
+        ctx.warn("--git-exclude: not a git repository, nothing excluded.")
+        return
+    exclude = Path(_git(ctx.project, "rev-parse", "--path-format=absolute", "--git-path", "info/exclude").stdout.strip())
+    existing = exclude.read_text(encoding="utf-8").splitlines() if exclude.exists() else []
+    entries = []
+    for path, is_dir in ctx.new_paths:
+        rel = path.relative_to(ctx.project).as_posix()
+        entry = "/" + rel + ("/" if is_dir else "")
+        if entry not in existing and entry not in entries:
+            entries.append(entry)
+    if entries:
+        if not ctx.dry_run:
+            exclude.parent.mkdir(parents=True, exist_ok=True)
+            block = ("" if not existing or existing[-1] == "" else "\n") + "# agent-guild\n" + "\n".join(entries) + "\n"
+            with exclude.open("a", encoding="utf-8") as fh:
+                fh.write(block)
+        ctx.log("would add" if ctx.dry_run else "added", exclude, f"{len(entries)} entries")
+    else:
+        ctx.log("unchanged", exclude)
+    for path in ctx.edited_existing:
+        rel = path.relative_to(ctx.project).as_posix()
+        if _git(ctx.project, "ls-files", "--error-unmatch", rel).returncode == 0:
+            ctx.warn(f"{rel} is tracked by git, so excluding can't hide the edit; `git diff {rel}` shows it.")
+
+
+def run_all(ctx: Ctx, opts: Options) -> None:
+    # The import runs before the auto-memory switch is flipped, so no notes are lost.
+    import_auto_memory(ctx, opts)
+    install_agents(ctx, opts)
+    install_skills(ctx, opts)
+    import_cursor_skills(ctx, opts)
+    install_rules(ctx, opts)
+    install_mcp(ctx, opts)
+    install_settings(ctx, opts)
+    git_exclude(ctx, opts)

agent_guild-1.0.0.dist-info/METADATA

@@ -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)

agent_guild-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agent_guild/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_guild/cli.py,sha256=ivThPoj2iVqXDYPREdsltbJUbbS4mMr4d04zToNCblc,4404
+agent_guild/files.py,sha256=mDpCJ5vu2QKqCBJsOUo1hpIukGRrt_ZGMtbj1iw0-D4,3860
+agent_guild/installer.py,sha256=24hKFukTIfAlraHFZOrh5jEw4ZovxRIHsx_YkJTzmSM,12004
+agent_guild/_assets/agents/architect.md,sha256=i74zN7wmbZx7EaYnQQaodHKN3mMpRTeN-QYg9OEHBhY,4291
+agent_guild/_assets/agents/code-grader.md,sha256=TyApB6vUnrNqmElxNTT1ZQ-ocse0npTNYarwhRw78yQ,4394
+agent_guild/_assets/agents/coder.md,sha256=MwWDM5QQGrh5vDRKtvDaHCvQWdNT82-thlQMJUYaDe4,3196
+agent_guild/_assets/agents/utility.md,sha256=F4NTzyNcCzsFWLsmAwfCG_OfpIiaoE2Ni18JNV0iaA0,1930
+agent_guild/_assets/development-workflow.md,sha256=PGsPcLnN5I2zjUqcmra6POCmMcFL9ZVX0QBNWIzu0eg,6143
+agent_guild/_assets/templates/agents-rules.md,sha256=UvL3cKSDK4zf7wtas5Rm2C5RKlTW66wtDAcImCSvl3Q,271
+agent_guild/_assets/templates/memory-bank-rules.md,sha256=XTJRr2UcVfHXtO3KBKygDSI4VCHIVXDGnKSMo3Wv2Xs,446
+agent_guild/_assets/templates/sdd-rules.md,sha256=mGfLVChemlAGqNaG97oQzgAjXWvZrPEj574tTaJvr0A,1462
+agent_guild-1.0.0.dist-info/METADATA,sha256=6TBIzMXu-MBzjBxjgeEx_Nv10IH7Rh_8IOYdkMeO0AI,14305
+agent_guild-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_guild-1.0.0.dist-info/entry_points.txt,sha256=RQ6c3z-koMe0ektui9uV4VQJGqhwQb6y9ZRcw4iQ6VI,53
+agent_guild-1.0.0.dist-info/licenses/LICENSE,sha256=Q28OPpoy0LGWJN9HZyo1Qycs-YcPAMC5cmAZjPf7xbI,1079
+agent_guild-1.0.0.dist-info/RECORD,,

agent_guild-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_guild-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-guild = agent_guild.cli:main

agent_guild-1.0.0.dist-info/licenses/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.