# Autonomous Agent Harness

This project uses a Codex-led development loop with independent worker,
verifier, and reviewer roles.

## Core Model

1. Codex reads `AGENTS.md`, the current git state, relevant code, and any
   project notes.
2. Codex defines one concrete worker task from the user's request.
3. Codex may use independent reviewer/verifier subagents for focused checks.
4. Pi is used as the implementation worker through `npm run agent:loop`.
5. Codex inspects the diff, runs checks, performs review, and asks for a worker
   fix pass if needed.
6. Once accepted, Codex stages only the expected files and creates a git
   checkpoint commit.

The worker is autonomous inside its assignment, but it does not own "done". It
must not commit, push, deploy, rewrite history, or start adjacent tasks.

## State

Git checkpoint commits are the durable state. Avoid long-lived execution logs for
ordinary implementation progress.

Pi run artifacts are technical traces only and are ignored under
`.codex/logs/agent-runs/`.

## Command

```bash
npm run agent:loop -- \
  --task "Add a calm end-game reset flow and verify the Svelte app."
```

Use `--name` only when a short run label helps:

```bash
npm run agent:loop -- \
  --name "End game reset" \
  --task "Add a reset flow on the result screen. Keep the copy calm and run the relevant checks."
```

## Gate

After a worker run, Codex accepts output only when `summary.json` reports
`orchestratorStatus=WORKER_DONE_PENDING_CODEX_GATE`. Then Codex runs:

- `git status --short`
- `git diff --check`
- `git status --short -- .pi .agents .codex AGENTS.md development/_reference/ai`
- automatic checks selected from changed files

For app changes the automatic checks are:

- `npm run check`
- `npm run build`

Visible UI changes still need a real local browser smoke before a commit.

## Stop Conditions

Stop and ask the user when:

- the task needs product/design judgment not present in context;
- credentials, deployment, external services, or destructive commands are needed;
- unrelated local changes block safe progress;
- reviewer returns the same blocking concern twice after fix attempts.