What is this?

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.

Installation

pi install npm:pi-superteam

Try without installing:

pi -e npm:pi-superteam

Development mode:

git clone https://github.com/coctostan/pi-superteam.git
pi -e ./pi-superteam/src/index.ts

Quick Start

Run an orchestrated workflow

The fastest way to get going — the orchestrator handles everything end-to-end:

/workflow Add rate limiting with token bucket algorithm

The orchestrator automatically:

1. Brainstorms — scouts your codebase, asks clarifying questions, proposes approaches, writes a design doc
2. Writes a plan — dedicated planner agent creates a detailed TDD plan from the approved design
3. Reviews the plan (architect + spec reviewer, with planner revisions)
4. Configures execution mode and review settings via interactive dialogs
5. Executes each task through implement → review → fix loops (with TDD enforced and live activity streaming)
6. Finalizes with a cross-task review and summary report

State persists to .superteam-workflow.json — resume anytime with /workflow.

Dispatch agents directly

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

Enable TDD enforcement

/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.

Run individual tasks with SDD

For more control, use /sdd to run individual tasks through the review pipeline:

/sdd load plan.md
/sdd run

Features

🤖 Multi-Agent Dispatch

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.

🎯 Workflow Orchestrator

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.

🧪 TDD Guard

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.

🔄 SDD Orchestration

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:

1. 🔨 Implement — dispatches implementer with TDD enforcement
2. 📋 Spec review — verifies implementation matches requirements
3. ✨ Quality review — checks code quality and test quality
4. 🔒 Security review — scans for vulnerabilities (optional, parallel)
5. ⚡ Performance review — identifies bottlenecks (optional, parallel)
6. 🔧 Fix loop — on failure, re-dispatches implementer with specific findings
7. 🚨 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"
}
```

📏 Context-Aware Rules

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`.

💰 Cost Tracking

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
  }
}

Agents

| 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.

Commands

| 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 |

Tools

| Tool | Description | |------|-------------| | team | Dispatch agents (single, parallel, chain modes) — available to the AI | | workflow | Run the orchestrator — available to the AI |

Prompt Templates

| 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 |

Configuration

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.

Architecture

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.ts is 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

Documentation

| 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 |

Credits

• 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)

License

MIT — see LICENSE