--- name: agent-workflow-host description: Drive an explicitly invoked agent-workflow in which Codex freezes the latest confirmed plan, delegates implementation to Reasonix, Claude Code, or Agy, independently reviews the result, submits fix decisions to the same executor session, and repeats until accepted or safely stopped. Use only when the user explicitly invokes $agent-workflow-host to execute, resume, inspect, or abort a stateful workflow after plan discussion. --- # Agent Workflow Host Act as the host planner, reviewer, and final acceptance authority. Let the selected executor implement and fix code. Use `agent-workflow`; do not replace its state machine with direct executor commands. ## Invocation Contract Support these explicit operations: ```text $agent-workflow-host 执行已确认计划 $agent-workflow-host 使用 claude 执行已确认计划 $agent-workflow-host 继续 $agent-workflow-host 查看 $agent-workflow-host 清理后重试 $agent-workflow-host 执行器重试 $agent-workflow-host 中止 原因：需求变化 ``` - Treat an explicit `执行` invocation as authorization to execute the latest clearly bounded plan in the conversation. - Do not start when the conversation contains multiple unresolved plan variants, missing scope, missing acceptance criteria, or missing verification commands. Ask only for the unresolved decision. - If invoked without an operation, show the supported operations and do nothing. - Default to `reasonix`. Use `claude` or `agy` only when the user explicitly selects it or the approved plan already names it. - Never switch or fall back to another executor during a run. ## Host Boundaries - Codex owns plan normalization, finding classification, verification, and acceptance. - The executor owns implementation, tests, and fixes. During an active workflow, Codex must not edit target repository files itself. - `agent-workflow review` only prepares evidence for Codex. Do not invoke another reviewer as an acceptance gate. - Never run or authorize `git commit`, `git push`, `git reset`, history rewriting, or branch deletion. - Never broaden the approved scope or silently change requirements after start. Abort and create a new plan when requirements materially change. ## Start A Confirmed Plan 1. Resolve the target Git root and inspect the repository before execution. 2. Run these preflight checks: - `command -v agent-workflow` - `git status --porcelain` must be empty. - Probe the selected executor with ` --version`. - Confirm no unresolved active workflow prevents a new run. 3. Do not install tools, commit, or stash automatically. Report the exact missing prerequisite and stop. 4. Convert the approved plan to `WorkflowPlanV1` without adding new product decisions: ```json { "version": "1", "title": "Concise title", "planMarkdown": "Decision-complete implementation plan", "scope": ["repo/relative/file-or-directory"], "acceptanceCriteria": ["Observable acceptance condition"], "verificationCommands": [["command", "arg1", "arg2"]] } ``` 5. Require non-empty repository-relative scope entries and at least one verification command. Use argument arrays; never encode shell pipelines, redirections, glob expansion, `&&`, or `;` as one command. 6. Store input JSON in a `mktemp -d` directory outside the repository. The workflow's durable state is the audit record; remove temporary input files after a terminal result. 7. Start the run and record the emitted run ID: ```bash agent-workflow start --plan --executor ``` Honor an explicit `max-cycles` argument. Otherwise use project configuration and workflow defaults. ## Drive The State Machine Continue until a terminal status. Do not stop after merely proposing a decision. ### `awaiting_review` 1. Run `agent-workflow review --run `. 2. Read the emitted `hostReviewFile`. Inspect its complete `diffFile`, full `executorLogFile`, plan, acceptance criteria, repository code, changed-file scope, and HEAD evidence yourself. 3. Review for correctness, regressions, security, and missing tests. Assign stable IDs such as `codex--1` to concrete issues. 4. Independently run every `verificationCommands` entry from the repository root and retain concise evidence. ### `awaiting_scope_resolution` 1. Confirm the Codex review bundle was not prepared and inspect every structured `scopeViolations` entry. 2. Decide whether each listed path was created by the executor and can be safely removed or restored. Never broaden scope, add ignore rules, or delete automatically. 3. To use `outcome: "fix"`, accept every current `scope-*` finding ID exactly once. The CLI resumes the same executor session with a prompt limited to those exact paths. 4. Use `needs_human` when any path may contain intentional work or ownership is unclear. Never use `accept` in this state. 5. After remediation, run `agent-workflow review` again. Codex review may proceed only after HEAD and scope gates pass. ### `awaiting_host` Classify every issue found by Codex: - `accept`: real, actionable, in scope, and required for the approved acceptance criteria. - `reject`: unsupported or incorrect; include a concrete rationale. - `followup`: valid but outside the frozen task; record it without sending it for implementation. Create `HostDecisionV1` in the temporary directory: ```json { "version": "1", "outcome": "fix", "findingDecisions": [ { "findingId": "codex-2-1", "disposition": "accept", "summary": "Concrete problem and required behavior", "path": "src/example.ts", "rationale": "Evidence-based reason" } ], "verificationEvidence": ["command: observed result"], "decidedAt": "ISO-8601 timestamp" } ``` - Use `outcome: "fix"` when at least one accepted finding must be fixed. Every accepted Codex finding requires a non-empty `summary`; include `path` when known. Submit it with `agent-workflow decide --run --input `. The CLI must resume the same executor session. - Use `outcome: "accept"` only when Codex has completed its own review, has no blocking issue, every verification command passes, HEAD is unchanged, and every changed file is in scope. - Use `outcome: "needs_human"` when intent, safety, architecture, or evidence cannot be resolved without the user. - Never send rejected findings or follow-ups to the executor as required fixes. After `fix`, repeat review and decision for the new cycle. Respect the configured cycle budget and the engine's persistence/oscillation stop conditions. ## Resume, Inspect, Or Abort - For `查看 `, run `agent-workflow status --run --json`, summarize it, and do not advance the workflow. - For `继续 `, read status first, then continue from `awaiting_review`, `awaiting_scope_resolution`, or `awaiting_host`. Read the persisted state and referenced cycle artifacts when earlier command output is no longer in context; do not reconstruct findings from memory. - For `清理后重试 `, run `agent-workflow retry-review --run ` after the approved scope artifacts have been removed. It must refuse when HEAD drift or out-of-scope paths remain. - For `执行器重试 `, run `agent-workflow retry-execute --run ` after the external cause of an executor failure is cleared (e.g., session conflict resolved, transient error gone). It preserves failed attempt logs and reuses the same session handle. Initial-cycle retries continue from the original plan; later-cycle retries resume from the preceding decision. Refuses when HEAD has drifted, scope violations exist, or the cycle already produced review artifacts. - Treat `completed`, `needs_human`, `blocked`, `budget_exhausted`, and `aborted` as terminal. Report them instead of attempting another cycle. - For an explicit abort, run `agent-workflow abort --run --reason ` and report the resulting status. ## Failure Handling - Missing session handle, executor failure, or HEAD drift must stop as `blocked`; do not work around the gate. - When a resume failed before producing cycle artifacts because the same session was busy, ask the user to close the owning executor process, then use `retry-execute`; never kill an unrelated process automatically. - Out-of-scope edits must enter `awaiting_scope_resolution`; inspect and remediate them through the same executor session. Repeated identical violations must stop as `needs_human`. - Same finding in consecutive reviews or disappear/reappear oscillation must stop as `needs_human` when the engine reports non-convergence. - If interrupted, preserve the run ID. A later explicit `继续 ` invocation resumes from durable state. - If the user changes requirements, abort the active run and return to plan discussion. Do not mutate the frozen plan in place. ## Final Report Report: - Run ID, executor, terminal status, and cycle count. - Files changed and how they satisfy the approved plan. - Verification commands and observed results. - Accepted fixes, rejected findings with rationale, and recorded follow-ups. - Stop reason and remaining risk, if any. Claim completion only for terminal `completed` after the clean acceptance gate passes.