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 使用 svn 执行已确认计划
$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> 使用会话 <claude-session-id>
$agent-workflow-host 延长 <run-id> 添加 <n> 个周期
$agent-workflow-host 中止 <run-id> 原因：需求变化
$agent-workflow-host 日志 <run-id> [--follow]

• 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, svn commit, svn switch, svn update, 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 VCS root (Git, SVN, or None/snapshot mode) and inspect the repository/directory before execution.
2. Run these preflight checks:
   • command -v agent-workflow
   • For Git: git status --porcelain must be empty.
   • For SVN: svn status must show a clean working copy with no mixed revisions.
   • For None (snapshot mode): No clean checks are required.
   • 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, then immediately print a logs-follow command the user can run independently:

agent-workflow start --plan <temp-plan.json> --executor <reasonix|claude|agy> [--vcs <git|svn|none>]

After starting, announce:

Run <run-id> started. Monitor live output: agent-workflow logs --run <run-id> --follow

Honor an explicit max-cycles argument or --vcs flag. Otherwise use project configuration and workflow defaults. VCS is auto-detected if not specified.

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.

While waiting for an executor

While agent-workflow status --run <run-id> --json reports status: "executing", provide a concise progress update approximately every 20-30 seconds using the activitySummary and executionElapsed fields from the status JSON or from agent-workflow status --run <run-id> --json. Example:

Executor has been running for ~2m. Current activity: Editing src/parser.ts (PID 12345).

• Do not emit raw JSON, empty heartbeat spam, or repeat identical summaries.
• Mention stage, error summaries, or notable file changes when available.
• Always invite the user to watch live output independently:

  Watch live: agent-workflow logs --run <run-id> --follow
  

timeoutSeconds is a consecutive inactivity timeout. Observable executor output refreshes the deadline, so do not treat total runtime beyond that value as a timeout while activity continues.

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, Extend, 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 baseline 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. If a Reasonix handle was not captured, the CLI may recover a persisted session only when its project directory, frozen plan title, and execution time window match the run, and must audit the recovery. Initial-cycle retries continue from the original plan; later-cycle retries resume from the preceding decision. Refuses when baseline has drifted, scope violations exist, or the cycle already produced review artifacts.
• For 执行器重试 <run-id> 使用会话 <claude-session-id>, run agent-workflow retry-execute --run <run-id> --session <claude-session-id> only when a Claude run's recorded session was never created or is unavailable and a known persisted replacement session contains the same frozen plan. The CLI must validate that the session belongs to the same repository and plan before recording the rebind in the audit log and retrying. Never edit state.json manually or guess a session ID.
• For 延长 <run-id> 添加 <n> 个周期, run agent-workflow extend --run <run-id> --additional-cycles <n> to extend a budget_exhausted run. This requires: the run ended at budget_exhausted, has a valid session handle, the last decision was fix, baseline hasn't drifted, and scope is clean. Returns to awaiting_host state to continue the same executor session.
• Treat completed, needs_human, blocked, and aborted as terminal. Report them instead of attempting another cycle.
• budget_exhausted is terminal but can be extended with the extend command if all conditions are met.
• 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 baseline drift (Git HEAD change, SVN revision change) must stop as blocked; do not work around the gate. A missing Reasonix handle may use validated automatic recovery, and a missing Claude session may use the explicit validated session-rebind retry operation when a matching persisted session is known.
• 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 the cycle budget is exhausted and more work remains, explain the extend command option to the user.
• 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.

VCS-Specific Guidance

Git Workflows

• Standard baseline tracking with HEAD SHA
• Diff includes tracked changes and unversioned additions
• Scope checking via git diff --name-only and git ls-files

SVN Workflows (Strict Mode)

• Baseline includes repository URL, UUID, and single working revision
• Before starting: verify svn info shows consistent state, no mixed revisions
• Diff includes tracked modifications, unversioned additions, deletions, and property changes
• The executor never runs svn commit, svn switch, or svn update
• Reject runs with switched paths, externals, conflicts, or incomplete states
• If mixed revisions detected: stop and instruct user to run svn update

None Workflows (Snapshot Mode)

• Automatically falls back to none if no Git or SVN repository is found.
• No repository cleanliness checks are required.
• Baseline is stored as a file system snapshot in the workflow run directory (baseline-snapshot.json).
• Ignores .gitignore and .agent-workflowignore directories/files. .git and .svn are always excluded. Ignored files are not protected by frozen scope gates.
• The executor safety prompt dynamically adapts to avoid running git status or svn status.

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.