docs(improve): headless-CLI executor variant for execute - #22
Conversation
execute currently requires a host that can spawn worktree-isolated subagents; hosts that can't are told to hand the plan over for manual execution. But the dispatch contract (inlined plan + preamble + report format) works just as well through any headless coding CLI run in a worktree the advisor creates itself. Documents that variant in closing-the-loop.md (worktree creation, prompt via temp file, claude -p / codex exec / t2code exec as examples, stateless REVISE loop) and softens the SKILL.md requirement to match. Review protocol, verdicts, and the never-merge rule are unchanged.
ifauzeee
left a comment
There was a problem hiding this comment.
Review: good addition, two things to tighten
The headless-CLI dispatch variant is a genuinely useful fallback — the contract (untrusted diff, review like a tech lead, max 2 revisions, never merge yourself) carries over cleanly, and "restate the plan context or reference the committed work" for REVISE is the right practical note for stateless CLIs.
1. "The CLI executes on a cheap one" repeats the exact defect #23 fixes
The last paragraph claims "the advisor plans on an expensive model, the CLI executes on a cheap one." That's an assumption, not a guarantee: unless you explicitly pass a model (claude -p --model haiku, or the equivalent flag), the CLI runs on its configured default — which may be the same expensive model the advisor uses. This is the identical failure mode PR #23 documents for subagents ("cheaper" is an adjective, not a value passed). Suggest making the model selection explicit in the dispatch commands, consistent with the #23 mandate.
2. Merge conflict with #23 / #28
This PR edits the same SKILL.md execute bullet and the same closing-the-loop.md section as #23 (and #28). The execute bullet will conflict on the shared hunk. Worth coordinating merge order — #23 changes the same line, and this PR's SKILL.md edit also keeps the "cheaper executor subagent" phrasing that #23's whole point is to eliminate.
Otherwise the doc is clear, well-scoped, and the isolation instructions (create the worktree yourself, run non-interactively, prompt from file) are exactly what a host without subagent isolation needs.
What
execute <plan>currently requires a host agent that can spawn subagents with worktree isolation — hosts that can't are told to hand the plan over for manual execution. This PR documents a middle path that keeps the advisor/executor split working on those hosts: dispatch any headless coding CLI (e.g.claude -p,codex exec,t2code exec) in a worktree the advisor creates itself.Changes
references/closing-the-loop.md— new "Dispatch variant — headless coding CLI" subsection after the report format: worktree creation, dispatch prompt via temp file (same inlined plan + preamble + report format as the subagent path), capturing stdout as the executor report, and how REVISE works when the executor is stateless across invocations.SKILL.md— theexecute <plan>bullet now names both executor shapes instead of hard-requiring subagent support; manual handover remains the final fallback.Why
The plan format is already executor-agnostic — it's the skill's biggest strength. This makes the execute flow match: the advisor plans on an expensive model, a cheap CLI executes, and the review protocol (untrusted diff, criteria re-runs, max 2 revision rounds, never merging) applies unchanged. No behavior changes for hosts that can spawn subagents.
Made with Cursor