pi-dev-team 0.2.0

package/knowledge/value-patterns.md

@@ -0,0 +1,55 @@
+# Value Patterns (Test Data Sourcing)
+
+Reference file for the `test-design-advisor` skill and the `test-review` / `test-smell-review` agents. Where `fixture-construction.md` decides *how the fixture object is built* and `test-doubles.md` decides *what stands in for a collaborator*, this file decides the **scalar values** that go into them: the literals, computed values, and generated values a test feeds the SUT and asserts against. Choosing the wrong value source is a common, quiet cause of Obscure Test, Fragile Test, and Erratic Test.
+
+Source: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com) — Ch. 27 *Value Patterns*. Language- and framework-agnostic.
+
+Core principle: **every value in a test should reveal its intent.** A reader should see *why* a value is what it is — whether it's significant, derived from another value, or simply "some unique thing that doesn't matter." A magic literal whose meaning is lost is the Hard-Coded Values smell.
+
+---
+
+## The four value sources
+
+| Pattern | What it is | Use when | Risk if misused |
+|---------|-----------|----------|-----------------|
+| **Literal Value** | A constant written directly in the test (`42`, `"ACTIVE"`) | The exact value *is* the point — a boundary, a known-pathological case, a spec example | Unexplained → Hard-Coded Values smell; reused across tests → fragile coupling |
+| **Derived Value** | Computed in the test from other values via a visible expression | A value relates to another by a rule (`total = price * (1 + TAX_RATE)`); the relationship documents the requirement | Same math bug can hide in both test and SUT — pin a few cases with Literals |
+| **Generated Value** | Produced at run time (sequence, UUID, faker) | The value must be **unique** (DB keys, idempotency tokens) or genuinely **doesn't affect** the outcome | Random generation → Erratic/Nondeterministic Test; only generate when uniqueness is required |
+| **Dummy Object** | A do-nothing placeholder passed only to satisfy a signature | An argument is required by a method but **never used** on the path under test | If the SUT actually touches it, you need a Stub/Fake instead |
+
+---
+
+## Choosing a value source (decision flow)
+
+```
+Does the SUT's behavior depend on this specific value?
+├─ YES → is it computed from another value by a documented rule?
+│        ├─ YES → Derived Value (show the expression; name the constant, e.g. MAX_RETRIES)
+│        └─ NO  → Literal Value (name it for its meaning; it's a boundary or spec example)
+│
+└─ NO → is the value required to be unique (DB key, token, filename)?
+         ├─ YES → Generated Value — prefer a *Distinct* (sequence) generator over random
+         └─ NO  → is it an object only present to fill a parameter slot?
+                  ├─ YES → Dummy Object
+                  └─ NO  → a named Literal with an Intent-Revealing Name ("irrelevant" made explicit)
+```
+
+---
+
+## Notes that matter when evaluating tests
+
+- **Derived vs. Literal trade-off.** Derived Values make a requirement's *relationship* explicit and survive legitimate change (raise the tax rate, the test follows). But a shared arithmetic error can appear in both the test and the SUT — so cover a few pathological cases with hand-computed **Literal** Values as a cross-check.
+- **Distinct over Random.** A *Distinct Generated Value* (an incrementing sequence, reset per run) gives uniqueness **and** repeatability — the same values appear each run, so failures reproduce. A *Random Generated Value* trades reproducibility for coverage and usually creates an Erratic Test; if you must use one, log the seed/value on failure so the case can be replayed. Default to Distinct.
+- **Generate only for uniqueness.** Don't reach for a generator just to avoid choosing a number. Unnecessary generation introduces nondeterminism (different values can expose different bugs — single- vs. multi-digit formatting, etc.). Prefer a named Literal when the value doesn't need to be unique.
+- **Dummy ≠ Stub.** A Dummy is *never used*; if any method on it is called, the test should blow up (that's the signal you actually needed a Stub or Fake). Using a Dummy keeps Obscure Test away by stating "this argument is irrelevant" instead of constructing a real, distracting object. (Choosing between Dummy/Stub/Fake/Mock lives in `test-doubles.md`.)
+- **Anonymous vs. significant.** Make the *significant* values prominent and push *irrelevant* ones behind builder defaults or a clearly-named "anonymous" helper, so the cause-and-effect the test proves isn't buried in noise (`fixture-construction.md`).
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`test-smells.md`** — Hard-Coded Values, Irrelevant Information, Erratic Test (from random values) are the smells these patterns prevent or, misused, cause.
+- **`fixture-construction.md`** — Test Data Builders carry sensible defaults so only the *significant* values surface in a test; value patterns choose those values.
+- **`test-doubles.md`** — Dummy Object sits at the boundary between value patterns and doubles; the Stub/Fake/Mock decision is there.
+- **`result-verification.md`** — Derived Values are the basis of a *Derived Expectation*; Generated Values often pair with a *Delta Assertion* against a shared fixture.
+- **`test-automation-principles.md`** — *Communicate Intent* (no unexplained literals) and *Repeatable Test* (Distinct over Random) are the principles at stake.

package/knowledge/verification-mode.md

@@ -0,0 +1,116 @@
+# Verification-mode re-dispatch (#1628)
+
+The single definition of what a **fix-verification** re-dispatch sends and
+what it may cost. Referenced by [`skills/code-review/SKILL.md`](../skills/code-review/SKILL.md)
+step 6a and [`skills/build/SKILL.md`](../skills/build/SKILL.md)'s inline
+checkpoint loops — stated once here, never restated in either caller.
+
+## The problem
+
+When a fix loop re-dispatches an agent to confirm a fix, that dispatch is
+indistinguishable from discovery: same tier, same full context payload. But
+the task is far narrower — *here is the finding, here is the fix diff:
+resolved or not?* `correctness-review` (opus/`effort: high`, the most
+dispatched review agent in the project's logged history at 24) pays full
+discovery cost for every confirmation.
+
+`/code-review` step 6a's deterministic-first triage (#1610) already removes
+the mechanically-checkable confirmations. This contract cheapens the ones
+that genuinely need semantic judgment.
+
+## Stage 1 — context narrowing (no routing change)
+
+A verification re-dispatch passes **only**:
+
+1. The finding: its signature (#1625), original message, severity, and
+   confidence.
+2. The fix diff hunks, ± ~20 lines of surrounding context.
+3. The agent's own lens definition.
+
+It does **not** pass the full target file set. Token cost of a confirmation
+drops roughly with context size regardless of tier, and #1611/#1618 measured
+full-file payloads as the dominant input cost.
+
+**The `insufficient-context` escape is mandatory.** The dispatch prompt must
+state the narrowed contract explicitly and grant the agent this exit:
+
+> If the fix's correctness cannot be judged from this context, reply
+> `insufficient-context` — do not guess.
+
+An `insufficient-context` reply escalates to a **full-context re-dispatch of
+that same agent**, at its discovery tier. Narrowing must never become a quiet
+downgrade in review quality: an agent that says it cannot judge is answered
+with more context, not with a shrug. A verification-mode prompt that omits
+this escape is malformed.
+
+## Stage 2 — tier-down, declared per agent, never inferred
+
+An agent may opt in to a cheaper tier **for verification dispatches only** by
+declaring these in its **body** (not frontmatter — see below):
+
+```
+Verify-model: haiku
+Verify-effort: medium
+```
+
+**Default when absent: unchanged** — verification runs at the same tier as
+discovery. This default is deliberate, not conservatism for its own sake:
+#1619 showed some confirmations genuinely need top-tier judgment. The
+`Intl.NumberFormat.prototype.format` call — determining that a spec-bound
+getter does not lose its receiver when unbound, per ECMA-402 — was a
+verification-shaped question that a cheap tier would plausibly have gotten
+wrong, and getting it wrong would have shipped a fixture that didn't test
+what it claimed.
+
+Resolve the pair with the shared helper, never by reading frontmatter
+directly:
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/verify_tier.py" --agent <name>
+```
+
+It prints `{"agent", "model", "effort", "opted_in"}` — the tier to dispatch
+this agent at in verification mode, already falling back to the discovery
+tier when no opt-in is declared.
+
+### Why a body declaration, not frontmatter
+
+Issue #1333 established that this plugin's own tooling metadata lives in the
+agent **body**, because frontmatter is reserved for the official Claude Code
+sub-agent contract recorded in
+`plugins/marketplace-dev/knowledge/agent-contract.json` — a dated snapshot of
+upstream documentation, not a schema this plugin may extend. `Scope:`,
+`Cites:`, and `Enforcement:` all follow that rule; these two join them.
+(Claude Code silently ignores unknown frontmatter keys, so putting them in
+frontmatter would also have made a typo invisible.) See
+[`docs/agent_info.md`](../docs/agent_info.md) § Non-standard body
+declarations.
+
+### Initial opt-ins
+
+| Agent | Verify tier | Why |
+| --- | --- | --- |
+| `structure-review` | haiku | Confirming an extracted function or a flattened nesting level is a structural read, not a judgment call |
+| `naming-review` | haiku | Confirming a rename landed consistently is near-mechanical once the rename itself is applied |
+| `doc-review` | haiku | Confirming a doc line now matches the code it describes is a comparison, not an inference |
+
+`correctness-review` and `security-review` deliberately do **not** opt in.
+They are the two most expensive lenses and the two most obvious candidates —
+and that is exactly why the decision waits for #1624's per-agent
+discovery-vs-verification data to show their verification dispatches are
+low-yield. Tiering them down on intuition is the mistake this table exists to
+avoid.
+
+## Recording
+
+Every verification dispatch is recorded with `dispatch_purpose: "verification"`
+(#1624), so per-agent cost splits by purpose. The dispatch ledger still records
+it as a genuine dispatch of that agent (`subagent_type` unchanged), so gate
+corroboration semantics are untouched — a tiered-down verification dispatch
+corroborates the commit gate exactly as a discovery dispatch does.
+
+## Out of scope
+
+- Auto-inferring the tier from a finding's severity or confidence. Needs
+  #1624's data first.
+- Changing discovery-dispatch tiers. This contract governs verification only.

package/knowledge/virtual-service-libraries.md

@@ -0,0 +1,75 @@
+# Virtual-Service Libraries — Record-and-Replay Catalog
+
+Reference file for the `cd-test-architecture` skill's Downstream-service
+branch (`Build (Fake)` bullet — see `skills/cd-test-architecture/SKILL.md`).
+Catalogs the record-and-replay virtual-service library preferred for each
+profiled backend stack, with a hand-rolled Fake as backup. These are
+recommended starting points, not mandates: drop items that don't apply,
+add what a component clearly needs.
+
+## Preferred vs. backup
+
+A record-and-replay virtual-service library is the **preferred** pre-merge
+double for outbound HTTP; a hand-rolled Fake is the **backup** — used when
+the operator declines the library, or when no protocol-appropriate library
+exists for the component's adapter kind. See `skills/cd-test-architecture/SKILL.md`'s
+Downstream-service branch (`Build (Fake)` bullet) for the full
+accept/name-a-different-library/decline interaction — not restated here.
+
+## Catalog
+
+| Stack | Library | Protocol scope |
+|---|---|---|
+| `dotnet` | WireMock.Net | HTTP |
+| `node` | Nock | HTTP |
+| `spring-boot` | WireMock | HTTP |
+| `go` | `go-vcr` | HTTP |
+| `django` | VCR.py (`vcrpy`) | HTTP |
+
+All five catalog entries above are HTTP-focused. Message-broker
+virtualization for Event Consumer/Producer components has no equally
+mature per-stack tool — Mountebank is the closest general-purpose fallback — via its generic TCP
+protocol support, though it has no native AMQP/Kafka/MQTT protocol — and it
+is itself thinner coverage than the HTTP-focused tools above, not an
+equivalent substitute.
+
+## Resolution order
+
+Three-valued precedence for selecting the tool a `Build (Fake)` row
+recommends:
+
+1. **Existing tool detected** — the target repo already depends on (or
+   already uses in its tests) a virtual-service/record-replay library.
+   That tool becomes the default; no switch is suggested.
+2. **Catalog default** — when no existing tool is detected, the stack's
+   entry from the table above.
+3. **Operator override or decline** — the operator names a different
+   library (used instead of 1 or 2), or declines (hand-rolled Fake, the
+   backup).
+
+## Recorded artifacts contain real traffic — scrub before commit
+
+A recorded cassette or stub mapping (VCR.py/go-vcr cassettes, Nock recorder
+output, WireMock/WireMock.Net stub mappings) captures a real
+request/response exchange — including `Authorization`/`Cookie` headers, API
+keys, and PII in the body — and, by design, gets committed to version
+control alongside the test. Treat every recorded artifact as potentially
+secret-bearing until reviewed, per `knowledge/deployment-pipeline.md`'s
+**Secrets are not in version control** rule (Configuration management
+table) — a recorded artifact heading into version control is exactly the
+case that rule guards against; it just arrives via a test tool instead of a
+config file.
+
+Configure each tool's credential-filtering hook **before the first
+recording** — not after:
+
+| Tool | Filtering hook |
+|---|---|
+| VCR.py (`vcrpy`) | `filter_headers` / `filter_query_parameters` / `before_record_response` |
+| go-vcr | its before-save hook |
+| Nock | no built-in filter — manually redact the recorder's output before committing |
+| WireMock / WireMock.Net | response transformers / body-capture limits |
+
+Record against a non-prod instance of the dependency, using non-prod
+credentials — scrubbing after the fact is a second line of defense, not the
+first.

package/knowledge/wave-consolidation-guidance.md

@@ -0,0 +1,21 @@
+# Wave / Review-Agent Fan-Out Consolidation
+
+Soft guidance for keeping a single review wave's agent count within a coordination budget. Advisory only — it never blocks dispatch and adds no new gate.
+
+## When it applies
+
+When a single wave's agent-selection would dispatch **5 or more** review agents in one wave — whether the Inline Review Checkpoint dispatch table in `${CLAUDE_PLUGIN_ROOT}/knowledge/three-phase-workflow.md#inline-review-checkpoint` or Step 2 of `agents/quality-reviewer.md` selected them — note it in the phase/review output as a coordination-cost signal, not a hard block. Each agent already returns a small structured result, so the context-pollution risk is mitigated; what remains unmeasured is the coordination cost of aggregating many independent verdicts and driving one fix loop across potentially-overlapping finding sets.
+
+## Why five
+
+Martin Fowler's ["The Orchestrator's Tax"](https://martinfowler.com/articles/orchestrator-tax.html) recommends 2–4 concurrent agents per wave as a default and consolidating rather than scaling past ~5. `DEV_TEAM_MAX_PARALLEL_BUILDS` already bounds *hardware* concurrency (`min(16, cores-2)`, `scripts/build_jobs.py`); this guideline adds the missing *cognitive*/coordination ceiling. A single commit touching JS/TS + tests + API surface + domain logic + UI routinely selects 7–8 agents (`naming-review`, `js-fp-review`, `test-review`, `security-review`, `domain-review`, `a11y-review`, `structure-review`, `component-architecture-review`) — well past the budget.
+
+## What to do
+
+- **Surface, don't block.** Emit a one-line note in the phase/review output — e.g. `wave fan-out: 8 agents selected (>5 coordination-cost threshold)`. Dispatch proceeds unchanged.
+- **Batch high-overlap agents.** Where two agents' scopes already overlap on the same lines, run them as a single combined pass instead of two. `structure-review` (baseline, every change) and `naming-review` frequently flag the same lines — `structure-review` already absorbed its other high-overlap case (`complexity-review`'s nesting and function-size charter, folded in #2093). Combining an overlapping pass cuts verdict-aggregation and fix-loop overhead without losing coverage.
+- **Prefer the higher-altitude rollup.** Strategic and test-design requests already consolidate into a `qa-engineer` / `/test-design` rollup rather than firing many per-file agents (see `agents/orchestrator.md` § Test-review request routing). Apply the same instinct wherever a rollup skill already exists.
+
+## What this is not
+
+Not a gate. It changes no dispatch behavior, blocks nothing, and adds no new metric or hook. It is a documented instinct for the orchestrator and quality-reviewer to weigh coordination cost when a wave's agent count is high — the cognitive analogue of the hardware ceiling `DEV_TEAM_MAX_PARALLEL_BUILDS` already provides.

package/overrides/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/overrides/agents/general-purpose.md

@@ -0,0 +1,10 @@
+---
+name: general-purpose
+description: General-purpose agent with the full tool set (pi port of Claude Code's built-in general-purpose agent). Use for multi-step research or implementation tasks that no specialist agent covers.
+tools: Read, Grep, Glob, Bash, Edit, Write
+---
+
+You are a general-purpose engineering agent working on a delegated task.
+Complete the task end to end, verify your work (run the relevant tests or
+commands), and finish with a concise report of what you did, what changed
+(`path:line`), and anything left open.

package/overrides/notes/autoship.md

@@ -0,0 +1,6 @@
+## pi port notes (read first)
+
+- Run each unit's `/ship` in an isolated child so `DEV_TEAM_AUTO_APPROVE=1` and its cost stay scoped to that unit: use the `headless-run` skill (`DEV_TEAM_AUTO_APPROVE=1 pi --mode json -p --no-session "/ship ..."`) rather than invoking `/ship` in this conversation.
+- `$CLAUDE_SESSION_ID` is set by the pi extension to the pi session id.
+- The GitHub MCP fallback (`mcp__github__*`) only exists if the user configured a GitHub MCP server in `.pi/mcp.json`; otherwise `gh` is required.
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.

package/overrides/notes/issues-from-assessment.md

@@ -0,0 +1,3 @@
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.

package/overrides/notes/issues-from-plan.md

@@ -0,0 +1,3 @@
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.

package/overrides/notes/mutation-night-watch.md

@@ -0,0 +1,3 @@
+## pi port notes
+
+- Where this skill schedules or runs `claude --print`, use `pi --mode json -p --no-session` (or the port's `claude` shim, which is on `PATH` inside pi sessions but not in cron). In a cron entry call `pi` directly.

package/overrides/notes/mutation-testing.md

@@ -0,0 +1,3 @@
+## pi port notes
+
+- Scripts in this skill that shell out to `claude --print` / `claude -p` run through the pi port's `claude` CLI shim (on `PATH` inside pi), which executes `pi --mode json -p --no-session` and returns a Claude-style result envelope. `CLAUDE_BIN` / `CLAUDE_CLI` may point at it explicitly.

package/overrides/notes/pr.md

@@ -0,0 +1,7 @@
+## pi port notes (read first)
+
+- Write the title and body in the "GitHub text style" from the system prompt. The extension blocks a `gh pr create` whose title or body breaks it, once.
+- Body order: one sentence that says what changes and why, then `## Summary` (at most 3 bullets), then `## Test Plan`, then `## Quality Gate` with its results on one line (`Tests 42 passed · types clean · lint clean · review clean`).
+- Put `## Decisions & Assumptions` and the four Evidence Bundle headers at the end, inside one `<details><summary>Decisions and evidence</summary>` block. Keep all of their content. Only the place changes.
+- If the repository has `.github/PULL_REQUEST_TEMPLATE.md`, its sections come first and the same `<details>` block goes at the end.
+- End the visible part with one next step for the reviewer, for example "Review: start at `src/auth.ts:42`."

package/overrides/notes/project-init.md

@@ -0,0 +1,6 @@
+## pi port notes (read first — these override the steps below)
+
+- **MCP servers (Step 4c):** pi reads project MCP servers from `.pi/mcp.json` (user level: `~/.pi/agent/mcp.json`), not `.mcp.json`. Register CodeGraph/Repowise there, or with `pi mcp add -l <name> -- <command>`. Tell the user to run `/reload`.
+- **Settings/hook guards (Step 4c, #1367):** there is no `.claude/settings.json` hook registration in pi; the settings.json guard reports `n/a (pi)`.
+- **`CLAUDE.md` guard around `graphify install`:** apply the same guard to `AGENTS.md`.
+- The `claude` CLI is not required; ignore checks for it.

package/overrides/notes/setup.md

@@ -0,0 +1,13 @@
+## pi port notes (read first — these override the steps below)
+
+This is the pi port of `/setup`. Follow the steps below with these substitutions:
+
+- **Hard dependencies (Step 3):** the `claude` CLI is not required. `pi`, `python3`, `jq`, `git` and `gh` are.
+- **Step 4:** run the `project-init` skill with the `skill` tool (`dev-team:project-init` and `project-init` are the same).
+- **Step 7 (agent templates):** activate templates into `.claude/agents/` exactly as written. The pi `dev_team_subagent` tool loads project agents from `.pi/agents/` and `.claude/agents/`, and they take precedence over the package agents.
+- **Step 8 / 8a (project CLAUDE.md):** pi loads context files from the project root and its ancestors (`AGENTS.md`, or `CLAUDE.md`), **not** from `.claude/CLAUDE.md`. Everywhere these steps say `.claude/CLAUDE.md`, use `AGENTS.md` at the repository root instead (if the repo already has a root `CLAUDE.md` and no `AGENTS.md`, use that `CLAUDE.md`). Same merge/skip and marker rules.
+- **Step 9 (formatting hook):** do not write `.claude/settings.json`. Instead set `"autoFormat": true` in `.pi/dev-team.json` (create the file if missing, keep other keys). The pi extension then runs `hooks/post_format.py` (prettier / ruff / black, auto-detected) after every `write`/`edit`.
+- **Step 9b (autocompact):** run `scripts/set_autocompact_env.py` exactly as written. It only merges `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` into `.claude/settings.json` (the one write to that file this port allows); the pi extension reads that value and compacts the session at that percentage of the model's window. pi's own threshold is `contextWindow - reserveTokens`, so the "values above ~83% have no effect" caveat becomes "values above pi's own threshold have no effect".
+- **Step 10 (/pr):** write the generated project command to `.claude/skills/pr/SKILL.md` as written. The pi port resolves project skills in `.pi/skills/` and `.claude/skills/` before the package's own.
+- **Step 11:** also add `.pi/dev-team.local.json` to the `.gitignore` block.
+- **Step 12 (report):** list `AGENTS.md` and `.pi/dev-team.json` instead of `.claude/CLAUDE.md`, and list `.claude/settings.json` only for the Step 9b `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` key. Add a line recommending `/dev-team models` to map the opus/sonnet/haiku agent tiers to this user's models.

package/overrides/notes/specs.md

@@ -0,0 +1,3 @@
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.

package/overrides/skills/headless-run/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: headless-run
+description: >-
+  Run a dev-team skill or prompt headlessly in an isolated pi subprocess
+  (fresh session, JSON result, timeout). Use for scripted one-shot invocations
+  and benchmark-harness cases, e.g. running /code-review once per case.
+argument-hint: "<prompt-or-slash-command> [--cwd DIR] [--model MODEL] [--timeout SECS]"
+user-invocable: true
+allowed-tools: Read, Bash
+---
+
+# Headless Run
+
+Role: worker. Runs one prompt in a separate, non-interactive pi process and
+returns its JSON result. It does not review, plan or edit by itself.
+
+Arguments: `$ARGUMENTS`
+
+## Isolation
+
+- New process, `--no-session` (nothing is written to the session store and the
+  parent's session id is not reused).
+- Non-interactive: `DEV_TEAM_INTERACTIVE` is unset, so every human gate takes
+  its documented non-interactive default.
+- Same packages and credentials as the parent (pi's auth store is read from
+  `~/.pi/agent`), so the run uses the same providers.
+
+## Steps
+
+1. Parse `--cwd` (default: current directory), `--model` (default: the
+   current `PI_PROVIDER/PI_MODEL`), `--timeout` (default 1800 seconds). The rest
+   is the prompt. A leading `/name` is a dev-team command; pass it through
+   unchanged, pi expands it in the child.
+2. Run:
+
+   ```bash
+   cd "<cwd>" && timeout <secs> env -u DEV_TEAM_INTERACTIVE \
+     pi --mode json -p --no-session --model "<model>" "<prompt>" > "$TMPDIR/headless-run-$$.jsonl"
+   ```
+
+3. Extract the result: the last `agent_end` event's final assistant text, its
+   `stopReason`, and the summed `usage` of all `message_end` assistant events.
+   Print one JSON object:
+   `{"is_error": <bool>, "result": "<text>", "stop_reason": "...", "usage": {...}, "total_cost_usd": <n>, "log": "<path>"}`.
+   Exit status 124 from `timeout` → `is_error: true, "result": "timeout"`.

package/overrides/skills/upgrade/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: upgrade
+description: >-
+  Check for and apply pi-dev-team package updates using pi's package manager.
+user-invocable: true
+allowed-tools: Read, Bash
+---
+
+# Upgrade
+
+Role: worker. Updates the pi-dev-team package through pi's own package
+mechanism. Never hand-edit installed package files.
+
+You have been invoked with the `/upgrade` command. Arguments: none.
+
+## Steps
+
+1. Report the current version: run the `/version` command's script
+   (`${CLAUDE_PLUGIN_ROOT}/package.json` and `UPSTREAM.json`).
+2. Find how the package is installed: `pi list` (look for `pi-dev-team`).
+   - **git or npm source** → run `pi update` (add `--local` if it is listed under
+     project settings). Report the version delta afterwards.
+   - **local path** (e.g. `./pi-dev-team`) → pi does not update local packages.
+     Tell the user to pull the package directory (`git -C <path> pull`) or, when
+     it is a sync of upstream, to run
+     `python3 <path>/sync/sync_upstream.py --upstream <agentic-dev-team checkout>`.
+3. Tell the user to run `/reload` (or restart pi) so the new extension code,
+   skills and agents load.
+
+**Be concise.** Report version deltas only.

package/overrides/skills/version/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: version
+description: >-
+  Report the installed version of the pi-dev-team package and the upstream
+  dev-team release it was synced from.
+user-invocable: true
+allowed-tools: Bash
+---
+
+# Version
+
+Role: worker. Purely mechanical lookup.
+
+You have been invoked with the `/version` command. Arguments: none.
+
+Run and report the single output line verbatim:
+
+```bash
+node -e 'const p=require(process.env.CLAUDE_PLUGIN_ROOT+"/package.json");const u=require(process.env.CLAUDE_PLUGIN_ROOT+"/UPSTREAM.json");console.log(`${p.name} v${p.version} (upstream dev-team v${u.version} @ ${String(u.commit).slice(0,10)})`)'
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unset, report exactly:
+`pi-dev-team extension is not loaded in this session.`
+
+Do not add commentary beyond the single result line.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pi-dev-team",
+  "version": "0.2.0",
+  "description": "pi port of Bryan Finster's dev-team (bdfinst/agentic-dev-team): persona-driven dev team, reviewer swarm, TDD-gated /specs -> /plan -> /build -> /pr workflow, guard hooks. Works with any pi model provider, including GitHub Copilot.",
+  "license": "MIT",
+  "author": "Sanjit Roopra (https://github.com/sanjit-roopra)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanjit-roopra/pi-dev-team.git"
+  },
+  "homepage": "https://github.com/sanjit-roopra/pi-dev-team#readme",
+  "bugs": {
+    "url": "https://github.com/sanjit-roopra/pi-dev-team/issues"
+  },
+  "keywords": ["pi-package", "agents", "code-review", "tdd", "dev-team"],
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions/dev-team/index.ts"],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "sync": "python3 sync/sync_upstream.py --upstream ../agentic-dev-team",
+    "test": "node --test test/unit/*.test.ts && python3 -m unittest discover -s test/py -p 'test_*.py'",
+    "e2e": "node test/e2e/run.mjs"
+  },
+  "files": ["extensions", "agents", "skills", "hooks", "scripts", "knowledge", "templates", "tools", "bin", "docs", "sync", "overrides", "UPSTREAM.json", "PORTING.md", "README.md", "LICENSE"]
+}

package/scripts/authoring_digest.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Build a per-diff authoring digest for the software-engineer (prototype).
+
+Each review lens may carry a ``## Authoring checklist`` section: terse,
+write-time reflexes distilled from its ``Detect`` rules. Given the files a step
+will touch, this resolves the applicable lenses with ``select_lenses`` (same
+``Scope:`` rules ``/build`` already uses) and prints only those lenses'
+checklists, so the engineer pays tokens only for lenses that can fire.
+
+The lens files stay the single source of truth; nothing is copied by hand.
+
+Lenses deliberately WITHOUT a checklist (#2208 triage) — each needs a reviewer's
+independence or whole-change view, not a write-time reflex: ``arch-review`` and
+``domain-review`` (cross-module/ADR/boundary judgement), ``spec-compliance-review``
+(verifies against the step's scenarios, which ``/build`` already hands the
+engineer), ``doc-review`` (whole-repo drift), and the on-demand repo-wide lenses.
+Framework lenses (React/Vue/Angular/a11y) are excluded by scope for other diffs.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+import select_lenses
+
+HEADING = "## Authoring checklist"
+_H2_RE = re.compile(r"^## ")
+
+
+def extract_checklist(text: str) -> list[str]:
+    """Bullet lines under the ``## Authoring checklist`` heading, else ``[]``."""
+    bullets: list[str] = []
+    active = False
+    for line in text.splitlines():
+        if line.startswith(HEADING):
+            active = True
+            continue
+        if active and _H2_RE.match(line):
+            break
+        if active and line.lstrip().startswith("- "):
+            bullets.append(line.rstrip())
+    return bullets
+
+
+def build_digest(files, agents_dir: Path, registry: Path):
+    """Return ``(digest_text, lenses_with_checklist, warnings)``."""
+    roster, warnings = select_lenses.build_review_roster(agents_dir, registry)
+    lenses, more = select_lenses.applicable_lenses(
+        list(files), roster, test_files=select_lenses.test_file_subset(list(files))
+    )
+    warnings = warnings + more
+    sections: list[str] = []
+    used: list[str] = []
+    for name in lenses:
+        try:
+            text = (agents_dir / f"{name}.md").read_text(encoding="utf-8")
+        except OSError:
+            warnings.append(f"unreadable-agent:{name}")
+            continue
+        bullets = extract_checklist(text)
+        if bullets:
+            used.append(name)
+            sections.append(f"### {name}\n" + "\n".join(bullets))
+    if not sections:
+        return "", used, warnings
+    return "## Authoring checklist (write-time)\n\n" + "\n\n".join(sections) + "\n", used, warnings
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--files", nargs="*", default=[], help="Files the step will touch")
+    p.add_argument("--agents-dir", type=Path, default=_HERE.parent / "agents")
+    p.add_argument(
+        "--registry", type=Path, default=_HERE.parent / "knowledge" / "agent-registry.md"
+    )
+    args = p.parse_args(argv)
+    digest, _used, warnings = build_digest(args.files, args.agents_dir, args.registry)
+    for w in warnings:
+        print(f"warning: {w}", file=sys.stderr)
+    sys.stdout.write(digest)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())