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>] [--new-task]
```

- `--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).
- When `CODEX_THREAD_ID` is available, runs in the same Codex thread and repository share a current task. Each executor is created lazily on first use and its reliable session handle is reused by later plans in that task.
- `--new-task` creates a new task boundary and clears all three lazy executor bindings. Use it only when the conversation has moved to a materially different task.
- Claude, Reasonix, and Agy bindings remain separate. Selecting another executor does not switch an active run; it starts or resumes that executor only in a later run after the repository is clean.
- Agy sessions without a captured conversation ID are not shared because `--continue` cannot guarantee which conversation will be selected.
- 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.
- When `CODEX_THREAD_ID` is set, only one `--follow` process for a given Run is allowed per Codex thread. A duplicate follower is rejected without affecting the executor; stale locks from dead followers are cleaned automatically. Different threads and manual viewers without `CODEX_THREAD_ID` remain allowed.
- **`--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`)
- `CODEX_THREAD_ID` — Supplied by Codex. Enables task-level executor session reuse for the current Codex thread and repository. Without it, each workflow run keeps the previous standalone behavior.

Task bindings are stored under the workflow state root, outside the target repository. Before reuse, the host checks the owning Codex thread, repository, task, executor kind, and persisted executor session. A missing or mismatched session blocks reuse instead of silently selecting a recent session. Start with `--new-task` only when a fresh task is intended.

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.