@prateek_ai/agents-maker 1.0.0 → 1.0.2

package/skills/analyze_repo.md

@@ -1,86 +1,86 @@
-# Skill: analyze_repo
-
-## Description
-
-Walk a repository's file tree and produce a compact, structured summary of the project: detected stack, primary services or modules, main entrypoints, test structure, and key configuration files. Used by the Orchestrator and Architect Agent to build the Project State block at the start of a session.
-
----
-
-## When to invoke
-
-- Session start, when no project summary is available.
-- When routing a task that requires understanding the broader project structure beyond the provided snippets.
-- When the Architect Agent needs a service map before designing a new component.
-
----
-
-## Input expectations
-
-| Input | Required | Description |
-|---|---|---|
-| `repo_path` | Yes | Root path of the repository |
-| `filter_paths` | No | List of subdirectory prefixes to include (e.g., `src/`, `app/`, `services/`) |
-| `exclude_patterns` | No | Patterns to exclude (e.g., `node_modules/`, `__pycache__/`, `.git/`) |
-| `max_depth` | No | Maximum directory depth to traverse (default: 4) |
-
-In a conversational context, the user provides these via the `context_loaders/repo_tree.py` and `context_loaders/project_summary.py` scripts, and pastes the output.
-
-**If required input is missing:**
-- `repo_path` — if no path is provided and no repo context has been pasted, ask: "Please paste the output of `python agents-maker/context_loaders/repo_tree.py` or describe your project's directory structure." Do not produce a summary from nothing.
-- `filter_paths` — default to scanning the entire repo up to `max_depth`.
-- `exclude_patterns` — default to excluding `node_modules/`, `__pycache__/`, `.git/`, `dist/`, `build/`.
-- `max_depth` — default to 4.
-
----
-
-## Output format
-
-The skill produces a structured text block:
-
-```
-## Project Summary
-
-**Stack**: <language(s), runtime version(s), primary framework(s)>
-**Build tool**: <e.g., pip + setuptools, npm + webpack, gradle>
-**Test framework**: <e.g., pytest, jest, JUnit>
-**Containerization**: <Docker | none | Kubernetes manifests present>
-
-## Services / Modules
-
-| Name | Path | Responsibility |
-|---|---|---|
-| <name> | <path> | <one-line description> |
-
-## Main Entrypoints
-
-| File | Purpose |
-|---|---|
-| <path> | <what it starts or exports> |
-
-## Key Config Files
-
-| File | Purpose |
-|---|---|
-| <path> | <what it configures> |
-
-## Test Structure
-
-| Path | Type | Coverage scope |
-|---|---|---|
-| <path> | unit | integration | e2e | <scope> |
-```
-
----
-
-## Token cost tier
-
-**Medium.** Involves reading file tree and inspecting key files. Output is typically 300–600 tokens.
-
-Compression hint: the output is already compact. Do not summarize it further — it is the basis for all other context in the session.
-
----
-
-## Notes
-
-- This skill is implemented as `context_loaders/project_summary.py`. In agent sessions without tool access, the user runs it locally and pastes the output.
-- If the repo has no recognizable structure, return the raw tree truncated at `max_depth` and note: "Could not detect stack — please specify language and framework manually."
+# Skill: analyze_repo
+
+## Description
+
+Walk a repository's file tree and produce a compact, structured summary of the project: detected stack, primary services or modules, main entrypoints, test structure, and key configuration files. Used by the Orchestrator and Architect Agent to build the Project State block at the start of a session.
+
+---
+
+## When to invoke
+
+- Session start, when no project summary is available.
+- When routing a task that requires understanding the broader project structure beyond the provided snippets.
+- When the Architect Agent needs a service map before designing a new component.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `repo_path` | Yes | Root path of the repository |
+| `filter_paths` | No | List of subdirectory prefixes to include (e.g., `src/`, `app/`, `services/`) |
+| `exclude_patterns` | No | Patterns to exclude (e.g., `node_modules/`, `__pycache__/`, `.git/`) |
+| `max_depth` | No | Maximum directory depth to traverse (default: 4) |
+
+In a conversational context, the user provides these via the `context_loaders/repo_tree.py` and `context_loaders/project_summary.py` scripts, and pastes the output.
+
+**If required input is missing:**
+- `repo_path` — if no path is provided and no repo context has been pasted, ask: "Please paste the output of `python agents-maker/context_loaders/repo_tree.py` or describe your project's directory structure." Do not produce a summary from nothing.
+- `filter_paths` — default to scanning the entire repo up to `max_depth`.
+- `exclude_patterns` — default to excluding `node_modules/`, `__pycache__/`, `.git/`, `dist/`, `build/`.
+- `max_depth` — default to 4.
+
+---
+
+## Output format
+
+The skill produces a structured text block:
+
+```
+## Project Summary
+
+**Stack**: <language(s), runtime version(s), primary framework(s)>
+**Build tool**: <e.g., pip + setuptools, npm + webpack, gradle>
+**Test framework**: <e.g., pytest, jest, JUnit>
+**Containerization**: <Docker | none | Kubernetes manifests present>
+
+## Services / Modules
+
+| Name | Path | Responsibility |
+|---|---|---|
+| <name> | <path> | <one-line description> |
+
+## Main Entrypoints
+
+| File | Purpose |
+|---|---|
+| <path> | <what it starts or exports> |
+
+## Key Config Files
+
+| File | Purpose |
+|---|---|
+| <path> | <what it configures> |
+
+## Test Structure
+
+| Path | Type | Coverage scope |
+|---|---|---|
+| <path> | unit | integration | e2e | <scope> |
+```
+
+---
+
+## Token cost tier
+
+**Medium.** Involves reading file tree and inspecting key files. Output is typically 300–600 tokens.
+
+Compression hint: the output is already compact. Do not summarize it further — it is the basis for all other context in the session.
+
+---
+
+## Notes
+
+- This skill is implemented as `context_loaders/project_summary.py`. In agent sessions without tool access, the user runs it locally and pastes the output.
+- If the repo has no recognizable structure, return the raw tree truncated at `max_depth` and note: "Could not detect stack — please specify language and framework manually."

