agent-workflow/README.md

# agent-workflow

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)

**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](https://reasonix.ai), [Claude Code](https://claude.ai/code), or [Agy](https://agy.dev)

## Installation

```bash
npm install -g agent-workflow
```

Or use locally in a project:

```bash
npm install --save-dev agent-workflow
```

## Quick Start

1. Create a plan (WorkflowPlanV1 JSON):

```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:

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

3. Review the implementation:

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

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

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

## Commands

### `agent-workflow start`

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

```bash
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.

```bash
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.

```bash
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.

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

### `agent-workflow retry-execute`

Retry executor resume after clearing an external session conflict.

```bash
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:

```bash
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.

For Reasonix runs blocked after a session handle was not captured, `retry-execute` automatically recovers the persisted session only when its project directory, frozen plan title, and execution time window match the run. The recovery is recorded in the workflow audit log.

### `agent-workflow status`

Display current workflow status.

```bash
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.

```bash
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:

```bash
# 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.

```bash
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.

```bash
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:

```json
{
  "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

```bash
npm install
npm run build
npm test
npm run check
```

## License

MIT — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.