pi-dev-team 0.2.0

package/knowledge/testability-patterns.md

@@ -0,0 +1,240 @@
+# Testability Design Patterns
+
+Reference file for test-review and structure-review agents. When flagging untestable code, use the patterns below to specify the required **production code change** — not a test workaround. Tests never hack around untestable designs; the design must change.
+
+Core principle: if code can't be tested through its public API, the production code's design must change. Per Seemann: "The hallmark of a testable design is that it's also a good design."
+
+---
+
+## "I Can't Test This Class" Decision Flow
+
+```
+Can I construct the object with the values I need for the test?
+│
+├─ YES → Write the test using the public constructor.
+│
+├─ NO: it has private-set properties with no public constructor
+│   └─ Add a constructor that accepts values directly.
+│      For 5+ parameters: apply Test Data Builder (Pattern 2).
+│
+├─ NO: it only has a static factory that calls a real database/service
+│   └─ Add a constructor alongside the factory.
+│      The factory uses the constructor internally.
+│
+├─ NO: the method I need to verify is protected/private
+│   └─ Extract the logic into a public method or invoke through the
+│      public behavior that calls it.
+│
+└─ NO: it depends on a concrete class I can't replace
+    └─ Extract an interface for what this class needs.
+       Mock the interface in tests, wire the concrete in production.
+
+Each NO branch requires a production code change. That IS the work.
+```
+
+> **Legacy code (no tests yet)?** Don't make the design change cold. First get the code under characterization tests using a *behavior-preserving* seam from [`dependency-breaking-techniques.md`](dependency-breaking-techniques.md), guided by effect/pinch reasoning in [`legacy-test-strategy.md`](legacy-test-strategy.md) — then refactor toward the target patterns below. The patterns here are the destination; those techniques are how you get there safely.
+
+---
+
+## Pattern 1: Constructor Injection (Replace Static Factories / Singletons)
+
+**Problem**: A class creates its own dependencies internally — `new ConcreteService()`, `ServiceLocator.get(T)`, static calls. The production code can't be given test doubles.
+
+**Solution**: Accept collaborators as constructor parameters. Static factories and singletons remain for production wiring; they delegate to the constructor internally.
+
+```
+// BEFORE — untestable
+class OrderProcessor:
+  def process(orderId):
+    db = Database.getInstance()     // static singleton
+    logger = new FileLogger()       // new-ed up
+    ...
+
+// AFTER — injectable
+class OrderProcessor:
+  constructor(db: IDatabase, logger: ILogger):
+    self.db = db
+    self.logger = logger
+
+  def process(orderId):
+    ...
+```
+
+**When to apply**: class instantiates its own collaborators; class has no constructor that accepts its dependencies; production code works but tests can't isolate the unit.
+
+---
+
+## Pattern 2: Test Data Builder
+
+**Problem**: Domain objects with many properties are painful to construct in every test. Most tests only care about 1-2 properties.
+
+**Solution**: A builder in the test project with sensible defaults and a fluent API.
+
+```
+// Builder lives in the test project
+class OrderBuilder:
+  customerId = "TEST-CUST"
+  amount = 100
+  status = "pending"
+
+  withCustomer(id): self.customerId = id; return self
+  withAmount(amt): self.amount = amt; return self
+  withStatus(s): self.status = s; return self
+  build(): return Order(customerId, amount, status)
+
+// In tests — only set what the test cares about
+order = new OrderBuilder().withStatus("cancelled").build()
+```
+
+**When to apply**: domain object has 5+ properties; multiple tests need variants of the same object; default values work for most tests.
+
+---
+
+## Pattern 3: Interface Extraction for Large Contexts
+
+**Problem**: Classes depend on a large context object with many properties. Mocking the full context is impractical and fragile.
+
+**Solution**: Extract an interface for what each consumer actually needs.
+
+```
+// BEFORE — consumer takes the whole context
+class FileProcessor:
+  constructor(context: ProcessingContext)  // 40-field object
+
+// AFTER — consumer takes only what it needs
+interface IFileProcessorContext:
+  tempFilePath(): string
+  isReprocess: bool
+  fileNames: List<string>
+
+class FileProcessor:
+  constructor(context: IFileProcessorContext)
+```
+
+The full context class implements this interface. Tests mock only the interface.
+
+**When to apply**: context has 30+ properties but any given consumer uses 5-10; creating a full context for each test is excessive.
+
+---
+
+## Pattern 4: Fake Data Generators (Test Data with Variation)
+
+**Problem**: Tests need realistic but controlled test data across many scenarios.
+
+**Solution**: A typed faker or factory in the test project that generates valid domain values.
+
+```
+// Instead of magic literals
+order = new Order(customerId="ABC123", amount=150.00, ...)
+
+// Use a generator that makes intent clear
+order = OrderFaker.pending()
+order = OrderFaker.withAmount(5000)
+orders = OrderFaker.generateBatch(100)
+```
+
+**When to apply**: tests need multiple records with varied data; domain validation rules constrain acceptable values; tests should not use unexplained magic numbers.
+
+---
+
+## The Design-for-Testability seam family
+
+Constructor Injection (Pattern 1) is the common case, but it is one of a named family of seams from *xUnit Test Patterns* Ch. 26. Pick by *how* the dependency reaches the SUT and *why* it's hard to test.
+
+| Seam | The change | Use when | Cost |
+| ------ | ----------- | ---------- | ------ |
+| **Dependency Injection** (Pattern 1) | Pass collaborators in (constructor/setter) | You control construction and can thread the dependency through | Low; the default |
+| **Dependency Lookup** | SUT asks a broker/service-locator for the collaborator; the test configures the broker | The DOC is buried deep and threading it through every caller would be messy (e.g. a Fake DB behind a service facade) | Medium; hides the dependency, but far easier to **retrofit onto legacy** code than DI |
+| **Humble Object** | Extract logic out of a hard-to-instantiate shell into a plain, synchronously-testable object | Logic is trapped in a UI control, framework callback, thread, or transaction boundary | Medium; the shell becomes a thin adapter |
+| **Test Hook** | Conditional `if (testing)` behavior baked into production code | **Last resort only** — nothing else can break the dependency | High; it *is* the Test Logic in Production smell |
+
+---
+
+## Pattern 5: Dependency Lookup (retrofit seam for legacy)
+
+**Problem**: A collaborator is constructed deep inside the system and there's no clean path to pass a test double down from the test — wiring DI through every intermediate layer would be invasive.
+
+**Solution**: The SUT requests its collaborator from a **component broker / service locator** instead of `new`-ing it. The test (or a Setup Decorator) configures the broker to hand back a double.
+
+```
+// Production wiring registers the real implementation
+ServiceRegistry.register(IClock, SystemClock)
+
+// SUT looks up rather than receiving
+class ExpiryService:
+  def isExpired(token):
+    clock = ServiceRegistry.get(IClock)   // broker, not `new`
+    ...
+
+// Test reconfigures the broker, no constructor threading needed
+ServiceRegistry.register(IClock, FakeClock(at="2026-01-01"))
+```
+
+**When to apply**: retrofitting tests onto legacy code where DI would touch too many call sites; a deep DOC (data-access layer, facade-backed service) you want to replace with a Fake for a whole test run. **Trade-off**: the dependency is no longer visible in the signature, and the broker is global state that each test must reset — keep DI the default and reach for lookup when threading is genuinely impractical.
+
+---
+
+## Pattern 6: Humble Object (rescue logic from untestable shells)
+
+**Problem**: Meaningful logic lives inside an object that's expensive or impossible to instantiate in a unit test — a GUI control, a framework callback, an async worker/thread, a transaction-managing controller. The asynchronicity or framework coupling forces slow, nondeterministic tests, so the logic ends up untested.
+
+**Solution**: Extract **all** the logic into a separate, plain object that's testable through synchronous calls. The original shell becomes a *humble* adapter that holds no logic — it just forwards framework calls to the testable object. The shell is so thin it needs no tests of its own.
+
+```
+// BEFORE — logic trapped in a UI/framework/thread shell
+class OrderView(FrameworkWidget):
+  def onSubmit():           // framework-invoked, hard to test
+    ...validation + pricing + state transitions...
+
+// AFTER — Humble shell + testable presenter
+class OrderPresenter:       // plain object, fully unit-testable
+  def submit(input) -> ViewModel: ...the real logic...
+
+class OrderView(FrameworkWidget):
+  def onSubmit():           // humble: no logic, just delegation
+    self.render(self.presenter.submit(self.readInput()))
+```
+
+Named variations: **Humble Dialog** (UI logic → presenter), **Humble Executable** (logic out of a thread/active object), **Humble Transaction Controller** (the business method takes no responsibility for begin/commit, so a test can wrap it in a transaction and roll back — the prerequisite for Transaction Rollback Teardown in `database-test-patterns.md`).
+
+**When to apply**: nontrivial logic in any component that's problematic to instantiate because it depends on a framework, a UI toolkit, a thread, or a transaction. This is the production-code answer to the *Minimize Untestable Code* principle.
+
+---
+
+## Pattern 7: Test Hook (last resort — prefer any seam above)
+
+**Problem**: None of the above seams can be introduced (e.g. a closed dependency that can't be injected, looked up, or subclassed), yet the code must be brought under test.
+
+**Solution**: A conditional in production code that alters behavior under test. **This is deliberately listed last because it *is* the Test Logic in Production smell** (`test-smells.md`): the tested path no longer equals the shipped path, and the hook can fail in production. Use only when no structural seam is possible, isolate the hook tightly, and treat its removal (by refactoring to a real seam) as outstanding debt.
+
+```
+// AVOID unless nothing else works — and plan to delete it
+def charge(amount):
+  if TEST_MODE: return FakeGatewayResult.ok()   // test logic in production
+  return realGateway.charge(amount)
+```
+
+Prefer, in order: Dependency Injection → Dependency Lookup → Test-Specific Subclass (override the seam method in a test subclass; see `test-doubles.md`) → Humble Object. A Test Hook is an admission that the design resisted all of them.
+
+---
+
+## Anti-Patterns Table
+
+| Anti-Pattern | Why It's Wrong | Correct Alternative |
+| --- | --- | --- |
+| `InternalsVisibleTo` + `internal set` for tests | Weakens encapsulation for test convenience | Add a public constructor that accepts values |
+| Reflection into private members as primary strategy — Java: `getDeclaredMethod`/`getDeclaredField` + `setAccessible(true)`, `Method.invoke` on a private/protected member; C#: `Type.GetMethod(..., BindingFlags.NonPublic \| BindingFlags.Instance)`, `Type.InvokeMember`; Python: `getattr`/`setattr`/`hasattr` on a name-mangled (`_ClassName__attr`) or underscore-prefixed attribute; JS/TS: bracket-notation into a `private`/non-exported member, or `Object.getOwnPropertyDescriptor`/`Object.defineProperty` to reach one | Fragile; breaks on rename; masks coupling — this is an architecture/encapsulation issue the test is reaching around, not a test-hygiene nit | Pick by shape of the code: extract the logic into a collaborator with its own public seam; relax visibility to package-private/internal only when a production collaborator in the same module/assembly independently needs it — never as a grant solely so the test can reach in (that recreates the `InternalsVisibleTo`/`@VisibleForTesting` rows above); or test the behavior through the existing public API (if already reachable) |
+| Static test helper that mutates private state | Bypasses object invariants | Use Test Data Builder with public construction |
+| Mocking concrete classes | Fragile; requires virtual/open methods; masks design issues | Extract interface; mock the interface |
+| Tests configuring global/static state | Shared state causes order-dependent failures | Inject dependencies through constructors |
+| Changing `private set` to `public set` for test access | Removes invariant protection | Add constructor parameter instead |
+| `[InternalsVisibleTo]` / `@VisibleForTesting` as the primary testability mechanism | Couples test and production assemblies | Redesign the API surface so tests don't need access to internals |
+
+---
+
+## References
+
+- Michael Feathers, *Working Effectively with Legacy Code* — seam insertion, Parameterize Constructor, Extract Interface
+- Mark Seemann & Steven van Deursen, *Dependency Injection: Principles, Practices, and Patterns* — Pure DI, Composition Root
+- Steve Freeman & Nat Pryce, *Growing Object-Oriented Software, Guided by Tests* — outside-in TDD, mock-roles-not-objects
+- Vladimir Khorikov, *Unit Testing: Principles, Practices, and Patterns* — resilient vs. fragile tests

package/knowledge/testing-quadrants.md

@@ -0,0 +1,44 @@
+# Agile Testing Quadrants
+
+Reference file for the `test-health` skill (project-wide audit) and `test-design-advisor`. The quadrants are a *coverage-completeness* lens — they answer "what **kind** of testing is missing?", orthogonal to `test-pyramid.md`'s "what **layer**?". Use them to find blind spots an all-unit suite can't see.
+
+Source: Brian Marick's testing matrix, popularized by Lisa Crispin & Janet Gregory, *Agile Testing* / *More Agile Testing*. Language- and stack-agnostic.
+
+Two axes: **business-facing ↔ technology-facing** (what the test speaks to) and **supporting the team ↔ critiquing the product** (does it guide building, or probe the finished thing).
+
+---
+
+## The Four Quadrants
+
+| Q | Facing × Stance | Tests | Mode |
+|---|-----------------|-------|------|
+| **Q1** | technology · support | unit, component, integration | automated |
+| **Q2** | business · support | functional / acceptance, story tests, BDD examples, prototypes | automated + manual |
+| **Q3** | business · critique | exploratory, usability, UAT, alpha/beta | manual |
+| **Q4** | technology · critique | performance, load, security, resilience, the "-ilities" | tool-driven |
+
+Q1+Q2 **guide development** (write them first — they're specifications). Q3+Q4 **probe the built product** for what specifications miss.
+
+---
+
+## Reading coverage against the quadrants
+
+For each quadrant, classify the suite as **strong / thin / empty**, then name the business impact of a gap:
+
+| Quadrant weak/empty | What slips through | How to strengthen |
+|---------------------|--------------------|-------------------|
+| **Q1 thin** | logic/wiring regressions | push checks down the pyramid (`test-pyramid.md`) |
+| **Q2 empty** | "built the wrong thing" — no shared definition of done | add acceptance/BDD examples before coding (see the `specs` skill) |
+| **Q3 empty** | bugs only a human notices: confusing flows, broken edge journeys | charter exploratory sessions (`exploratory-testing-field-guide.md`) |
+| **Q4 empty** | non-functional failures in prod: slow, insecure, falls over under load | add perf/security/resilience checks; route to `security-review`, `performance-review` |
+
+---
+
+## Anti-pattern: "Q3 as the gate"
+
+Leaning on manual exploratory/UAT (Q3) as the *primary* safety net — instead of Q1/Q2 automation — is the quadrant form of the ice-cream cone (`test-pyramid.md`). Exploratory testing **finds new** problems; it must not be the regression net. If Q3 is the only thing catching regressions, the fix is more Q1/Q2, not more manual testing.
+
+## Boundaries
+
+- A suite need not fill every quadrant equally — weight by risk. A pure library leans Q1/Q4; a user-facing app needs Q2/Q3. Flag *empty* quadrants where the product's risk clearly demands coverage, not arithmetic imbalance.
+- This file classifies; it does not score. Quantitative suite scoring stays in `farley-score`.

package/knowledge/testing-techniques/approval.md

@@ -0,0 +1,15 @@
+# Approval testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior produces a large or structured **text artifact** — rendered HTML/Markdown, JSON/CSV export, generated code, a report, a log — and asserting field-by-field would be unreadable.
+
+**What it is.** Capture the output once, have a human approve it as the *approved* (golden) file; the test then diffs current output against approved. A change surfaces as a diff to re-approve, not a rewritten assertion.
+
+**When to use.** Output is wide, stable, and a diff is more legible than N equality asserts. Excellent for characterizing legacy output before refactoring.
+
+**Trade-offs / cost.** Approved files must be reviewed on every intended change — rubber-stamping defeats the test. Non-deterministic fields (timestamps, ids, ordering) must be scrubbed/normalized first or the test flaps. Store approved files in VCS.
+
+**Minimal shape.** `approve("invoice-html", renderInvoice(order))` → first run writes `invoice-html.approved`; later runs diff against it.
+
+**Complements.** A verification *style* at unit/component/integration — not a new pyramid layer. For **visual/CSS** fidelity use `screenshot.md` instead; for **text** correctness, approval is cheaper. Tools: ApprovalTests, Verify, jest snapshots (treat snapshots as approval — review them).

package/knowledge/testing-techniques/chaos.md

@@ -0,0 +1,17 @@
+# Chaos / resilience testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior makes a **resilience claim under dependency failure** — "retries on a 5xx", "degrades gracefully when the cache is down", "the circuit breaker opens", "recovers after the broker reconnects". The risk is in the *failure* path, which happy-path tests never exercise.
+
+**What it is.** Deliberately inject failure — latency, errors, dropped connections, killed dependencies — and assert the system's degradation/recovery behavior matches the claim.
+
+**When to use.** Distributed systems, anything with retries/timeouts/circuit-breakers/fallbacks, jobs that must survive a mid-run dependency outage.
+
+**Scope split (important).** Inject failure at the **owned adapter** in a component test to verify retry/fallback *logic* deterministically (pre-merge). Reserve infrastructure-level chaos (kill a pod, partition the network) for **out-of-band/staging** — it is non-deterministic and never belongs in the pre-merge gate (`cd-test-architecture.md`).
+
+**Trade-offs / cost.** Infra chaos is flaky and slow; needs a controlled environment and observability to read results. Start with adapter-level fault injection — most resilience bugs surface there cheaply.
+
+**Minimal shape.** Stub the payment adapter to throw `Timeout` twice then succeed → assert two retries then success.
+
+**Complements.** Component (adapter fault injection) and out-of-band (infra). Q4 in `testing-quadrants.md`. Tools: Toxiproxy, fault-injecting test doubles, Chaos Monkey / Litmus (infra).

package/knowledge/testing-techniques/fuzz.md

@@ -0,0 +1,15 @@
+# Fuzz testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior **parses or accepts untrusted/unstructured input** — a file/format parser, protocol decoder, deserializer, public API request body, anything at a trust boundary where malformed input is an attack surface.
+
+**What it is.** Feed large volumes of malformed, random, or mutated input and assert the code **never crashes, hangs, or corrupts state** — it either handles or cleanly rejects. Coverage-guided fuzzers mutate toward new code paths.
+
+**When to use.** Input parsers, decoders, file/upload handling, anything reachable by an attacker. The goal is robustness, not a specific output.
+
+**Trade-offs / cost.** Findings are crashes/hangs, not "wrong answer" — pair with example/property tests for correctness. Needs a sanitizer or crash oracle to be useful; can be slow; corpus and seeds need maintenance.
+
+**Minimal shape.** `fuzz(parseConfig)` runs mutated byte strings; any unhandled exception / OOM / timeout is a failure.
+
+**Complements.** Sits at unit/integration on the parser; security-adjacent — cross-reference `security-review` for the trust-boundary finding. For *valid* inputs obeying a law, use `property-based.md`; for *declared schema* conformance, see `schema-validation.md`. Tools: libFuzzer/AFL, jazzer (Java), Atheris (Python), go-fuzz.

package/knowledge/testing-techniques/property-based.md

@@ -0,0 +1,15 @@
+# Property-based testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior has an **invariant that holds for all inputs** — a roundtrip (`decode(encode(x)) == x`), a mathematical law (commutativity, idempotency, sum-preservation), an ordering/closure property — rather than a handful of known example pairs.
+
+**What it is.** Instead of fixed examples, declare a property and a generator; the framework generates hundreds of random inputs, and on failure **shrinks** to the minimal counterexample.
+
+**When to use.** Parsers/serializers, encoders, money/quantity math, sorting/merging, state machines, anything with an algebraic law. Pairs well with a few example tests for documentation.
+
+**Trade-offs / cost.** Finding the right property is the hard part — a weak property passes vacuously. Generators for complex domain types take effort. Slower than example tests; seed failures so they reproduce.
+
+**Minimal shape.** `forAll(integers, integers, (a,b) => add(a,b) === add(b,a))`.
+
+**Complements.** A unit/integration *technique*, not a layer — apply it at the layer where the invariant lives. Tools: fast-check (JS), Hypothesis (Python), jqwik (Java), FsCheck (.NET). For *malformed/hostile* inputs rather than law-checking, see `fuzz.md`.

package/knowledge/testing-techniques/schema-validation.md

@@ -0,0 +1,15 @@
+# Schema-validation testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior produces or consumes a payload governed by a **declared schema** — an OpenAPI/Swagger spec, JSON Schema, Avro/Protobuf, a GraphQL type. The risk is the payload **drifting from its own declared shape**.
+
+**What it is.** Assert that real request/response payloads validate against the schema artifact — and, in reverse, that the schema matches what the code emits. The schema becomes an executable spec, not just documentation.
+
+**When to use.** Public/partner APIs with a published spec, event payloads on a shared bus, config files with a schema, codegen boundaries. Catches "docs say one thing, code does another" before consumers do.
+
+**Trade-offs / cost.** Validates *shape*, not *meaning* — a semantically wrong-but-well-formed payload still passes (cover that with unit/contract tests). The schema must be kept authoritative or the check rots.
+
+**Minimal shape.** `expect(validate(openapi.paths['/orders'].post.response, actualBody)).toPass()`.
+
+**Complements.** Integration/component on the boundary. **Not a substitute for contract testing** between two owned services — for consumer↔provider agreement route to `microservice-testing.md` (CDC). Schema-validation checks conformance to a *declared* schema; CDC checks two parties still *agree*. Cross-reference `security-review` for input-validation at trust boundaries. Tools: ajv, openapi-validator, Spectral, schemathesis.

package/knowledge/testing-techniques/screenshot.md

@@ -0,0 +1,15 @@
+# Screenshot / visual-regression testing
+
+Overlay technique for `test-design-advisor`. Loaded only when the trigger matches.
+
+**Trigger.** A behavior's correctness is **visual** — CSS layout, theming, charts/canvas, print/PDF rendering, responsive breakpoints — where the right markup can still *look* wrong and a DOM/text assertion can't catch it.
+
+**What it is.** Render the component/page, capture an image, and diff it against an approved baseline image (approval testing for pixels). A visual change surfaces as an image diff to re-approve.
+
+**When to use.** Design-system components, layout-critical pages, anything where appearance is the requirement. Pin a few representative states, not every page.
+
+**Trade-offs / cost.** The most maintenance-heavy technique: baselines drift across OS/browser/font-rendering → false diffs. Mitigate with a consistent render environment (containerized/CI runner), tolerance thresholds, and masking dynamic regions. Baselines live in VCS and need review on every intended change.
+
+**Minimal shape.** `await expect(page).toHaveScreenshot('cart-badge.png')`.
+
+**Complements.** Component/E2E layer. Decision: **text/markup** correctness → `approval.md` (cheaper, stabler); **CSS/visual** fidelity → screenshot. Often the visual half of a Gate D / Gate C behavior (`test-layer-gates.md`). Tools: Playwright/Percy/Chromatic/Storybook test-runner, BackstopJS.

package/knowledge/three-phase-workflow.md

@@ -0,0 +1,198 @@
+# Three-Phase Workflow
+
+The orchestrator's phase reference, loaded on demand. `agents/orchestrator.md`
+§ Three-Phase Workflow carries the always-on part — the phase list, each phase's
+goal and human gate, and the invariants that hold across all three. Everything
+below is the detail a session needs *once it is actually running a phase*: the
+persona rosters to dispatch, the conditional dispatch rules, the review
+checkpoints, and the wave mechanics. Read the section for the phase you are in
+via its anchor, not the whole file.
+
+Notes on what `scripts/orchestrator.py` — the `Enforcement: script` deterministic
+implementation — actually does, and where it diverges from the policy below, live
+in `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md`. They are needed when running or working on that script, not
+when following the policy interactively.
+
+Every non-trivial task follows three explicit phases. Each phase runs in minimal context, and a human review gate separates each phase. The output of each phase is a structured progress file written to `.claude/memory/` that onboards the next phase.
+
+## Phase 1: Research
+
+- **Goal**: Understand how the system works, identify all relevant files, locate the problem or feature surface area
+- **Agents**: `codebase-recon` (gated on RECON artifact freshness — see Codebase Recon dispatch below), `architect`, `data-flow-tracer` (always dispatched — see the Research persona roster in `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-1-research`), `security-engineer` (conditional — see Security Engineer dispatch), plus the Orchestrator itself and further sub-agents for exploration as needed (context isolation — sub-agents search, read, and return concise findings so the parent context stays clean)
+- **Output**: A research progress file with file paths, line numbers, data flows, and key findings
+- **Design doc**: For non-trivial features (see Design Doc skill for criteria), produce a design document at `docs/specs/{feature-name}.md` with problem statement, proposed approach, alternatives, key decisions, and scope boundaries. The human approves the design doc as part of the research gate.
+- **Human gate**: Human reviews the research findings and design doc before planning begins. Catching a misunderstanding here prevents hundreds of bad lines of code downstream.
+- **Context**: Compact after this phase — write progress file, start fresh context for Phase 2
+
+Script behavior and known gaps: `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-1-research`.
+
+### Codebase Recon dispatch
+
+Dispatch `codebase-recon` as a sub-agent **before any other exploration**,
+at the start of Research, when no `.claude/memory/recon-<slug>.json`
+artifact exists, or the existing one is more than 24 hours old (`<slug>` is
+the repo basename) — skip the dispatch (silently) when a fresh artifact is
+present. It returns entry points, dependency graph, security surface, and
+git history in a structured artifact (`.claude/memory/recon-<slug>.json` /
+`.claude/memory/recon-<slug>.md`, checked for freshness against the `.json`
+half since that's the machine-readable artifact other agents consume)
+intended to onboard the Architect and Security Engineer without those
+agents needing to re-read the codebase themselves.
+
+Script behavior and known gaps: `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-1-research`.
+
+### Security Engineer dispatch
+
+Dispatch `security-engineer` during Research when any of these signals is
+present: the task touches authentication, authorization, cryptography,
+session management, or secrets handling; it introduces a new external
+integration or API surface; or the user explicitly asks to "threat model
+this", "design this securely", or "what's the attack surface here" (these
+three match `agents/security-engineer.md`'s own dispatch description) — or a
+recent `/code-review` run's `security-review` produced a `fail` verdict with
+high-severity findings on this area (orchestrator-owned: only the
+orchestrator sees `/code-review` history). Its `effort: high` cost is only
+justified on security-relevant work, so this dispatch stays conditional
+rather than unconditional.
+
+Script behavior and known gaps: `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-1-research`.
+
+## Phase 2: Plan
+
+- **Goal**: Specify every change to be made — files, snippets, test strategy, verification steps
+- **Agents**: `product-manager`, `architect`, `qa-engineer` (core trio that drafts the plan — always dispatched, see the Plan persona roster in `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-2-plan`), then the `plan-review-*` critics reviewing that draft (below)
+- **Input**: Research progress file from Phase 1 + approved design doc (if produced in Phase 1)
+- **Output**: An implementation plan with explicit file changes, test expectations, and acceptance criteria
+- **Automated plan review**: Before the human gate, dispatch the plan review
+  personas in parallel as sub-agents — `plan-review-acceptance`,
+  `plan-review-design`, `plan-review-ux`, `plan-review-strategic`,
+  `plan-review-parallelization`. Each is a registered agent
+  (`agents/plan-review-<name>.md`); dispatch by `subagent_type` like any
+  other agent — the harness reads its `model:`/`effort:` frontmatter
+  natively, no dispatch-time override needed. The reviewer set scales to
+  plan tier and complexity; see the plan skill's
+  [Run plan review personas step](../skills/plan/SKILL.md#5-run-plan-review-personas)
+  for the tier classification (that table is the single source of truth —
+  do not re-duplicate the reviewer set here, it drifts).
+
+  Each returns a `verdict` of `approve` or `needs-revision`. If **any**
+  dispatched reviewer returns `needs-revision`, address the blocker issues
+  before presenting to the human. Aggregate all findings (including
+  warnings from approving reviewers) into the plan review summary.
+- **Human gate**: Human reviews the plan and the aggregated review findings. This is the primary review artifact — 200 lines of plan is far more reviewable than 2,000 lines of code. If the plan is wrong, fix it here, not in code.
+- **Design intent: no choice made during Implementation is meant to compensate for a weak plan.** A plan carrying an unresolved `needs-revision` verdict (a blocker, or 3+ warnings — 2+ for `plan-review-parallelization` — per `${CLAUDE_PLUGIN_ROOT}/knowledge/plan-review-rubric.md#verdict-rules`) is revised and re-reviewed before the human gate — see the plan skill's [Run plan review personas step](../skills/plan/SKILL.md#5-run-plan-review-personas) for that iteration cap and its escalation path — and never carried silently into Phase 3. Code-First Small Batches (Phase 3's sole cadence, per ADR 0017) is not a substitute for plan quality, it is what a *good* plan gets executed with. When a plan looks weak going into the human gate, the fix is another Phase 2 iteration, never a Phase 3 workaround. See `${CLAUDE_PLUGIN_ROOT}/knowledge/test-cadence-tradeoffs.md#the-decision-rule` for the evidence bar an alternative Phase 3 cadence has to clear before it changes this.
+- **Context**: Compact after this phase — write progress file, start fresh context for Phase 3
+
+Script behavior and known gaps: `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-2-plan`.
+
+## Phase 3: Implement
+
+- **Goal**: Execute the plan. Write code, run tests, verify at each step.
+- **Agents**: Software Engineer (primary), QA Engineer (validation), others as needed
+- **Input**: Plan progress file from Phase 2
+- **Subagent dispatch**: Dispatch the `software-engineer` agent by `subagent_type` when dispatching implementation subagents, scoped to a single plan step — the harness reads its `model:`/`effort:` frontmatter natively, no dispatch-time override needed. For parallel implementation of independent units, prefer `isolation: "worktree"` on the Agent tool to give each subagent its own git worktree. Disjoint *final* file sets are not sufficient justification to skip it: two parallel subagents sharing one working directory can still observe each other's mid-edit, intermediate state — a shared production file transiting a broken half-edited form at the exact moment a sibling's own test run reads it — even when neither subagent's final diff ever touches the other's files (#1609). If worktree isolation is skipped for a given dispatch because its per-agent cost (~200-500ms + disk) isn't justified for that unit of work, treat any test failure one parallel subagent reports while siblings are still running as provisional: re-verify it once every parallel subagent in that batch has completed before treating it as a real regression, not a timing artifact. **Never instruct a dispatched parallel worker to dispatch its own review agent.** A subagent that calls the Agent tool itself does not receive that call's completion notification the way the top-level session does — notifications for a subagent's own dispatched children route to the top-level session instead, so a worker that dispatches a review and then stops to wait for it stalls indefinitely (#1881). This applies to any fan-out of independent units, not only the wave mechanism documented in § Wave-aware build dispatch: each parallel worker fixes/implements, tests, commits, and pushes only; review is dispatched once, from the top level, after every worker in the batch has finished — never once per worker. (This is why the Three-stage inline review below is described as something the orchestrator runs after each unit completes, not something a software-engineer subagent runs on itself.)
+- **Cadence enforcement**: The Software Engineer follows the single per-behavior cadence for every unit — Code-First Small Batches (IMPLEMENT → TEST → REFACTOR), per `docs/experiments/RECOMMENDATIONS.md` Rec 3. The orchestrator verifies that each unit's output includes the cadence's verification evidence: green full-suite output. Defect fixes are the one exception — they follow `systematic-debugging`'s mandatory Phase 4 gate, which requires a failing test that reproduces the bug before any fix code is written.
+- **Output**: Working code that passes all tests, acceptance criteria, and code review
+- **Three-stage inline review**: After each discrete unit of work completes, run the deterministic static self-heal pass to pass-or-cap (`skills/build/references/static-self-heal.md`), then spec-compliance, then quality, then browser verification for UI changes:
+  1. **Stage 1 — Spec compliance**: Dispatch the `spec-reviewer` agent by `subagent_type`. Does the code match the spec? If fail → fix before proceeding to Stage 2. (This is a distinct, narrower per-step check than the `spec-compliance-review` agent used as the first gate before the final `/code-review` — see § Inline review checkpoint below and `${CLAUDE_PLUGIN_ROOT}/knowledge/agent-registry.md#review-agents` for how the two differ.)
+  2. **Stage 2 — Code quality**: Dispatch the `quality-reviewer` agent by `subagent_type` to run the standard **Inline Review Checkpoint** (see below). Is the code high quality?
+  3. **Stage 3 — Browser verification (UI changes only)**: If the plan step involves UI components, run `/browse` in automated smoke test mode against the running dev server. Capture screenshots, verify rendering, and check basic interaction. If the dev server is not running, skip with a warning (do not fail). Timeout: 30 seconds. Failures enter the review loop (max 2 iterations). This stage is skipped for non-UI changes.
+- **Final verify**: After all units complete and tests pass, run `/code-review` on all modified files:
+  - `fail` → Software Engineer addresses critical issues, re-run review
+  - `warn` → include findings in human gate summary
+  - `pass` → proceed to doc review
+- **Doc review**: Before the human gate, invoke `dev-team:tech-writer` to review all documentation affected by the changes:
+  - Any behavioral or architectural change → check `docs/agent-architecture.md`, `README.md`
+  - Any configuration or tooling change → check `docs/agent-architecture.md` (Governance section)
+  - Any agent or skill change → check `CLAUDE.md`, `docs/agent_info.md`, `docs/team-structure.md`; regenerate `docs/skills.md` (generated — `hooks/lib/build_skills_index.py`)
+  - Tech-writer updates outdated sections and confirms all docs reflect current behavior before proceeding
+- **Human gate**: Human reviews the final output. If the plan was good, implementation review is lightweight.
+- **Context**: If implementation is large, compact mid-phase — update the plan progress file with completed steps and continue in a fresh context
+
+Script behavior and known gaps: `${CLAUDE_PLUGIN_ROOT}/knowledge/orchestrator-script-implementation.md#phase-3-implement`.
+
+### Wave-aware build dispatch
+
+During `/build`, the orchestrator executes the plan **wave by wave** (the plan's `## Parallelization` schedule from `scripts/plan_waves.py`):
+
+1. **Resolve** the wave schedule (`build_wave.py`) and the effective concurrency (`build_jobs.py` → `min(--jobs, DEV_TEAM_MAX_PARALLEL_BUILDS, wave width)`).
+2. **Dispatch** each independent slice in the wave to its own git worktree (`isolation: "worktree"`) up to that concurrency — each runs its full per-behavior cycle (Code-First Small Batches) + inline review in isolation.
+3. **Barrier + reconcile** (`build_wave_reconcile.py`): order-independently merge the wave's slice branches, gate on the full suite, and only then start the next wave. A failing slice or a reconcile conflict halts loudly (names the offender, preserves succeeded worktrees, prints the resume command) and starts no next-wave slice.
+
+Effective concurrency 1 (fully-dependent plan, `--jobs 1`, or `DEV_TEAM_MAX_PARALLEL_BUILDS=1`) degrades to sequential single-worktree build with no fan-out or reconcile.
+
+> Read a slice's status during a wave only from its structured result, never from a live transcript read into this orchestrating context — see `docs/agent-architecture.md` → Subagent status checks.
+
+**`worktree.baseRef` prerequisite (issue #553).** Worktree fan-out only works when Claude Code's `worktree.baseRef` setting is `"head"` — otherwise each subagent worktree branches from `origin/<default>` and cannot see the caller's uncommitted-to-remote spec, plan, or prior-wave commits. Users must set this in **`.claude/settings.json`** (project scope) or **`~/.claude/settings.json`** (user scope); plugin-scope `plugins/<name>/settings.json` and project-local `.claude/settings.local.json` are **not** honored by 2.1.198's worktree isolation. `/build`'s Step 4 detect-and-warn surfaces the requirement loudly on every invocation until the user sets it (or opts out with `DEV_TEAM_WORKTREE_BASE_FRESH=1`). Full audit trail: `docs/spikes/worktree-baseref-head-spike.md`.
+
+### Review depth by complexity
+
+Each plan step includes a **Complexity** classification that controls review depth:
+
+| Complexity | Inline review behavior | Granularity |
+|------------|----------------------|-------------|
+| `trivial` | Skip inline review entirely. The final `/code-review` covers all files. | — |
+| `standard` | Run spec-compliance + quality agents relevant to the change type (see table below). | **Batched at the slice boundary** — one pass over the slice's accumulated `standard`/`trivial` changes once all its steps are green, not per step. |
+| `complex` | Run spec-compliance + full quality suite including high-effort agents (security-review, domain-review, arch-review). | **Per step** — smaller blast radius per fix. |
+
+If a step has no complexity annotation, default to `standard`.
+
+Each checkpoint that runs records a find/fix/no-op outcome to `.claude/metrics/review-value.jsonl` (#348) so the review overhead is measurable and the tiering can be evidence-based.
+
+### Inline review checkpoint
+
+After each discrete unit of work classified as **standard** or **complex** (a function, a module, a feature slice — as defined in the Phase 2 plan):
+
+**Step 1 — Select agents by what changed:**
+
+| Changed | Agents to run |
+|---|---|
+| JS/TS functions | naming-review, js-fp-review |
+| Test files | test-review |
+| API surface / auth | security-review |
+| Domain/business logic | domain-review |
+| UI components | a11y-review, structure-review, component-architecture-review |
+| Agent or command files | eval-compliance-check hook runs automatically; also run /agent-audit |
+| Dockerfile or .dockerignore | docker-image-audit skill |
+| Documentation files (.md) | doc-review |
+| Architecture/dependency changes | arch-review |
+| All changes | structure-review as a baseline |
+| All changes (before quality review) | spec-compliance-review as first gate |
+
+**Step 2 — Run selected agents in parallel** using the Agent tool by `subagent_type` — the harness reads each agent's `model:`/`effort:` frontmatter natively per `agents/orchestrator.md` § Model/Effort Resolution.
+
+When the selection above would dispatch 5+ agents in one wave, note the coordination-cost signal and consider batching high-overlap lenses per `${CLAUDE_PLUGIN_ROOT}/knowledge/wave-consolidation-guidance.md#when-it-applies` — advisory only; dispatch still proceeds.
+
+**Step 3 — Aggregate findings and apply Review Loop:**
+
+- `pass` / `warn` → log findings in phase output, continue
+- `fail` → enter the **Review Loop** below
+
+### Review loop
+
+When any checkpoint agent returns `fail`:
+
+1. Classify issues by actionability (same criteria as `/code-review` step 5):
+   - **Actionable**: severity `error` or `warning` with confidence `high` or `medium`
+   - **Human-required**: confidence `none` — log and skip, do not attempt auto-fix
+2. For actionable issues, apply the minimal fix directly:
+   - Apply file-by-file, top-to-bottom by line number
+   - Run tests after each batch of fixes — revert and mark as human-required if tests break
+3. Re-run only the agents that reported actionable issues.
+4. Repeat up to **5 iterations** total (matching `/code-review` loop behavior).
+5. **Exit conditions**:
+   - Zero actionable issues remain → continue to next plan step
+   - Same issues persist after fix attempt → not converging, escalate
+   - Iteration limit reached (5) → escalate to human with:
+     - The original findings
+     - All fix attempts
+     - Remaining issues and recommended resolution path
+6. `warn` after any iteration is acceptable; document in phase output and continue.
+
+## Phase transitions
+
+1. Complete the current phase's work
+2. Write a structured progress file to `.claude/memory/` (see Context Summarization skill)
+3. Human reviews and approves before proceeding
+4. Start new context window for the next phase
+5. Load only the progress file + agents needed for the new phase