package/token_optimization/compressor.py

@@ -126,11 +126,13 @@ class RelevanceFilter:
     See token_optimization/relevance_filter.md for the full scoring model.
     """
 
+    # Weights sum to 1.0. (A prior "recency" weight was removed: it had no data
+    # source and was hardwired to 0.0, so it silently contributed nothing; its
+    # budget is folded into lexical_overlap, the primary textual signal.)
     weights = {
-        "lexical_overlap": 0.35,
+        "lexical_overlap": 0.45,
         "direct_reference": 0.30,
         "symbol_mention": 0.20,
-        "recency": 0.10,
         "structural_importance": 0.05,
     }
 
@@ -177,15 +179,10 @@ class RelevanceFilter:
         symbol = self._symbol_mention(content_lower, raw_query)
         structural = 1.0 if any(p in path_lower for p in self._structural_patterns) else 0.0
 
-        # recency: caller must set f.relevance_score > 0 before calling this method
-        # to use it as a recency hint; otherwise defaults to 0.
-        recency = 0.0
-
         return (
             self.weights["lexical_overlap"] * lexical
             + self.weights["direct_reference"] * direct
             + self.weights["symbol_mention"] * symbol
-            + self.weights["recency"] * recency
             + self.weights["structural_importance"] * structural
         )
 

package/tools/_core.py

@@ -0,0 +1,102 @@
+"""
+tools/_core.py
+
+Shared low-level primitives for the agents-maker tools: YAML loading,
+crash-safe atomic writes, source-hash computation, and shell-invocation
+formatting. Centralizing these removes the copy-pasted helpers that were
+previously duplicated across init_project.py, generate_prompt.py,
+generate_claude_md.py, generate_platform_configs.py, and validate_kit.py.
+
+Behavior is intentionally identical to the helpers it replaces.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+import hashlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# agents-maker/ (parent of tools/)
+KIT_DIR = Path(__file__).resolve().parent.parent
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - environment guard
+    print("[ERROR] pyyaml is required: pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# YAML loading
+# ---------------------------------------------------------------------------
+
+def load_yaml(path: Path) -> dict:
+    """Load a YAML file, returning {} on missing file and logging parse/permission errors."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except FileNotFoundError:
+        return {}
+    except yaml.YAMLError as e:
+        print(f"[ERROR] YAML parse error in {path}: {e}", file=sys.stderr)
+        return {}
+    except PermissionError:
+        print(f"[ERROR] Permission denied reading {path}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Atomic writes (write to temp then os.replace — crash-safe)
+# ---------------------------------------------------------------------------
+
+def atomic_write(path: Path, content: str) -> None:
+    """Atomically write text to path (temp file + os.replace)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w", dir=path.parent, delete=False, suffix=".tmp", encoding="utf-8"
+    ) as f:
+        f.write(content)
+        tmp = f.name
+    os.replace(tmp, path)
+
+
+def atomic_write_yaml(path: Path, data: dict) -> None:
+    """Atomically dump a dict to a YAML file (temp file + os.replace)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w", dir=path.parent, delete=False, suffix=".tmp", encoding="utf-8"
+    ) as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+        tmp = f.name
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Source hash — lets validate_kit.py detect a stale system_prompt.md
+# ---------------------------------------------------------------------------
+
+def source_hash(kit_dir: Path = KIT_DIR) -> str:
+    """SHA-256 (first 16 hex chars) over all agent + skill markdown, line-ending normalized."""
+    h = hashlib.sha256()
+    agent_files = sorted((kit_dir / "agents").glob("*.md")) if (kit_dir / "agents").is_dir() else []
+    skill_files = sorted((kit_dir / "skills").glob("*.md")) if (kit_dir / "skills").is_dir() else []
+    for path in agent_files + skill_files:
+        try:
+            h.update(path.read_bytes().replace(b"\r\n", b"\n"))
+        except (OSError, PermissionError):
+            pass
+    return h.hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Shell-invocation formatting
+# ---------------------------------------------------------------------------
+
+def py_invocation(kit_rel: str, tool: str) -> str:
+    """Return a shell-safe 'python ...' invocation, quoting the path when it contains spaces."""
+    path = f"{kit_rel}/tools/{tool}"
+    return f'python "{path}"' if " " in path else f"python {path}"

package/tools/compare_prompts.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+compare_prompts.py — Proof-of-value harness for agents-maker.
+
+For a given task it builds TWO prompts and runs BOTH through the same model,
+so you can see what the structuring actually changes:
+
+  1. NAIVE      — the raw task, exactly as a user would type it into a chat box.
+  2. STRUCTURED — the agents-maker prompt (system prompt + domain routing +
+                  project context + Companion Mode), via generate_prompt.py --full.
+
+Outputs (prompts + raw model responses) are written to examples/proof/<slug>/
+so the comparison is reproducible and auditable — no cherry-picking.
+
+Model runner
+------------
+By default it shells out to the Claude Code CLI in non-interactive mode
+(`claude -p`), which reuses your existing auth (no API key needed). Override
+with --runner to use any command that reads a prompt on stdin and prints the
+completion on stdout, e.g.:
+
+    python tools/compare_prompts.py "..." --runner "llm -m gpt-4o"
+
+Usage
+-----
+    python tools/compare_prompts.py "add rate limiting to the auth service"
+    python tools/compare_prompts.py "[domain: ops_process] write a Redis failover runbook"
+    python tools/compare_prompts.py "write a launch tweet" --skip-run   # build prompts only
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+KIT_DIR = SCRIPT_DIR.parent
+PROOF_DIR = KIT_DIR / "examples" / "proof"
+
+_SEP = "=" * 60
+
+
+def _slug(task: str) -> str:
+    s = re.sub(r"\[domain:[^\]]*\]", "", task).strip().lower()
+    s = re.sub(r"[^a-z0-9]+", "-", s).strip("-")
+    return (s[:48] or "task").rstrip("-")
+
+
+def build_structured_prompt(task: str, full: bool = True) -> str:
+    """Run generate_prompt.py and extract the pasteable prompt body.
+
+    full=True inlines the whole system prompt (single-message / free-tier paste).
+    full=False returns only the context+task+routing block — use it as the `user`
+    message when the system prompt is supplied separately in the `system` field.
+    """
+    cmd = [sys.executable, str(SCRIPT_DIR / "generate_prompt.py"), task]
+    if full:
+        cmd.append("--full")
+    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace")
+    if proc.returncode != 0:
+        raise RuntimeError(f"generate_prompt.py failed: {proc.stderr[:300]}")
+    # Output is: SEP / header / SEP / <body> / SEP / footer / SEP
+    parts = proc.stdout.split(_SEP)
+    if len(parts) < 4:
+        raise RuntimeError("Unexpected generate_prompt.py output format.")
+    return parts[2].strip()
+
+
+def run_anthropic(system: str | None, user: str, model: str, max_tokens: int = 3000) -> str:
+    """Call the Anthropic Messages API with proper role separation. Key from env."""
+    key = os.environ.get("ANTHROPIC_API_KEY")
+    if not key:
+        raise RuntimeError("ANTHROPIC_API_KEY is not set.")
+    body: dict = {"model": model, "max_tokens": max_tokens, "messages": [{"role": "user", "content": user}]}
+    if system:
+        # Mark the (large, stable) system prompt as cacheable: the first call writes
+        # the cache, later calls read it at ~0.1x input cost.
+        body["system"] = [{"type": "text", "text": system, "cache_control": {"type": "ephemeral"}}]
+    req = urllib.request.Request(
+        "https://api.anthropic.com/v1/messages",
+        data=json.dumps(body).encode("utf-8"),
+        method="POST",
+        headers={"x-api-key": key, "anthropic-version": "2023-06-01", "content-type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=180) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return f"[api error {e.code}] {e.read().decode('utf-8', 'replace')[:400]}"
+    u = data.get("usage", {})
+    print(
+        f"       [usage] input={u.get('input_tokens',0)} "
+        f"cache_write={u.get('cache_creation_input_tokens',0)} "
+        f"cache_read={u.get('cache_read_input_tokens',0)} "
+        f"output={u.get('output_tokens',0)}",
+        file=sys.stderr,
+    )
+    return "".join(b.get("text", "") for b in data.get("content", [])).strip()
+
+
+def run_model(prompt: str, runner: str, cwd: str) -> str:
+    """Feed a prompt to the model runner (stdin) and return the completion text.
+
+    Runs in an isolated empty `cwd` so an agent-style runner (e.g. claude -p)
+    answers the prompt as text instead of inspecting the current repository —
+    otherwise the comparison is confounded by whatever project it is run from.
+    """
+    cmd = runner.split() + ([] if runner.split()[0] != "claude" else ["-p"])
+    proc = subprocess.run(
+        cmd, input=prompt, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", cwd=cwd,
+    )
+    if proc.returncode != 0:
+        return f"[runner error rc={proc.returncode}]\n{proc.stderr[:500]}"
+    return proc.stdout.strip()
+
+
+def main() -> None:
+    sys.stdout.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="Compare a naive vs agents-maker structured prompt on the same model.")
+    ap.add_argument("task", help="The task to test (supports a leading [domain: X] prefix).")
+    ap.add_argument("--runner", default="claude",
+                    help='CLI mode: model command reading stdin, printing stdout (default: "claude" -> claude -p).')
+    ap.add_argument("--api", action="store_true",
+                    help="Use the Anthropic Messages API with proper system/user role separation (needs ANTHROPIC_API_KEY).")
+    ap.add_argument("--model", default="claude-haiku-4-5-20251001", help="Model id for --api mode.")
+    ap.add_argument("--skip-run", action="store_true", help="Only build the two prompts; do not call the model.")
+    ap.add_argument("--out", default=None, help="Output directory (default: examples/proof/<slug>/).")
+    args = ap.parse_args()
+
+    out_dir = Path(args.out) if args.out else PROOF_DIR / _slug(args.task)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.api:
+        # Role-separated: task-scoped system prompt in `system`, task+context as `user`.
+        sp = subprocess.run(
+            [sys.executable, str(SCRIPT_DIR / "generate_prompt.py"), args.task, "--system-only"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+        )
+        if sp.returncode != 0:
+            raise RuntimeError(f"generate_prompt --system-only failed: {sp.stderr[:300]}")
+        system_prompt = sp.stdout.strip()
+        naive = args.task
+        structured_user = build_structured_prompt(args.task, full=False)
+        (out_dir / "naive_prompt.txt").write_text(naive + "\n", encoding="utf-8")
+        (out_dir / "structured_user.txt").write_text(structured_user + "\n", encoding="utf-8")
+        print(f"[built] {out_dir} (api mode, model={args.model})")
+        print(f"        naive user: {len(naive)} chars | structured system: {len(system_prompt)} + user: {len(structured_user)} chars")
+        if args.skip_run:
+            print("[skip-run] prompts written; model not called.")
+            return
+        print("[run] naive (no system prompt)...")
+        naive_out = run_anthropic(None, naive, args.model)
+        (out_dir / "naive_output.md").write_text(naive_out + "\n", encoding="utf-8")
+        print("[run] structured (system=system_prompt.md, user=task+context)...")
+        structured_out = run_anthropic(system_prompt, structured_user, args.model)
+        (out_dir / "structured_output.md").write_text(structured_out + "\n", encoding="utf-8")
+        print(f"[done] outputs written to {out_dir}")
+        print(f"       naive_output: {len(naive_out)} chars | structured_output: {len(structured_out)} chars")
+        return
+
+    naive = args.task
+    structured = build_structured_prompt(args.task, full=True)
+
+    (out_dir / "naive_prompt.txt").write_text(naive + "\n", encoding="utf-8")
+    (out_dir / "structured_prompt.txt").write_text(structured + "\n", encoding="utf-8")
+    print(f"[built] {out_dir}")
+    print(f"        naive: {len(naive)} chars | structured: {len(structured)} chars")
+
+    if args.skip_run:
+        print("[skip-run] prompts written; model not called.")
+        return
+
+    sandbox = tempfile.mkdtemp(prefix="am-proof-")
+
+    print(f"[run] naive via '{args.runner}' (isolated cwd)...")
+    naive_out = run_model(naive, args.runner, sandbox)
+    (out_dir / "naive_output.md").write_text(naive_out + "\n", encoding="utf-8")
+
+    print(f"[run] structured via '{args.runner}' (isolated cwd)...")
+    structured_out = run_model(structured, args.runner, sandbox)
+    (out_dir / "structured_output.md").write_text(structured_out + "\n", encoding="utf-8")
+
+    print(f"[done] outputs written to {out_dir}")
+    print(f"       naive_output: {len(naive_out)} chars | structured_output: {len(structured_out)} chars")
+
+
+if __name__ == "__main__":
+    main()

package/tools/generate_claude_agents.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+generate_claude_agents.py — Emit Claude Code subagents + slash commands.
+
+Turns the agents-maker roster into native Claude Code files so a user can clone
+the kit into their project and immediately invoke named agents:
+
+    /brain      brainstorm the whole project (options + trade-offs + recommendation)
+    /planpro    produce the best-possible implementation plan
+    /architect /code /execute /ui /ux /review /orchestrate /compress
+
+For each agent it writes:
+  <dest>/.claude/agents/<name>.md    — subagent (frontmatter + the agent spec body)
+  <dest>/.claude/commands/<name>.md  — slash command that invokes the subagent
+
+Non-destructive by default: existing same-named files are skipped (never clobber
+a user's own agents/commands). Use --force to overwrite.
+
+Usage:
+    python agents-maker/tools/generate_claude_agents.py                 # -> <project>/.claude
+    python agents-maker/tools/generate_claude_agents.py --project /path # -> /path/.claude
+    python agents-maker/tools/generate_claude_agents.py --template      # -> agents-maker/claude (shipped copy)
+    python agents-maker/tools/generate_claude_agents.py --dry-run
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent   # agents-maker/tools/
+KIT_DIR = SCRIPT_DIR.parent                    # agents-maker/
+sys.path.insert(0, str(KIT_DIR))
+
+try:
+    from tools._core import atomic_write, load_yaml
+except ImportError:
+    from _core import atomic_write, load_yaml
+
+# Full autonomy: agents may read, edit, write, and run commands.
+AGENT_TOOLS = "Read, Grep, Glob, Edit, Write, Bash"
+
+# command name -> agent id (filename stem in agents/). The command/subagent use
+# the short, clean name; the body comes from the (possibly _agent-suffixed) spec.
+COMMANDS: dict[str, str] = {
+    "brain":       "brain",
+    "planpro":     "planpro",
+    "orchestrate": "orchestrator",
+    "architect":   "architect_agent",
+    "code":        "code_agent",
+    "execute":     "execution_agent",
+    "ui":          "ui_agent",
+    "ux":          "ux_agent",
+    "review":      "reviewer_agent",
+    "compress":    "compression_agent",
+}
+
+
+def _flatten(text: str, limit: int = 300) -> str:
+    """Collapse whitespace to a single line (YAML-frontmatter-safe) and cap length."""
+    one = " ".join(text.split())
+    return one[: limit - 1] + "…" if len(one) > limit else one
+
+
+def _description(agent_id: str, agents_cfg: dict) -> str:
+    desc = _flatten(str(agents_cfg.get(agent_id, {}).get("description", "")))
+    return desc or f"agents-maker {agent_id} agent"
+
+
+def build_subagent(cmd: str, agent_id: str, agents_cfg: dict, kit_dir: Path) -> str:
+    body = (kit_dir / "agents" / f"{agent_id}.md").read_text(encoding="utf-8").strip()
+    return (
+        "---\n"
+        f"name: {cmd}\n"
+        f"description: {_description(agent_id, agents_cfg)}\n"
+        f"tools: {AGENT_TOOLS}\n"
+        "model: inherit\n"
+        "---\n\n"
+        f"{body}\n"
+    )
+
+
+def build_command(cmd: str, agent_id: str, agents_cfg: dict) -> str:
+    return (
+        "---\n"
+        f"description: {_description(agent_id, agents_cfg)}\n"
+        "---\n"
+        f"# /{cmd}\n\n"
+        "$ARGUMENTS\n\n"
+        "## Task\n"
+        f"Use the `{cmd}` subagent (agents-maker) to handle the request above.\n\n"
+        "CONTEXT:\n"
+        "- Project config, if present: `agents-maker/config/project.yaml` — read it for "
+        "domain, stack, and constraints before acting.\n"
+        "- User request: $ARGUMENTS\n\n"
+        f"Follow the `{cmd}` agent's output contract. If the request is a self-contained "
+        "task, deliver the finished artifact directly (Direct Task Mode) — do not ask for "
+        "project context you can infer. End with the [Companion] next-steps block.\n"
+    )
+
+
+def generate(dest_claude: Path, kit_dir: Path, *, force: bool = False, dry_run: bool = False) -> tuple[list[str], list[str]]:
+    """Write subagents + commands under dest_claude. Returns (written, skipped) rel paths."""
+    agents_cfg = load_yaml(kit_dir / "config" / "agents.yaml").get("agents", {})
+    written: list[str] = []
+    skipped: list[str] = []
+
+    for cmd, agent_id in COMMANDS.items():
+        targets = [
+            (dest_claude / "agents" / f"{cmd}.md", build_subagent(cmd, agent_id, agents_cfg, kit_dir)),
+            (dest_claude / "commands" / f"{cmd}.md", build_command(cmd, agent_id, agents_cfg)),
+        ]
+        for path, content in targets:
+            rel = f"{path.parent.name}/{path.name}"
+            if path.exists() and not force:
+                skipped.append(rel)
+                continue
+            if dry_run:
+                written.append(rel)
+                continue
+            atomic_write(path, content)
+            written.append(rel)
+
+    return written, skipped
+
+
+def main() -> None:
+    sys.stdout.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="Generate Claude Code subagents + slash commands from the agents-maker roster.")
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    ap.add_argument("--project", help="Project root; writes <root>/.claude/ (default: parent of agents-maker/).")
+    ap.add_argument("--template", action="store_true", help="Write the shipped template copy to agents-maker/claude/ instead of a project's .claude/.")
+    ap.add_argument("--force", action="store_true", help="Overwrite existing files (default: skip existing).")
+    ap.add_argument("--dry-run", action="store_true", help="List what would be written without writing.")
+    args = ap.parse_args()
+
+    if args.template:
+        dest = KIT_DIR / "claude"
+    else:
+        root = Path(args.project).resolve() if args.project else KIT_DIR.parent
+        dest = root / ".claude"
+
+    written, skipped = generate(dest, KIT_DIR, force=args.force, dry_run=args.dry_run)
+
+    tag = "[dry-run] would write" if args.dry_run else "wrote"
+    print(f"{tag} {len(written)} file(s) under {dest}")
+    for r in written:
+        print(f"  + {r}")
+    if skipped:
+        print(f"skipped {len(skipped)} existing file(s) (use --force to overwrite):")
+        for r in skipped:
+            print(f"  = {r}")
+    if not args.dry_run and not args.template:
+        cmds = ", ".join(f"/{c}" for c in COMMANDS)
+        print(f"\nCommands available in this project: {cmds}")
+
+
+if __name__ == "__main__":
+    main()