224 lines
17 KiB
Markdown
224 lines
17 KiB
Markdown
---
|
|
name: agent-workflow-host
|
|
description: Drive an explicitly invoked agent-workflow in which the host (Codex or Claude) freezes the latest confirmed plan, delegates implementation to an executor, 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. You must pass your own identity (codex or claude) as the `--reviewer` on lifecycle commands. Use `agent-workflow`; do not replace its state machine with direct executor commands. You cannot use the `claude` executor if you are the `claude` reviewer. You cannot use the `codex` executor if you are the `codex` reviewer. On resume, you must inspect the `reviewer` field in the status output and refuse to continue if it belongs to a different host. When executing lifecycle commands, pass your concrete current identity (e.g. `--reviewer codex`) instead of using a literal `<codex|claude>` placeholder.
|
|
|
|
## 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]
|
|
```
|
|
|
|
When invoked, the host (Codex or Claude) drives the workflow using its respective `--reviewer` flag.
|
|
|
|
- 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`, `codex`, 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, one Codex, 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
|
|
|
|
- The host (Codex or Claude) owns plan normalization, finding classification, verification, and acceptance.
|
|
- The executor owns implementation, tests, and fixes. During an active workflow, the host must not edit target repository files itself.
|
|
- `agent-workflow review` only prepares evidence for the host. 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|codex> --reviewer YOUR_IDENTITY [--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> --reviewer YOUR_IDENTITY`.
|
|
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>-<n>` (if you are Codex) or `claude-<cycle>-<n>` (if you are Claude) 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 web server that reads workflow state files without taking follower locks or interrupting the main execution loop. Workflow monitoring remains read-only: it displays status, execution events, cycle summaries, and live log updates, and cannot reconstruct unlogged private model reasoning. The console also exposes a Chinese global model settings view that can write only `executors.<kind>.model` overrides in `~/.agent-workflow/config.json`. Discovery uses each executor's current CLI environment, isolates failures per executor, never returns credentials, and always allows manual model entry. Project configuration can still override global values, and saved models take effect on later cycles/retries without restarting active executors. The server binds only to 127.0.0.1.
|
|
|
|
`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 your 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 --run <run-id> --reviewer YOUR_IDENTITY` again. Review may proceed only after HEAD and scope gates pass.
|
|
|
|
### `awaiting_host`
|
|
|
|
Classify every issue found during your review:
|
|
|
|
- `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",
|
|
"reviewer": "YOUR_IDENTITY",
|
|
"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 your respective prefix, e.g., `claude-2-1` if Claude).*
|
|
|
|
- Use `outcome: "fix"` when at least one accepted finding must be fixed. Every accepted finding requires a non-empty `summary`; include `path` when known. Submit it with `agent-workflow decide --run <run-id> --input <temp-decision.json> --reviewer YOUR_IDENTITY`. The CLI must resume the same executor session.
|
|
- Use `outcome: "accept"` only when you have completed your own review, have 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> --reviewer YOUR_IDENTITY` 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. For `执行器重试 <run-id> 使用会话 <claude-or-codex-session-id>`, explicitly bind a known Claude or Codex session; the CLI validates the session JSONL against the repository, frozen plan title, and executor kind, and records an audit event with the previous and new session IDs. 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> 添加 <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.
|