pi-dev-team 0.2.0

package/docs/upstream/README.md

@@ -0,0 +1,155 @@
+# dev-team
+
+A Claude Code plugin that adds a full persona-driven AI development team to any project. The Orchestrator routes tasks to specialized agents, inline review checkpoints catch quality issues during implementation, and skills provide reusable knowledge modules that any agent can draw on.
+
+For the workflow overview, team philosophy, and three-phase (Research → Plan → Implement) process, see the [repository README](../../README.md).
+
+## Install
+
+Three commands total: register the marketplace, install the plugin, then run `/setup` in your project. That's the whole flow.
+
+**Prerequisite:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), installed and authenticated. Nothing else needs to be installed by hand — `/setup` installs the tools your stack needs.
+
+### Install
+
+Register the marketplace, then install the plugin. The marketplace is named **`bfinster`** (the `name` field in `marketplace.json`); the plugin is **`dev-team`**. `claude plugin marketplace add` accepts a GitHub `owner/repo`, any git URL, or a local path; `claude plugin install` takes `<plugin>@<marketplace>`.
+
+**From GitHub (recommended):**
+
+```bash
+claude plugin marketplace add bdfinst/agentic-dev-team
+claude plugin install dev-team@bfinster
+```
+
+The `owner/repo` shorthand and the full `https://github.com/bdfinst/agentic-dev-team` URL are equivalent.
+
+### Set up your project
+
+Open Claude Code in your project and run one command:
+
+```
+/setup
+```
+
+`/setup` detects your stack, shows you a plan, and — once you confirm it — installs everything the team needs and writes project config. You do not pre-install anything:
+
+- **Tool dependencies** — `jq` and `python3` (used by the hooks and gates), and for a recognized stack, the stack's linters, formatters, type checkers, test runner, and per-language mutation testing (Stryker for JS/TS, pitest for Java/Kotlin, Stryker.NET for C#).
+- **Capability tools, each installed only when its signal fires** — `gh` when the repo has a GitHub remote (used by `/pr` and `/issues-from-plan`), `semgrep` for static analysis, Playwright + Chromium for `/browse`, the docker scanners (`hadolint`/`trivy`/`grype`) when a Dockerfile is present, and ADR tooling when the repo already keeps ADRs.
+- **Optional code-intelligence indexes** — CodeGraph, Repowise, and Graphify, offered as keyless opt-ins for faster code navigation.
+- **Project config** — a project-level `CLAUDE.md`, the auto-format PostToolUse hook, language-specific agent templates, a generated `/pr` command, and `.gitignore` entries for the workflow's runtime artifacts.
+
+Recognized stacks are **JS/TS, Python, C#, and Java**. On a stack that isn't recognized, `/setup` installs the language-neutral pieces and tells you plainly what it could not set up — it never guesses at a toolchain.
+
+For an unattended run (CI, scripted onboarding), pass `--yes` to accept the detected plan without the confirmation prompt: `/setup --yes`. Add `--dry-run` to report what it would install and configure without writing anything.
+
+After `/setup`, you're ready to work: run `/specs` to start a feature, or just describe a task and let the Orchestrator route it. To confirm the team is live, see [Verify](#verify).
+
+<details>
+<summary><b>Manual / offline install of individual tools</b></summary>
+
+`/setup` installs all of these for you. This section is a reference for air-gapped machines, an unsupported stack, or installing a single tool by hand.
+
+**Hard dependencies** (any stack): `jq` (`brew install jq` / `apt install jq`) and `python3`.
+
+**GitHub CLI** — `gh`, used by `/pr` and `/issues-from-plan`. `brew install gh` (macOS) or [GitHub CLI install docs](https://github.com/cli/cli#installation), then `gh auth login`.
+
+**By feature:**
+
+| Tool(s) | Required for | Install |
+| --- | --- | --- |
+| `semgrep` | `/semgrep-analyze`, static analysis pre-pass in `/code-review` | `pip install semgrep`, `brew install semgrep`, or `pipx install semgrep` |
+| `playwright` | `/browse` (browser-based QA) | `npx playwright install chromium` (requires Node.js) |
+| `hadolint`, `trivy`, `grype` | `/docker-image-audit` | `brew install hadolint trivy grype`; Linux install scripts and Docker-container usage in the [docker-image-audit skill docs](skills/docker-image-audit/SKILL.md) |
+| `az` (with `az boards` extension) | `/test-modernize` when the parent issue lives on Azure DevOps | `brew install azure-cli` or [Azure CLI install docs](https://learn.microsoft.com/cli/azure/install-azure-cli); then `az extension add --name azure-devops` and `az login` |
+| `glab` | `/test-modernize` when the parent issue lives on GitLab | `brew install glab` or [GitLab CLI install docs](https://gitlab.com/gitlab-org/cli#installation); then `glab auth login` |
+| `acli` | `/test-modernize` when the parent issue lives on Jira (Atlassian Cloud) | See [Atlassian CLI install docs](https://developer.atlassian.com/cloud/acli/); REST + `JIRA_TOKEN` is the fallback |
+
+`/test-modernize` falls back to local plan files under `./plans/test-modernize/` whenever the tracker CLI for the given parent URL is missing — the workflow continues uninterrupted, only the destination of the issues changes.
+
+**Auto-formatting (the `post-format` hook, detected per language):** the hook auto-formats files on every edit, detecting available formatters and degrading silently if none are installed.
+
+| Tool | Language | Install |
+| --- | --- | --- |
+| `prettier` | JS/TS/CSS/HTML/JSON | `npm install -D prettier` (project-local) |
+| `eslint` | JS/TS | `npm install -D eslint` (project-local) |
+| `ruff` | Python | `pip install ruff` or `brew install ruff` |
+| `black` | Python (fallback if ruff absent) | `pip install black` |
+| `gofmt` | Go | Included with Go toolchain |
+| `rustfmt` | Rust | `rustup component add rustfmt` |
+| `rubocop` | Ruby | `gem install rubocop` (or add to Gemfile) |
+| `google-java-format` | Java | `brew install google-java-format` or [GitHub releases](https://github.com/google/google-java-format/releases) |
+| `ktlint` | Kotlin | `brew install ktlint` or [GitHub releases](https://github.com/pinterest/ktlint/releases) |
+| `dotnet format` | C# | Included with .NET SDK 6+ |
+
+**Quality gates in `/pr` (detected per stack):** `/pr` auto-detects test runners, type checkers, and linters from project manifests — if the tool is installed and the project has the relevant config file, it runs automatically.
+
+| Tool | Detected via | Install |
+| --- | --- | --- |
+| `tsc` | `tsconfig.json` | `npm install -D typescript` (project-local) |
+| `mypy` | `mypy.ini` or `pyproject.toml` [mypy] | `pip install mypy` |
+| `ruff` | `which ruff` | `pip install ruff` (project venv / dev requirements) |
+| `golangci-lint` | `which golangci-lint` | `brew install golangci-lint` or [install docs](https://golangci-lint.run/welcome/install/) |
+
+</details>
+
+### Self-hosted / other git hosts
+
+For a self-hosted or other git host (GitLab, Bitbucket, Gitea, Azure DevOps, on-prem), end the URL with `.git` so Claude Code clones the repository instead of treating the URL as a direct link to a `marketplace.json`, and append `#<branch-or-tag>` to pin a ref. The repository must contain `.claude-plugin/marketplace.json` at its root.
+
+```bash
+# HTTPS (private repos use your git credential helper)
+claude plugin marketplace add https://gitlab.example.com/team/agentic-dev-team.git
+
+# SSH
+claude plugin marketplace add git@gitlab.example.com:team/agentic-dev-team.git
+
+# pin a release tag
+claude plugin marketplace add https://gitlab.example.com/team/agentic-dev-team.git#dev-team-v6.6.0
+
+# then, for any of the above:
+claude plugin install dev-team@bfinster
+```
+
+For a private host that needs a token, embed a **read-scoped** token in the URL — `https://<user>:<token>@host/team/agentic-dev-team.git` — but never commit it or paste it in chat (Azure DevOps PATs need **Code (Read)** scope). Behind a corporate proxy, clone first and add the local path: `git clone <url> /path/to/clone && claude plugin marketplace add /path/to/clone`.
+
+**Scope and monorepo options** — these flags apply to `marketplace add` and `install`:
+
+| Flag | Effect |
+| --- | --- |
+| `--scope user` | You, across all projects (**default**) |
+| `--scope project` | All collaborators in this repo (writes `.claude/settings.json`) |
+| `--scope local` | You, this repo only (writes `.claude/settings.local.json`) |
+| `--sparse .claude-plugin plugins` | Limit the marketplace checkout to these directories — for monorepos; `marketplace add` only |
+
+Full reference: [Claude Code plugin marketplaces docs](https://docs.anthropic.com/en/docs/claude-code/plugin-marketplaces).
+
+### Upgrading
+
+Run `/upgrade` from any session, or update manually:
+
+```bash
+claude plugin update --scope <scope> dev-team@bfinster
+```
+
+To re-point the marketplace (e.g., after moving git hosts), remove it by its **marketplace name** (`bfinster`) and re-add the source:
+
+```bash
+claude plugin marketplace remove bfinster
+claude plugin marketplace add bdfinst/agentic-dev-team
+```
+
+### Verify
+
+After `/setup` completes, confirm the system is working:
+
+```
+> What agents are available on this team?
+```
+
+## What's included
+
+- **11 team agents** — Orchestrator, Software Engineer, QA Engineer, Architect, Product Manager, etc.
+- **28 review agents** — security-review, domain-review, test-review, naming-review, …
+- **93 skills** — knowledge modules and procedures the team draws on, 89 of them user-invocable as slash commands (`/plan`, `/build`, `/pr`, `/code-review`, `/browse`, `/triage`, …)
+
+Full catalogs: [Agents](docs/agent_info.md) · [Skills](docs/skills.md) · [Workflows](docs/workflows.md)

package/docs/upstream/agent-architecture.md

@@ -0,0 +1,214 @@
+# Architecture
+
+> **Reading order**: Start with the System Overview flowchart, then read Context Management to understand how agents are loaded and unloaded, followed by Quality Assurance for the validation sequence during Phase 3.
+
+**On this page:** [System Overview](#system-overview) · [Three-phase workflow](#three-phase-workflow) · [Model Routing](#model-routing) · [Knowledge Index](#knowledge-index) · [Review-Fix Loop](#review-fix-loop) · [Test improvement workflow](#test-improvement-workflow-test-improve) · [Context Management](#context-management) · [Plan Review Personas](#plan-review-personas) · [Quality Assurance](#quality-assurance) · [Human Oversight](#human-oversight) · [Governance](#governance) · [Feedback Loop](#feedback-loop) · [Performance Targets](#performance-targets)
+
+## System Overview
+
+![System Overview](diagrams/architecture-overview.svg)
+
+The Orchestrator receives every request, classifies it by type and complexity, selects agents, assigns models, and coordinates delivery. During Phase 3 (Implement), review agents check coding agent output at each discrete unit-of-work checkpoint. Findings feed back as structured corrections (max 2 cycles before human escalation). After each task, the learning loop captures metrics and evaluates whether configuration updates are needed.
+
+## Three-phase workflow
+
+Feature work flows through three phases — **Research → Plan → Implement** — with a human gate between each. Research turns a request into approved specs (`/specs` produces Intent, Architecture, and Acceptance Criteria) plus a design doc; Plan decomposes them into vertical slices, authors each slice's Gherkin scenarios, and lays out the TDD steps, which up to five critic personas (Acceptance, Design, UX, Strategic, Parallelization — the set scales to plan tier) challenge before the human approves; Implement runs the per-behavior build loop — Code-First Small Batches (IMPLEMENT → TEST → REFACTOR), the sole build cadence — with a three-stage inline review (spec-compliance, quality agents, and browser verification for UI changes) and a `/code-review` gate, then opens the PR and feeds the learning loop.
+
+![Three-phase workflow: Research (/specs producing Intent, Architecture, and Acceptance Criteria → design doc → approve), Plan (/plan authoring slices and Gherkin plus TDD steps, challenged by the Acceptance, Design, UX, Strategic, and Parallelization critics → approve), and Implement (TDD loop → spec-compliance → quality agents → browser verify for UI → /code-review with auto-fix → approve), ending in /pr and the learning loop.](diagrams/workflow-three-phase.svg)
+
+## Model Routing
+
+Each agent declares `model:` (an alias, a full model ID, or `inherit`) and `effort:` (`low|medium|high|xhigh|max`) directly in its frontmatter — the native Claude Code sub-agent contract, resolved by the harness itself before dispatch. There is no plugin-side resolution hook, routing map, or per-environment ladder file (ADR 0026 retired that machinery once the native fields were confirmed to already provide it). See `agents/orchestrator.md` → Model/Effort Resolution.
+
+## Knowledge Index
+
+`knowledge/index.json` is a deterministic, checked-in catalog of every H2/H3 section across `knowledge/**.md` and `skills/**/SKILL.md`. Each entry has a one-sentence summary and a slugified GitHub-style anchor. Agents that reference knowledge files cite an anchor (e.g. `knowledge/owasp-detection.md#a03-injection`) and read only the relevant section via `offset`/`limit`. Four freshness gates keep the index current: (1) PostToolUse hook auto-regen on save, (2) pre-commit sibling hook blocks stale commits, (3) `tests/repo/test_knowledge_index_current.py` runs in CI, (4) `tests/agents/test_agent_knowledge_anchor.py` validates every reference resolves. See `agents/orchestrator.md` → Knowledge index — consumer usage pattern for the canonical lookup flow, and `hooks/lib/build_knowledge_index.py --check` for ad-hoc verification.
+
+## Review-Fix Loop
+
+Both inline review checkpoints (Phase 3) and `/code-review` use the same review-fix loop: targeted agents run in parallel, actionable issues (error/warning severity with high/medium confidence) are auto-fixed, and only the agents that reported issues are re-run against the modified files. The loop converges in up to 5 iterations or escalates to a human. `/code-review` is the final gate before commit.
+
+For the full pipeline — targeting, pre-flight gates, static analysis pre-pass, ACCEPTED-RISKS suppression, fix-loop exit conditions, report generation, and the `.pr-review-passed` gate file — see [Code Review Process](code-review-process.md).
+
+## Test improvement workflow (`/test-improve`)
+
+`/test-improve` is the **consolidated** analyze-then-improve orchestrator for legacy or in-flight test suites. It defaults to lightweight ceremony, prompts for heavier capabilities on demand, and always baselines coverage (and mutation, when enabled) before any test change.
+
+![/test-improve ten-phase (0-9) workflow with human gates between each phase](diagrams/test-improve-flow.svg)
+
+It runs ten phases (0-9) with a human gate between each, every phase writing a progress file at `.claude/memory/test-improve/<slug>/phase-<n>.md` so `/continue` (and `--from-phase`) can resume. The full phase-by-phase reference — gates, arguments, and the flow diagram — lives on its own page: **[test-improve.md](test-improve.md)**.
+
+## Context Management
+
+The Orchestrator manages context utilization using two operational skills.
+
+### Loading Protocol
+
+[Context Loading Protocol](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/context-loading-protocol/SKILL.md) controls what gets loaded and when:
+
+1. **Classify** the task (simple, standard, multi-agent, complex)
+2. **Select** the minimum set of agents and skills required
+3. **Load in phases**: primary agent first, supporting agents as their phase begins
+4. **Unload** previous-phase agents via summarization before loading next-phase agents
+
+### Summarization
+
+[Handoff](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/handoff/SKILL.md) (continue mode) controls when to compress:
+
+| Utilization | Action |
+| --- | --- |
+| < 40% | Normal operation |
+| 40-50% | Prepare for summarization |
+| 50-60% | Summarize older conversation turns |
+| 60-75% | Aggressive summarization |
+| 75%+ | Write summary to `.claude/memory/`, start new conversation |
+
+Utilization is estimated via proxy signals (tool call volume, message count, accumulated file reads) as described in the Context Loading Protocol. Summaries follow a structured template and are stored in `.claude/memory/` for cross-session continuity.
+
+### Token Budgets
+
+| Component | ~Tokens |
+| --- | --- |
+| CLAUDE.md (always loaded) | ~800 |
+| Single team agent | 290-560 |
+| Single skill | 420-1,020 |
+| All team agents (no skills) | ~3,590 |
+| All review agents | ~3,100 (sub-agents, not loaded in parent context) |
+| Knowledge files | ~3,450 (loaded on demand by agents) |
+| Plan review persona agents | ~1,800 (loaded by orchestrator when dispatching) |
+| Full load (all team agents + all skills) | ~18,100 |
+
+A typical task loads 1 agent + 1-2 skills: roughly 1,000-2,000 tokens of configuration overhead. Review agents and plan review personas run as isolated sub-agents — their context burden does not accumulate in the parent.
+
+### Subagent status checks
+
+A subagent's progress or status reaches a *live* orchestrating agent's context only as its structured summary output — the verdict/findings contract the `Agent` tool already returns — never as a raw transcript read. Pulling a running subagent's full transcript into the orchestrator's working context is the failure mode Martin Fowler's ["The Orchestrator's Tax"](https://martinfowler.com/articles/orchestrator-tax.html) warns about: unlike a one-time token bill, that transcript then persists and degrades every subsequent turn. The `Agent` tool's contract already enforces this — it returns only final text/schema output, not a transcript — so the failure cannot occur through the standard dispatch path; this subsection states the rule explicitly for future tool and skill authors.
+
+**Offline-resume exception.** The `Workflow` tool's resume mechanism legitimately reads `journal.jsonl` / `agent-<id>.jsonl` transcript files to reconstruct cached results for continuation. That is an *offline* diagnostic read, not a feed into a live orchestrator's context, and is fine. The constraint targets specifically a raw-transcript read flowing back into an *active* orchestrating agent's working context.
+
+## Plan Review Personas
+
+Before the human reviews a plan (Phase 2), a tier-scaled set of critical review personas runs **in parallel** as sub-agents. The reviewer set scales to a **plan tier** (`trivial`/`standard`/`complex`, derived from slice count, file count, per-step complexity, and whether the plan takes a stance on any high-reversal-cost decision axis) so a one-function plan does not pay a complex feature's review ceremony: `trivial` runs the Acceptance Test Critic alone, `standard` adds the Design & Architecture Critic (plus the UX Critic for user-facing plans and the Parallelization Critic when the slice count > 1), and `complex` runs all five. The Acceptance Test Critic always runs; the Parallelization Critic runs only when slice count > 1. Each persona challenges the plan from a distinct perspective:
+
+| Persona | Agent | What It Challenges |
+| --- | --- | --- |
+| Acceptance Test Critic | `agents/plan-review-acceptance.md` | Per-slice Gherkin quality (determinism, isolation, completeness), criteria verifiability, error-path coverage, TDD step traceability |
+| Design & Architecture Critic | `agents/plan-review-design.md` | Dependency direction, abstraction quality, structural risks, pattern consistency |
+| Parallelization Critic | `agents/plan-review-parallelization.md` | Same-wave independence: file-overlap collisions (plan_waves.py), disjoint-file behavioral coupling, residual cycles |
+| Strategic Critic | `agents/plan-review-strategic.md` | Problem-solution fit, scope assessment, risk analysis, opportunity cost |
+| UX Critic | `agents/plan-review-ux.md` | User journey, error experience, cognitive load, accessibility (self-skips for non-UI plans) |
+
+Each persona is a registered agent, dispatched by `subagent_type` like any other agent — `/plan` step 5b no longer needs a dispatch-time `model:` override; the harness reads each persona's own `model:`/`effort:` frontmatter natively.
+
+Each reviewer returns a structured `approve` or `needs-revision` verdict. If any reviewer flags blockers, the plan is revised before the human sees it (max 2 iterations). Warnings from the dispatched reviewers are aggregated into a Plan Review Summary appended to the plan file, which also records the chosen tier and reviewer set so the scaling decision is auditable.
+
+This gate catches problems when they cost minutes to fix (in a plan), not hours (in code).
+
+## Quality Assurance
+
+Validation happens in this sequence during Phase 3:
+
+| Order | Layer | Who | When |
+| --- | --- | --- | --- |
+| 1 | Self-validation | Active agent | Before delivering any unit of work |
+| 2 | Inline review checkpoint | Targeted review agents | After each discrete unit of work |
+| 3 | Review feedback correction | Coding agent | Up to 2 correction cycles per checkpoint |
+| 4 | Final code review | `/code-review` | Before committing; auto-scopes to uncommitted changes, runs full agent suite with fix loop |
+| 5 | Documentation review | Tech-writer | After code review passes; verifies docs reflect current behavior |
+| 6 | Peer validation | QA agent | After implementation, before phase delivery |
+| 7 | Human gate | User | At each phase transition (Research, Plan, Implement) |
+| 8 | Post-hoc monitoring | Orchestrator | During learning loop after task completion |
+
+Every agent applies the [Quality Gate Pipeline](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/quality-gate-pipeline/SKILL.md) before output. This includes self-validation (Phase 1: factual accuracy, instruction fidelity, consistency, confidence scoring), verification evidence (Phase 2), and review-correction loops (Phase 3).
+
+Quality gates by task type:
+
+| Task Type | Required Gates |
+| --- | --- |
+| Code implementation | Self-validation + QA review |
+| Architecture design | Self-validation + human approval |
+| Documentation | Self-validation + terminology check |
+| Bug fix | Self-validation + regression test |
+| Data analysis | Self-validation + statistical validation |
+
+## Human Oversight
+
+Agents operate autonomously within boundaries. The [Human Oversight Protocol](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/human-oversight-protocol/SKILL.md) defines three levels of human involvement:
+
+| Level | When | Example |
+| --- | --- | --- |
+| **Autonomous** | Routine work within scope | Writing a unit test |
+| **Notify** | Significant but within scope | Choosing between two valid patterns |
+| **Approve** | High-impact or outside scope | Database schema change, production deploy |
+
+Intervention commands (`override`, `pause`, `stop`) give humans immediate control when needed.
+
+## Governance
+
+[Governance & Compliance](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/governance-compliance/SKILL.md) defines audit and ethics requirements:
+
+- All task completions logged to `.claude/metrics/` (JSONL format)
+- All configuration changes logged to `.claude/metrics/config-changelog.jsonl`
+- Conversation summaries stored in `.claude/memory/` for cross-session continuity
+- Significant routing and architectural decisions logged to `.claude/memory/decisions.md`
+- Sensitive data (credentials, PII) never stored in metrics or memory files
+- All agent decisions must be explainable on request
+
+### Pre-Execution Hook Pipeline
+
+A `PreToolUse` hook (`hooks/pre_tool_guard.py`) intercepts every Write and Edit call before execution:
+
+| Action | Trigger | Behavior |
+| --- | --- | --- |
+| Block | Path matches `blocked_paths` in `guards.json` | Exit 2 — write cancelled, message shown |
+| Warn | Path matches `warn_paths` in `guards.json` | Exit 0 — write proceeds, warning shown |
+| Allow | No match | Exit 0 — write proceeds silently |
+
+Default blocked patterns: `.env`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*credential*`, `*secret*`, `*.token`. Configurable via `.claude/hooks/guards.json`.
+
+### Destructive Command Guard
+
+A second `PreToolUse` hook (`hooks/destructive_guard.py`) monitors Bash tool calls for destructive commands: file deletion (`rm -rf`), database drops (`DROP TABLE`), git destruction (`force-push`, `reset --hard`), process killing, and permission escalation. Patterns are configurable via `hooks/destructive-commands.json`, which also includes a `safe_allowlist` for routine operations like `rm -rf node_modules`.
+
+By default, destructive commands produce a **warning** (exit 0). When `/careful` mode is active, they are **blocked** (exit 2).
+
+### Pre-PR Review Gate
+
+A `PreToolUse` hook on `gh pr create` (`hooks/pre_pr_review.py`, #1886) blocks opening the PR (exit 2) unless `.claude/memory/.pr-review-passed` carries a hash matching the branch's current diff vs. its base, corroborated by genuine review-agent dispatch evidence. `git commit` is no longer gated: a branch may accumulate any number of local commits without triggering a review-agent panel; the hard block fires once, against the branch's full diff, at PR-creation time. (`hooks/pre_commit_review.py`, the former commit-time gate, is now a documented no-op.)
+
+`/code-review`'s own gate-file write (step 9, [Code Review Process → Pre-PR gate file](code-review-process.md#9-pre-pr-gate-file)) now writes `.pr-review-passed` bound to the branch-diff hash this gate reads, when the review was auto-scoped to uncommitted changes and passed. **Known residual gap (#1886 follow-up):** `agent_dispatch_ledger.py` still stamps dispatch evidence with the staged-diff hash, not the branch-diff hash, so this only lines up automatically in the common single-commit-then-PR shape — a branch with multiple separate review-and-commit cycles needs a fresh `/code-review` run against its current diff right before `gh pr create`, or falls back to the audited `PR_GATE_BYPASS_REASON` escape hatch below.
+
+**Reasoned bypass.** Setting a non-empty `PR_GATE_BYPASS_REASON` env var allows `gh pr create` through even without a passing gate — `gh` has no `--no-verify`-shaped flag to key a bypass off, so the env var alone is both the trigger and the reason. When present, the bypass is logged — timestamp, branch, reason, branch-diff file count — to `.claude/metrics/gate-bypass-audit.jsonl` (#709/#1886), unconditionally:
+
+```bash
+PR_GATE_BYPASS_REASON="hotfix, review to follow" gh pr create ...
+```
+
+### Code-Intelligence Nudge
+
+A `PreToolUse` hook (`hooks/code_intelligence_nudge.py`) registered on `Read`, `Grep`, and `Glob` detects which of CodeGraph (`.codegraph/`), Repowise (`.repowise/`), and Graphify (`graphify-out/graph.json`) are present in the project and recommends whichever are present and not yet used this turn over multi-file exploration — composing a single-tool message when only one is present, or a combined, precedence-ordered message (Graphify, then Repowise, then CodeGraph) when two or more are. The hook is silent for single-file Read calls, for Grep with a regular-file `path`, for Glob with a literal `pattern`, and for any tool already used earlier in the current turn (tracked via a sentinel accumulating `tools_used`, written by a companion `PostToolUse` hook on `mcp__codegraph__.*` and `mcp__plugin_repowise_repowise__.*`). Warns to stderr by default; blocks (`exit 2`) under `/careful`. Fail-open posture throughout — any internal error, or a missing/malformed detection or sentinel surface, exits 0. See `docs/code-intelligence-nudge.md` for the full mechanism.
+
+### Context Management
+
+The plugin no longer enforces a context ceiling with a hook ([ADR 0043](https://github.com/bdfinst/agentic-dev-team/blob/main/docs/adr/0043-replace-the-context-ceiling-guard-with-harness-autocompact.md)). `/setup` writes the harness's own `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` (default 40) into each repo's `.claude/settings.json`; the harness compacts at that percentage of its window. Two `SessionStart` hooks support it: `autocompact_setup_nudge.py` (advisory, recommends `/setup` when the key is missing) and `post_compact_state_reinject.py` (matcher `compact`, re-injects the active `/build` phase, step and plan progress). `/handoff` is a manual tool. See [Context Management](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/docs/context-management.md) and [Context Loading Protocol → Why 40%](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/context-loading-protocol/SKILL.md#why-40).
+
+### Freeze Mode
+
+The `hooks/pre_tool_guard.py` hook also enforces freeze mode. When `/freeze <glob>` is invoked, it writes a state file (`.claude/hooks/freeze-state.json`, resolved per invoking repo via `hooks/lib/artifact_paths.py` — issue #1890) that restricts Write/Edit operations to files matching the allowed pattern. This prevents accidental edits outside the scope of a debugging session, and — because the state file is repo-scoped rather than relative to the hook's own shared install directory — one session's freeze can never scope-lock a different, concurrently-running session's edits. `/unfreeze` removes the restriction. `/guard <glob>` activates both careful mode and freeze mode together.
+
+### Decision Log
+
+Agents append to `.claude/memory/decisions.md` when making non-obvious decisions during task execution. The log persists across session resets, giving future phases visibility into prior reasoning without re-reading full conversation history.
+
+## Feedback Loop
+
+[Feedback & Learning](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/feedback-learning/SKILL.md) enables continuous improvement:
+
+1. User provides feedback via keywords (`amend`, `learn`, `remember`, `forget`)
+2. Changes are previewed, applied, and logged with full audit trail
+3. The Orchestrator monitors for recurring patterns (3+ occurrences)
+4. System-initiated changes are proposed to the user with rationale
+
+## Performance Targets
+
+Two metrics are instrumented today: token budgets (measured by `scripts/measure_tokens.py`) and per-agent detection accuracy (measured by `/agent-eval` against `evals/expected/*.json`). Other goals — efficiency gains, hallucination rate, extraction accuracy, first-pass acceptance — are aspirational and have **no sensor in this repo**, so no numeric target is published until an instrument exists. See the *Claims discipline* section of [`CLAUDE.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/CLAUDE.md) for the full instrumented-vs-aspirational breakdown.

package/docs/upstream/agent_info.md

@@ -0,0 +1,187 @@
+# Agents
+
+Agents define **who does the work**. There are two categories: **team agents** (persona-driven roles that implement, design, and coordinate) and **review agents** (focused reviewers that inspect code quality during implementation).
+
+## Team Agents
+
+Each team agent file in `agents/` specifies a role's persona, behavior, collaboration style, and which skills it uses.
+
+| Agent | File | Purpose |
+| --- | --- | --- |
+| ADR Author | [`adr-author.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/adr-author.md) | Creates and manages Architecture Decision Records |
+| Architect | [`architect.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/architect.md) | System design, tech decisions, scalability planning |
+| Codebase Recon | [`codebase-recon.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/codebase-recon.md) | Surveys a codebase's structure, entry points, dependencies, security surface, and git history; produces a RECON artifact in `.claude/memory/` that other agents consume |
+| Orchestrator | [`orchestrator.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/orchestrator.md) | Routes tasks, assigns models, coordinates inline review loop |
+| Platform Engineer | [`platform-engineer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/platform-engineer.md) | Pipeline, deployment, reliability, observability |
+| Product Manager | [`product-manager.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/product-manager.md) | Requirements clarification, prioritization, stakeholder alignment |
+| QA/SQA Engineer | [`qa-engineer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/qa-engineer.md) | Test generation, automated testing, quality gates |
+| Security Engineer | [`security-engineer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/security-engineer.md) | Security analysis, threat modeling, compliance |
+| Software Engineer | [`software-engineer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/software-engineer.md) | Code generation, implementation, applies review corrections |
+| Technical Writer | [`tech-writer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/tech-writer.md) | Documentation, terminology consistency, style enforcement |
+| UI/UX Designer | [`ui-ux-designer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/ui-ux-designer.md) | Interface design, UX flows, accessibility compliance |
+
+## Review Agents
+
+Review agents run as sub-agents during Phase 3 inline checkpoints and full `/code-review` runs. The Orchestrator selects and spawns them — they are never invoked directly by the user. Each agent declares its own `model:`/`effort:` frontmatter — the native Claude Code sub-agent contract, resolved by the harness itself (see Model/Effort Resolution in `agents/orchestrator.md`). For the full dispatch pipeline, see [Code Review Process](code-review-process.md).
+
+| Agent | File | Model | What It Checks |
+| --- | --- | --- | --- |
+| `a11y-review` | [`a11y-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/a11y-review.md) | sonnet | WCAG 2.1 AA, ARIA, keyboard navigation |
+| `ai-provenance-review` | [`ai-provenance-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/ai-provenance-review.md) | opus | AI-authored test assertion verification debt, regeneration-risk candidates |
+| `angular-reactivity-review` | [`angular-reactivity-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/angular-reactivity-review.md) | sonnet | Angular Zone.js pitfalls, OnPush violations, RxJS subscription leaks |
+| `arch-review` | [`arch-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/arch-review.md) | opus | ADR compliance, layer violations, dependency direction |
+| `claude-setup-review` | [`claude-setup-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/claude-setup-review.md) | haiku | CLAUDE.md completeness and accuracy |
+| `component-architecture-review` | [`component-architecture-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/component-architecture-review.md) | sonnet | Reusable component extraction, UI duplication, prop drilling, component APIs |
+| `concurrency-review` | [`concurrency-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/concurrency-review.md) | sonnet | Race conditions, async pitfalls |
+| `correctness-review` | [`correctness-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/correctness-review.md) | opus | Functional/behavioral defects — implementation diverges from evident intent |
+| `data-flow-tracer` | [`data-flow-tracer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/data-flow-tracer.md) | sonnet | Data flow tracing through architecture layers (analysis-only) |
+| `doc-review` | [`doc-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/doc-review.md) | sonnet | README accuracy, API doc alignment, comment drift |
+| `domain-review` | [`domain-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/domain-review.md) | opus | Abstraction leaks, boundary violations |
+| `js-fp-review` | [`js-fp-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/js-fp-review.md) | haiku | Array mutations, impure patterns, global state, point-free/composition opportunities (JS/TS) |
+| `mutation-kill` | [`mutation-kill.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/mutation-kill.md) | opus | Autonomous survivor-reduction loop — generates targeted tests, verifies, commits, repeats; not a reviewer, invoked per Story by `/test-improve` Phase 5 or directly |
+| `naming-review` | [`naming-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/naming-review.md) | haiku | Intent-revealing names, magic values |
+| `performance-review` | [`performance-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/performance-review.md) | haiku | Resource leaks, N+1 queries |
+| `progress-guardian` | [`progress-guardian.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/progress-guardian.md) | sonnet | Plan adherence, commit discipline, scope creep |
+| `quality-reviewer` | [`quality-reviewer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/quality-reviewer.md) | sonnet | Coordinates the Inline Review Checkpoint's review agents and drives the fix loop — Stage 2 of the three-stage inline review |
+| `react-reactivity-review` | [`react-reactivity-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/react-reactivity-review.md) | sonnet | React hook violations, stale closures, missing deps, subscription leaks |
+| `refactor-opportunity-review` | [`refactor-opportunity-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/refactor-opportunity-review.md) | sonnet | Post-GREEN refactoring opportunities |
+| `security-review` | [`security-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/security-review.md) | opus | Injection, auth, data exposure |
+| `session-analysis` | [`session-analysis.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/session-analysis.md) | sonnet | Maps an aggregated session digest to probable plugin causes and ranked, tagged improvement suggestions (analysis-only) |
+| `spec-compliance-review` | [`spec-compliance-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/spec-compliance-review.md) | sonnet | Spec-to-code matching — general first gate before quality review (final `/code-review` gate; pre-build and batched/complex-slice checkpoints in `/build`) |
+| `spec-reviewer` | [`spec-reviewer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/spec-reviewer.md) | haiku | Spec-to-diff matching for a single freshly-implemented unit — Stage 1 of the three-stage inline review |
+| `structure-review` | [`structure-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/structure-review.md) | sonnet | SRP, DRY, coupling, file organization, nesting depth, cognitive load, async-pattern judgment |
+| `test-review` | [`test-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/test-review.md) | sonnet | Coverage gaps, assertion quality, test hygiene |
+| `test-smell-review` | [`test-smell-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/test-smell-review.md) | sonnet | xUnit test smells, test-double selection, pyramid placement |
+| `token-efficiency-review` | [`token-efficiency-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/token-efficiency-review.md) | haiku | File size, LLM anti-patterns |
+| `vue-reactivity-review` | [`vue-reactivity-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/vue-reactivity-review.md) | sonnet | Vue ref/reactive pitfalls, watchEffect tracking, proxy escapes, subscription leaks |
+
+To add a new review agent, use `/agent-add`. See [Add a Review Agent](#add-a-review-agent) below.
+
+## Plan Review Personas
+
+Plan review personas are registered agents (`agents/plan-review-*.md`) that critically challenge implementation plans during Phase 2, before the human gate. Unlike review agents (which check code), these check the plan itself. See [Plan Review Personas in the architecture doc](agent-architecture.md#plan-review-personas) for the full persona table and revision loop.
+
+## Persona Template
+
+Every agent file follows this structure:
+
+```markdown
+# [Role Name] Agent
+
+## Technical Responsibilities
+- [Primary capabilities - what this agent delivers]
+
+## Skills
+- [Skill Name](../skills/{file}.md) - [when/why this agent uses it]
+
+## Collaboration Protocols
+### Primary Collaborators
+- [Agent Name]: [What they exchange]
+
+### Communication Style
+- [Tone, detail level, update frequency]
+
+## Behavioral Guidelines
+### Decision Making
+- Autonomy level: [High/Moderate/Low] for [what]
+- Escalation criteria: [When to escalate]
+- Human approval requirements: [What needs sign-off]
+
+### Conflict Management
+- [How disagreements are resolved]
+
+## Psychological Profile
+- Work style: [Preferences]
+- Problem-solving approach: [Methods]
+- Quality vs. speed trade-offs: [Tendencies]
+
+## Success Metrics
+- [Measurable KPIs]
+```
+
+The `## Skills` section is the bridge between agents and skills. The agent defines *when and why* to invoke a skill; the skill defines *how* to execute it.
+
+## Non-standard body declarations
+
+Several `Key: value` lines appear in some agents' **bodies**, not their frontmatter — they are intentional internal tooling metadata, deliberately kept out of frontmatter because none of them are part of the official Claude Code sub-agent contract (`plugins/marketplace-dev/knowledge/agent-contract.json`); frontmatter is reserved for that contract (issue #1333).
+
+- **`Cites: [...]`** — a list of canonical skill/knowledge-file sources an agent's normative rules (MUST/SHOULD/SHALL thresholds) derive from, e.g. `Cites: [owasp-detection, accepted-risks-schema]`. `scripts/citation_lint.py` reads this list and flags a warning when a stated numeric threshold doesn't appear in any cited source — catching silent drift when a canonical file changes but a reviewer agent's inline rule doesn't. See the script's module docstring for the full contract. See `tests/repo/test_citation_lint_corpus.py` for the regression guard over the real corpus.
+- **`Scope: always` / `Scope:` (glob list) / `Scope: added-only` (glob list) / `Scope: on-demand`** — self-declares which files an agent is eligible to review; read by `/code-review`'s dispatch step (`skills/code-review/SKILL.md`). `scripts/check_agent_scope.py` only validates that *some* `Scope:` line is present, not which of the four forms it takes or that the value parses — a misspelled sentinel (e.g. `Scope: added_only`) passes that check silently, then falls through to `select_lenses.py`'s `parse_scope`, which fails open (include-biased, and warned) on an unrecognized value. `added-only` (#1733) narrows the glob-list form to only files that are newly *added* (git change-type `A`), not merely modified. `on-demand` (#1733's closing-pass follow-up) is a bare declaration with no bullet block — it means the agent is a genuine review agent whose findings are whole-repository properties, never dispatched by the per-diff resolver at all (`claude-setup-review`, `token-efficiency-review`, `ai-provenance-review` — see `scripts/lib/review_roster.py`'s docstring for why this replaced listing them in `NON_REVIEW_AGENTS`). `parse_scope` treats the **first** `Scope:` line as authoritative, so the machine-readable form (`added-only`/`on-demand`/plain glob-list) must stay above any later free-text `Scope:` prose in the same body, or the declaration a reader sees first is not the one the resolver reads.
+- **`Verify-model:` / `Verify-effort:`** — a review agent's optional opt-in to a cheaper model/effort tier for **fix-verification** re-dispatches only; discovery dispatches are unaffected. Absent means "same tier as discovery" — the deliberate default, since #1619 showed some confirmations genuinely need top-tier judgment. Resolved by `scripts/verify_tier.py`, which validates each value against the same closed enums the official contract declares for `model:`/`effort:` and falls back to the discovery tier on a typo (failing toward the more expensive tier, never the cheaper one). Full contract: [`knowledge/verification-mode.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/verification-mode.md) (#1628).
+- **`Enforcement: script`** — marks an agent whose behavior is deterministically implemented by a script rather than driven by free-form LLM reasoning from the persona prose alone. Agents carrying this declaration also carry a `> **Implemented by:** ${CLAUDE_PLUGIN_ROOT}/scripts/<name>.py` blockquote near the top of the file pointing at that implementation (e.g. `orchestrator.md` → `${CLAUDE_PLUGIN_ROOT}/scripts/orchestrator.py`, `codebase-recon.md` → `${CLAUDE_PLUGIN_ROOT}/scripts/codebase_recon.py`).
+
+## Add a Team Agent
+
+1. Create `agents/{role-name}.md` using the template above
+2. Add the agent to the Team Organization diagram in `docs/team-structure.md`
+3. Add it to the Team Agents table in `CLAUDE.md`
+4. Define collaboration protocols with existing agents
+5. Reference any applicable skills in the `## Skills` section
+
+See the `marketplace-dev` plugin's `agent-skill-authoring` guidance for detailed authoring conventions.
+
+## Add a Review Agent
+
+Use the `/agent-add` slash command — it scaffolds a compliant agent, checks for scope overlap with existing review agents, runs `/agent-audit` automatically, and registers the agent in `CLAUDE.md`.
+
+```text
+/agent-add "React hook violations" --tier mid --lang js,ts,jsx,tsx
+```
+
+Manual process:
+
+1. Create `agents/{name}-review.md` using the review agent template (see any existing review agent for reference)
+2. Run `/agent-audit agents/{name}-review.md --fix` to validate compliance
+3. Add eval fixtures to `evals/fixtures/` and expected results to `evals/expected/`
+4. Run `/agent-eval --agent {name}-review` to validate accuracy
+5. Add a row to the Review Agents table in `CLAUDE.md`
+
+## Add a Project-Specific Custom Agent
+
+Custom agents extend the team with knowledge specific to your project — your domain model, internal frameworks, coding conventions, or tech stack. They live in your project's `agents/` directory alongside the standard team agents and are invisible to other projects.
+
+**When to add a custom agent** (rather than relying on a standard agent):
+
+- The agent needs deep knowledge of your domain that would bloat the standard agent's context
+- The role is specific to your team's process (e.g., a `compliance-reviewer` for regulated industries)
+- You want a review agent that enforces internal conventions the standard agents don't know about
+
+**Steps**:
+
+1. Create the agent file in your project's `agents/`:
+
+   ```bash
+   # In your project (not this repo)
+   touch .claude/agents/django-review.md
+   ```
+
+2. Write the agent using the [persona template](#persona-template) above. For a review agent, copy an existing one (e.g., `agents/js-fp-review.md`) as a starting point.
+
+3. Register it in your project's `CLAUDE.md` under the appropriate table (Team Agents or Review Agents).
+
+4. If it's a review agent, add eval fixtures so you can validate its accuracy:
+
+   ```
+   .claude/evals/fixtures/django-review/     # sample code the agent should flag
+   .claude/evals/expected/django-review.json # expected findings
+   ```
+
+5. Validate with `/agent-audit` and test with `/agent-eval --agent django-review`.
+
+**Important**: Custom agents in your project's `.claude/` are *additive* — they extend the standard team without replacing it. The Orchestrator will route to them when appropriate based on the task.
+
+## Install or Update the Plugin
+
+The standard install path is `claude plugin install dev-team@bfinster` — see the [repository README](../../../README.md#getting-started) for the full procedure, including how to update to a newer version. Copying agent files by hand is not supported: the Orchestrator routes by marketplace registry, not by file scan.
+
+To contribute a custom agent back upstream:
+
+1. Ensure the agent file follows the standard template (run `/agent-audit` against it)
+2. Add eval fixtures and expected outputs
+3. Submit a PR to this repository with the agent file, fixtures, and a registry entry in `CLAUDE.md`
+
+## Remove an Agent
+
+1. Delete the agent file from `agents/`
+2. Remove it from the organization diagram and registry in `CLAUDE.md`
+3. Update other agents' collaboration protocols that referenced the removed agent