200 lines
4.7 KiB
Markdown
200 lines
4.7 KiB
Markdown
# agent-workflow
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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.
|