🐍 pi-ouroboros

Structured autonomous development workflow runtime for pi: grill → goal → plan → task execution → review → commit.

Ouroboros is not a rigid all-or-nothing pipeline. It gives pi a reusable workflow runtime for complex coding work while keeping the main agent in charge of decisions and user interaction.

What it provides

• Requirement grilling — clarify high-impact ambiguities before coding.
• Goal files — freeze user-confirmed scope in .ouroboros/runs/<run-id>/goal.md.
• Plan + TaskList — convert goals into independently verifiable tasks.
• Subagents — isolated executor/reviewer/explorer/challenger/deployer roles.
• Runtime scheduler — ouroboros_run executes safe parallel read-only work and sequential write work.
• Task review gates — every write task is reviewed before it is marked done.
• Pre-authorization — authorization.json allows the user to approve a bounded automatic execution window.
• Safety guard — blocks denied paths and dangerous commands.
• Traceability — status.json, trace.jsonl, discoveries.md, and report.md capture execution state.

Architecture

flowchart TB
    User([User]) --> Main[pi Main Agent]

    Main --> Skill[Ouroboros Skill\nintent routing + workflow]
    Main --> Grill[Grill Skill\nclarification interview]

    Skill --> RunFiles[(.ouroboros/runs/<run-id>\ninterview.md\ngoal.md\nplan.md\nauthorization.json\nstatus.json\ndiscoveries.md\ntrace.jsonl\nreport.md)]

    Main --> Approval{User approval\nplan + authorization}
    Approval --> Runtime[Ouroboros Extension Runtime]

    subgraph RuntimeLayer[Extension Runtime]
      Runtime --> CreateRun[ouroboros_create_run]
      Runtime --> Runner[ouroboros_run\nTaskList scheduler]
      Runtime --> SubagentTool[ouroboros_subagent\nisolated pi subprocesses]
      Runtime --> Safety[Safety Guard\ntool_call hook]
      Runtime --> Discovery[ouroboros_discovery_append\natomic append]
      Runtime --> Status[ouroboros_status]
    end

    Runner -->|parallel safe| Explorer[explorer\nreadonly]
    Runner -->|sequential write| Executor[executor\nwrite + verify]
    Executor --> Reviewer[task-reviewer\nread-only gate]
    Runner --> Acceptance[acceptance-reviewer\nfinal acceptance]
    Acceptance --> Deployer[deployer\ngit sanity + commit]

    Safety -. protects .-> Executor
    Discovery --> RunFiles
    Runner --> RunFiles
    SubagentTool --> RunFiles

Execution model

Ouroboros v1 deliberately avoids parallel writes to the same working tree.

Task Type	Parallel?	Writes?	Typical agent
readonly	yes	no	explorer
review	yes	no	challenger, task-reviewer
verify	conditional	no	task-reviewer / configured
write	no	yes	executor
decision	no	no	main agent asks user

This keeps the system robust while still speeding up safe exploration, review, and failure classification.

Install

pi install npm:pi-ouroboros

For local development from this repository:

pi -e ./extensions/index.ts

If using local development mode, child subagent processes may not automatically load the local extension unless pi discovers it through the normal extension locations. For realistic testing, install or symlink the package into a pi extension location.

Usage

Full workflow

/implement Add rate limiting to the API endpoints

The agent should:

1. Load the ouroboros skill.
2. Create a run with ouroboros_create_run.
3. Clarify requirements using the grill skill if needed.
4. Write and confirm goal.md.
5. Write plan.md with a flat TaskList.
6. Get user approval and write authorization.json.
7. Call ouroboros_run.
8. Run final acceptance review and commit with deployer.

Check status

Ask the agent to call:

ouroboros_status

Or inspect:

.ouroboros/current.json
.ouroboros/runs/<run-id>/status.json

Run directory layout

.ouroboros/
├── current.json
└── runs/
    └── 2026-05-28-rate-limiting/
        ├── interview.md
        ├── goal.md
        ├── plan.md
        ├── authorization.json
        ├── status.json
        ├── discoveries.md
        ├── report.md
        ├── trace.jsonl
        └── checklists/
            ├── requirements.md
            └── plan.md

Plan TaskList format

## TaskList

- [ ] T001 Explore existing middleware patterns
  **Type**: readonly
  **Agent**: explorer
  **Depends On**: None
  **Files**: read-only
  **Output**:
  - Relevant files and conventions

- [ ] T002 Add rate limiter middleware
  **Type**: write
  **Agent**: executor
  **Depends On**: T001
  **Files**:
  - src/middleware/rateLimiter.ts
  - tests/rateLimiter.test.ts
  **Verify**:
  ```bash
  npm test -- rateLimiter

Expected:

• Tests pass
• Middleware exports createRateLimiter

## Registered tools

| Tool | Purpose |
|---|---|
| `ouroboros_create_run` | Create `.ouroboros/runs/<run-id>/` and initial files. |
| `ouroboros_subagent` | Run bundled agents in isolated pi subprocesses. |
| `ouroboros_run` | Execute a plan TaskList with safe scheduling and task review. |
| `ouroboros_discovery_append` | Atomically append discoveries to the active run. |
| `ouroboros_status` | Report current run and task status. |

## Bundled agents

| Agent | Role |
|---|---|
| `explorer` | Read-only codebase exploration. |
| `executor` | Execute one write task and verify it. |
| `task-reviewer` | Read-only task compliance gate. |
| `challenger` | Pre-execution plan review. |
| `acceptance-reviewer` | Final goal/plan acceptance review. |
| `deployer` | Git sanity checks and local commit. |

## Safety model

The safety guard blocks by default:

- writes to `.env`, `.git/**`, `node_modules/**`;
- `rm -rf` unless explicitly authorized;
- `sudo`;
- `chmod/chown 777`;
- package installs not listed in `authorization.json`.

The goal is to let the user approve a bounded execution window and then step away without granting unlimited autonomy.

## Testing and local development

See [`docs/testing.md`](docs/testing.md) for the recommended two-project workflow:

- develop `pi-ouroboros` in this repository;
- test it against `fixtures/basic-project` copied into `.tmp/basic-fixture` or another sandbox;
- load local source changes via `-e ./extensions/index.ts` and `OUROBOROS_DEV_EXTENSION_PATH`.

Quick fixture setup:

```bash
./scripts/setup-fixture.sh

Status

Early implementation. The v1 runtime implements the core architecture, but advanced features such as worktree-based parallel writes, PR creation, model routing, and full resume UI are intentionally deferred.

License

MIT