pi-super-devteam logo # pi-super-devteam [简体中文](README.md) | [English](README_EN.md) **A project director firmware for [pi](https://github.com/earendil-works/pi)** Turn a coding agent from a general-purpose code assistant into an engineering team
that can **plan, review, verify, recover, and take responsibility for delivery.** [![npm version](https://img.shields.io/npm/v/pi-super-devteam?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/pi-super-devteam) [![CI](https://img.shields.io/github/actions/workflow/status/patrickleehua/pi-super-devteam/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/patrickleehua/pi-super-devteam/actions/workflows/ci.yml) [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![License](https://img.shields.io/github/license/patrickleehua/pi-super-devteam?style=flat-square&color=22c55e)](LICENSE) [Quick Start](#quick-start) · [Core Capabilities](#core-capabilities) · [How It Works](#how-it-works) · [Commands](#command-reference) · [Development](#development)
--- pi provides the model and its execution capabilities: file access, shell commands, search, and more. pi-super-devteam adds an engineering delivery layer on top: **intent routing, visible plans, single-writer discipline, read-only reviews, deterministic verification, bounded rework, and evidence-based delivery language**. It requires no additional API key and does not run a second reasoning service on the side. pi remains responsible for every real file operation, build, and test. > [!TIP] > Chat and explanation requests have zero workflow overhead. Delivery controls are activated only when a request needs to change the workspace, and their depth scales with the task. ## Quick Start ### Requirements - pi ≥ 0.84 - Node.js ≥ 20 ### Install ```bash # Install for the current user and enable it in every project pi install npm:pi-super-devteam # Or install it only in the current project pi install npm:pi-super-devteam -l ``` You can also install directly from GitHub or try it for one session: ```bash pi install git:github.com/patrickleehua/pi-super-devteam pi -e npm:pi-super-devteam ``` Launch `pi` after installation. No additional configuration is required: ```bash pi ``` Then describe your goal as usual: ```text > Add user authentication to this project and cover it with tests ``` To explicitly enter the full project director workflow, use: ```text /dev Add user authentication to this project and cover it with tests ``` ## Core Capabilities | Capability | What it solves | |---|---| | **Intent routing** | Separates chat, explanation, small edits, debugging, and full builds so the process fits the task | | **Visible plan DAG** | Persists goals as verifiable steps that survive interruptions instead of living only in model context | | **Single-writer discipline** | Allows only one writer per workspace at a time, reducing overwrites and opaque concurrent changes | | **Read-only cross-review** | Runs reviewers in tool-restricted processes that can inspect artifacts but cannot silently modify them | | **Deterministic verification** | Uses files, command output, and execution facts instead of accepting “the tests should pass” | | **Bounded rework** | Produces targeted repair instructions and allows two additional repair attempts by default | | **Honest delivery status** | Reports only `Clean`, `Partial`, or `Blocked`, based on evidence rather than self-assessment | | **Graceful degradation** | Falls back to a deterministic floor if routing, planning, review, or lesson retrieval becomes unavailable | ## How It Works ```mermaid flowchart LR A[User goal] --> B{Intent routing} B -->|Chat / Explain| C[Direct response] B -->|Scoped edit| D[Fast execution] B -->|Debug / Build| E[Visible plan DAG] E --> F[Controlled implementation] D --> G F --> G[Deterministic verification] G -->|Failed with budget left| H[Targeted repair] H --> F G -->|fast| J G -->|standard / deep| I[Read-only review] I --> J[Clean / Partial / Blocked] ``` ### Intent Routing | Category | Typical use | Writes workspace | |---|---|:---:| | `chat` | Conversation and capability questions | No | | `explain` | Code explanation and read-only analysis | No | | `quick_edit` | Small, clearly scoped changes | Yes | | `debug` | Diagnose and fix a defect | Yes | | `build` | New features, real products, and non-trivial changes | Yes | ### Delivery Depth | Depth | Plan | Reviewers | Best for | |---|---|:---:|---| | `fast` | No heavyweight plan | 0 | Small edits and narrow fixes | | `standard` | 3–6 step DAG | ≤ 3 | Normal features and medium-sized changes | | `deep` | 5–8 step DAG | ≤ 8 | Complex products and high-risk work | ### Four Engineering Rules 1. **Single writer**: only the primary session can modify the current workspace, and planned write steps run serially. 2. **Parallel but read-only review**: reviewers receive only `read / grep / find / ls`, making artifact modification impossible. 3. **Facts control the loop; opinions assist**: files, build results, and execution facts decide whether work continues. Reviews produce repair lists, not release authority by themselves. 4. **Every enhancement can degrade gracefully**: when an enhanced stage fails, the workflow returns to a deterministic floor instead of blocking delivery indefinitely. ## Command Reference | Command | Purpose | |---|---| | `/dev ` | Force a goal through the full `build` route | | `/dev-status` | Show the current route, plan, verification, and review state | | `/dev-fleet` | Show parallel subagent capabilities and fleet status | | `/dev-off` | Disable workflow injection; irreversible-action confirmation remains active | | `/dev-on` | Re-enable the project director firmware | | `/dev-unlock` | Force-release the workspace write lock after a crash or interruption | | `/dev-adopt-legacy` | Explicitly copy legacy workspace-level state into the current session | ## Safety and Quality Floor The system prompt is a soft constraint. The actual safety floor is enforced by tool-call interception. - **Irreversible action confirmation**: operations such as `git push --force`, `rm -rf`, `npm publish`, `kubectl delete`, `terraform destroy`, database `DROP`, and opening a PR must show the action, target, impact, recoverability, and exact command before execution. - **Business approval is separate from tool authorization**: approving an implementation plan does not authorize a push, deployment, or data deletion. - **Single-writer lock**: write operations are blocked when unsettled plan steps exist but no step owns the write lock. - **Protected paths**: `.env`, secret files, `node_modules/`, `.git/`, and lockfiles require separate confirmation. > [!IMPORTANT] > `/dev-off` disables workflow enhancements, not safety controls. The irreversible-action gate is always active. Non-interactive environments without a confirmation UI block such operations instead of silently allowing them. ### How Completion Is Verified `dev_verify` selects the strongest applicable acceptance method for each step: | Acceptance method | Evidence | |---|---| | `build-test` | Runs the project's build, test, lint, and typecheck commands and inspects the real result | | `contract` | Runs the configured contract check | | `source-present` | Verifies that promised files exist and are non-empty | | `review-clean` | Confirms the bounded review has settled; it does not mean there are no findings | | `turn-settled` | Weakest floor, used only when mechanical verification is genuinely unavailable | Checks that cannot run are marked `unavailable`; checks that do not apply are marked `skipped`. **Neither counts as passed.** ### How Delivery Is Classified | Status | Conditions | |---|---| | **Clean** | Every step is done, every check passed, no findings remain, and no reviewer is absent | | **Partial** | A step is unsettled, a finding remains, a reviewer is absent, or a check is `unavailable` | | **Blocked** | A step is blocked or verification failed | Without plan and verification evidence, delivery can only be `Partial`. A review step marked `done` means the bounded process settled; it does not mean that every reviewer accepted the result. ## Eight Specialist Seats The package ships with eight stable roles. They are selected dynamically by task type, review face, and delivery depth instead of assembling the entire team for every request. | Seat | Focus | |---|---| | Product Manager | User value, scope, requirements, and acceptance criteria | | Architect | System boundaries, API contracts, data models, and technical constraints | | UI/UX Designer | Design systems, component states, accessibility, and visual identity | | Frontend Engineer | Client implementation, state completeness, responsiveness, and API integration | | Backend Engineer | Server layering, contract consistency, error handling, and data access | | QA Engineer | Requirements traceability, critical paths, boundaries, and regression evidence | | Security Engineer | Authentication, authorization, injection, secrets, and input/output safety | | DevOps Engineer | Builds, configuration, deployment, and release readiness | Each reviewer runs in an isolated process and returns the same decision schema: ```json { "role": "qa-engineer", "accepts": false, "blocking": ["The unauthorized path for FR-12 has no test coverage"], "advisory": ["Consider adding a session-expiry boundary test"], "evidence": ["output/app-prd.md#FR-12", "tests/auth.spec.ts"] } ``` A reviewer that times out, is unavailable, or returns invalid JSON is marked **absent**. An absent seat cannot deadlock the team, but it never counts as a pass. To customize a seat, add a file with the same name to the current project. Project definitions override the packaged defaults: ```text your-project/.pi/agents/security-engineer.md ```
Model tool reference (9 tools) | Tool | Purpose | |---|---| | `dev_route` | Select the category, task kind, depth, and team | | `dev_plan` | Create or advance the plan DAG, claim steps, and acquire the write lock | | `dev_verify` | Run deterministic acceptance before a step can be marked complete | | `dev_review` | Assemble read-only reviewers for parallel cross-review | | `dev_dispatch` | Dispatch independent steps to isolated worktrees; requires `pi-subagents` | | `dev_steer` | Send context or corrections to a running subagent; requires `pi-subagents` | | `dev_deliver` | Produce a Clean / Partial / Blocked result from evidence | | `dev_note` | Append facts, decisions, assumptions, or questions to the shared blackboard | | `dev_lesson` | Store evidence-backed lessons and count recurrences by failure fingerprint |
## Optional Parallel Execution Install [`pi-subagents`](https://github.com/nicobailon/pi-subagents) to enable parallel execution in isolated Git worktrees. Without it, the workflow stays serial; the integration is not a hard dependency. ```bash pi install npm:pi-subagents ``` Before dispatch, the extension verifies that: 1. every target is a ready `build` step; 2. no steps in the batch depend on one another, and all external dependencies are done; 3. promised output paths do not overlap. > There is still only one writer per workspace. Worktrees are isolated workspaces, so they can be written in parallel. Merges back into the primary branch remain serial, and every branch must pass its own acceptance floor first. ## State and Configuration Runtime state is persisted inside the project so work can recover after interruption and the delivery process remains auditable: ```text .pi/dev/ # Runtime state; gitignored ├── preferences.json # Project-level firmware toggle ├── write-lock.json # Project-level lock and owning session ├── lessons.jsonl # Project-level lessons ├── config.json # Optional acceptance-command overrides └── sessions// # Workflow owned by the active Pi session ├── state.json # Session QC counters and runtime state ├── route.json # Current route card ├── plan.json # Recoverable plan DAG ├── blackboard.md # Decisions, assumptions, and open questions ├── ledger.jsonl # Append-only audit ledger └── evidence/ # Command output and raw review decisions output/ └── -delivery.md # Final delivery report ``` ### Custom Acceptance Commands The extension auto-detects npm, pnpm, yarn, bun, Cargo, Go, and pytest projects. To override commands, create `.pi/dev/config.json`: ```json { "build": "pnpm build", "test": "pnpm test -- --run", "lint": "pnpm lint", "typecheck": "tsc --noEmit", "contract": "node scripts/check-openapi-drift.js" } ``` If `contract` is not configured, contract verification honestly reports `unavailable` instead of pretending to pass. ## Development ```bash git clone https://github.com/patrickleehua/pi-super-devteam.git cd pi-super-devteam npm install npm test npm run typecheck ``` The current regression suite contains **230 assertions**: | Check group | Assertions | Coverage | |---|---:|---| | Irreversible action gate | 70 | 27 dangerous command classes, false positives, protected paths, and write-tool detection | | Registration wiring | 51 | 9 tools, 7 commands, 4 events, schemas, result-rendering fallbacks, and session lifecycle | | Session state | 18 | Session isolation, checkpoint restore, fork divergence, cross-session locking, and legacy migration | | Business invariants | 32 | Plan DAGs, blocking propagation, single writer, delivery rules, and failure fingerprints | | UI rendering | 28 | Widget thresholds, CJK alignment, icon widths, and review progress | | Parallel dispatch | 31 | Dependencies, output conflicts, script escaping, and RPC timeout fallback | Tests run inside pi's own extension loader. They need no API key and consume no model calls. Workflow state is isolated by Pi session: `/new` starts without the old panel, `/resume` restores its matching workflow, and `/fork` copies the state at the fork point before diverging independently. Use `pi -c` to start in the most recent conversation; the extension restores the matching super-devteam state for whichever session Pi selects. Legacy `.pi/dev/` state is never attached to a blank new session automatically; use `/dev-adopt-legacy` after confirming the migration.
Why does CI not trust the test process exit code by itself? pi controls the process exit code, so setting `process.exitCode` inside an extension has no effect. CI therefore looks for the `CHECKS_FAILED` marker on stderr and verifies that a test summary was produced. To perform the same check manually: ```bash npm test 2>&1 | tee out ! grep -q CHECKS_FAILED out ```
### Local Debugging Reference the repository entry point from the target project's `.pi/settings.json`, then run `/reload` in pi after changing the source: ```json { "extensions": ["/absolute/path/to/pi-super-devteam/src/index.ts"] } ``` ### Release Publishing is triggered by a Git tag: ```bash npm version patch # or minor / major git push --follow-tags ``` CI validates the version, runs typechecking and regression checks, publishes to npm with provenance, and creates a GitHub Release. Before the first release, configure an npm Automation Token in the repository as `NPM_TOKEN`. ## Acknowledgements The business model was ported from [UmaDev](https://github.com/umacloud/umadev), including its team constitution, intent routing, explicit team composition, recoverable planning, deterministic acceptance, bounded rework, cumulative lessons, and auditable delivery. pi-super-devteam is an independent TypeScript implementation for pi's extension system. It does not reuse UmaDev's Rust source code and does not depend on its CLI or runtime. ## License Released under the [MIT License](LICENSE). ---
**An agent should not merely claim that work was done—it should prove that the delivery holds.**