pi-superteam 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0 (2026-02-06)
+
+Initial release.
+
+### Features
+
+- **Multi-Agent Dispatch** — `team` tool with single, parallel, and chain modes
+  - 7 built-in agents: scout, implementer, spec-reviewer, quality-reviewer, security-reviewer, performance-reviewer, architect
+  - Custom agent support via markdown profiles
+  - Deterministic subprocess isolation
+
+- **TDD/ATDD Guard** — mechanical enforcement of test-driven development
+  - Blocks impl writes without test file + test run
+  - Bash heuristic catches shell file mutations
+  - ATDD mode with acceptance test awareness
+  - Configurable file mapping strategies
+
+- **SDD Orchestration** — automated implement → review → fix loops
+  - Plan parsing from `superteam-tasks` fenced blocks or headings
+  - Structured reviewer output parsing (`ReviewFindings` JSON)
+  - Fix loops with specific findings passed to implementer
+  - Escalation to human on failure
+
+- **Context-Aware Rules** — TTSR-like rule injection
+  - 3 built-in rules: test-first, YAGNI, no-impl-before-spec
+  - Custom rules with regex triggers and frequency control
+
+- **Cost Tracking** — session-level budget management
+  - Warning threshold and hard limit
+  - Mid-stream abort on hard limit
+  - Per-dispatch and cumulative tracking
+
+- **5 Skills** — TDD, ATDD, SDD, writing-plans, brainstorming
+- **4 Prompt Templates** — /sdd, /review-parallel, /scout, /implement
+- **Branch-aware persistence** — workflow state tracked per session branch

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to pi-superteam
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. Clone the repo:
+   ```bash
+   git clone https://github.com/coctostan/pi-superteam.git
+   cd pi-superteam
+   ```
+
+2. Run with pi in development mode:
+   ```bash
+   pi -e ./src/index.ts
+   ```
+
+   No build step needed — pi loads TypeScript directly.
+
+3. Test your changes:
+   ```bash
+   # Quick smoke test
+   pi -e ./src/index.ts -p --mode text "Use the team tool to dispatch scout to count files in src/"
+   
+   # Test TDD guard
+   cd /tmp && mkdir test-project && cd test-project
+   echo '{"tddMode":"tdd"}' > .superteam.json
+   pi -e /path/to/superteam/src/index.ts
+   ```
+
+## Project Structure
+
+```
+src/
+  index.ts              ← Extension entry point (thin — delegates everything)
+  config.ts             ← Config discovery and defaults
+  dispatch.ts           ← Agent subprocess management
+  review-parser.ts      ← Structured JSON extraction
+  rules/engine.ts       ← Context-aware rule injection
+  workflow/state.ts     ← Plan tracking and persistence
+  workflow/tdd-guard.ts ← TDD enforcement
+  workflow/sdd.ts       ← SDD orchestration loop
+
+agents/   ← Agent profiles (markdown)
+skills/   ← Methodology skills (markdown)
+rules/    ← Context rules (markdown)
+prompts/  ← Prompt templates (markdown)
+```
+
+## Design Principles
+
+1. **`src/index.ts` is a thin composition root** — no business logic, only wiring
+2. **Graceful degradation** — missing models, unavailable tools, flaky SDD all degrade gracefully
+3. **JSON-serializable state** — no Maps, Sets, or classes in persisted state
+4. **Deterministic subprocesses** — agents run in full isolation with explicit add-backs
+5. **Every piece is independently useful** — TDD guard, team tool, rules engine, SDD all work alone
+
+## Adding an Agent
+
+1. Create `agents/your-agent.md` with frontmatter
+2. Test: `pi -e ./src/index.ts -p "Use team to dispatch your-agent to do something"`
+3. If it's a reviewer, include the `ReviewFindings` JSON contract in the system prompt
+
+## Adding a Rule
+
+1. Create `rules/your-rule.md` with trigger regex
+2. Test: start pi with the extension, trigger the pattern, verify rule fires
+
+## Adding a Skill
+
+1. Create `skills/your-skill/SKILL.md`
+2. Follow pi's [skill format](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
+
+## Pull Requests
+
+- Keep changes focused — one feature or fix per PR
+- Test manually via pi (automated tests coming)
+- Update relevant docs if behavior changes
+- Follow existing code style
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coctostan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+<p align="center">
+  <h1 align="center">🦸 pi-superteam</h1>
+  <p align="center">
+    Multi-agent orchestration · TDD enforcement · Iterative review cycles · Context-aware rules
+    <br/>
+    <em>A <a href="https://github.com/badlogic/pi">pi</a> extension package that makes your AI write better code.</em>
+  </p>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#agents">Agents</a> ·
+  <a href="#configuration">Config</a> ·
+  <a href="docs/guides/">Docs</a>
+</p>
+
+---
+
+## 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
+
+```bash
+pi install npm:pi-superteam
+```
+
+**Try without installing:**
+```bash
+pi -e npm:pi-superteam
+```
+
+**Development mode:**
+```bash
+git clone https://github.com/coctostan/pi-superteam.git
+pi -e ./pi-superteam/src/index.ts
+```
+
+## Quick Start
+
+### 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 an automated SDD workflow
+
+Create a plan:
+```markdown
+# Feature: Rate Limiting
+
+\`\`\`superteam-tasks
+- title: Token bucket implementation
+  description: Implement token bucket rate limiter with configurable rate and burst
+  files: [src/rate-limiter.ts]
+- title: Middleware integration
+  description: Express middleware that applies rate limiting per IP
+  files: [src/middleware/rate-limit.ts]
+\`\`\`
+```
+
+Then:
+```
+/sdd load plan.md
+/sdd run
+```
+
+Superteam dispatches the implementer (with TDD enforcement), runs spec + quality reviews, fixes issues automatically, and advances to the next task.
+
+---
+
+## Features
+
+### 🤖 Multi-Agent Dispatch
+
+The `team` tool dispatches specialized agents in isolated subprocesses. Each gets its own context window, model, 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 |
+| **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.
+```
+
+### 🧪 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:
+
+```
+/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
+
+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:**
+```markdown
+---
+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
+```
+
+```json
+{
+  "costs": {
+    "warnAtUsd": 5.0,       // Notification at $5
+    "hardLimitUsd": 20.0     // Hard block + subprocess kill at $20
+  }
+}
+```
+
+---
+
+## Agents
+
+| Agent | Purpose | Tools | Model |
+|-------|---------|-------|-------|
+| 🔍 `scout` | Fast codebase recon | read, grep, find, ls, bash | haiku |
+| 🔨 `implementer` | TDD implementation | all (+ TDD guard) | sonnet |
+| 📋 `spec-reviewer` | Spec compliance check | read-only | sonnet |
+| ✨ `quality-reviewer` | Code + test quality | read-only | sonnet |
+| 🔒 `security-reviewer` | Vulnerability scanning | read-only | sonnet |
+| ⚡ `performance-reviewer` | Bottleneck detection | read-only | sonnet |
+| 🏗️ `architect` | Design + structure review | read-only | sonnet |
+
+**Custom agents** — drop a `.md` file in `~/.pi/agent/agents/`:
+
+```markdown
+---
+name: api-reviewer
+description: REST API design review
+tools: read,grep,find,ls
+model: claude-sonnet-4-5
+---
+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](docs/guides/agents.md) for details.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/team` | List agents and session cost |
+| `/tdd [off\|tdd\|atdd]` | Toggle TDD enforcement mode |
+| `/tdd allow-bash-write once <reason>` | One-time bash write escape hatch |
+| `/sdd load <file>` | Load a plan file |
+| `/sdd run` | Run SDD for current task |
+| `/sdd status` | Show task progress |
+| `/sdd next` | Advance to next task |
+| `/sdd reset` | Reset SDD state |
+
+## 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.
+
+```json
+{
+  "configVersion": 1,
+  "tddMode": "tdd",
+  "testFilePatterns": ["*.test.ts", "*.spec.ts"],
+  "testCommands": ["npm test", "npx vitest"],
+  "exemptPaths": ["*.d.ts", "*.config.*"],
+  "agents": {
+    "scoutModel": "claude-haiku-4-5",
+    "modelOverrides": {
+      "implementer": "claude-opus-4-6"
+    }
+  },
+  "costs": {
+    "warnAtUsd": 10.0,
+    "hardLimitUsd": 50.0
+  }
+}
+```
+
+See the [Configuration Guide](docs/guides/configuration.md) for the full reference.
+
+---
+
+## Architecture
+
+```
+pi-superteam/
+│
+├── src/                          TypeScript extension source
+│   ├── index.ts                  Entry point (thin composition root)
+│   ├── config.ts                 Config discovery + defaults
+│   ├── dispatch.ts               Agent subprocess management
+│   ├── review-parser.ts          Structured JSON extraction
+│   ├── rules/engine.ts           Context-aware rule injection
+│   └── workflow/
+│       ├── state.ts              Plan tracking + persistence
+│       ├── tdd-guard.ts          TDD enforcement
+│       └── sdd.ts                SDD orchestration loop
+│
+├── agents/                       Agent profiles (7 built-in)
+├── skills/                       Methodology skills (5)
+├── rules/                        Context rules (3)
+├── prompts/                      Prompt templates (4)
+└── 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 `pi.appendEntry()`
+- Deterministic subprocesses — full isolation with explicit add-backs
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Agents](docs/guides/agents.md) | Built-in agents, custom agents, model config, subprocess isolation |
+| [TDD Guard](docs/guides/tdd-guard.md) | Enforcement mechanics, file mapping, modes, escape hatches |
+| [SDD Workflow](docs/guides/sdd-workflow.md) | Plan format, review pipeline, fix loops, escalation |
+| [Configuration](docs/guides/configuration.md) | Full `.superteam.json` reference |
+| [Rules](docs/guides/rules.md) | How rules work, built-in rules, creating custom rules |
+| [Contributing](CONTRIBUTING.md) | Development setup, project structure, PR guidelines |
+| [Changelog](CHANGELOG.md) | Release notes |
+
+---
+
+## Credits
+
+- TDD/SDD methodology adapted from [obra/superpowers](https://github.com/obra/superpowers) (MIT)
+- TTSR concept inspired by [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) (MIT)
+- Agent dispatch patterns from pi's built-in [subagent example](https://github.com/badlogic/pi-mono)
+- LSP integration via [lsp-pi](https://www.npmjs.com/package/lsp-pi) (MIT, optional)
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/agents/architect.md

@@ -0,0 +1,45 @@
+---
+name: architect
+description: Architecture review for design patterns, modularity, and system structure
+tools: read,grep,find,ls
+---
+
+# Architecture Reviewer
+
+You are a software architect reviewing code for structural quality, modularity, and design patterns.
+
+## Instructions
+
+1. Read the codebase structure and changed files
+2. Assess module boundaries and separation of concerns
+3. Check dependency direction (dependencies should point inward)
+4. Evaluate API design and interface contracts
+5. Consider maintainability and extensibility
+
+## Output Format
+
+You MUST end your response with a structured JSON block:
+
+```superteam-json
+{
+  "passed": true,
+  "findings": [
+    {
+      "severity": "medium",
+      "file": "src/index.ts",
+      "issue": "Business logic mixed with routing — violates separation of concerns",
+      "suggestion": "Extract business logic into a service module"
+    }
+  ],
+  "mustFix": [],
+  "summary": "Good overall structure. Minor separation of concerns issue."
+}
+```
+
+## What to Check
+- **Module boundaries**: Clear responsibilities, minimal coupling
+- **Dependency direction**: No circular dependencies, proper layering
+- **API design**: Consistent interfaces, proper abstractions
+- **Error boundaries**: Errors handled at appropriate levels
+- **Configuration**: No hardcoded values, proper config management
+- **Extensibility**: Easy to add features without modifying existing code

package/agents/implementer.md

@@ -0,0 +1,40 @@
+---
+name: implementer
+description: TDD implementation — write failing tests first, then minimal implementation
+tools: read,bash,edit,write,grep,find,ls
+---
+You are implementing a specific task using strict Test-Driven Development (TDD).
+
+## TDD Process (mandatory)
+
+1. **RED** — Write a failing test first. Run it. Verify it fails for the right reason.
+2. **GREEN** — Write the minimal implementation to make the test pass. Run tests. Verify they pass.
+3. **REFACTOR** — Clean up the code while keeping tests green. Run tests after each change.
+4. **COMMIT** — Make a descriptive commit with the changes.
+
+## Rules
+
+- NEVER write implementation code before a failing test exists
+- NEVER write more code than needed to pass the current test
+- ALWAYS run tests after writing them to verify they fail
+- ALWAYS run tests after implementation to verify they pass
+- ALWAYS run tests after refactoring to verify nothing broke
+- If you're tempted to skip a test because the code is "simple" — write the test anyway
+- If you realize you need a helper/utility, write a test for it first
+
+## Output
+
+When complete, summarize:
+- Files created/modified
+- Tests written and their status (all should pass)
+- Key implementation decisions
+- Any concerns or follow-up items
+
+## Self-Review Checklist
+
+Before reporting completion, verify:
+- [ ] All tests pass
+- [ ] No unnecessary code beyond what tests require
+- [ ] Error cases are tested
+- [ ] Code is clean and well-named
+- [ ] No TODO/FIXME left unaddressed

package/agents/performance-reviewer.md

@@ -0,0 +1,51 @@
+---
+name: performance-reviewer
+description: Performance review for bottlenecks, memory issues, and scalability
+tools: read,grep,find,ls
+---
+
+# Performance Reviewer
+
+You are a performance-focused code reviewer. You look for bottlenecks, memory issues, and scalability concerns.
+
+## Instructions
+
+1. Read ALL changed files
+2. Identify hot paths and computational complexity
+3. Check for memory leaks, unbounded growth, unnecessary allocations
+4. Assess I/O patterns: N+1 queries, missing batching, unnecessary serialization
+5. Check for blocking operations in async code paths
+
+## Output Format
+
+You MUST end your response with a structured JSON block:
+
+```superteam-json
+{
+  "passed": true,
+  "findings": [
+    {
+      "severity": "medium",
+      "file": "src/data.ts",
+      "line": 55,
+      "issue": "N+1 query pattern: fetching related records in a loop",
+      "suggestion": "Batch the related records query using IN clause"
+    }
+  ],
+  "mustFix": [],
+  "summary": "Minor N+1 query pattern. No critical performance issues."
+}
+```
+
+## What to Check
+- **Complexity**: O(n²) or worse in hot paths
+- **Memory**: Unbounded arrays/maps, missing cleanup, large object retention
+- **I/O**: N+1 queries, missing connection pooling, synchronous I/O in async context
+- **Concurrency**: Missing parallelization opportunities, unnecessary serialization
+- **Caching**: Missing obvious cache opportunities, cache invalidation issues
+
+## Severity Guide
+- **critical**: Performance issue causing system failure at normal load
+- **high**: Significant degradation under expected load
+- **medium**: Suboptimal but functional, noticeable at scale
+- **low**: Micro-optimization opportunity

package/agents/quality-reviewer.md

@@ -0,0 +1,53 @@
+---
+name: quality-reviewer
+description: Review code quality, test quality, and engineering practices
+tools: read,grep,find,ls
+---
+
+# Code Quality Reviewer
+
+You are a senior code quality reviewer focused on engineering excellence.
+
+## Instructions
+
+1. Read ALL changed files thoroughly
+2. Assess code quality: naming, structure, DRY, error handling, complexity
+3. Assess test quality: real behavior tests (not mock-heavy), edge cases, assertions
+4. Check for anti-patterns, unnecessary complexity, missing error handling
+5. Verify the code is production-ready
+
+## Output Format
+
+You MUST end your response with a structured JSON block:
+
+```superteam-json
+{
+  "passed": true,
+  "findings": [
+    {
+      "severity": "low",
+      "file": "src/utils.ts",
+      "line": 15,
+      "issue": "Function name 'processData' is too generic",
+      "suggestion": "Rename to 'parseUserInput' to better describe its purpose"
+    }
+  ],
+  "mustFix": [],
+  "summary": "Code quality is good. Minor naming suggestion."
+}
+```
+
+## What to Check
+- **Naming**: Clear, descriptive, consistent conventions
+- **DRY**: No unnecessary duplication (but don't over-abstract)
+- **Error handling**: All failure modes handled, meaningful error messages
+- **Complexity**: Functions under ~30 lines, cyclomatic complexity reasonable
+- **Test quality**: Tests verify behavior, not implementation details
+- **Edge cases**: Null, empty, boundary conditions tested
+- **Type safety**: No unnecessary `any`, proper TypeScript usage
+
+## Severity Guide
+- **critical**: Security vulnerability, data loss risk, race condition
+- **high**: Missing error handling, untested critical path, memory leak
+- **medium**: DRY violation, unclear naming, missing edge case test
+- **low**: Style preference, minor naming improvement