Multi-agent orchestration · TDD enforcement · Iterative review cycles · Context-aware rules
A pi extension package that makes your AI write better code.
Install · Quick Start · Features · Agents · Config · Docs
pi-superteam turns your pi agent into a development team. Instead of one AI doing everything, you get specialized agents — a scout that explores code, an implementer that writes tests first, reviewers that catch bugs — all coordinated automatically.
It also makes your AI follow TDD whether it wants to or not. Try to write code without a test? Blocked. Try to rationalize skipping tests? A rule fires and says "no." The three-layer defense (mechanical guard + context rules + methodology skills) makes test-first the path of least resistance.
pi install npm:pi-superteamTry without installing:
pi -e npm:pi-superteamDevelopment mode:
git clone https://github.com/coctostan/pi-superteam.git
pi -e ./pi-superteam/src/index.tsThe fastest way to get going — the orchestrator handles everything end-to-end:
/workflow Add rate limiting with token bucket algorithm
The orchestrator automatically:
- Brainstorms — scouts your codebase, asks clarifying questions, proposes approaches, writes a design doc
- Writes a plan — dedicated planner agent creates a detailed TDD plan from the approved design
- Reviews the plan (architect + spec reviewer, with planner revisions)
- Configures execution mode and review settings via interactive dialogs
- Executes each task through implement → review → fix loops (with TDD enforced and live activity streaming)
- Finalizes with a cross-task review and summary report
State persists to .superteam-workflow.json — resume anytime with /workflow.
Ask pi to use the team tool. It'll show up automatically:
> Have the scout agent find all authentication-related code in this project
> Use team in parallel mode — send security-reviewer and quality-reviewer
to analyze src/auth/
> Chain: scout maps the database layer, then architect reviews the structure
/tdd tdd
Now try writing code without a test:
> Write src/utils.ts with a helper function
🚫 TDD: Create a test file first. Expected: src/utils.test.ts
Write a failing test, run it, then implement.
The AI learns fast. After one block, it writes tests first on its own.
For more control, use /sdd to run individual tasks through the review pipeline:
/sdd load plan.md
/sdd run
The team tool dispatches specialized agents in isolated subprocesses. Each gets its own context window, model, thinking level, and tools — no cross-contamination.
Three dispatch modes:
| Mode | Usage | Description |
|---|---|---|
| Single | agent + task |
One agent, one task |
| Parallel | tasks: [{agent, task}, ...] |
Up to 8 concurrent agents (4 concurrency limit) |
| Chain | chain: [{agent, task}, ...] |
Sequential, {previous} passes context |
# Single — scout explores
Dispatch scout to find all files that handle payment processing
# Parallel — multiple reviewers at once
Run security-reviewer and performance-reviewer in parallel on src/api/
# Chain — scout feeds implementer
Chain: scout finds the auth module, then implementer adds rate limiting.
Use {previous} to pass scout's findings.
A deterministic state machine that drives the full development pipeline — agents do creative work, the orchestrator controls flow.
flowchart LR
BS[Brainstorm] --> PW[Plan Write]
PW --> PR[Plan Review]
PR --> CF[Configure]
CF --> EX[Execute]
EX --> FN[Finalize]
/workflow <description> Start a new orchestrated workflow
/workflow Resume an in-progress workflow
/workflow status Show current phase, task progress, cost
/workflow abort Abort and clear state
Seven phases (brainstorm pipeline):
| Phase | What happens |
|---|---|
| brainstorm | Scout explores codebase → brainstormer generates questions → you answer → approaches proposed → design sections written and approved |
| plan-write | Planner agent writes a detailed TDD plan from the approved design |
| plan-review | Architect + spec reviewer validate the plan against the design (planner revises if needed) |
| configure | Interactive dialogs for execution mode, review mode, and batch size |
| execute | Implement → spec review → quality review → optional reviews per task, with fix loops and live activity streaming |
| finalize | Final cross-task quality review + summary report |
The workflow persists to .superteam-workflow.json and resumes from where it left off. See the Workflow Guide for details.
Hard enforcement at the tool level. The guard intercepts every write, edit, and bash call:
write(src/foo.ts) → Test file exists? → Tests run? → ✅ ALLOW
↓ No ↓ No
🚫 "Create test first" 🚫 "Run tests first"
Three-layer defense:
| Layer | What | When |
|---|---|---|
| Rules | Injects "write tests first" into context | Agent thinks about skipping tests |
| Guard | Blocks the write/edit tool call |
Agent tries to skip tests |
| Skills | Teaches RED→GREEN→REFACTOR | Agent doesn't know the methodology |
ATDD mode adds acceptance test awareness — warns when writing unit tests without an acceptance test to frame the feature.
Automated implement → review → fix loops for individual tasks:
/sdd load plan.md Load tasks from a plan file
/sdd run Execute current task through the pipeline
/sdd status View progress across all tasks
/sdd next Advance to next task
/sdd reset Start over
Pipeline per task:
- 🔨 Implement — dispatches implementer with TDD enforcement
- 📋 Spec review — verifies implementation matches requirements
- ✨ Quality review — checks code quality and test quality
- 🔒 Security review — scans for vulnerabilities (optional, parallel)
- ⚡ Performance review — identifies bottlenecks (optional, parallel)
- 🔧 Fix loop — on failure, re-dispatches implementer with specific findings
- 🚨 Escalation — after max retries, asks you for help
stateDiagram-v2
[*] --> Implement
Implement --> Review
Review --> Done: Pass
Review --> Fix: Findings
Fix --> Review: Retry
Fix --> Escalate: Max retries
Done --> [*]
Reviews return structured JSON — no LLM needed to interpret results:
```superteam-json
{
"passed": false,
"findings": [{ "severity": "high", "file": "src/auth.ts", "line": 42, "issue": "..." }],
"mustFix": ["src/auth.ts:42"],
"summary": "Missing input validation on login endpoint"
}
```
TTSR-inspired rule injection. When the AI's output matches a trigger pattern, corrective guidance is injected into the next turn's context.
Built-in rules:
| Rule | Triggers on | Action |
|---|---|---|
test-first |
"simple enough to skip tests" | Fires once: "Write tests first. No exceptions." |
yagni |
"might need later", "future-proof" | Cooldown: "Implement only what's needed now." |
no-impl-before-spec |
"let me just implement" | Per-turn: "Stop. Write the test first." |
Create your own:
---
name: no-any
trigger: ": any\\b|as any\\b"
priority: medium
frequency: per-turn
---
Do NOT use `any` type. Use proper TypeScript types, generics, or `unknown`.Session-level budget with mid-stream enforcement:
/team # Shows cumulative session cost
{
"costs": {
"warnAtUsd": 5.0, // Notification at $5
"hardLimitUsd": 20.0 // Hard block + subprocess kill at $20
}
}| Agent | Purpose | Tools | Default Model |
|---|---|---|---|
🔍 scout |
Fast codebase recon | read, grep, find, ls, bash | haiku |
💡 brainstormer |
Questions, approaches, design sections | read, find, grep, ls | sonnet |
📝 planner |
Write detailed TDD implementation plans | read, write, find, grep, ls | sonnet |
🔨 implementer |
TDD implementation | all (+ TDD guard + TDD skill) | sonnet |
📋 spec-reviewer |
Spec compliance check | read, grep, find, ls | sonnet |
✨ quality-reviewer |
Code + test quality | read, grep, find, ls | sonnet |
🔒 security-reviewer |
Vulnerability scanning | read, grep, find, ls | sonnet |
⚡ performance-reviewer |
Bottleneck detection | read, grep, find, ls | sonnet |
🏗️ architect |
Design + structure review | read, grep, find, ls | sonnet |
All models and thinking levels are configurable per agent via modelOverrides and thinkingOverrides in .superteam.json. The /team command shows the effective model and thinking level for each agent, with annotations showing whether values come from config overrides, frontmatter, or defaults.
Custom agents — drop a .md file in ~/.pi/agent/agents/:
---
name: api-reviewer
description: REST API design review
tools: read,grep,find,ls
model: claude-sonnet-4-5
thinking: high
---
Review REST API design for consistency, proper HTTP methods, status codes,
pagination, error format, and versioning strategy.
End with a ```superteam-json block.See the Agent Guide for details.
| Command | Description |
|---|---|
/team |
List agents with effective models/thinking levels and session cost |
/team --project |
Include project-local agents from .pi/agents/ |
/tdd [off|tdd|atdd] |
Toggle/set TDD enforcement mode |
/tdd allow-bash-write once <reason> |
One-time bash write escape hatch |
/workflow <description> |
Start a new orchestrated workflow |
/workflow |
Resume an in-progress workflow |
/workflow status |
Show phase, task progress, and cost |
/workflow abort |
Abort workflow and clear state |
/sdd load <file> |
Load a plan file (lower-level) |
/sdd run |
Run SDD for current task |
/sdd status |
Show task progress |
/sdd next |
Advance to next task |
/sdd reset |
Reset SDD state |
| Tool | Description |
|---|---|
team |
Dispatch agents (single, parallel, chain modes) — available to the AI |
workflow |
Run the orchestrator — available to the AI |
| Template | Description |
|---|---|
/sdd <plan.md> |
Start SDD for a plan |
/review-parallel <target> |
Parallel spec + quality review |
/scout <area> |
Scout a codebase area |
/implement <feature> |
Chain: scout → implementer |
Create .superteam.json in your project root. All settings are optional — defaults are sensible.
{
"configVersion": 1,
"tddMode": "tdd",
"testFilePatterns": ["*.test.ts", "*.spec.ts"],
"testCommands": ["npm test", "npx vitest"],
"exemptPaths": ["*.d.ts", "*.config.*"],
"agents": {
"defaultModel": "claude-sonnet-4-5",
"scoutModel": "claude-haiku-4-5",
"modelOverrides": {
"implementer": "claude-opus-4-6"
},
"thinkingOverrides": {
"implementer": "high",
"architect": "xhigh",
"scout": "low"
}
},
"costs": {
"warnAtUsd": 10.0,
"hardLimitUsd": 50.0
}
}Model override priority: config.agents.modelOverrides[name] → agent frontmatter model → scoutModel (for scout) → defaultModel
Thinking override priority: config.agents.thinkingOverrides[name] → agent frontmatter thinking → undefined (no thinking)
Valid thinking levels: off, minimal, low, medium, high, xhigh — invalid values are warned and dropped during config loading.
See the Configuration Guide for the full reference.
pi-superteam/
│
├── src/ TypeScript extension source
│ ├── index.ts Entry point (thin composition root)
│ ├── config.ts Config discovery, defaults, ThinkingLevel type
│ ├── dispatch.ts Agent subprocess management, resolveAgentModel/Thinking
│ ├── team-display.ts /team command formatting (formatAgentLine)
│ ├── review-parser.ts Structured JSON extraction from reviewer output
│ ├── rules/engine.ts Context-aware rule injection (TTSR)
│ └── workflow/
│ ├── state.ts SDD plan tracking + persistence (line-walker parser)
│ ├── tdd-guard.ts TDD enforcement (tool call interception)
│ ├── sdd.ts SDD orchestration loop
│ ├── brainstorm-parser.ts Quote-aware JSON extraction with fallback chain
│ ├── orchestrator.ts Workflow orchestrator entry point + phase dispatch
│ ├── orchestrator-state.ts Typed state, persistence, phase transitions
│ ├── prompt-builder.ts Deterministic prompt construction for all agents
│ ├── interaction.ts Structured user interaction helpers
│ ├── ui.ts Status bar formatting + activity buffer
│ ├── progress.ts Progress file rendering + persistence
│ ├── git-utils.ts Async git utilities (tracked files, changed files, SHA)
│ └── phases/
│ ├── brainstorm.ts Brainstorm phase (scout → questions → approaches → design)
│ ├── plan-write.ts Plan write phase (planner agent dispatch)
│ ├── plan-review.ts Plan review phase (architect + spec reviewer)
│ ├── configure.ts Configure phase (review mode, exec mode, batch size)
│ ├── execute.ts Execute phase (implement → review → fix loops)
│ └── finalize.ts Finalize phase (cross-task review + report)
│
├── agents/ Agent profiles (9 built-in)
│ ├── scout.md
│ ├── brainstormer.md
│ ├── planner.md
│ ├── implementer.md
│ ├── spec-reviewer.md
│ ├── quality-reviewer.md
│ ├── security-reviewer.md
│ ├── performance-reviewer.md
│ └── architect.md
│
├── skills/ Methodology skills (5)
│ ├── superteam-test-driven-development/
│ ├── acceptance-test-driven-development/
│ ├── superteam-subagent-driven-development/
│ ├── superteam-writing-plans/
│ └── superteam-brainstorming/
│
├── rules/ Context rules (3)
│ ├── test-first.md
│ ├── yagni.md
│ └── no-impl-before-spec.md
│
├── prompts/ Prompt templates (4)
│ ├── sdd.md
│ ├── review-parallel.md
│ ├── scout.md
│ └── implement.md
│
└── docs/guides/ Documentation
Design principles:
index.tsis a thin composition root — no business logic- Every piece works independently (TDD guard without SDD, team tool without TDD, rules without either)
- Graceful degradation — missing models, unavailable tools, broken config all handled
- JSON-serializable state — no Maps or Sets, persistence via file or
pi.appendEntry() - Deterministic subprocesses — full isolation with explicit add-backs
- Workflow orchestrator is a pure state machine — agents do creative work, TypeScript controls flow
| Guide | Description |
|---|---|
| Workflow | Orchestrator phases, interaction points, execution modes, resuming |
| Agents | Built-in agents, custom agents, model/thinking config, subprocess isolation |
| TDD Guard | Enforcement mechanics, file mapping, modes, escape hatches |
| SDD Workflow | Plan format, review pipeline, fix loops, escalation |
| Configuration | Full .superteam.json reference |
| Rules | How rules work, built-in rules, creating custom rules |
| Contributing | Development setup, project structure, PR guidelines |
| Changelog | Release notes |
- TDD/SDD methodology adapted from obra/superpowers (MIT)
- TTSR concept inspired by can1357/oh-my-pi (MIT)
- Agent dispatch patterns from pi's built-in subagent example
- LSP integration via lsp-pi (MIT, optional)
MIT — see LICENSE