superpi

Long-running task orchestration for pi via Plan → Execute → Verify decomposition.

Breaks complex tasks into atomic subtasks managed by a Supervisor agent and executed by Worker agents. Progress is tracked on the filesystem (.super/) with full git history.

Install

pi install npm:superpi

Quick start

/super init "build a REST API with authentication and tests"
/super run
/super status

Commands

| Command | Description | |---------|-------------| | /super init "description" | Initialize .super/ and generate initial task breakdown | | /super run [id] | Execute next ready subtask (or a specific one); auto-reviews on completion | | /super review | Trigger Supervisor review of subtasks in verify/ or with attention-needed status | | /super status [id] | Show full subtask tree, or details for a single subtask | | /super revise "instruction" | Ask Supervisor to revise the current plan | | /super plan on\|off\|approve [id\|all] | Control dry-run mode | | /super docs | Show docs index | | /super escalate | View and respond to a Supervisor escalation |

Status icons: [✓] done · [▶] in-progress · [⏳] pending · [?] ready for review · [✗] failed · [!] needs revision · [~] revised

How it works

1. /super init — Supervisor reads your project context and creates TASK.md, PLAN.md, and subtask files in .super/subtasks/pending/
2. /super run — picks the next unblocked subtask, moves it to in_progress/, spawns a Worker agent
3. Worker follows Plan → Execute → Verify, then moves the subtask to verify/
4. Supervisor reviews the result: accepts (→ done/), rejects with feedback, revises the plan, or escalates to you
5. Repeat until all criteria in TASK.md are satisfied

TUI Visibility

All operations (directory initialization, subtask movement, supervisor/worker execution) appear as tool calls in the TUI with full rendering:

• Directory creation shown as bash tool calls
• File writes appear with diffs and syntax highlighting
• Subprocess execution (supervisor/worker) displayed in bash tool boxes
• Progress indicators for long-running operations

This is achieved via built-in tool factories (createBashTool, createWriteTool) wrapped in registered extension tools, triggered through pi.sendUserMessage() for full LLM pipeline integration.

Directory structure

.super/
├── TASK.md              # top-level success criteria
├── PLAN.md              # subtask tree + revision history
├── PROJECT.md           # project context, architecture, constraints
├── config.json          # dry-run mode and other settings
├── supervisor/
│   └── state.md         # supervisor state and escalation notes
├── docs/
│   ├── INDEX.md
│   ├── api-contracts.md
│   ├── decisions.md
│   └── pitfalls.md
└── subtasks/
    ├── pending/          # ready to run
    ├── in_progress/      # currently executing
    ├── verify/           # awaiting supervisor review
    ├── done/             # accepted
    └── revised/          # revised after rejection

Subtask file format

# Task: {title}
**ID:** {sequence}-{slug}
**Parent:** {parent_id | root}
**Depth:** {1-4}
**Status:** pending
**Created:** {ISO timestamp}
**Version:** 1
**Budget:** {N} iterations

## Dependencies
- {id} — {reason}

## Context
## Task
## Success Criteria
- [ ] {verifiable criterion}

## Verification Commands
\`\`\`bash
# commands to verify the result
\`\`\`

## Output Artifacts
## Revision History

Development

git clone https://github.com/mdsalnikov/superpi.git
cd superpi
npm install
npm test

To test locally with pi:

pi install /path/to/superpi -l

License

MIT