pi-dev-team 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bryan Finster
+
+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/PORTING.md

@@ -0,0 +1,134 @@
+# Porting dev-team (Claude Code) to pi
+
+Upstream: `bdfinst/agentic-dev-team`, plugin `plugins/dev-team` v14.0.0 (commit 2bf3d98, 2026-09-30).
+Target: pi coding agent 1.0.x (`@earendil-works/pi-coding-agent`; verified on 1.0.0 and 1.0.1, which provide the `agent_settled` event autocompact needs).
+
+## 1. What upstream is
+
+`dev-team` is a Claude Code plugin made of five kinds of parts (upstream counts; the port drops a few skills and adds two agents, see section 4 and the README):
+
+| Part | Count | What it relies on in Claude Code |
+|---|---|---|
+| Agents (`agents/*.md`) | 46 | `Agent`/`Task` tool with `subagent_type`, frontmatter `model: opus/sonnet/haiku`, `effort`, `tools`, `skills` |
+| Skills (`skills/*/SKILL.md`) | 99 (96 user-invocable) | Slash commands, `$ARGUMENTS`/`$0` substitution, `Skill` tool for chaining, `AskUserQuestion`, `allowed-tools` |
+| Hooks (`hooks/*.py`, `hooks.json`) | 42 wired | PreToolUse / PostToolUse / SessionStart / Stop / SubagentStop / SessionEnd / UserPromptSubmit, JSON on stdin, exit 2 = block |
+| Scripts, libs, tools | ~135 Python files | `${CLAUDE_PLUGIN_ROOT}`, `.claude/` project state, 6 call sites of `claude -p` |
+| Knowledge, templates | ~135 files | Plain markdown and JSON, referenced by path |
+
+Many guarantees in the skills are only true because a hook enforces them: careful/freeze/guard, tests-frozen during REFACTOR, the verify loop guard, the `gh pr create` review gate, the review-verdict ledger, cost metering.
+
+## 2. Porting strategy: a compatibility runtime, not a rewrite
+
+Rewriting 99 skills and 46 agents by hand would fork the content and make every upstream release a manual merge. Instead the port ships the upstream content almost unchanged and adds a pi extension that provides the Claude Code runtime contract that content expects.
+
+```
+upstream plugins/dev-team  --sync/sync_upstream.py-->  pi-dev-team package
+                                                      + extensions/dev-team (TypeScript runtime)
+                                                      + bin/claude (CLI shim -> pi)
+                                                      + overrides/ (pi-specific skills)
+```
+
+`sync/sync_upstream.py` is re-runnable. A new upstream release is one command, and the diff shows only upstream changes plus the small, listed patch set.
+
+## 3. Concept mapping
+
+| Claude Code | pi port | Where |
+|---|---|---|
+| Plugin + marketplace | pi package (`pi install ./pi-dev-team` or `git:`) | `package.json` |
+| `${CLAUDE_PLUGIN_ROOT}` | Set in `process.env` by the extension, so bash, hooks, scripts and subagents see it | `index.ts` (`applyEnv`) |
+| `CLAUDE_PROJECT_DIR`, `CLAUDE_SESSION_ID` | Same, from `ctx.cwd` and the pi session id | same |
+| Slash command `/plan args` | Extension command `/plan` that expands `SKILL.md` with `$ARGUMENTS`, `$0..$N` substituted and sends it as the user turn | `skills.ts` |
+| `Skill` tool (skill chaining, e.g. `/specs` -> `/plan`) | `skill` tool: `{name, args}` returns the expanded skill | `skills.ts` |
+| Skill listing for the model | Compact index (name, command, first ~220 chars of the description) in a `<dev_team>` system-prompt section, like Claude Code's budgeted Skill tool listing. Skills are deliberately *not* registered as native pi skills: pi's full listing of 99 descriptions was 61 KB of system prompt; the compact index keeps the whole prompt at ~26 KB. Project skills (`.pi/skills`, `.claude/skills`) are used only when pi trusts the project, as pi does for its own | `skills.ts`, `index.ts` |
+| `Agent` / `Task` tool | `dev_team_subagent` tool: spawns `pi --mode json -p --no-session` with the agent body as appended system prompt, mapped tools, tier-resolved model, thinking level from `effort`. Single, parallel (`tasks[]`), `isolation: "worktree"`. Namespaced to coexist with other extensions such as `pi-subagents`. Follows pi's `examples/extensions/subagent`: child usage (including its own nested dispatches) is returned as the tool result's `usage` (pi adds it to session totals), and the cost meter credits nested dispatches to the agent and model that ran them; project agents are skipped only when pi trust was declined for the project (also for `--dev-team-agent`), and the child gets that decision explicitly (`--no-approve`; `--approve` only in the session's own directory, symlinks resolved, or a worktree this session made of the repository rooted there, since pi decides trust per directory); `renderCall`/`renderResult` draw live per-agent progress in the TUI, with child text stripped of terminal escape sequences and carriage returns as pi's own renderer does, and each child tool call shown with its key argument (`$ cmd`, `read path`); output over 50 KB (by bytes) is cut; the model is told which file holds the complete output and how to page through it, the TUI only shows the path; child tool calls are kept as structured summaries (a few shown arguments, capped) and formatted at render time; the tool declares pi's safety hints (`destructiveHint`, `openWorldHint`) for permission extensions | `subagent.ts`, `child-run.ts`, `trust.ts`, `subagent-render.ts`, `subagent-types.ts`, `terminal-text.ts` |
+| `model: opus/sonnet/haiku/fable` | Tier table in `dev-team.json` (per user or project). The project's `.pi/dev-team.json` is ignored when pi trust was declined, and its `env` may only set an explicit list of dev-team tuning settings (`PROJECT_ENV_SETTINGS` in `config.ts`, plain numbers, words or flags): pi asks about trust only when a repo has pi-protected files, so a repo with just this file is trusted without a prompt, and its env must not reach `PATH`, `NODE_OPTIONS`, `PYTHONPATH`, a path the port reads or runs (`DEV_TEAM_PY_CACHE` is executed by `hooks/py.sh`), a program choice, or a gate bypass. Its `hooks` are ignored (hooks include the guards; set them in your own `~/.pi/agent/dev-team.json`); `/dev-team` status lists what was ignored. Repo-supplied files (agents, skills, settings, config) are read only when they are regular files up to 1 MB (`safe-read.ts`). Default `inherit` = parent's model. Presets: `github-copilot`, `anthropic`, `inherit` | `config.ts`, `/dev-team models` |
+| `effort: low/medium/high` | `--thinking low/medium/high` | `agents.ts` |
+| `tools: Read, Grep, Glob, Bash, Edit, Write` | `read, grep, find, ls, bash, edit, write` (+ `skill`, `dev_team_subagent`, `ask_user`, `web_fetch` when listed) | `agents.ts` |
+| Agent `skills:` frontmatter | Skill names appended to the child system prompt as a hint, with how to load them (exactly what upstream's `subagent_skill_context.py` injects, because Claude Code does not preload skills for plugin agents). Full preload would add up to 290 KB per dispatch | `subagent.ts` |
+| Agent `memory:`, `color:` | Ignored (UI / Claude-only persistent agent memory) | – |
+| Agent `tools: Bash(cmd *)` scoped grants | pi cannot scope bash; the allowed patterns are stated in the child prompt | `agents.ts` |
+| `AskUserQuestion` | `ask_user` tool (select or free text; errors in non-interactive mode so gates fall back to their documented default). `model-only` exposure, so codemode scripts cannot ask the user | `tools-misc.ts` |
+| `WebFetch` | `web_fetch` tool (URL to text). `WebSearch` has no equivalent; skills fall back as upstream documents | `tools-misc.ts` |
+| hooks.json + Python hooks | Hook bridge: reads upstream `hooks/hooks.json`, builds the Claude-shaped stdin payload from pi events, runs the same Python scripts, translates exit codes and JSON back | `hooks.ts` |
+| PreToolUse | `tool_call` (block, or mutate input for `updatedInput`) | |
+| PostToolUse | `tool_result` (advisories appended to the tool result, `decision: block` sets `isError`) | |
+| SessionStart / UserPromptSubmit / Stop / SessionEnd | `session_start` / `input` / `agent_end` / `session_shutdown` | |
+| SubagentStop | Fired by the `dev_team_subagent` tool after each child, with a synthetic Claude-format transcript so `review_verdict_recorder.py` and `subagent_completion_guard.py` run unchanged | `transcript.ts` |
+| `cost_meter.py` (parses Claude transcripts, Claude-only price table) | TypeScript cost meter using pi's own `usage.cost` (works for Copilot and every provider). Same `cost-metering.jsonl` row shape plus `session_id`, so `/cost-report`, `regression`, `pace`, `/autoship --max-cost-usd` keep working | `metrics.ts` |
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` (Claude Code compacts at that % of the window; written by `/setup` via `scripts/set_autocompact_env.py`) | Read with the same precedence as `hooks/lib/autocompact_config.py` (process env, `.claude/settings.local.json`, `.claude/settings.json`, user settings). At `agent_settled` (after pi's own retry and overflow recovery, never inside a run) the extension calls `ctx.compact()` once usage reaches that % (`ctx.getContextUsage()` knows every model's window). Inside one long run pi's own threshold (`contextWindow - reserveTokens`) is the backstop. Project settings files are ignored when pi reports the project untrusted. Unconfigured repos keep pi's default | `autocompact.ts` |
+| SessionStart `source: "compact"` (`post_compact_state_reinject.py`) | Fired from pi's `session_compact` event. The re-injected `/build` state is added to the context with `sendMessage(..., { triggerTurn: false })`, deferred to the end of a running turn, so like Claude's `additionalContext` it never starts a model turn by itself. SessionStart matchers are applied to the source | `index.ts` |
+| `claude -p` / `claude --print` in scripts | `bin/claude` shim translating the flags the scripts use into `pi --mode json -p` and printing a Claude-style result envelope. Prepended to `PATH` inside pi only. Its pi children get `--no-approve` when the session declined trust, and `--approve` only when run in the session's own directory (`DEV_TEAM_TRUSTED_DIR`) | `bin/claude`, `trust.ts` |
+| `test -t 0` interactivity check | Always false under a tool shell (would auto-approve every gate). Patched to `DEV_TEAM_INTERACTIVE=1`, which the extension sets when a human UI is attached | sync patch |
+| `.claude/` project state | Kept as is (`.claude/memory`, `.claude/metrics`, `.claude/hooks`). 67 Python files and ~50 skills address it; changing the name buys nothing and breaks resync | – |
+| `CLAUDE.md` | pi reads both `AGENTS.md` and `CLAUDE.md`. `/setup` writes `AGENTS.md` | override |
+| `/setup`, `/help`, `/version`, `/upgrade`, `/headless-run` | Rewritten for pi | `overrides/` |
+
+### Tools the extension adds
+
+The model uses dev-team through four tools:
+
+| Tool | Claude Code equivalent | Notes |
+|---|---|---|
+| `dev_team_subagent` | Agent / Task | Runs the agent in a child `pi` process with its own context, tools and tier model. Single calls, parallel calls (several calls in one message, or `tasks[]`), and `isolation: "worktree"`. Accepts `subagent_type`/`prompt` too. Live per-agent progress in the TUI; child spend counts in pi's session totals. |
+| `skill` | Skill | Loads a skill with arguments substituted. This is how skills chain (`/specs` → `/plan`, `/ship` → everything). |
+| `ask_user` | AskUserQuestion | The human gates. In non-interactive runs (`pi -p`, subagents) it tells the model to take the documented default. |
+| `web_fetch` | WebFetch | URL to text. |
+
+The dispatch tool is named `dev_team_subagent` so this package can coexist with `pi-subagents`, which registers `subagent`. Dev-team workflows use their own dispatch tool for model tiers, hooks, and metrics. Other workflows can still use the other package's `subagent` tool.
+
+## 4. What is dropped, and why
+
+| Upstream | Reason |
+|---|---|
+| Skills `agent-audit`, `agent-eval`, `harness-e2e-check`, `long-eval`, `orchestration-benchmark`, `claude-setup-review` | Test or audit Claude Code's own harness and plugin layout. The agent files `claude-setup-review` and `session-analysis` still ship (agents stay byte-identical) but nothing in the port dispatches them |
+| Skill `session-review` | Mines `~/.claude/projects` transcripts. A pi session backend for `session_log` is future work |
+| Hook `mcp_json_repowise_nudge` | About Claude's `.mcp.json` |
+| Hooks `code_intelligence_nudge`, `code_intelligence_turn_mark`, `phase_marker` | Need Claude transcript turn structure; nudges only. Off by default, can be re-enabled |
+| Monorepo-only hooks (`contract_version_guard`, `pre_commit_knowledge_index`, `knowledge_index`, `skills_index`, both banned-script scanners, `eval_compliance_check`) | Only act inside the upstream repo itself. Shipped but disabled by default |
+
+## 5. Known differences
+
+- Hook output. In Claude Code, text a PreToolUse/PostToolUse hook prints with exit 0 is only shown in the transcript view. The plugin was written as if the model sees it. The port appends it to the tool result so the model does see it (`hookOutputToModel`, default on).
+- Parallel tool calls. Claude Code runs several `Agent` calls in one message in parallel; so does pi. The `dev_team_subagent` tool also accepts `tasks[]`. A global limit (`maxParallelAgents`, default 6) applies across both.
+- Subagent transcripts are not saved as sessions (`--no-session`). Usage is captured from the JSON event stream and recorded.
+- `allowed-tools` in skills is advisory in pi (as in upstream under `bypassPermissions`).
+- Autocompact timing. Claude Code compacts at `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` between any two turns. The port compacts at that percentage when an agent run ends, because `ctx.compact()` aborts a running turn; within one long run pi's own threshold applies.
+- GitHub text style. The port adds rules for pull request, issue and comment text (`lib/github-style.ts`, with `lib/gh-command.ts` and `lib/shell-scan.ts`: plain English after ASD-STE100 and a skim-first layout). The rules are in the `dev_team` system-prompt section of every session and subagent. In `tool_call`, before the PreToolUse hook bridge, a quote- and heredoc-aware scan finds each `gh pr|issue create|edit|comment` and checks its literal title and body. A breaking call is blocked once with the list of problems; the identical resend goes on to the hooks, so `pre_pr_review` still applies (`githubStyle`: `block`, `warn`, `off`; `off` also drops the rules from the prompt). Notes on `/pr`, `/specs`, `/issues-from-plan`, `/issues-from-assessment` and `/autoship` keep their required sections; `/pr` moves Decisions & Assumptions and the Evidence Bundle into one `<details>` block.
+- `skill-injection.jsonl` (v14 instrument stream) is not written. The port injects skill hints natively instead of via `subagent_skill_context.py`, and uptake is computed from Claude subagent transcripts, which pi children do not save.
+
+## 6. Implementation plan (done)
+
+1. `sync/sync_upstream.py`: copy, drop list, overrides, frontmatter normalisation (description <= 1024, Claude keys moved under `metadata`), text patches, `UPSTREAM.json`.
+2. Extension modules: `config`, `agents`, `skills` (commands + `skill` tool), `subagent` (+ `subagent-types`, `subagent-render`, `child-run`, `trust`, `terminal-text`), `hooks` (bridge; the Python interpreter is resolved on first use, not at load), `transcript`, `session-files` (one private `mkdtemp` directory per pi process, owner-only files created exclusively, removed when pi quits; kept across reload, new, resume and fork, whose tool results may name them), `metrics`, `autocompact`, `safe-read`, `shell-scan`, `gh-command`, `github-style`, `tools-misc` (`ask_user`, `web_fetch`), and in `index.ts` the plugin env, the `/dev-team` command and the compatibility guidelines in the system prompt.
+3. `bin/claude` shim.
+4. Overrides: setup, help, version, upgrade, headless-run. Notes: autoship, issues-from-assessment, issues-from-plan, mutation-night-watch, mutation-testing, pr, project-init, setup, specs.
+5. Verification: unit tests for pure mapping code; offline end-to-end runs of the real `pi` binary against a scripted provider (commands, `skill`, `dev_team_subagent` single/parallel/worktree, hook blocks, SubagentStop ledger rows, cost rows); upstream Python hook test suite against the shipped copy.
+
+## 7. Verification
+
+- **Byte identity.** `hooks/`, `scripts/`, `tools/`, `knowledge/`, `templates/` and the 46 upstream agents are byte-identical to upstream (`diff -rq`). Only 17 `SKILL.md` files differ, each by a listed patch or note (`UPSTREAM.json`). The upstream Python test suite therefore applies unchanged.
+- **Upstream Python suite** run against the shipped copy (`uv run --with pytest ... pytest plugins/dev-team/tests/{hooks,scripts,lib}` plus the top-level `tests/test_*.py` added in v14): 4293 passed. The single error is `test_durable_runner.py`, which tests the dropped `long-eval` skill.
+- **Unit tests** (`test/unit`, node:test, 496 tests): tool and MCP-name mapping, tier and effort resolution, parsing of every upstream agent and skill, argument substitution, hook wiring, Claude input mapping, the synthetic transcript shape, argument forwarding, SessionStart source matchers, autocompact validity, precedence and threshold, trust-aware agent and skill discovery, config loading (trust gate, project env allowlist and values, malformed env, project hooks ignored, file guard), the bounded read itself, the GitHub style shell scan, gh flag extraction, rules and block-once gate (including hook order and the resend), skill file guard and untrusted-skill reasons, child trust flags (session directory, own worktrees, symlinks) and the shim trust env, the cost row's nested crediting, child event folding and nested-usage crediting, progress streaming and the model-facing result text, usage roll-up, byte-safe output cutting and the full-output note for model and view, the private session files (modes, no overwrite, path segments, failed saves, transcripts, cleanup), loading the extension with a fake pi (no process started at load, safety hints on all four tools, `ask_user` model-only), and the TUI renderers including tool-call formatting and terminal-escape sanitizing. The renderers were also drawn once by hand with pi's real theme; that check is not automated.
+- **Python tests** (`test/py`, 12 tests): sync helpers (description trimming, note insertion, idempotency) and the `claude` shim (flag translation, envelope, error path, trust forwarding in the child argv).
+- **End-to-end** (`test/e2e/run.mjs`, 28 scenarios). These run the real `pi` binary with an offline scripted provider in throwaway git repos, verified on pi 1.0.0 and 1.0.1:
+  - `/commands` with `$0`/`$ARGUMENTS`
+  - the plugin env in bash
+  - the `autocompact_setup_nudge` advisory, shown only while autocompact is unconfigured
+  - subagent usage on the tool result matching the children's usage
+  - project agents running by default with a trusted child, and with `--no-approve` package agents only and an untrusted child
+  - `--dev-team-agent` ignoring project agents under `--no-approve`
+  - the cost row crediting a nested dispatch to the agent that ran it
+  - project `.pi/dev-team.json`: an allowed tuning setting applied, `NODE_OPTIONS` and `DEV_TEAM_PY_CACHE` not, nothing under `--no-approve`; its `hooks` cannot switch the guards off
+  - `pre_tool_guard`, `destructive_guard`, freeze scope and `pre_pr_review` blocks
+  - PostToolUse advisories reaching the model
+  - single and parallel subagents
+  - the dispatch ledger and review-verdict ledger rows (pass/findings)
+  - worktree isolation, both kept and removed
+  - the `skill` tool and `ask_user` (non-interactive)
+  - cost rows split by agent type
+  - the `claude -p` shim
+  - coexistence with an extension registering `subagent`, in both load orders
+  - parent/child prompt mapping and dispatch depth limits
+  - an installed package whose guards also run inside subagent children alongside the other extension
+- **Interactive.** A tmux session in pi's TUI covered `/dev-team` status, `/plan` expansion, and an `ask_user` select dialog whose answer reaches the model.
+- **Not verified here.** Runs against real model providers. The sandbox had no provider credentials, so the first real Copilot run is the remaining check.

package/README.md

@@ -0,0 +1,207 @@
+# pi-dev-team
+
+pi-dev-team gives the [pi coding agent](https://pi.dev) a team of AI agents. The team writes a specification, makes a plan, builds the change with tests, reviews the code, and opens a pull request. You approve each important step.
+
+The package is a port of the dev-team plugin by Bryan Finster ([bdfinst/agentic-dev-team](https://github.com/bdfinst/agentic-dev-team)), which was written for Claude Code. It works with every model provider that pi supports, for example GitHub Copilot, Anthropic, and OpenAI.
+
+## Quick start
+
+The installation takes about 5 minutes if Node.js and Python are already on your computer.
+
+1. Install pi, if you do not have it: `npm install -g @earendil-works/pi-coding-agent`
+2. Install this package: `pi install git:github.com/sanjit-roopra/pi-dev-team`
+3. Go to a Git repository and start pi: `cd my-project && pi`
+4. In pi, log in to a model provider: `/login`
+5. Check the installation: `/dev-team doctor`
+6. Prepare the repository for the team: `/setup`
+7. Give the team its first task: `/specs add rate limiting to the public API`
+
+After step 5, each line of the report starts with `ok` or `MISSING`. If a line shows `MISSING`, install that tool (see [Requirements](#requirements)).
+
+## Requirements
+
+| Tool | Version | The team uses it to | If it is missing |
+|---|---|---|---|
+| [Node.js](https://nodejs.org) | 22.19 or later | Run pi | pi does not start. |
+| [pi](https://pi.dev) | 1.0 or later | Run the agents | The package does not load. |
+| Git | Any recent version | Track changes, make worktrees | Most commands do not work. |
+| Python | 3.10 or later | Run the guard hooks and scripts | The guards are off. pi shows a warning. |
+| [GitHub CLI](https://cli.github.com) (`gh`) | Any recent version | Open pull requests and read issues | `/pr` and `/ship` cannot open a pull request. |
+| `jq` | Any version | Run some quality gates | Those gates do not run. |
+
+A guard hook is a small script that runs before or after a tool call. It can stop an unsafe action, for example a pull request without a code review.
+
+## How the team works
+
+A normal change goes through four commands. Each command stops and asks you before it continues.
+
+| Command | What it does | What it leaves behind |
+|---|---|---|
+| `/specs <task>` | Asks you questions until the task is clear. Then it writes the intent, the architecture notes, and the acceptance criteria. | A spec file or a GitHub issue |
+| `/plan` | Splits the work into small steps. Each step has its own tests. | `plans/<task>.md` |
+| `/build` | Does the plan one step at a time. It writes a test, makes the test pass, and then cleans up the code. | Commits on your branch |
+| `/pr` | Runs the tests, the linter, and the code review. Then it opens a pull request. | A pull request |
+
+To do all four steps with one command, use `/ship <task>`. It stops at the same approval points.
+
+### Other commands
+
+- `/code-review`: About 25 review agents read your change at the same time. Each agent checks one topic, for example security, tests, or naming. Then the team can fix what they find.
+- `/triage <bug>`: Finds the root cause of a bug and writes a fix plan.
+- `/fix <bug>`: Does `/triage`, proves the bug, fixes it with tests, and opens a pull request.
+- `/continue`: Continues the work from your last session.
+- `/help`: Shows the main commands. `/help --all` shows all commands.
+
+## Choose the models
+
+Each agent has a tier. The tier tells the agent how strong a model it needs:
+
+| Tier | Used for |
+|---|---|
+| `opus` | Deep reviews and difficult design work |
+| `sonnet` | Most work |
+| `haiku` | Small, cheap checks |
+| `fable` | The strongest model. No agent uses this tier by default. |
+
+By default, every tier uses the model that you selected in pi. To use a different model for each tier, run `/dev-team models` and select a preset:
+
+- `github-copilot`: Uses the Claude models that GitHub Copilot gives you.
+- `anthropic`: Uses the Claude models from the Anthropic API.
+- `inherit`: Every agent uses your current model. This is the default.
+
+If you use GitHub Copilot, every agent uses AI credits for the tokens it sends and receives. A code review can start more than 20 agents, so a less expensive model for the lower tiers can reduce the cost a lot.
+
+## Safety and cost
+
+The agents can do the same things that you can do in a terminal.
+
+- They can read and change files in your repository.
+- They can run shell commands, for example your tests.
+- They can make many model calls. Up to 6 agents run at the same time by default.
+
+The guard hooks reduce the risk. For example, they stop `gh pr create` until a code review passes, and they keep the tests fixed while the team cleans up code. The guards need Python.
+
+To limit the work, set these values in `~/.pi/agent/dev-team.json`:
+
+```json
+{
+  "maxParallelAgents": 2,
+  "subagentTimeoutSec": 900
+}
+```
+
+To see what the team spends, run `/telemetry on`. Then run `/cost-report`. The numbers come from pi, so they are correct for every provider.
+
+pi's footer shows the cost of the whole session in USD, including the agents. If you use GitHub Copilot models, the status line also shows `GitHub Copilot: N AI credits` for the session, and the agent view shows the AI credits of each agent next to its USD cost. GitHub bills 1 AI credit for each $0.01 of token cost ([models and pricing](https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing)). The number is gross usage: it does not subtract your plan's monthly allowance. It includes the usage of context compaction and branch summaries, counted at the model in effect when they ran, since pi does not record which provider ran them.
+
+### See where the spend went
+
+Run `/dev-team usage` to open a chart of what your sessions spent. It counts every provider, for example GitHub Copilot, OpenAI and Anthropic, and also local models that cost nothing.
+
+- The header shows the total in USD. If GitHub Copilot served part of it, the header also shows the AI credits of that part.
+- **By model** ranks the models by USD, largest first, with the share of the total. Each model shows its provider, for example `openai/gpt-5.5`.
+- **By provider** ranks the providers by USD.
+- **By agent** ranks the dev-team agents that ran as subagents. An agent that ran on two providers has one row for each, for example `software-engineer · github-copilot`. The share is of the subagent total.
+- Each row shows USD, the AI credits (`cr`) when Copilot served it, and the share. If a row cost $0, for example a local model, the rows also show their tokens (`tok`). A $0 row has a share of 0%.
+- Above the chart, split bars show how the USD divides. The first bar shows the providers, when more than one has a cost. The second bar shows the threads: main `█`, subagents `▓` and overhead `▒`. A thread always has the same glyph, so the bars read without colour.
+
+| Term | Meaning |
+|---|---|
+| USD | pi's price for the tokens, from its model catalog. Every provider has it. |
+| AI credits | What GitHub Copilot counts for its share: 1 AI credit for each $0.01 of Copilot's USD. It is gross use, before your plan's monthly allowance. |
+| Tokens | The input, output and cache tokens of a run |
+| Main | The USD of your own conversation with pi |
+| Subagents | The USD of the dev-team agents that the team started, including the agents they started |
+| Overhead | The USD that pi spends outside a turn: cache warm-ups, context compaction, and branch summaries |
+
+For a ChatGPT or Claude plan, USD is pi's catalog price, not what the plan bills you.
+
+The chart shows **this session** (all branches) at first. Press `s` to see **this month** instead: every saved pi session of all your projects, from the 1st of the month at 00:00 UTC. That is also when GitHub's monthly period starts, so the month's AI credits match GitHub's period. pi reads the files when you press `s` and shows the progress. The header shows the time of that reading ("as of"). To refresh, close the chart and open it again. A session that was forked or cloned counts once.
+
+| Key | Action |
+|---|---|
+| `Tab`, `Shift+Tab` | Switch between By model, By provider and By agent |
+| `s` | Switch between this session and this month. While the month loads, `s` cancels the loading. |
+| `Esc`, `q`, `Ctrl+C` | Close |
+
+Letter keys work in either case: `S` and `Q` do the same as `s` and `q`.
+
+To start on a scope, run `/dev-team usage session` or `/dev-team usage month`. Without a terminal UI (`pi -p`, or an RPC client), the command prints a plain-text summary instead: the total, the same splits as the chart, and the models, providers and agents ranked with their USD, AI credits and share. The same argument selects the scope.
+
+The month counts the session files that pi keeps in `~/.pi/agent/sessions/<project>/`. It does not count the transcripts in nested `run-N/session.jsonl` files that other extensions keep in the same folder. If a file cannot be read, the chart shows how many files it could not read.
+
+## Pull request and issue text
+
+The team writes pull requests, issues and comments for a reader who skims. The rules come from [SimpleEnglish](https://github.com/AminBlg/SimpleEnglish) (plain English after ASD-STE100) and [i-have-adhd](https://github.com/ayghri/i-have-adhd) (the point first, short lists, one next step):
+
+- The title has 69 characters or fewer.
+- The first sentence of the body says what changes and why.
+- The visible body has 250 words or fewer (a comment has 150). Sentences have 25 words or fewer. Lists have 5 items or fewer.
+- The text has no em-dashes, bold, hedges (should, may, might) or filler (robust, seamlessly, leverage).
+- Long required content, for example the evidence bundle of `/pr`, goes at the end in one collapsed `<details>` block. Code, URLs, HTML comments, tables, headings and `<details>` blocks do not count toward the word limit.
+- Headings and markers that a skill needs, for example the sections of a `/specs` issue, stay as they are.
+
+Before a `gh pr` or `gh issue` command creates, edits or comments, the extension checks the title and the body. If the text breaks a rule, the extension blocks the command one time and tells the agent what to fix. If the agent sends the same command again, it runs. To only show the problems, set `"githubStyle": "warn"`. To turn off the check and the rules, set `"githubStyle": "off"`.
+
+The check reads text in quotes, in `$(cat <<EOF ...)` and in a `--body-file`. It does not check text that the shell makes when the command runs, for example `--body "$BODY"`, or a `gh` command that runs inside another program, for example `bash -c` or `xargs`.
+
+## Configuration
+
+The package reads three configuration files. A later file overrides an earlier file.
+
+1. `~/.pi/agent/dev-team.json`: Your settings for all projects
+2. `<project>/.pi/dev-team.json`: The settings for one project, shared in Git
+3. `<project>/.pi/dev-team.local.json`: Your own settings for one project, not in Git
+
+All settings, with the default values:
+
+```jsonc
+{
+  "models": { "opus": "inherit", "sonnet": "inherit", "haiku": "inherit", "fable": "inherit" },
+  "thinking": { "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max" }, // agent effort -> pi thinking level
+  "maxParallelAgents": 6,      // agents that run at the same time
+  "maxSubagentDepth": 2,       // agents can start other agents, 2 levels deep
+  "subagentTimeoutSec": 3600,  // stop an agent after this time
+  "autoFormat": false,         // format files after each edit (/setup turns this on)
+  "githubStyle": "block",      // block, warn, or off: the rules and the check for pull request and issue text
+  "skillIndex": "compact",     // compact, full, or off: the command list in the system prompt
+  "skillIndexChars": 220,      // the maximum length of each description in the compact list
+  "claudeShim": true,          // a `claude -p` call in the scripts runs pi instead
+  "env": {},                   // DEV_TEAM_* settings, for example "DEV_TEAM_MAX_PARALLEL_BUILDS": "2"
+  "hooks": { "enabled": true, "disabled": ["cost_meter", "..."], "enable": [], "outputToModel": true, "timeoutSec": 60 }
+}
+```
+
+Some hooks are off by default. A project file cannot change the `hooks` setting. Only your own file in `~/.pi/agent/` can change it. In a project file, `env` accepts only `DEV_TEAM_*` tuning settings. These rules stop a cloned repository from turning off your guards or from changing your `PATH`.
+
+To see which guard hooks are on, run `/dev-team hooks`.
+
+## Update
+
+To get the newest version, run:
+
+```bash
+pi update git:github.com/sanjit-roopra/pi-dev-team
+```
+
+To install the package for one project only, run `pi install -l git:github.com/sanjit-roopra/pi-dev-team` in that project. pi writes the package to `.pi/settings.json`.
+
+## Troubleshooting
+
+| What you see | Cause | What to do |
+|---|---|---|
+| `dev-team: python >= 3.10 not found — hook guards are disabled.` | pi cannot find Python 3.10 or later. | Install Python 3.10 or later. Then restart pi. |
+| `/dev-team doctor` shows `NO AUTH (/login)` | You are not logged in to the provider of that tier. | Run `/login`, or set that tier to `inherit`. |
+| `/dev-team doctor` shows `UNKNOWN MODEL` | pi does not know the model name of that tier. | Run `/dev-team models` and select a preset again. |
+| `gh pr create` is blocked | The review gate needs a passed code review first. | Run `/code-review`, or use `/pr`, which runs the review for you. |
+| An agent stops after one hour | The agent reached `subagentTimeoutSec`. | Make the task smaller, or increase the value. |
+
+## More information
+
+- [PORTING.md](PORTING.md): How the port works, what is different from the Claude Code plugin, and what is not ported
+- [CONTRIBUTING.md](CONTRIBUTING.md): How to run the tests and update to a new upstream version
+- `UPSTREAM.json`: The upstream version of this package (now dev-team v14.0.0)
+
+## License
+
+MIT. The upstream content is copyright Bryan Finster (see [LICENSE](LICENSE)). This package is an unofficial port. It is not part of Anthropic or the pi project.

package/UPSTREAM.json

@@ -0,0 +1,64 @@
+{
+  "repository": "https://github.com/bdfinst/agentic-dev-team",
+  "plugin": "dev-team",
+  "version": "14.0.0",
+  "commit": "2bf3d9852ca13999c9af4a83614935cc07f4503c",
+  "commitDate": "2026-09-30T20:49:31-05:00",
+  "droppedSkills": [
+    "agent-audit",
+    "agent-eval",
+    "claude-setup-review",
+    "harness-e2e-check",
+    "long-eval",
+    "orchestration-benchmark",
+    "session-review"
+  ],
+  "overridden": [
+    "agents/Explore.md",
+    "agents/general-purpose.md",
+    "skills/headless-run/SKILL.md",
+    "skills/upgrade/SKILL.md",
+    "skills/version/SKILL.md"
+  ],
+  "notes": [
+    "autoship",
+    "issues-from-assessment",
+    "issues-from-plan",
+    "mutation-night-watch",
+    "mutation-testing",
+    "pr",
+    "project-init",
+    "setup",
+    "specs"
+  ],
+  "normalisedFrontmatter": [
+    "skills/project-init/SKILL.md"
+  ],
+  "patches": [
+    {
+      "file": "skills/plan/SKILL.md",
+      "reason": "interactivity: tool shells have no TTY in pi",
+      "hits": 1
+    },
+    {
+      "file": "skills/build/SKILL.md",
+      "reason": "interactivity: tool shells have no TTY in pi",
+      "hits": 1
+    },
+    {
+      "file": "skills/review-agent/SKILL.md",
+      "reason": "agent definitions live in the package, not the project",
+      "hits": 1
+    },
+    {
+      "file": "skills/help/SKILL.md",
+      "reason": "skills live in the package root",
+      "hits": 1
+    },
+    {
+      "file": "skills/triage/SKILL.md",
+      "reason": "Claude's built-in Explore agent is provided by the port",
+      "hits": 1
+    }
+  ]
+}

package/agents/Explore.md

@@ -0,0 +1,15 @@
+---
+name: Explore
+description: Fast read-only codebase exploration agent (pi port of Claude Code's built-in Explore agent). Use to search broadly and return a compressed, factual summary with file:line references.
+tools: Read, Grep, Glob, Bash
+model: haiku
+---
+
+You are a read-only exploration agent. Investigate the codebase to answer the
+task you are given.
+
+- Never modify files. Bash is for read-only commands only (git log/show/diff,
+  ls, test runners in dry/list mode).
+- Search broadly first (grep/find), then read only the relevant sections.
+- Return a compressed, factual report: what you found, with `path:line`
+  references, and what you could not determine. No speculation presented as fact.

package/agents/a11y-review.md

@@ -0,0 +1,118 @@
+---
+
+name: a11y-review
+description: WCAG 2.1 AA compliance, semantic HTML, ARIA, keyboard navigation, focus management
+tools: Read, Grep, Glob, mcp__codegraph__*, mcp__plugin_repowise_repowise__get_context, mcp__plugin_repowise_repowise__get_symbol, mcp__plugin_repowise_repowise__search_codebase, mcp__plugin_repowise_repowise__get_risk
+model: haiku
+effort: medium
+color: green
+---
+
+# Accessibility Review
+
+Scope:
+- **/*.svelte
+- **/*.html
+- **/*.jsx
+- **/*.tsx
+- **/*.vue
+- **/*.razor
+- **/*.cshtml
+- **/*.jsp
+Cites: [adversarial-review-protocol]
+
+Scope: UI component and template files only (.svelte, .html, .jsx, .tsx, .vue, .razor, .cshtml, .jsp).
+Skip non-component files (utilities, services, stores, configs, tests, routes/pages without markup).
+
+Output JSON: per `${CLAUDE_PLUGIN_ROOT}/knowledge/review-agent-output-contract.md` (Whole-file load: short, canonical schema).
+
+Status: pass=accessible, warn=minor gaps, fail=WCAG AA violations
+Severity: error=blocks users, warning=degrades experience, suggestion=enhancement
+Confidence: high=mechanical fix (add missing attribute, swap element); medium=direction clear, implementation may vary; none=requires human judgment (design decisions, color palette)
+
+Context needs: full-file
+
+## Skip
+
+Return `{"status": "skip", "issues": [], "summary": "No UI component files found"}` when:
+
+- Target contains only logic files, configs, tests, or utilities
+- No .svelte, .html, .jsx, .tsx, .vue, .razor, .cshtml, or .jsp files with component markup present
+- Files are non-component modules (stores, services, helpers, route loaders)
+
+## Detect
+
+Semantic HTML:
+
+- div/span used where semantic element fits (nav, main, section, article, aside, header, footer)
+- Heading levels skipped (h1 to h3 without h2)
+- Lists of items not using ul/ol/li
+- Buttons implemented as clickable divs or spans
+
+ARIA attributes:
+
+- Interactive elements missing accessible names (aria-label, aria-labelledby, or visible text)
+- Redundant ARIA on elements with implicit roles (role="button" on button)
+- aria-hidden="true" on focusable elements
+- Missing aria-live for dynamic content updates
+
+Keyboard navigation:
+
+- Click handlers without corresponding keyboard handlers (onkeydown/onkeyup)
+- Custom interactive elements missing tabindex
+- Focus traps without escape mechanism
+- Missing visible focus indicators (outline:none without replacement)
+
+Color and contrast:
+
+- Text color with insufficient contrast against background (WCAG AA: 4.5:1 normal, 3:1 large)
+- Information conveyed by color alone without additional indicator
+- Disabled states with very low contrast
+
+Form accessibility:
+
+- Inputs missing associated labels (label element or aria-label)
+- Required fields without aria-required or required attribute
+- Error messages not associated with inputs (aria-describedby)
+- Form submission feedback not announced to screen readers
+
+Images and media:
+
+- Images missing alt attribute
+- Decorative images not marked with alt="" or aria-hidden="true"
+- SVG icons without accessible text
+
+Focus management:
+
+- Modal/dialog not trapping focus
+- Focus not returned after modal close
+- Dynamic content insertion without focus management
+- Route changes not announcing new content
+
+## Self-Challenge
+
+After producing findings, run the shared challenger loop in `${CLAUDE_PLUGIN_ROOT}/knowledge/adversarial-review-protocol.md` (Whole-file load: the slim shared methodology — The Loop + Output format — read in full), then work these a11y-review-specific challenges:
+
+- Did you examine every component/template file in scope, not just the most obviously interactive one?
+- For each contrast finding, did you cite the actual color values and the computed WCAG ratio rather than estimate "looks low"?
+- Did you check keyboard operability for EVERY custom interactive element (handler + focusability + visible focus), not just buttons?
+- Are there dynamic regions (live updates, route changes, modal open/close) with no announcement/focus-management finding — a suspicious absence?
+- For each "missing label" finding, did you verify there's no `aria-labelledby` or visible-text association before flagging?
+
+Append confidence level (High/Medium/Low) to the `summary` field.
+
+## Ignore
+
+Code style, naming, test coverage, performance (handled by other agents)
+
+**Anything the static-analysis pre-pass already reported (#1979).** When the
+run supplies pre-pass findings, honor their "do not re-report" framing — the
+`oxlint.jsx-a11y.*` rules cover a real slice of the `## Detect` list above
+mechanically: missing `alt` attributes, invalid anchor `href`s, click handlers
+with no keyboard equivalent, and static elements carrying handlers without a
+role. A violation already named in that table is settled. What remains yours
+is what a per-element linter cannot see: focus order and focus management
+across a flow, whether an accessible name is *meaningful* rather than merely
+present, live-region and announcement behavior, color and contrast decisions,
+and whether the whole interaction is operable by keyboard end to end. On a
+target with no oxlint lane, the mechanical checks are still yours too.