agent-workflow/skills/agent-workflow-host/SKILL.md

name, description

name

description

agent-workflow-host

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:

$agent-workflow-host 执行已确认计划
$agent-workflow-host 使用 claude 执行已确认计划
$agent-workflow-host 继续 <run-id>
$agent-workflow-host 查看 <run-id>
$agent-workflow-host 清理后重试 <run-id>
$agent-workflow-host 执行器重试 <run-id>
$agent-workflow-host 中止 <run-id> 原因：需求变化

• 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 <executor> --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:

{
  "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:

agent-workflow start --plan <temp-plan.json> --executor <reasonix|claude|agy>

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 <run-id>.
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-<cycle>-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:

{
  "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 <run-id> --input <temp-decision.json>. 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-id>, run agent-workflow status --run <run-id> --json, summarize it, and do not advance the workflow.
• For 继续 <run-id>, 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-id>, run agent-workflow retry-review --run <run-id> after the approved scope artifacts have been removed. It must refuse when HEAD drift or out-of-scope paths remain.
• For 执行器重试 <run-id>, run agent-workflow retry-execute --run <run-id> 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 <run-id> --reason <text> 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 继续 <run-id> 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.