# 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, Git baseline gates, scope enforcement, and convergence limits

## Prerequisites

- Node.js >= 20
- Git repository
- 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> [--max-cycles <n>]
```

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

### `agent-workflow status`

Display current workflow status.

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

### `agent-workflow abort`

Terminate an active workflow.

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

## Configuration

Create `agent-workflow.json` in your repository root:

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

## 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 from the workflow `timeoutSeconds` value so long tasks
do not fall back to Agy's five-minute default.

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

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