A small repo-native workflow for architecture-constrained agent engineering.
Agents are disposable. Project state is durable.
architecture + current frontier
→ plan → isolated execution → review → merge → reconcile
→ fresh planner → repeat
A round ends when its observations are reconciled into project state, not merely when its PRs merge. The architecture defines the target; one backlog records current status and dependencies. Assignments bound execution, PRs carry evidence, and a fresh planner reconstructs state without previous chats. Only the next executable frontier needs detailed planning.
Bring your own architecture, README and backlog. Ask an agent to follow bootstrap. It maps existing paths and verification into the config template, adapts AGENTS.md, and prepares one small executable item. Your project need not adopt any particular taxonomy, stack or agent vendor.
The pack contains:
- A short protocol and the eight phase procedures.
- Optional read-only status and advisory PR verdict helpers.
- Assignment, result, item and handoff templates.
- A standard-library round CLI for local records and packet/result checks.
- One worked round.
Copy/merge .agent/, scripts/round.py, templates/, SPEC.md and examples/one-round.md,
preserving their relative paths.
Keep your project's README and merge its operating contract from the template. Optional entry points
are one .agents/skills/reconcile-loop/ skill, ten .claude/commands/ wrappers and three
.claude/agents/ subagents (review lens, CI watcher, quick fixer). All use the same canonical
procedures. If your runner does not discover them, read the procedure directly as a prompt.
Ignore .agent-runs/ and HANDOFF.md; keep durable findings in tracked records or PRs.
| Phase | Contract |
|---|---|
| takeoff | Reconstruct current state; no selection or mutations |
| plan-round | Choose executable work and produce packets; no execution |
| execute-task | Implement in isolation and return evidence; no merge |
| review-round | Verify current heads against scope and acceptance |
| merge-round | Merge authorized reviewed changes serially |
| reconcile | Update project truth and close the round |
| handoff | Record a bounded delta for the next fresh session |
Planner decisions remain with the planner; executors own only assigned work. Existing authorization applies; reserved decisions block dependent work while independent authorized work can continue.
The CLI requires Python 3.11+ and Git. Run python3 scripts/round.py --help. It does not launch agents,
run your tests, approve work, contact the PR host, merge branches or manage service locks. Use one
coordinator and run ledger writes serially. Manual packet delivery is supported; unattended
supervision can be added later against the same contracts.
Run python3 -m unittest discover -s tests and git diff --check. The tests use temporary local Git
repositories; no service, network, third-party Python dependency or agent runtime is required.
Only main is maintained. The expanded experimental snapshot
is retained for reference and receives no parallel feature development.
Licensed under the MIT License. Retain its notice when copying the scaffolding.