agent-workflow/README.md

agent-workflow

Codex-hosted autonomous implementation loop with Reasonix, Claude Code, and Agy executors.

agent-workflow orchestrates a stateful implement-review-fix cycle where:

• Codex acts as the host planner, reviewer, and final acceptance authority
• Reasonix, Claude Code, or Agy executes implementation and fixes in the same session
• The workflow maintains atomic state, VCS baseline gates, scope enforcement, and convergence limits
• Supports both Git and SVN working copies with strict validation

Prerequisites

• Node.js >= 20
• Git repository or SVN working copy
• At least one executor: Reasonix, Claude Code, or Agy

Installation

npm install -g agent-workflow

Or use locally in a project:

npm install --save-dev agent-workflow

Quick Start

1. Create a plan (WorkflowPlanV1 JSON):

{
  "version": "1",
  "title": "Add user authentication",
  "planMarkdown": "Implement JWT-based authentication with login and logout endpoints.",
  "scope": ["src/auth/", "src/routes/auth.ts"],
  "acceptanceCriteria": [
    "Login endpoint returns valid JWT",
    "Protected routes reject unauthenticated requests",
    "All tests pass"
  ],
  "verificationCommands": [
    ["npm", "test"],
    ["npm", "run", "lint"]
  ]
}

2. Start a workflow:

agent-workflow start --plan plan.json --executor reasonix

3. Review the implementation:

agent-workflow review --run <run-id>

4. Submit a decision (fix, accept, or needs_human):

agent-workflow decide --run <run-id> --input decision.json

Commands

agent-workflow start

Start a new workflow run. Requires a clean working tree.

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

• --vcs - Explicitly specify VCS kind (git, svn, or none). If omitted, auto-detects from the working directory. If neither Git nor SVN is detected, it automatically falls back to none (snapshot mode).
• Git and SVN working copies are automatically detected when --vcs is not provided.
• SVN working copies must be in a clean, consistent state (no mixed revisions, switched paths, externals, or conflicts).
• None (snapshot) mode skips clean checks, capturing the directory state of the working directory and storing it in the run directory.

agent-workflow review

Generate a Codex review bundle after executor completion. Checks HEAD stability and scope compliance.

agent-workflow review --run <run-id>

agent-workflow decide

Submit a Codex decision (fix, accept, or needs_human). A fix decision resumes the same executor session.

agent-workflow decide --run <run-id> --input <decision.json|->

agent-workflow retry-review

Retry review after the executor has removed approved out-of-scope artifacts.

agent-workflow retry-review --run <run-id>

agent-workflow retry-execute

Retry executor resume after clearing an external session conflict.

agent-workflow retry-execute --run <run-id>

If a failed Claude launch recorded a session ID that was never created, explicitly bind a known persisted Claude session from the same repository and frozen plan while retrying:

agent-workflow retry-execute --run <run-id> --session <claude-session-id>

The override is accepted only for Claude runs. The session JSONL must exist under ~/.claude/projects, belong to the run repository, and contain the frozen plan title. Baseline, scope, and review-artifact gates still apply, and the old/new session IDs are appended to the workflow audit log.

agent-workflow status

Display current workflow status.

agent-workflow status --run <run-id> [--json]

When the workflow is executing, additional live fields are shown:

• Executor PID — process ID of the running executor
• Elapsed — running time
• Activity — current operation being performed
• Last activity — timestamp of most recent output
• Log bytes — bytes written to the attempt log so far
• Live log — path to the streaming log file

agent-workflow logs

Tail and follow live executor output for a running workflow.

agent-workflow logs --run <run-id> [--follow] [--tail <lines>]

• --follow / -f — continuously follow new output. Automatically switches to new retry attempt logs when a retry begins.
• --tail <lines> — number of lines to show from the end of the current log (default: 50).

Examples:

# Show the last 50 lines of the current attempt log
agent-workflow logs --run <run-id>

# Follow new output (like tail -f)
agent-workflow logs --run <run-id> --follow

