relay-workflow 0.1.0__py3-none-any.whl

relay/__init__.py

@@ -0,0 +1,2 @@
+"""Relay — cross-agent (Claude Code + Codex) planning/execution workflow."""
+__version__ = "0.1.0"

relay/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m relay <subcommand>` to dispatch through the CLI."""
+from relay.cli import main
+
+if __name__ == "__main__":
+    main()

relay/cli.py

@@ -0,0 +1,55 @@
+"""Relay CLI dispatcher: routes `relay <step> ...` to each step's main().
+
+Each step module (plan/project/implement/ship) keeps its own argparse parser
+and `main()`. The dispatcher just slices `sys.argv` so the step sees argv as
+if it had been invoked directly.
+"""
+from __future__ import annotations
+import sys
+from importlib import import_module
+
+from relay import __version__
+
+STEPS = {
+    "plan": "relay.plan",
+    "project": "relay.project",
+    "implement": "relay.implement",
+    "ship": "relay.ship",
+}
+
+USAGE = f"""\
+relay {__version__} — cross-agent planning/execution workflow
+
+Usage:
+  relay <step> [options]
+
+Steps (run in pipeline order):
+  plan       bounded plan-only agent run → plan.json / plan.md
+  project    idempotent GitHub epic + milestones + issues
+  implement  headless agent implements one issue → PR (Closes #N)
+  ship       merge mergeable PRs → bubble up issue/milestone state
+
+Run `relay <step> --help` for step-specific options.
+
+See https://github.com/applied-artificial-intelligence/relay for the design doc.
+"""
+
+
+def main() -> None:
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(USAGE)
+        sys.exit(0)
+    if sys.argv[1] in ("-V", "--version"):
+        print(f"relay {__version__}")
+        sys.exit(0)
+    step = sys.argv[1]
+    if step not in STEPS:
+        print(f"relay: unknown step {step!r}.\n", file=sys.stderr)
+        print(USAGE, file=sys.stderr)
+        sys.exit(2)
+    sys.argv = [f"relay {step}"] + sys.argv[2:]
+    import_module(STEPS[step]).main()
+
+
+if __name__ == "__main__":
+    main()

relay/implement.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""
+relay_implement.py — the Relay `implement` step (prototype).
+
+Consumes a projected plan.json (from relay_project.py) and drives a **headless
+coding agent** to implement ONE issue at a time on its own branch, then opens a
+PR that closes the GitHub issue. This is the step that lets Relay execute its own
+backlog (self-hosting) instead of a human hand-building each change.
+
+Model (workflow-design.md):
+  IMPLEMENT → one issue at a time → branch + PR → GitHub issue (Closes #N)
+
+Each issue in plan.json already carries (from the PROJECT step):
+  number  — GitHub issue #
+  branch  — relay/m<n>-<mslug>/<islug>
+  closes  — "Closes #N"  (the PR-body contract)
+
+Flow per issue:
+  1. select target issue (default: first pending; or --issue <n|title>)
+  2. resolve target repo working tree (--repo-dir, else git toplevel of the unit)
+     + base branch (--base, else origin default)
+  3. create/checkout the issue branch off base (idempotent: reuse if present)
+  4. assemble an implementation brief (objective + milestone + issue + spec.md)
+  5. run the host's headless agent in the working tree (Claude: claude -p …)
+  6. verify commits landed on the branch (else: report no-op, don't open a PR)
+  7. push branch + open PR with the `Closes #N` body (idempotent: reuse PR)
+  8. write pr number/state back into plan.json
+
+Local is the source of truth; GitHub is the projection. **Dry-run by default** —
+prints the target, branch, assembled brief, and the commands it WOULD run. Pass
+--execute to mutate the repo / spend an agent run / open a PR.
+"""
+from __future__ import annotations
+import argparse, json, shutil, subprocess, sys, textwrap
+from pathlib import Path
+
+HOST_DEFAULT = "auto"
+
+
+def sh(cmd: list[str], cwd: str | None = None, check: bool = True) -> str:
+    res = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    if check and res.returncode != 0:
+        sys.exit(f"error: {' '.join(cmd[:3])}… failed: {res.stderr.strip()}")
+    return res.stdout.strip()
+
+
+def git(args: list[str], cwd: str, check: bool = True) -> str:
+    return sh(["git", "-C", cwd, *args], check=check)
+
+
+# --- repo / base resolution -------------------------------------------------
+
+def repo_toplevel(start: Path) -> str:
+    res = subprocess.run(["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+                         capture_output=True, text=True)
+    if res.returncode != 0:
+        sys.exit(f"error: {start} is not inside a git repo (use --repo-dir)")
+    return res.stdout.strip()
+
+
+def default_base(repo_dir: str) -> str:
+    # origin/HEAD -> e.g. "origin/main"; fall back to current branch then "main".
+    ref = git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"],
+              repo_dir, check=False)
+    if ref:
+        return ref.rsplit("/", 1)[-1]
+    cur = git(["branch", "--show-current"], repo_dir, check=False)
+    return cur or "main"
+
+
+def has_remote(repo_dir: str) -> bool:
+    return bool(git(["remote"], repo_dir, check=False))
+
+
+# --- issue selection --------------------------------------------------------
+
+def iter_issues(plan: dict):
+    """Yield (milestone_index, milestone, issue) in plan order."""
+    for mi, m in enumerate(plan.get("milestones", []), 1):
+        for issue in m.get("issues", []):
+            yield mi, m, issue
+
+
+# states that mean "don't pick this again by default"
+DONE_STATES = {"open", "implemented", "implemented-local", "merged", "done", "no-op"}
+
+
+def is_pending(issue: dict) -> bool:
+    # an issue with a recorded PR is in flight, not pending.
+    return not issue.get("pr") and issue.get("state") not in DONE_STATES
+
+
+def select_issue(plan: dict, selector: str | None):
+    """Return (mi, milestone, issue) for the target, or exit with a message."""
+    candidates = list(iter_issues(plan))
+    if not candidates:
+        sys.exit("error: plan.json has no milestones/issues — run relay_plan.py")
+    if selector is None:
+        for mi, m, issue in candidates:
+            if is_pending(issue):
+                return mi, m, issue
+        sys.exit("nothing pending — every issue is already implemented/merged")
+    # explicit selector: match by number then by (sub)string title.
+    for mi, m, issue in candidates:
+        if selector.lstrip("#").isdigit() and str(issue.get("number")) == selector.lstrip("#"):
+            return mi, m, issue
+    for mi, m, issue in candidates:
+        if selector.lower() in issue.get("title", "").lower():
+            return mi, m, issue
+    sys.exit(f"error: no issue matched {selector!r}")
+
+
+# --- implementation brief (the agent's instructions) ------------------------
+
+def build_brief(plan: dict, mi: int, milestone: dict, issue: dict, spec: str) -> str:
+    parts = [
+        f"# Implement one issue from the Relay plan\n",
+        f"## Objective (whole project)\n{plan.get('objective', '(none)')}\n",
+        f"## Milestone M{mi}: {milestone['title']}\n"
+        f"{milestone.get('rationale', '').strip()}\n",
+        f"## YOUR ISSUE (#{issue.get('number', '?')}): {issue['title']}\n"
+        f"{issue.get('body', '').strip() or '(no body)'}\n",
+    ]
+    if spec:
+        parts.append("## Durable spec (the contract — do not contradict it)\n"
+                     f"{spec.strip()}\n")
+    parts.append(textwrap.dedent("""\
+        ## Rules (mechanical, non-negotiable)
+        - Implement ONLY this issue's scope. Do not start other issues or refactor
+          unrelated code. Out-of-scope changes will be rejected in review.
+        - Match the surrounding code's style, naming, and test conventions.
+        - If the repo has tests, add/extend tests for this change and make them pass.
+        - Commit your work with focused, conventional-commit messages
+          (`feat:`/`fix:`/`test:`/`docs:`). The runner pushes and opens the PR; you
+          only need to leave committed changes on the current branch.
+        - If the issue is already satisfied by existing code, make no commits and say so.
+        """))
+    return "\n".join(parts)
+
+
+# --- host resolution --------------------------------------------------------
+
+def resolve_host(requested: str) -> str:
+    """Map --host to a concrete agent. An explicit 'claude'/'codex' is honoured
+    as-is; 'auto' mirrors `relay plan`'s precedence — claude on PATH first, then
+    codex, else exit naming both binaries."""
+    if requested in ("claude", "codex"):
+        return requested
+    if shutil.which("claude"):
+        return "claude"
+    if shutil.which("codex"):
+        return "codex"
+    sys.exit("error: --host auto, but neither `claude` nor `codex` found on PATH")
+
+
+# --- host runner ------------------------------------------------------------
+
+def run_claude(brief: str, repo_dir: str, perm_mode: str, model: str | None) -> dict:
+    """Run a headless Claude Code session in repo_dir. Returns parsed JSON result."""
+    cmd = ["claude", "-p", brief, "--output-format", "json",
+           "--permission-mode", perm_mode, "--add-dir", repo_dir]
+    if model:
+        cmd += ["--model", model]
+    res = subprocess.run(cmd, cwd=repo_dir, capture_output=True, text=True)
+    if res.returncode != 0:
+        sys.exit(f"error: claude headless run failed (exit {res.returncode}): "
+                 f"{res.stderr.strip()[:500]}")
+    try:
+        return json.loads(res.stdout)
+    except json.JSONDecodeError:
+        return {"result": res.stdout.strip(), "raw": True}
+
+
+def run_codex(brief: str, repo_dir: str, perm_mode: str, model: str | None) -> dict:
+    """Run a headless Codex session in repo_dir.
+
+    IMPLEMENT must write the working tree and commit, so the sandbox is
+    `workspace-write` (read-only is correct for PLAN, wrong here). The
+    permission mapping mirrors the Claude host: `bypassPermissions` is the
+    autonomous mode, so it also passes
+    `--dangerously-bypass-approvals-and-sandbox` to skip approval prompts;
+    `acceptEdits`/`default` keep Codex's approvals on.
+
+    Codex `exec` has no `--output-format json`, so success is git-verified by
+    the caller (commit count on the branch), not parsed from stdout. The
+    returned dict matches run_claude's shape only for the human-facing `result`
+    hint shown on a no-op."""
+    cmd = ["codex", "exec", "--sandbox", "workspace-write",
+           "--skip-git-repo-check", "--cd", repo_dir]
+    if perm_mode == "bypassPermissions":
+        cmd.append("--dangerously-bypass-approvals-and-sandbox")
+    if model:
+        cmd += ["--model", model]
+    cmd.append(brief)
+    res = subprocess.run(cmd, cwd=repo_dir, capture_output=True, text=True)
+    if res.returncode != 0:
+        sys.exit(f"error: codex headless run failed (exit {res.returncode}): "
+                 f"{res.stderr.strip()[:500]}")
+    return {"result": res.stdout.strip(), "raw": True}
+
+
+# --- PR projection ----------------------------------------------------------
+
+def existing_pr(repo_dir: str, branch: str) -> int | None:
+    # Only an *open* PR should make open_pr() skip creating a fresh one. A
+    # previously closed/merged PR on the same branch (close-and-redo) would
+    # otherwise return a stale number, leaving plan.json pointing at a dead PR
+    # that SHIP rejects with "PR closed without merging".
+    out = sh(["gh", "pr", "list", "--head", branch, "--state", "open",
+              "--json", "number", "-q", ".[0].number"], cwd=repo_dir, check=False)
+    return int(out) if out.strip().isdigit() else None
+
+
+def open_pr(repo_dir: str, base: str, branch: str, title: str, body: str) -> int:
+    existing = existing_pr(repo_dir, branch)
+    if existing:
+        return existing
+    out = sh(["gh", "pr", "create", "--base", base, "--head", branch,
+              "--title", title, "--body", body], cwd=repo_dir)
+    return int(out.rstrip("/").rsplit("/", 1)[-1])
+
+
+def persist_state(plan: dict, plan_file: Path, repo_dir: str, base: str,
+                  msg: str, log: list[str]) -> None:
+    """Record plan.json state on the BASE branch (cross-issue state must survive
+    between runs and not leave the tree dirty for the next issue). Returns the repo
+    to base; commits + best-effort pushes the metadata change."""
+    git(["checkout", base], repo_dir, check=False)
+    plan_file.write_text(json.dumps(plan, indent=2))
+    if git(["status", "--porcelain", str(plan_file)], repo_dir, check=False):
+        git(["add", str(plan_file)], repo_dir, check=False)
+        git(["-c", "commit.gpgsign=false", "commit", "-m", msg], repo_dir, check=False)
+        if has_remote(repo_dir):
+            # base may be protected; don't fail the run if the push is rejected.
+            pushed = subprocess.run(["git", "-C", repo_dir, "push", "origin", base],
+                                    capture_output=True, text=True)
+            log.append("state committed to " + base +
+                       (" + pushed" if pushed.returncode == 0 else " (push rejected — commit local)"))
+        else:
+            log.append("state committed to " + base + " (local-only)")
+
+
+# --- main -------------------------------------------------------------------
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Relay implement step (prototype)")
+    ap.add_argument("unit", help="work unit dir containing plan.json")
+    ap.add_argument("--issue", help="target issue by #number or title substring "
+                                     "(default: first pending issue)")
+    ap.add_argument("--repo-dir", help="repo working tree to implement in "
+                                       "(default: git toplevel of the unit dir)")
+    ap.add_argument("--base", help="base branch (default: origin default / current)")
+    ap.add_argument("--host", default=HOST_DEFAULT, choices=["claude", "codex", "auto"],
+                    help="headless agent host. 'auto' (default) detects claude on "
+                         "PATH first, then codex (same precedence as `relay plan`).")
+    ap.add_argument("--permission-mode", default="acceptEdits",
+                    help="permission mode (acceptEdits|bypassPermissions|default). "
+                         "Autonomous runs that must run tests/commits usually need "
+                         "bypassPermissions — for the codex host this maps to "
+                         "--dangerously-bypass-approvals-and-sandbox.")
+    ap.add_argument("--model", help="model alias/id for the headless run")
+    ap.add_argument("--redo", action="store_true",
+                    help="re-run even if the issue already has an open PR recorded")
+    ap.add_argument("--execute", action="store_true",
+                    help="actually branch + run the agent + open a PR (default: dry-run)")
+    args = ap.parse_args()
+
+    unit = Path(args.unit).resolve()
+    plan_file = unit / "plan.json"
+    if not plan_file.exists():
+        sys.exit(f"error: {plan_file} not found — run relay_plan.py first")
+    plan = json.loads(plan_file.read_text())
+
+    repo_dir = args.repo_dir or repo_toplevel(unit)
+    base = args.base or default_base(repo_dir)
+    spec = ""
+    spec_file = unit / "spec.md"
+    if spec_file.exists():
+        spec = spec_file.read_text()
+
+    host = resolve_host(args.host)
+    mi, milestone, issue = select_issue(plan, args.issue)
+    branch = issue.get("branch")
+    if not branch:
+        sys.exit("error: issue has no branch — run relay_project.py --execute first "
+                 "(branch/closes wiring lives in the PROJECT step)")
+    closes = issue.get("closes", "")
+    brief = build_brief(plan, mi, milestone, issue, spec)
+    pr_title = issue["title"]
+    pr_body = f"{issue.get('body', '').strip()}\n\n{closes}".strip()
+
+    log = [
+        f"repo: {repo_dir}",
+        f"base: {base}    branch: {branch}",
+        f"issue: #{issue.get('number', '?')}  {issue['title']!r}  (M{mi}: {milestone['title']})",
+        f"host: {host}  perm-mode: {args.permission_mode}  "
+        f"mode: {'EXECUTE' if args.execute else 'dry-run'}",
+    ]
+
+    if not args.execute:
+        print("\n".join(log), file=sys.stderr)
+        print("\n--- would create/checkout branch off base, then run: ---", file=sys.stderr)
+        print(f"  git checkout -b {branch} {base}   (reuse if exists)", file=sys.stderr)
+        if host == "codex":
+            bypass = (" --dangerously-bypass-approvals-and-sandbox"
+                      if args.permission_mode == "bypassPermissions" else "")
+            print(f"  codex exec --sandbox workspace-write --skip-git-repo-check "
+                  f"--cd {repo_dir}{bypass} <brief>", file=sys.stderr)
+        else:
+            print(f"  claude -p <brief> --output-format json "
+                  f"--permission-mode {args.permission_mode} --add-dir {repo_dir}", file=sys.stderr)
+        print(f"  git push -u origin {branch}", file=sys.stderr)
+        print(f"  gh pr create --base {base} --head {branch} "
+              f"--title {pr_title!r} --body <body+{closes!r}>", file=sys.stderr)
+        print("\n--- assembled brief ---\n", file=sys.stderr)
+        print(brief, file=sys.stderr)
+        print("\n(dry-run) re-run with --execute to branch, run the agent, and open a PR.",
+              file=sys.stderr)
+        return
+
+    # --- EXECUTE ---
+    if issue.get("pr") and not args.redo:
+        sys.exit(f"issue #{issue.get('number', '?')} already has PR #{issue['pr']} "
+                 "(state in flight). Use --redo to re-run the agent on it.")
+    # only tracked modifications block us; untracked files (build caches, lockfiles
+    # an agent may emit) don't affect branching and won't be committed by the runner.
+    if git(["status", "--porcelain", "--untracked-files=no"], repo_dir):
+        sys.exit("error: tracked files modified — commit/stash before --execute")
+    git(["checkout", base], repo_dir)  # always plan/branch from a known base
+    # idempotent branch: reuse if it already exists, else create off base.
+    branches = git(["branch", "--list", branch], repo_dir)
+    git(["checkout", branch] if branches else ["checkout", "-b", branch, base], repo_dir)
+    log.append(f"on branch {branch} ({'reused' if branches else 'created'} off {base})")
+
+    head_before = git(["rev-parse", "HEAD"], repo_dir)
+    runner = run_codex if host == "codex" else run_claude
+    result = runner(brief, repo_dir, args.permission_mode, args.model)
+    head_after = git(["rev-parse", "HEAD"], repo_dir)
+
+    if head_after == head_before:
+        issue["state"] = "no-op"
+        git(["checkout", base], repo_dir, check=False)
+        if not branches:  # delete the empty branch we just created
+            git(["branch", "-D", branch], repo_dir, check=False)
+        persist_state(plan, plan_file, repo_dir, base,
+                      f"chore(relay): issue #{issue.get('number', '?')} no-op", log)
+        print("\n".join(log), file=sys.stderr)
+        sys.exit("agent left no commits — nothing to PR. Recorded state=no-op. "
+                 f"Agent said: {str(result.get('result', ''))[:300]}")
+    n_commits = git(["rev-list", "--count", f"{head_before}..{head_after}"], repo_dir)
+    log.append(f"agent landed {n_commits} commit(s)")
+
+    if not has_remote(repo_dir):
+        issue["state"] = "implemented-local"
+        persist_state(plan, plan_file, repo_dir, base,
+                      f"chore(relay): issue #{issue.get('number', '?')} implemented-local", log)
+        print("\n".join(log), file=sys.stderr)
+        print(f"no git remote — branch {branch} left local (state=implemented-local). "
+              "Add a remote and re-run to open a PR.", file=sys.stderr)
+        return
+
+    git(["push", "-u", "origin", branch], repo_dir)
+    pr = open_pr(repo_dir, base, branch, pr_title, pr_body)
+    issue["pr"] = pr
+    issue["state"] = "open"
+    log.append(f"PR #{pr} open ({closes})")
+    persist_state(plan, plan_file, repo_dir, base,
+                  f"chore(relay): record PR #{pr} for issue #{issue.get('number', '?')}", log)
+    print("\n".join(log), file=sys.stderr)
+    print(f"\n✓ implemented issue #{issue.get('number', '?')} → PR #{pr}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

relay/plan.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+relay_plan.py — the Relay `plan` step (prototype).
+
+Turns an aligned spec into a structured, milestone/issue plan WITHOUT letting the
+coding agent run off into implementation. Host-neutral: drives Claude or Codex
+through its mechanically-bounded "plan-but-don't-build" primitive.
+
+  Claude:  claude -p --permission-mode plan          (ExitPlanMode is terminal)
+  Codex:   codex exec --sandbox read-only             (read-only sandbox; can't write)
+
+Flow (matches relay-workflow-design.md):
+  1. read   .workspace/work/<unit>/spec.md           (the WHAT/WHY, from `align`)
+  2. plan   bounded subprocess produces a decomposition (milestones -> issues)
+  3. write  .workspace/work/<unit>/plan.json + plan.md  (local source of truth)
+  4. project  stub: emit the `gh` commands to mirror plan onto GitHub
+              (milestones + issues + Closes-# links). --project to execute.
+
+Empirical basis: relay-planmode-probe.md (live trials, 2026-05-27).
+This is a PROTOTYPE: single-pass, no auth handling beyond what the host CLIs do,
+gh projection is dry-run by default.
+"""
+from __future__ import annotations
+import argparse, json, os, shutil, subprocess, sys, time
+from pathlib import Path
+
+# --- the schema we want the plan to conform to (Codex enforces it; Claude is asked) ---
+PLAN_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["objective", "milestones"],
+    "properties": {
+        "objective": {"type": "string"},
+        "milestones": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["title", "rationale", "issues"],
+                "properties": {
+                    "title": {"type": "string"},
+                    "rationale": {"type": "string"},
+                    "issues": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "additionalProperties": False,
+                            "required": ["title", "body", "labels"],
+                            "properties": {
+                                "title": {"type": "string"},
+                                "body": {"type": "string"},
+                                "labels": {"type": "array", "items": {"type": "string"}},
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+}
+
+PROMPT = """You are producing an IMPLEMENTATION PLAN ONLY. Do not write or modify any files.
+
+Read the specification below and explore the repository as needed. Decompose the work
+into a small number of milestones (delivery chunks), each broken into 5-10 concrete,
+independently-shippable issues. Each issue should be a clear work contract: a title and
+a short body describing scope and acceptance. Prefer the smallest safe slices.
+
+Return ONLY a JSON object matching this shape:
+{schema}
+
+=== SPECIFICATION (spec.md) ===
+{spec}
+"""
+
+
+def detect_host() -> str:
+    if shutil.which("claude"):
+        return "claude"
+    if shutil.which("codex"):
+        return "codex"
+    sys.exit("error: neither `claude` nor `codex` found on PATH")
+
+
+def run_plan_codex(prompt: str, outdir: Path, timeout: int) -> dict:
+    """codex exec --sandbox read-only with an enforced output schema."""
+    schema_file = outdir / "plan.schema.json"
+    schema_file.write_text(json.dumps(PLAN_SCHEMA, indent=2))
+    last = outdir / "plan.codex.json"
+    cmd = [
+        "codex", "exec", "--sandbox", "read-only", "--skip-git-repo-check",
+        "--output-schema", str(schema_file), "-o", str(last), prompt,
+    ]
+    print(f"[codex] {' '.join(cmd[:6])} … (read-only, bounded)", file=sys.stderr)
+    subprocess.run(cmd, timeout=timeout, check=True)
+    return json.loads(last.read_text())
+
+
+def run_plan_claude(prompt: str, outdir: Path, timeout: int) -> dict:
+    """claude -p --permission-mode plan (ExitPlanMode is terminal -> can't implement).
+
+    Claude can't enforce a schema, so we ask for JSON and parse the newest plan file
+    as a fallback. We snapshot ~/.claude/plans before/after to find the new file.
+    """
+    plans = Path.home() / ".claude" / "plans"
+    before = {p: p.stat().st_mtime for p in plans.glob("*.md")} if plans.exists() else {}
+    cmd = [
+        "claude", "-p", prompt, "--permission-mode", "plan",
+        "--setting-sources", "user,project,local", "--output-format", "json",
+    ]
+    print("[claude] claude -p --permission-mode plan … (ExitPlanMode terminal)", file=sys.stderr)
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=True)
+    # Prefer the structured result payload; fall back to newest plan file.
+    text = res.stdout
+    try:
+        payload = json.loads(text)
+        text = payload.get("result", text)
+    except json.JSONDecodeError:
+        pass
+    plan = _extract_json(text)
+    if plan is None and plans.exists():
+        new = sorted(
+            [p for p in plans.glob("*.md") if before.get(p) != p.stat().st_mtime],
+            key=lambda p: p.stat().st_mtime,
+        )
+        if new:
+            plan = _extract_json(new[-1].read_text())
+            (outdir / "plan.claude.raw.md").write_text(new[-1].read_text())
+    if plan is None:
+        sys.exit("error: could not extract a JSON plan from Claude output (see plan.claude.raw.md)")
+    return plan
+
+
+def _extract_json(text: str) -> dict | None:
+    """Pull the first balanced {...} block that parses as our plan."""
+    start = text.find("{")
+    while start != -1:
+        depth = 0
+        for i in range(start, len(text)):
+            depth += (text[i] == "{") - (text[i] == "}")
+            if depth == 0:
+                try:
+                    obj = json.loads(text[start : i + 1])
+                    if isinstance(obj, dict) and "milestones" in obj:
+                        return obj
+                except json.JSONDecodeError:
+                    pass
+                break
+        start = text.find("{", start + 1)
+    return None
+
+
+def write_plan_md(plan: dict, path: Path) -> None:
+    lines = [f"# Plan: {plan.get('objective', '(no objective)')}", ""]
+    for mi, m in enumerate(plan.get("milestones", []), 1):
+        lines.append(f"## M{mi}. {m['title']}")
+        if m.get("rationale"):
+            lines.append(f"_{m['rationale']}_")
+        lines.append("")
+        for ii, issue in enumerate(m.get("issues", []), 1):
+            labels = " ".join(f"`{l}`" for l in issue.get("labels", []))
+            lines.append(f"- [ ] **{issue['title']}** {labels}".rstrip())
+            if issue.get("body"):
+                lines.append(f"      {issue['body']}")
+        lines.append("")
+    path.write_text("\n".join(lines))
+
+
+def gh_projection(plan: dict, execute: bool) -> list[str]:
+    """Emit (or run) the `gh` commands that mirror the plan onto GitHub."""
+    cmds: list[str] = []
+    for m in plan.get("milestones", []):
+        cmds.append(
+            f'gh api repos/:owner/:repo/milestones -f title={_q(m["title"])} '
+            f'-f description={_q(m.get("rationale", ""))}'
+        )
+        for issue in m.get("issues", []):
+            labels = ",".join(issue.get("labels", []))
+            label_arg = f" --label {_q(labels)}" if labels else ""
+            cmds.append(
+                f'gh issue create --title {_q(issue["title"])} '
+                f'--body {_q(issue.get("body", ""))} '
+                f'--milestone {_q(m["title"])}{label_arg}'
+            )
+    if execute:
+        if not shutil.which("gh"):
+            sys.exit("error: --project given but `gh` not on PATH")
+        for c in cmds:
+            print(f"$ {c}", file=sys.stderr)
+            subprocess.run(c, shell=True, check=False)
+    return cmds
+
+
+def _q(s: str) -> str:
+    return "'" + str(s).replace("'", "'\\''") + "'"
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Relay plan step (prototype)")
+    ap.add_argument("unit", help="path to work unit dir containing spec.md")
+    ap.add_argument("--host", choices=["claude", "codex", "auto"], default="auto")
+    ap.add_argument("--timeout", type=int, default=300)
+    ap.add_argument("--project", action="store_true",
+                    help="actually create GitHub milestones/issues via gh (default: dry-run)")
+    args = ap.parse_args()
+
+    unit = Path(args.unit).resolve()
+    spec_file = unit / "spec.md"
+    if not spec_file.exists():
+        sys.exit(f"error: {spec_file} not found — run `align` first to produce the spec")
+
+    host = detect_host() if args.host == "auto" else args.host
+    prompt = PROMPT.format(schema=json.dumps(PLAN_SCHEMA), spec=spec_file.read_text())
+
+    t0 = time.time()
+    plan = (run_plan_codex if host == "codex" else run_plan_claude)(prompt, unit, args.timeout)
+    dt = time.time() - t0
+
+    (unit / "plan.json").write_text(json.dumps(plan, indent=2))
+    write_plan_md(plan, unit / "plan.md")
+    n_m = len(plan.get("milestones", []))
+    n_i = sum(len(m.get("issues", [])) for m in plan.get("milestones", []))
+    print(f"✓ planned via {host} in {dt:.0f}s → {n_m} milestones, {n_i} issues", file=sys.stderr)
+    print(f"  wrote {unit/'plan.json'} and {unit/'plan.md'}", file=sys.stderr)
+
+    cmds = gh_projection(plan, execute=args.project)
+    (unit / "gh_projection.sh").write_text("#!/bin/bash\nset -e\n" + "\n".join(cmds) + "\n")
+    if args.project:
+        print(f"✓ projected {n_i} issues onto GitHub", file=sys.stderr)
+    else:
+        print(f"  (dry-run) gh commands written to {unit/'gh_projection.sh'} — "
+              f"run with --project to execute", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()