221 lines
16 KiB
Markdown
221 lines
16 KiB
Markdown
---
|
|
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 执行新任务计划
|
|
$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.
|
|
- Treat the current task as the durable binding identified by `CODEX_THREAD_ID` plus the target repository. Each task may lazily bind one Reasonix, one Claude, and one Agy session; do not eagerly start unused executors.
|
|
- A normal `执行` starts a new run in the current task and automatically reuses the selected executor's bound session when one exists. The other executor bindings remain untouched.
|
|
- Use `执行新任务计划` and pass `--new-task` only when the user clearly starts a materially different task. If the boundary is ambiguous, ask whether the prior executor context should be retained.
|
|
|
|
## 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:
|
|
|
|
```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, then immediately print a logs-follow command the user can run independently:
|
|
|
|
```bash
|
|
agent-workflow start --plan <temp-plan.json> --executor <reasonix|claude|agy> [--vcs <git|svn|none>] [--new-task]
|
|
```
|
|
|
|
Do not pass `--new-task` for a follow-up plan, a correction, or another implementation slice of the same user goal. The CLI validates persisted task bindings before reuse and blocks stale or mismatched handles. An executor selected for the first time in the task starts lazily and is then recorded for later runs. Agy degraded `--continue` handles are intentionally not shared.
|
|
|
|
After starting, announce:
|
|
```text
|
|
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 (`agent-workflow.json`), global configuration (`~/.agent-workflow/config.json`), and workflow defaults, in that order. VCS is auto-detected if not specified.
|
|
|
|
The executor `model` is reloaded from the latest config before each later cycle, scope remediation, cycle extension, and executor retry, while the binary path, agent, profile, budget, timeout, and other executor settings remain locked from run start. Audit events (`workflow_started`, `executor_started`, `executor_completed`, `executor_retried`) record the effective model actually used.
|
|
|
|
## 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.
|
|
- Invite the user once after the Run starts to watch live output independently; do not repeat this command in every progress update:
|
|
```
|
|
Watch live: agent-workflow logs --run <run-id> --follow
|
|
Or view Web console: agent-workflow web [--port <port>] (defaults to http://127.0.0.1:4317/)
|
|
```
|
|
|
|
Start that `logs --follow` command at most once for a given Run in the current Codex thread. If it reports that a follower is already active, do not retry the same command; use `agent-workflow status --run <run-id> --json` for progress instead.
|
|
|
|
The `agent-workflow web` command starts a local read-only web server that reads workflow state files without taking follower locks or interrupting the main execution loop. It only binds to the local loopback interface (127.0.0.1) for safety, as logs can contain sensitive code and environment details. The web interface displays status, execution events, cycle summaries, and live log updates. The console displays the CLI's actual stdout/stderr outputs and parsed structured activity; it cannot reconstruct unlogged private model reasoning.
|
|
|
|
`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:
|
|
|
|
```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 <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, or corrected an invalid `model` configuration). 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.
|
|
- If task-level reuse is rejected because a persisted session is missing or belongs to another repository, do not fall back to a recent external session. Use `--new-task` only after confirming this is a new task; otherwise preserve the binding and report the recovery problem.
|
|
- 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.
|