# Show the last 200 lines
agent-workflow logs --run <run-id> --tail 200

agent-workflow abort

Terminate an active workflow.

agent-workflow abort --run <run-id> --reason "requirements changed"

agent-workflow extend

Extend a budget_exhausted run with additional cycles. The run must have ended at budget_exhausted status with a valid session handle and a final fix decision.

agent-workflow extend --run <run-id> --additional-cycles <n>

This allows continuation of the same executor session after reaching the cycle limit, preserving all audit history and convergence checks.

Configuration

Create agent-workflow.json in your repository root:

{
  "version": "1",
  "defaultExecutor": "reasonix",
  "defaultVcs": "auto",
  "maxCycles": 5,
  "timeoutSeconds": 1800,
  "executors": {
    "reasonix": {
      "binary": "reasonix",
      "model": "claude-opus-4"
    },
    "claude": {
      "binary": "claude"
    },
    "agy": {
      "binary": "agy",
      "agent": "code-assistant"
    }
  }
}

timeoutSeconds is an inactivity timeout, not a total runtime limit. The host resets the timeout whenever the executor emits stdout/stderr progress, so an active task may run longer than the configured window. A continuously silent executor is terminated after the configured number of seconds. Agy receives a 24-hour internal print-mode ceiling while the host inactivity timeout remains the primary stuck-process guard.

• defaultVcs - Default VCS kind: "auto" (detect), "git", "svn", or "none". Default is "auto".

Environment Variables

• AGENT_WORKFLOW_DIR — Override state root (default: ~/.agent-workflow/workflows)
• AGENT_WORKFLOW_META_STDOUT — Emit metadata to stdout instead of stderr (set to 1)

The Agy adapter runs its non-interactive implementation sessions with --dangerously-skip-permissions. This is required because Agy cannot prompt for tool approval in --print mode. The workflow's frozen scope, Git gates, and executor safety prompt remain the authorization boundary. Its internal --print-timeout is set to a 24-hour internal ceiling so active tasks do not fall back to Agy's five-minute default; the workflow inactivity timeout remains the primary guard.

State Machine

executing → awaiting_review → awaiting_host → executing (next cycle)
                           ↘ awaiting_scope_resolution ↗

Any active state → completed | needs_human | blocked | budget_exhausted | aborted

Scope Gates

All file modifications must stay within the approved scope. Out-of-scope changes trigger awaiting_scope_resolution, where Codex inspects each violation and decides whether to remove it or escalate to needs_human.

VCS Support

Git

Standard Git repositories are fully supported with baseline HEAD tracking and diff generation.

SVN (Strict Mode)

SVN working copies are supported with strict validation:

• Requires: Single consistent revision (no mixed revisions)
• Rejects: Switched paths, externals, conflicts, incomplete states, locked files
• Baseline: Repository URL, UUID, and working revision
• Diff: Tracks modifications, additions (including unversioned), deletions, and property changes
• The workflow never runs svn commit, svn switch, or svn update

None (Snapshot Mode)

Used for directories without any version control system.

• Trigger: Runs automatically when no Git or SVN repository is found, or when forced using --vcs none (or config defaultVcs: "none").
• Clean Checks: Skips standard VCS cleanliness checks.
• Baseline: Captures and writes metadata, file paths, size/content hashes, text contents, and symlink targets into baseline-snapshot.json in the workflow run directory.
• Diff: Generates clean unified diffs by comparing active file systems with the captured baseline.
• Ignores: Automatically honors POSIX relative rules in .gitignore and .agent-workflowignore. Directories like .git and .svn are always ignored. Only files outside the ignore boundaries are checked against scope gates.
• Safety constraints: Dynamic executor safety prompts are adapted so that executors do not attempt to run git status or svn status.

Convergence Limits

The workflow stops with needs_human when:

• The same finding persists across 2+ consecutive cycles
• Findings oscillate (disappear then reappear)

Development

npm install
npm run build
npm test
npm run check

License

MIT — see LICENSE and NOTICE for details.