Skip to content

docs(improve): headless-CLI executor variant for execute - #22

Open
funkiirabu wants to merge 1 commit into
shadcn:mainfrom
funkiirabu:headless-cli-executor
Open

docs(improve): headless-CLI executor variant for execute#22
funkiirabu wants to merge 1 commit into
shadcn:mainfrom
funkiirabu:headless-cli-executor

Conversation

@funkiirabu

Copy link
Copy Markdown

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 — the execute <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

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 ifauzeee left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants