Autonomous Agent Harness

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

Core Model

Codex reads AGENTS.md, the current git state, relevant code, and any project notes.
Codex defines one concrete worker task from the user's request.
Codex may use independent reviewer/verifier subagents for focused checks.
Pi is used as the implementation worker through npm run agent:loop.
Codex inspects the diff, runs checks, performs review, and asks for a worker fix pass if needed.
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

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:

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.

2.1 KiB Raw Blame History