@prateek_ai/agents-maker 1.0.0 → 1.0.2

package/tools/generate_claude_md.py

@@ -14,10 +14,8 @@ Usage:
 from __future__ import annotations
 
 import argparse
-import os
 import re
 import sys
-import tempfile
 from pathlib import Path
 
 __version__ = "1.0.0"
@@ -27,25 +25,21 @@ KIT_DIR = SCRIPT_DIR.parent                     # agents-maker/
 sys.path.insert(0, str(KIT_DIR))
 
 try:
-    import yaml
+    from tools._core import atomic_write, load_yaml, py_invocation
+    from tools.routing import AGENT_ROLES, PHASE_AGENTS, PHASE_LABELS, phase_agents
 except ImportError:
-    print("[ERROR] pyyaml is required: pip install pyyaml", file=sys.stderr)
-    sys.exit(1)
+    from _core import atomic_write, load_yaml, py_invocation
+    from routing import AGENT_ROLES, PHASE_AGENTS, PHASE_LABELS, phase_agents
+
+# Backward-compatible aliases (generate_platform_configs imports these names).
+_PHASE_AGENTS = PHASE_AGENTS
+_PHASE_LABELS = PHASE_LABELS
+_AGENT_ROLES = AGENT_ROLES
 
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 
-def _load_yaml(path: Path) -> dict:
-    if not path.exists():
-        return {}
-    try:
-        with open(path, encoding="utf-8") as f:
-            return yaml.safe_load(f) or {}
-    except Exception:
-        return {}
-
-
 def _parse_phase(state_text: str) -> str:
     m = re.search(r"##\s+Current Phase\s*\n+(\S+)", state_text)
     if m:
@@ -53,65 +47,8 @@ def _parse_phase(state_text: str) -> str:
     return "task_framing"
 
 
-# Phase → domain → active agents mapping (derived from agents.yaml lifecycle)
-_PHASE_AGENTS: dict[str, dict[str, list[str]]] = {
-    "task_framing":     {"_all": ["orchestrator"]},
-    "requirements":     {"_all": ["orchestrator", "architect_agent"]},
-    "solution_design":  {
-        "_all":          ["architect_agent"],
-        "software":      ["architect_agent", "ui_agent"],
-        "product_design":["architect_agent", "ui_agent", "ux_agent"],
-        "marketing":     ["architect_agent", "ux_agent"],
-    },
-    "implementation":   {
-        "_all":          ["execution_agent"],
-        "software":      ["code_agent"],
-        "data_analytics":["code_agent"],
-    },
-    "review_refinement":{
-        "_all":          ["reviewer_agent"],
-        "software":      ["reviewer_agent", "code_agent"],
-        "product_design":["reviewer_agent", "ui_agent", "ux_agent"],
-        "marketing":     ["reviewer_agent", "ux_agent"],
-    },
-    "handoff":          {"_all": ["orchestrator", "execution_agent"]},
-}
-
-_PHASE_LABELS: dict[str, str] = {
-    "task_framing":     "Task Framing",
-    "requirements":     "Requirements",
-    "solution_design":  "Solution Design",
-    "implementation":   "Implementation",
-    "review_refinement":"Review & Refinement",
-    "handoff":          "Handoff",
-    # aliases accepted by generate_prompt.py
-    "framing":          "Task Framing",
-    "design":           "Solution Design",
-    "implement":        "Implementation",
-    "review":           "Review & Refinement",
-}
-
-_AGENT_ROLES: dict[str, str] = {
-    "orchestrator":       "routing",
-    "architect_agent":    "design",
-    "code_agent":         "implementation",
-    "execution_agent":    "execution",
-    "ui_agent":           "UI",
-    "ux_agent":           "UX",
-    "reviewer_agent":     "QA",
-    "compression_agent":  "compression",
-}
-
-
-def _py(kit_rel: str, tool: str) -> str:
-    """Return a shell-safe 'python ...' invocation. Quotes the full path when it contains spaces."""
-    path = f"{kit_rel}/tools/{tool}"
-    return f'python "{path}"' if " " in path else f"python {path}"
-
-
 def _active_agents(domain: str, phase: str) -> list[str]:
-    phase_map = _PHASE_AGENTS.get(phase, {"_all": ["orchestrator"]})
-    return phase_map.get(domain, phase_map["_all"])
+    return phase_agents(phase, domain)
 
 
 # ---------------------------------------------------------------------------
@@ -132,8 +69,8 @@ def build_claude_md(
     agent_list = ", ".join(
         f"{a} ({_AGENT_ROLES.get(a, 'specialist')})" for a in agents
     )
-    regen_cmd = _py(kit_rel_path, "generate_claude_md.py")
-    prompt_cmd = _py(kit_rel_path, "generate_prompt.py")
+    regen_cmd = py_invocation(kit_rel_path, "generate_claude_md.py")
+    prompt_cmd = py_invocation(kit_rel_path, "generate_prompt.py")
 
     return (
         f"# agents-maker — Project AI Config\n"
@@ -207,7 +144,7 @@ def main() -> None:
         sys.exit(1)
 
     # Load project config
-    project_cfg = _load_yaml(KIT_DIR / "config" / "project.yaml")
+    project_cfg = load_yaml(KIT_DIR / "config" / "project.yaml")
     if not project_cfg:
         print(
             "[WARN] config/project.yaml not found — run init_project.py first.",
@@ -250,10 +187,7 @@ def main() -> None:
         return
 
     out_path = project_root / "CLAUDE.md"
-    with tempfile.NamedTemporaryFile("w", dir=out_path.parent, delete=False, suffix=".tmp", encoding="utf-8") as f:
-        f.write(content)
-        tmp = f.name
-    os.replace(tmp, out_path)
+    atomic_write(out_path, content)
 
     print(f"\nWritten: {out_path}")
     print(f"  Domain : {domain}  (confidence: {confidence})")

package/tools/generate_platform_configs.py

@@ -24,9 +24,7 @@ from __future__ import annotations
 __version__ = "1.0.0"
 
 import argparse
-import os
 import sys
-import tempfile
 from pathlib import Path
 
 SCRIPT_DIR = Path(__file__).resolve().parent   # agents-maker/tools/
@@ -34,12 +32,7 @@ KIT_DIR = SCRIPT_DIR.parent                    # agents-maker/
 sys.path.insert(0, str(KIT_DIR))
 
 try:
-    import yaml as _yaml_probe  # noqa: F401 — ensures pyyaml is installed
-except ImportError:
-    print("[ERROR] pyyaml is required: pip install pyyaml", file=sys.stderr)
-    sys.exit(1)
-
-try:
+    from tools._core import atomic_write, load_yaml, py_invocation
     from tools.generate_claude_md import (
         _AGENT_ROLES,
         _PHASE_AGENTS,
@@ -48,6 +41,7 @@ try:
         build_claude_md,
     )
 except ImportError:
+    from _core import atomic_write, load_yaml, py_invocation
     from generate_claude_md import (
         _AGENT_ROLES,
         _PHASE_AGENTS,
@@ -56,12 +50,7 @@ except ImportError:
         build_claude_md,
     )
 
-try:
-    from tools.domain_utils import _load_yaml
-except ImportError:
-    from domain_utils import _load_yaml
-
-PLATFORMS = ["claude", "copilot", "cursor", "antigravity"]
+PLATFORMS = ["claude", "claude_agents", "copilot", "cursor", "antigravity"]
 
 # ---------------------------------------------------------------------------
 # Helpers shared across builders
@@ -76,12 +65,6 @@ def _agent_list_str(agents: list[str]) -> str:
     return ", ".join(f"{a} ({_AGENT_ROLES.get(a, 'specialist')})" for a in agents)
 
 
-def _py(kit_rel: str, tool: str) -> str:
-    """Return a shell-safe 'python ...' invocation. Quotes the full path when it contains spaces."""
-    path = f"{kit_rel}/tools/{tool}"
-    return f'python "{path}"' if " " in path else f"python {path}"
-
-
 def _yaml_str(value: str) -> str:
     """Return a YAML-safe scalar: quoted if it contains spaces or YAML special characters."""
     if " " in value or any(c in value for c in ":{}[]#&*!|>'\"%@`"):
@@ -89,16 +72,6 @@ def _yaml_str(value: str) -> str:
     return value
 
 
-def _atomic_write(path: Path, content: str) -> None:
-    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)
-
-
 # ---------------------------------------------------------------------------
 # Builder: GitHub Copilot — .github/copilot-instructions.md
 # ---------------------------------------------------------------------------
@@ -114,7 +87,7 @@ def build_copilot_md(
     stack_str = ", ".join(stack) if stack else "unknown"
     phase_label = _PHASE_LABELS.get(phase, phase)
     agents = _active_agents(domain, phase)
-    regen_cmd = _py(kit_rel_path, "generate_platform_configs.py")
+    regen_cmd = py_invocation(kit_rel_path, "generate_platform_configs.py")
 
     all_agents = [
         "orchestrator (routing — always active)",
@@ -173,7 +146,7 @@ def build_cursor_rules(
     stack_str = ", ".join(stack) if stack else "unknown"
     phase_label = _PHASE_LABELS.get(phase, phase)
     agents = _active_agents(domain, phase)
-    regen_cmd = _py(kit_rel_path, "generate_platform_configs.py")
+    regen_cmd = py_invocation(kit_rel_path, "generate_platform_configs.py")
 
     return (
         f"# agents-maker — Cursor Rules\n"
@@ -219,6 +192,8 @@ _AGENT_DESCRIPTIONS: dict[str, str] = {
     "ux_agent":          "Flow critique, onboarding sequences, funnel analysis, friction ID",
     "reviewer_agent":    "Severity-rated QA review for any domain (CRITICAL/HIGH/MEDIUM/LOW)",
     "compression_agent": "Token budget enforcement, context compression, cross-session resumption",
+    "brain":             "Project brainstorming — 3+ approaches with trade-offs + a recommendation",
+    "planpro":           "Implementation planning — short, specific, dependency-ordered plan file",
 }
 
 _AGENT_PHASES: dict[str, list[str]] = {
@@ -230,6 +205,8 @@ _AGENT_PHASES: dict[str, list[str]] = {
     "ux_agent":          ["solution_design", "review_refinement"],
     "reviewer_agent":    ["review_refinement"],
     "compression_agent": ["handoff"],
+    "brain":             ["task_framing", "solution_design"],
+    "planpro":           ["task_framing", "requirements", "solution_design"],
 }
 
 _AGENT_DOMAINS: dict[str, list[str]] = {
@@ -241,10 +218,12 @@ _AGENT_DOMAINS: dict[str, list[str]] = {
     "ux_agent":          ["product_design", "marketing"],
     "reviewer_agent":    ["software", "content", "research", "data_analytics", "product_design", "marketing", "ops_process", "general"],
     "compression_agent": ["software", "content", "research", "data_analytics", "product_design", "marketing", "ops_process", "general"],
+    "brain":             ["software", "content", "research", "data_analytics", "product_design", "marketing", "ops_process", "general"],
+    "planpro":           ["software", "content", "research", "data_analytics", "product_design", "marketing", "ops_process", "general"],
 }
 
 _AGENT_ORDER = [
-    "orchestrator", "architect_agent", "code_agent", "execution_agent",
+    "orchestrator", "brain", "planpro", "architect_agent", "code_agent", "execution_agent",
     "ui_agent", "ux_agent", "reviewer_agent", "compression_agent",
 ]
 
@@ -256,7 +235,7 @@ def build_agkit_yaml(
     phase: str,
     kit_rel_path: str,
 ) -> str:
-    regen_cmd = _py(kit_rel_path, "generate_platform_configs.py")
+    regen_cmd = py_invocation(kit_rel_path, "generate_platform_configs.py")
     stack_list = stack if stack else ["unknown"]
 
     lines: list[str] = [
@@ -346,7 +325,7 @@ def generate_all(
     platforms: list[str],
     dry_run: bool,
 ) -> None:
-    project_cfg = _load_yaml(kit_dir / "config" / "project.yaml")
+    project_cfg = load_yaml(kit_dir / "config" / "project.yaml")
     if not project_cfg:
         print("[WARN] config/project.yaml not found — run init_project.py first.", file=sys.stderr)
 
@@ -384,6 +363,17 @@ def generate_all(
         content = build_agkit_yaml(project_name, domain, stack, phase, kit_rel_path)
         builders["antigravity"] = (_PLATFORM_PATHS["antigravity"], content)
 
+    # Claude Code subagents + slash commands (.claude/agents, .claude/commands).
+    if "claude_agents" in platforms:
+        try:
+            from tools.generate_claude_agents import generate as _gen_claude
+        except ImportError:
+            from generate_claude_agents import generate as _gen_claude
+        cw, cs = _gen_claude(project_root / ".claude", kit_dir, force=False, dry_run=dry_run)
+        tag = "[dry-run] would write" if dry_run else "  [DONE]"
+        print(f"{tag} {len(cw)} .claude/ file(s) — subagents + slash commands"
+              + (f"; kept {len(cs)} existing" if cs else ""))
+
     if dry_run:
         for platform, (rel_path, content) in builders.items():
             print(f"\n{'='*60}")
@@ -397,7 +387,7 @@ def generate_all(
     for platform, (rel_path, content) in builders.items():
         out_path = project_root / rel_path
         try:
-            _atomic_write(out_path, content)
+            atomic_write(out_path, content)
             print(f"  [DONE] {rel_path}  ({platform})")
             written.append(rel_path)
         except OSError as e:

package/tools/generate_prompt.py

@@ -21,10 +21,8 @@ Usage:
 from __future__ import annotations
 
 import argparse
-import os
 import re
 import sys
-import tempfile
 from datetime import date
 from pathlib import Path
 
@@ -36,12 +34,6 @@ SCRIPT_DIR = Path(__file__).resolve().parent   # agents-maker/tools/
 KIT_DIR = SCRIPT_DIR.parent                    # agents-maker/
 sys.path.insert(0, str(KIT_DIR))
 
-try:
-    import yaml
-except ImportError:
-    print("[ERROR] pyyaml is required: pip install pyyaml", file=sys.stderr)
-    sys.exit(1)
-
 __version__ = "1.0.0"
 
 MAX_PROBLEM_LENGTH = 5000
@@ -51,11 +43,13 @@ MAX_PROBLEM_LENGTH = 5000
 # ---------------------------------------------------------------------------
 
 try:
-    from tools.domain_utils import _load_yaml
+    from tools._core import atomic_write_yaml, load_yaml
     from tools.domain_utils import detect_domain as _du_detect
+    from tools.routing import active_agents, domain_agents
 except ImportError:
-    from domain_utils import _load_yaml
+    from _core import atomic_write_yaml, load_yaml
     from domain_utils import detect_domain as _du_detect
+    from routing import active_agents, domain_agents
 
 
 def detect_domain(problem: str) -> tuple[str, str, float]:
@@ -118,53 +112,14 @@ def infer_phase(state_path: Path) -> str:
 # Agent selection per phase × domain
 # ---------------------------------------------------------------------------
 
-PHASE_AGENTS: dict[str, list[str]] = {
-    "task_framing":      ["orchestrator"],
-    "requirements":      ["orchestrator", "architect_agent"],
-    "solution_design":   ["orchestrator", "architect_agent"],
-    "implementation":    ["orchestrator"],
-    "review_refinement": ["orchestrator", "reviewer_agent"],
-    "handoff":           ["orchestrator"],
-}
-
-IMPLEMENTATION_AGENT: dict[str, str] = {
-    "software":       "code_agent",
-    "data_analytics": "code_agent",
-    "content":        "execution_agent",
-    "research":       "execution_agent",
-    "product_design": "execution_agent",
-    "marketing":      "execution_agent",
-    "ops_process":    "execution_agent",
-    "general":        "execution_agent",
-}
-
-DESIGN_AGENTS: dict[str, list[str]] = {
-    "product_design": ["ui_agent", "ux_agent"],
-    "marketing":      ["ux_agent"],
-}
-
-
 def select_agents(phase: str, domain: str) -> list[str]:
-    agents = list(PHASE_AGENTS.get(phase, ["orchestrator"]))
-
-    if phase == "implementation":
-        impl_agent = IMPLEMENTATION_AGENT.get(domain, "execution_agent")
-        if impl_agent not in agents:
-            agents.append(impl_agent)
-        for extra in DESIGN_AGENTS.get(domain, []):
-            if extra not in agents:
-                agents.append(extra)
-
-    if phase == "solution_design":
-        for extra in DESIGN_AGENTS.get(domain, []):
-            if extra not in agents:
-                agents.append(extra)
-
-    return agents
+    # Routing is centralized in tools/routing.py (single source of truth) so the
+    # generated prompt, CLAUDE.md, and platform configs all agree.
+    return active_agents(phase, domain)
 
 
 def select_skills(agents: list[str]) -> list[str]:
-    agents_cfg = _load_yaml(KIT_DIR / "config" / "agents.yaml").get("agents", {})
+    agents_cfg = load_yaml(KIT_DIR / "config" / "agents.yaml").get("agents", {})
     seen: set[str] = set()
     skills: list[str] = []
     for agent in agents:
@@ -199,6 +154,42 @@ def load_skill_md(skill_key: str) -> str:
     return ""
 
 
+# ---------------------------------------------------------------------------
+# Task-scoped system prompt (lazy-load: only the routed agents + skills)
+# ---------------------------------------------------------------------------
+
+COMPANION_DIRECTIVE = (
+    "# agents-maker — active kit (task-scoped)\n"
+    "You are operating under the agents-maker system below, loaded with only the "
+    "agents and skills routed for this task. The Orchestrator leads.\n"
+    "After every response append a [Companion] block:\n"
+    "  ---\n"
+    "  [Companion] Phase: <phase> | Domain: <domain> | Est. token budget used: ~N%\n"
+    "  What to do next (pick one):\n"
+    "  [Recommended] A: <action>  Command: python agents-maker/tools/generate_prompt.py \"...\"\n"
+    "  B: <action>\n"
+    "  C: <action>\n"
+    "  ---\n"
+    "In Direct Task Mode (a single self-contained task) deliver the finished artifact "
+    "first, then the [Companion] block — do not open the phase lifecycle."
+)
+
+
+def build_scoped_system(agents: list[str], skills: list[str]) -> str:
+    """Assemble a task-scoped system prompt: companion directive + only the routed
+    agent and skill specs. Far smaller than the full 8-agent / 12-skill system_prompt.md."""
+    parts: list[str] = [COMPANION_DIRECTIVE, "=" * 60]
+    for agent in agents:
+        parts.append(load_agent_md(agent))
+        parts.append("---")
+    for skill in skills:
+        content = load_skill_md(skill)
+        if content:
+            parts.append(content)
+            parts.append("---")
+    return "\n\n".join(parts)
+
+
 # ---------------------------------------------------------------------------
 # Token estimation
 # ---------------------------------------------------------------------------
@@ -223,28 +214,16 @@ def build_prompt(
     project_cfg: dict,
     state_text: str,
     include_system: bool = False,
+    system_agents: list[str] | None = None,
+    system_skills: list[str] | None = None,
 ) -> str:
     parts: list[str] = []
 
     if include_system:
-        sys_path = KIT_DIR / "system_prompt.md"
-        if sys_path.exists():
-            try:
-                parts.append(sys_path.read_text(encoding="utf-8").strip())
-                parts.append("\n" + "=" * 60 + "\n")
-            except (OSError, PermissionError):
-                print("[WARN] Could not read system_prompt.md — inlining agents instead.", file=sys.stderr)
-                include_system = False
-
-        if not sys_path.exists() or not include_system:
-            for agent in agents:
-                parts.append(load_agent_md(agent))
-                parts.append("---")
-            for skill in skills:
-                content = load_skill_md(skill)
-                if content:
-                    parts.append(content)
-                    parts.append("---")
+        # Task-scoped: inline only the domain's routed agents + skills (not the full
+        # 8-agent / 12-skill system_prompt.md) to keep token cost low.
+        parts.append(build_scoped_system(system_agents or agents, system_skills or skills))
+        parts.append("\n" + "=" * 60 + "\n")
 
     project_name = project_cfg.get("project_name", "unknown")
     proj_domain = project_cfg.get("primary_domain", domain)
@@ -266,7 +245,13 @@ def build_prompt(
         session_num = project_cfg.get("session_count", 0) + 1
         parts.append(f"## Session State\nSession {session_num} — starting fresh")
 
-    parts.append(f"## Task\n{problem}")
+    parts.append(
+        f"## Task\n{problem}\n\n"
+        "Execute this task now. If it is self-contained, deliver the finished artifact "
+        "immediately in Direct Task Mode — do not greet, do not restate this configuration, "
+        "do not ask for project context, and do not open the phase lifecycle unless the task "
+        "is clearly multi-phase. End with the [Companion] next-steps block."
+    )
 
     routing_lines = [
         "## Domain & Routing",
@@ -320,6 +305,11 @@ def main() -> None:
         action="store_true",
         help="Apply token policy for the detected phase/domain: appends output style instruction and reports token budget.",
     )
+    parser.add_argument(
+        "--system-only",
+        action="store_true",
+        help="Print only the task-scoped system prompt (routed agents + skills) and exit. Use as the `system` field of an API call.",
+    )
     args = parser.parse_args()
 
     # Validate problem statement
@@ -332,7 +322,7 @@ def main() -> None:
 
     # Load project config
     project_yaml_path = KIT_DIR / "config" / "project.yaml"
-    project_cfg = _load_yaml(project_yaml_path)
+    project_cfg = load_yaml(project_yaml_path)
     if not project_cfg:
         print(
             "[WARN] project.yaml not found or empty. Run init_project.py first for best results.",
@@ -378,6 +368,19 @@ def main() -> None:
     agents = select_agents(phase, domain)
     skills = select_skills(agents)
 
+    # A self-contained system prompt (--full / --system-only) must carry the whole
+    # domain's specialists so Direct Task Mode can deliver — scope by domain, not phase.
+    if args.full or args.system_only:
+        sys_agents = domain_agents(domain)
+        sys_skills = select_skills(sys_agents)
+    else:
+        sys_agents, sys_skills = agents, skills
+
+    # --system-only: emit just the task-scoped system prompt (for the API `system` field).
+    if args.system_only:
+        print(build_scoped_system(sys_agents, sys_skills))
+        return
+
     prompt_text = build_prompt(
         problem=args.problem,
         domain=domain,
@@ -389,6 +392,8 @@ def main() -> None:
         project_cfg=project_cfg,
         state_text=state_text,
         include_system=args.full,
+        system_agents=sys_agents,
+        system_skills=sys_skills,
     )
 
     # Apply token policy when --compress is requested
@@ -447,12 +452,7 @@ def main() -> None:
         project_cfg["session_count"] = project_cfg.get("session_count", 0) + 1
         project_cfg["last_session"] = date.today().isoformat()
         try:
-            with tempfile.NamedTemporaryFile(
-                "w", dir=project_yaml_path.parent, delete=False, suffix=".tmp", encoding="utf-8"
-            ) as _f:
-                yaml.dump(project_cfg, _f, default_flow_style=False, allow_unicode=True, sort_keys=False)
-                _tmp = _f.name
-            os.replace(_tmp, project_yaml_path)
+            atomic_write_yaml(project_yaml_path, project_cfg)
         except (OSError, PermissionError) as e:
             print(f"[WARN] Could not update session_count in project.yaml: {e}", file=sys.stderr)
 

package/tools/grade_proof.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+grade_proof.py — Blind adversarial grading for compare_prompts.py output.
+
+Takes a proof folder (naive_prompt.txt + naive_output.md + structured_output.md),
+anonymizes the two responses as A/B (order decided by a stable per-folder seed,
+so it is blind but reproducible), and asks an impartial judge model to score both
+on completeness / correctness / actionability / structure and pick a winner.
+
+The judge is a DIFFERENT model from the one that produced the outputs, to reduce
+self-preference bias. Judge input excludes the system prompt, so it stays well
+under tight input-token rate limits.
+
+Usage:
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python tools/grade_proof.py examples/proof/<folder>
+    python tools/grade_proof.py examples/proof/<folder> --judge claude-sonnet-5
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+CRITERIA = ["completeness", "correctness", "actionability", "structure"]
+
+
+def call_judge(prompt: str, model: str, max_tokens: int = 1200) -> str:
+    key = os.environ.get("ANTHROPIC_API_KEY")
+    if not key:
+        raise RuntimeError("ANTHROPIC_API_KEY is not set.")
+    body = {"model": model, "max_tokens": max_tokens, "messages": [{"role": "user", "content": prompt}]}
+    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=120) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"judge api error {e.code}: {e.read().decode('utf-8','replace')[:300]}") from None
+    return "".join(b.get("text", "") for b in data.get("content", [])).strip()
+
+
+def build_prompt(task: str, resp_a: str, resp_b: str) -> str:
+    return (
+        "You are a strict, impartial evaluator. A user made this request:\n\n"
+        f"<request>\n{task}\n</request>\n\n"
+        "Two assistants answered. Judge only how well each fulfills the request "
+        "(ignore length; longer is not better).\n\n"
+        f"### Response A\n{resp_a}\n\n### Response B\n{resp_b}\n\n"
+        "Score each response 1-5 on completeness, correctness, actionability, structure. "
+        "Then pick the overall winner. Respond with ONLY JSON, no prose:\n"
+        '{"A":{"completeness":0,"correctness":0,"actionability":0,"structure":0},'
+        '"B":{"completeness":0,"correctness":0,"actionability":0,"structure":0},'
+        '"winner":"A|B|tie","reason":"one sentence"}'
+    )
+
+
+def main() -> None:
+    sys.stdout.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="Blind-grade a compare_prompts.py proof folder.")
+    ap.add_argument("folder", help="Proof folder containing naive_/structured_ files.")
+    ap.add_argument("--judge", default="claude-sonnet-5", help="Judge model id (default: claude-sonnet-5).")
+    args = ap.parse_args()
+
+    d = Path(args.folder)
+    task = (d / "naive_prompt.txt").read_text(encoding="utf-8").strip()
+    naive = (d / "naive_output.md").read_text(encoding="utf-8").strip()
+    structured = (d / "structured_output.md").read_text(encoding="utf-8").strip()
+
+    # Stable, reproducible blind assignment: structured is A iff folder-hash is even.
+    seed = int(hashlib.sha256(d.name.encode()).hexdigest(), 16)
+    structured_is_a = (seed % 2 == 0)
+    resp_a, resp_b = (structured, naive) if structured_is_a else (naive, structured)
+
+    raw = call_judge(build_prompt(task, resp_a, resp_b), args.judge)
+    m = re.search(r"\{.*\}", raw, re.DOTALL)
+    if not m:
+        raise RuntimeError(f"Judge did not return JSON:\n{raw[:300]}")
+    verdict = json.loads(m.group(0))
+
+    label = {"A": "structured" if structured_is_a else "naive",
+             "B": "naive" if structured_is_a else "structured"}
+    winner = label.get(verdict.get("winner", ""), verdict.get("winner", "tie"))
+    scores = {label[k]: verdict[k] for k in ("A", "B")}
+
+    lines = [
+        f"# Blind grade — {d.name}",
+        "",
+        f"- **Judge:** `{args.judge}` (different model than the one that produced the outputs)",
+        f"- **Blind mapping:** structured = Response {'A' if structured_is_a else 'B'}",
+        f"- **Winner:** **{winner}**",
+        f"- **Reason:** {verdict.get('reason','')}",
+        "",
+        "| Criterion | naive | structured |",
+        "|---|---|---|",
+    ]
+    for c in CRITERIA:
+        lines.append(f"| {c} | {scores['naive'].get(c,'?')} | {scores['structured'].get(c,'?')} |")
+    n_tot = sum(scores["naive"].get(c, 0) for c in CRITERIA)
+    s_tot = sum(scores["structured"].get(c, 0) for c in CRITERIA)
+    lines.append(f"| **total** | **{n_tot}** | **{s_tot}** |")
+    (d / "grade.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    print(f"[graded] {d.name}: winner={winner} | naive={n_tot} structured={s_tot} (judge={args.judge})")
+
+
+if __name__ == "__main__":
+    main()