https://github.com/ctxswitch/agent-loop
https://github.com/ctxswitch/agent-loop
Last synced: 8 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/ctxswitch/agent-loop
- Owner: ctxswitch
- Created: 2026-06-05T14:36:29.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-06-05T15:27:37.000Z (19 days ago)
- Last Synced: 2026-06-05T16:24:13.598Z (19 days ago)
- Size: 21.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# agent-loop
`agent-loop` is a workflow runtime concept for coding agents. The goal is to
make an agent work through a disciplined development loop with real phase
isolation, structured evidence, and explicit transitions.
The loop is:
1. Implementation
2. Verification
3. Review
4. Close
5. Retro
Each phase should run as a fresh subagent. The orchestrator owns the state
machine, prepares a narrow context packet for the phase, launches the subagent,
records the returned artifact, and decides the next transition.
Users can start, stop, continue, and inspect status; they never choose phase
transitions directly.
For the Pi runtime, an active loop is scoped to the current branch path inside a
Pi session. Loop commands must reconstruct state from append-only Pi custom
entries on that active branch path rather than from one project-wide or
session-file-wide run. Durable run ledgers can still live inside the project, but
Pi-managed ledgers are mirrors of Pi session state and are namespaced by session.
The core design principle is artifact exchange instead of chat-history exchange.
Fresh subagents should receive the goal, relevant repo context, diffs, evidence,
and prior phase outputs. They should not inherit the full implementation
conversation unless the orchestrator intentionally includes it.
## Intended Shape
- `agent-loop-core`: shared schemas, ledger, transition engine, and phase packet
builder used by the Pi extension.
- `pi-agent-loop`: Pi extension that enforces the protocol, launches phase
agents through child Pi processes, injects phase prompts, and updates
UI/status.
Pi is the primary runtime target because Pi extensions can register commands and
tools, subscribe to events, persist session state, inject messages, prompt
through UI, and run extension code that delegates to child Pi processes. The
project intentionally does not target Codex plugins, skills, or CLI adapters in
the current scope.
## Phase Overview
### Implementation
Purpose: produce the smallest working change.
Inputs:
- User goal
- Repo instructions
- Relevant context
- Constraints
- Prior verification or review failures, if any
Outputs:
- Changed files
- Diff summary
- Tests or checks run
- Implementation notes
- Known risks or unresolved questions
### Verification
Purpose: prove the change works from fresh eyes.
Inputs:
- User goal
- Diff
- Implementation evidence
- Known risks
Outputs:
- Scenario matrix
- Commands or checks run
- Pass/fail evidence
- Defects, if any
- Confidence note
### Review
Purpose: inspect correctness, maintainability, style, and principle fit.
Inputs:
- User goal
- Diff
- Verification evidence
- Repo principles
Outputs:
- Findings ordered by severity
- Required fixes
- Waived findings, if any
- Explicit no-findings statement when clean
### Close
Purpose: reconcile evidence and prepare handoff.
Inputs:
- Goal
- Final diff
- Test and scenario evidence
- Review result
- Git status
Outputs:
- Evidence packet
- Final status
- Commit or PR proposal
- Remaining risks
### Retro
Purpose: improve the next run.
Inputs:
- All phase artifacts
- Timings
- Failures and regressions
- User interventions
Outputs:
- Process friction
- Prompt or tool failures
- Memory or harness behavior recommendations
## Transition Rules
```text
implementation -> verification
verification pass -> review
verification fail -> implementation with defect packet
review pass -> close
review fail -> implementation with finding packet
close incomplete -> relevant previous phase
close complete -> retro
retro complete -> done
```
## Current Status
This repository is a design scaffold. The next step is to define the protocol
schema, evidence schema, session lifecycle behavior, and minimal phase packet
format before implementing the Pi extension.