pi-dev-team 0.2.0

package/docs/upstream/session-review.md

@@ -0,0 +1,212 @@
+# Session-review harness (#131)
+
+`/session-review` mines **ground-truth Claude Code session transcripts**
+(`~/.claude/projects/<slug>/*.jsonl`) to suggest plugin improvements that reduce
+**re-work**, cut **token usage**, and improve **accuracy**.
+
+It fills a blind spot. The plugin already measures quality from two angles, both
+with gaps:
+
+- `/agent-eval` + `evals/` grade agents on a *synthetic* fixture corpus — proves
+  an agent *can* detect a planted issue, says nothing about real behaviour.
+- `/harness-audit` + `.claude/metrics/` analyse effectiveness from *self-reported*
+  task logs — sparse, and only what the model chose to record about itself.
+
+Neither reads what *actually happened*: per-turn token usage, tool errors,
+failed edits, user corrections, and skill/agent attribution. `/session-review`
+does.
+
+## Three stages (the model never reads raw transcripts)
+
+| Stage | Component | What it does |
+|---|---|---|
+| 1. Extract | `${CLAUDE_PLUGIN_ROOT}/scripts/session_report.py --profile maintainer` (#127, #2046) | Deterministic, **zero model tokens**. Distills MBs of JSONL into a KB digest capturing all four signal classes equally (token / rework / accuracy / utilization). Privacy: metrics only — never prompt or code content. |
+| 2. Analyze | `agents/session-analysis.md` + `skills/session-review/SKILL.md` (#128) | A focused agent reads **only the digest** and maps aggregated patterns to probable *plugin* causes. |
+| 3. Suggest | `.dev-team-reports/session-review-<date>.md` (#128) | Ranked recommendations, each tagged `{token \| rework \| accuracy}`, naming the target artifact and handing off — never auto-applying. |
+
+## Hand-off, not auto-apply
+
+| Suggestion | Handed to |
+|---|---|
+| Config / prompt / convention fix | `/feedback-learning` |
+| Model/effort re-tuning | `/harness-audit` + the agent's `model:`/`effort:` frontmatter (ADR 0026) |
+| New / changed detection rule | `/agent-eval` |
+| Token-heavy skill / agent | `token-efficiency-review` |
+
+## Trend persistence (#129)
+
+Each run appends one metrics-only record to the append-only trend stream
+`metrics/session-digest.jsonl` (deliberately left bare — /session-review's own
+scratch-state writer is out of scope for the #1406 `.claude/`-scoped artifact
+migration) — the real-session counterpart to the self-reported
+`.claude/metrics/*-task-log.jsonl` streams — so `/harness-audit` can
+consume ground-truth data alongside the task logs. This is the canonical
+description of both the record schema and the harness-audit join;
+[`eval-system.md`](eval-system.md) links here.
+
+### Record schema (`session-digest/v2`)
+
+Each line is a JSON object with **aggregate counts only** — no file names,
+prompts, command strings, or code (privacy by construction):
+
+| Field | Meaning |
+|---|---|
+| `recorded_at` | UTC ISO-8601 of the run (the only wall-clock field) |
+| `sessions` | distinct sessions covered (subagents share their parent's session, so they do not inflate it) |
+| `transcripts` / `subagent_transcripts` | main-thread sessions vs dispatched agent runs |
+| `tokens` | input/output/cache token totals |
+| `cost_usd`, `cache_hit_ratio` | session cost and cache-read efficiency |
+| `token.by_agent_type` | per-agent token buckets keyed by agent name — `main`, `unattributed` where none resolves, `sidechain` for an older harness's inlined turns. **Was a bare message count before #2010**, which read as a token figure under this key and was off from `token.totals` by orders of magnitude |
+| `rework` | counts: `failed_edits`, `repeated_file_edits`, `retried_bash_commands`, `repeated_verify_runs`, `permission_denials`, `compaction_events` |
+| `accuracy` | `tool_calls`, `tool_error_rate`, `user_correction_turns` |
+| `utilization` | `skills_invoked`, `agents_invoked` (RUNS), `agent_dispatches` (Agent/Task calls), `never_observed_skills`, `never_observed_agents` |
+
+**v1 records are not comparable to v2** (#1994). Before v2 the extractor
+globbed only `<project>/<sessionId>.jsonl`, so every dispatched agent's own
+transcript was unread and its tokens, tool calls and rework were missing
+entirely — on the machine that motivated this, about a third of the tokens and
+nearly half the cost. `retried_bash_commands` and `repeated_verify_runs` also
+changed basis: they are counted within one thread of execution now rather than
+per session, because subagents share their parent's `sessionId` and a
+session-keyed tally scored a review panel's siblings running one command each
+as retries. A trend stream holding both eras must split them on `schema`.
+
+### harness-audit consumption (the join)
+
+`/harness-audit` historically read only the self-reported
+`.claude/metrics/*-task-log.jsonl`. It joins real-session data by reading
+`metrics/session-digest.jsonl`:
+
+- **token / cost trends** → corroborate or contradict self-reported efficiency
+  claims (the audit's blind spot was that it saw only self-reports).
+- **`utilization.never_observed_*`** → flag stale/undiscoverable harness surface
+  for the simplification recommendations harness-audit already makes.
+- **`rework` / `accuracy` trends** → evidence for re-tiering or prompt fixes.
+
+Join key: correlate by `recorded_at` time window (the two streams live at
+different roots — `metrics/session-digest.jsonl` is deliberately bare,
+`.claude/metrics/*-task-log.jsonl` is migrated — see the note above). The
+session-digest stream is ground-truth; the task-log stream is self-reported —
+where they disagree, prefer the session digest.
+
+## Downstream extraction (no monorepo checkout)
+
+`/session-review`'s core steps (Extract/Analyze/Suggest above) now run from
+any installed plugin — `session_report.py --profile maintainer` ships
+inside the plugin package, closing #1779 at the root (#2046/#2047). Only
+two OPT-IN paths still require this monorepo's own dev checkout:
+`--cross-machine` sync/rollup and the raw-log semantic tier it gates — both
+deliberately self-referential to this marketplace repo's own cross-machine
+telemetry database (ADR 0032 Category 2), not something a downstream
+install has a database for.
+
+For a downstream user of the plugin who has no access to this repo but
+wants to hand the maintainer their own session data for analysis without
+running `/session-review`'s own orchestrated flow, use the sibling
+`--profile downstream`: `${CLAUDE_PLUGIN_ROOT}/scripts/session_report.py
+--profile downstream`. It ships inside the plugin package (so it's present
+after a normal `claude plugin install`), runs from a bare `python3` with no
+dependencies, and writes ONE metrics-only JSON file — for the current
+project, an explicit `--project <path>`, or `--all-projects` for every
+project the plugin has been used in on that machine. Same privacy stance as
+everything else in this doc: counts/ratios/names only, never prompt text,
+code, or command strings. The user sends the resulting file to the
+maintainer themselves (e.g. over MS Teams); the script has no network code
+and never transmits anything on its own.
+
+### Report schema (`downstream-session-report/v4`)
+
+Alongside the main-thread session at `<project>/<sessionId>.jsonl`, every
+dispatched agent writes its own transcript under
+`<project>/<sessionId>/subagents/` (a Workflow's agents nest one level deeper
+still). Both are read. Two fields distinguish the two signals a reader will
+otherwise conflate:
+
+**`--plugin-version VERSION` and its coverage (#2018).** Scopes the report
+to sessions whose project recorded `VERSION` in its own
+`.claude/metrics/boundary-events.jsonl` (best-effort — a session that never
+dispatched anything through a hook that stamps `session_id` can't be
+attributed and is excluded). Rather than dropping those sessions silently,
+the report's top-level `version_filter_coverage` field (non-null only when
+`--plugin-version` was passed) names `requested_version`,
+`sessions_considered`, `sessions_attributed`,
+`sessions_attributed_other_version` (a resolvable version, just not the
+requested one — the filter working as intended, not a data gap), and
+`sessions_unattributed` (no resolvable version at all) — see
+`knowledge/telemetry-schema.md`'s "Version-filtered downstream report
+coverage" note for the full contract. The exclusion behavior itself is
+unchanged; only its visibility is new.
+
+| Field | Meaning |
+|---|---|
+| `transcripts` / `subagent_transcripts` | main-thread sessions vs dispatched agent runs, both scoped to the reported window |
+| `token.by_agent_type` | **per-agent token buckets** (#2010), keyed by agent name — `main` for the main thread, `unattributed` where no agent is resolvable. Same vocabulary as cost-metering's `by_agent_type` (`knowledge/telemetry-schema.md`) and now the same field names as its buckets; deliberately NOT `by_subagent`, which means main-vs-sidechain in the maintainer profile |
+
+Each `token.by_agent_type` bucket carries:
+
+| Key | Meaning |
+|---|---|
+| `input_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` | the usage fields that make up what a dispatch **carried in** |
+| `output_tokens` | what it generated — tracked, but deliberately outside `context_tokens` |
+| `context_tokens` | the sum of the three context fields. Session telemetry puts ~90% of spend here, which is why this is the figure a panel-cost decision reads |
+| `messages` | assistant messages carrying usage — the value this key held on its own before #2010 |
+| `dispatches` | runs, counted one per subagent transcript. Never inferred from message volume, which would make a verbose agent look cheap per dispatch |
+| `context_per_dispatch` | `context_tokens / dispatches`, or **`null`** when `dispatches` is 0 (`main`, and any agent that never ran). Null rather than 0 so a never-dispatched agent cannot sort as the cheapest row |
+
+**Reconciliation invariant.** The per-agent `context_tokens` sum exactly to `token.totals`' three context fields. Both are derived from the same usage records, so a mismatch means a dispatch was double-counted or dropped; `tests/scripts/test_extract_session_report.py` pins it.
+
+**Not comparable across the #2010 boundary.** A pre-#2010 digest carries an int here. The cross-project merge preserves such a label at zero rather than summing a message count into a token total.
+| `utilization.agents_invoked` | agent RUNS, from each subagent transcript's `attributionAgent` — ground truth |
+| `utilization.agent_dispatches` | `Agent`/`Task` tool calls, i.e. dispatches requested |
+
+Transcripts are recognised by DEPTH: any `.jsonl` directly in a project
+directory is a main-thread session whatever it is named, while below
+`subagents/` only `agent-<id>.jsonl` counts.
+The harness writes bookkeeping alongside them — `subagents/workflows/<runId>/journal.jsonl`
+— which is not a transcript and is skipped. A Workflow's agents carry
+`attributionAgent: "workflow-subagent"`, a harness role rather than an agent name;
+their tokens count, but they land in `unattributed` rather than inventing an agent.
+
+Every string that becomes a report key passes a strict name filter, and anything
+failing it is aggregated under `other`. Report keys come from transcripts this
+script does not author — a cloned repo's own `.claude/agents/*.md` chooses
+`attributionAgent` — so the "names, never full paths" guarantee is enforced at the
+output boundary rather than trusted at each input site.
+
+`rework` answers at two scopes, deliberately: `retried_bash_commands` and
+`repeated_verify_runs` are per thread of execution (one transcript), while
+`repeated_file_edits`, `failed_edits`, `permission_denials` and `compaction_events`
+remain project-wide. A bash retry is a property of one agent's loop; a file is
+shared state.
+
+Runs and dispatches legitimately differ: a dispatch made from inside another
+agent appears only in that agent's own transcript, and a dispatch whose
+transcript is absent never ran. `agents_invoked` falls back to dispatch counts
+for a tree written by an older harness that produced no subagent transcripts.
+
+**v1 reports are not comparable to v2.** Before v2 (issue #1990) the extractor
+globbed only the main-thread layout, so subagent tokens, tool calls and runs
+were missing entirely — on the report that surfaced the bug, 41% of total spend.
+`retried_bash_commands` and `repeated_verify_runs` also changed basis in v2 —
+and still carry the v1 (project-wide, session-keyed) basis in `session-digest/v1`
+above, so the same names are not comparable across the two artifacts until #1994
+lands:
+they are now counted within one thread of execution rather than across a whole
+project, because subagents share their parent's `sessionId` and a session-keyed
+tally scores a review panel's siblings running one command each as retries.
+
+## OSS complements (#130)
+
+For continuous *quantitative* monitoring, reach for `ccusage`, native
+OpenTelemetry, or `claude-code-log` — they cover what `/session-review` does not.
+`/session-review` covers the plugin-specific *qualitative* suggestions they
+cannot, since they don't know this plugin's agents and skills. See
+`session-review-oss-complements.md`.
+
+## Child issues
+
+- #127 — deterministic session-log extractor (now `session_report.py --profile maintainer`, #2046)
+- #128 — `/session-review` skill + `session-analysis` agent + report
+- #129 — trend digest persistence + harness-audit consumption
+- #130 — document OSS complements
+- #1990 — count subagent transcripts (`downstream-session-report/v2`)

package/docs/upstream/skills.md

@@ -0,0 +1,188 @@
+# Skills
+
+<!-- GENERATED FILE — do not edit by hand.
+     Rows: each plugins/dev-team/skills/<name>/SKILL.md frontmatter (name, description).
+     Grouping: plugins/dev-team/hooks/lib/skill_categories.yaml (by capability).
+     Regenerate: python3 plugins/dev-team/hooks/lib/build_skills_index.py
+     A CI freshness gate (--check) fails if this file drifts from the skills on disk. -->
+
+Skills are the unified reusable capability layer in this system. Every skill lives in `skills/<name>/SKILL.md`. This catalog groups them **by capability** (the sections below); each row's description is the skill's own frontmatter `description`, verbatim.
+
+Most skills are **user-invocable** as slash commands — shown as `/name`; run them directly or let the Orchestrator dispatch them. The rest are **agent-loaded** knowledge modules — shown as a plain `name` — that agents read for domain expertise.
+
+
+## Specs & Planning
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/api-design` | no flags — run directly | [`api-design/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/api-design/SKILL.md) | Contract-first API design for stable, evolvable interfaces. Use whenever defining a new API endpoint, inter-service boundary, or modifying an existing contract. Includes backward compatibility checklist and error contract specification. |
+| `/design-doc` | no flags — run directly | [`design-doc/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/design-doc/SKILL.md) | Produce a written design document in docs/specs/ with user approval before planning begins. Use this skill during the Research phase when a feature request, architectural change, or non-trivial task enters the pipeline. Ensures misunderstandings are caught before any planning or implementation work starts. Also use when the user says "brainstorm", "design", "spec", or "let's think through this". |
+| `/design-interrogation` | no flags — run directly | [`design-interrogation/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/design-interrogation/SKILL.md) | Relentlessly interview the user about a plan, design, or feature spec to surface unresolved decisions, hidden assumptions, and edge cases. Use when the user says "grill me", "stress-test this plan", "poke holes in my design", "what am I missing", or before committing to a plan that feels under-examined. Unlike /specs (which produces artifacts) this skill produces clarity — it's a thinking tool. Also use proactively in the Research phase when a design doc has implicit decisions that need to be made explicit. |
+| `/design-it-twice` | no flags — run directly | [`design-it-twice/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/design-it-twice/SKILL.md) | Generate multiple radically different interface designs for a module using parallel sub-agents, then compare and synthesize. Based on Ousterhout's "Design It Twice" principle. Use when the user wants to explore interface options, design an API, compare module shapes, or says "design it twice", "what are my options", or "show me alternatives". Also use when the Architect agent is designing a new module boundary or public interface. |
+| `/feature-file-validation` | no flags — run directly | [`feature-file-validation/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/feature-file-validation/SKILL.md) | Validate Gherkin feature files for structural quality, determinism, and implementation independence, then verify each scenario has matching test automation. Use this skill whenever reviewing test files, feature files, or BDD scenarios — including during /code-review when .feature files or step definition files appear in the changeset. Also use when a user asks to "check my feature files", "validate my Gherkin", "are my scenarios testable", or "do my feature files have tests". |
+| `/gherkin-derive` | <repo-path> [--mode none\|xunit-with-annotations\|bdd-runner] [--repo-slug <slug>] | [`gherkin-derive/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/gherkin-derive/SKILL.md) | Derive Gherkin scenarios directly from a codebase — standalone, with no prior legacy-modernization analysis. Discovers the public surface (OpenAPI, routes, existing tests, exported signatures, plus message-queue, cron, and websocket/GraphQL surfaces), recommends a BDD binding mode via the bdd-value-guide rubric, and merges scenarios into `.feature` files (preserving prior enrichment, never overwriting) plus (in bdd-runner mode) pending step-definition stubs. Use it on its own to capture intended behavior before changing tests, or as Phase 3 of `/test-improve`. Creates no tracker Stories. |
+| `/gherkin-public` | <repo-path> [--repo-slug <slug>] [--parent <issue-url>] [--create-stories] | [`gherkin-public/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/gherkin-public/SKILL.md) | Author Gherkin scenarios for the entire public interface of a repository — every API endpoint, UI screen, batch-job entry point, library export, and event type — at the observable boundary, not internal steps. The scenarios become the executable specification of intended behavior before any test or production-code change lands. After the operator approves the scenarios at the Phase-2 gate, this skill also creates the Phase-4 and Phase-5 `[Component tests]` Stories that will bind their test code to specific scenario names — so the component tests are written from the approved Gherkin, not from the assessment. |
+| `/issues-from-assessment` | <assessment-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--refactor-mode <no-refactor\|refactor-allowed>] [--dry-run] | [`issues-from-assessment/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/issues-from-assessment/SKILL.md) | Convert a `/cd-test-architecture` assessment into a parent + Phase-tagged child issues on the tracker the operator points at (ADO, GitHub, GitLab, Jira). Dispatches by parent URL host to the tracker's own CLI (`az boards`, `gh`, `glab`, `acli`). When no parent URL is given, or when the required CLI is not installed, falls back to local plan files under `.claude/plans/<workflow>/` after informing the operator. Multi-workflow: called by `/test-improve` (Phase 4), via its own `--workflow` namespace so memory paths and tracker labels never collide. |
+| `/issues-from-plan` | [plan file path] | [`issues-from-plan/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/issues-from-plan/SKILL.md) | Break a plan into independently-grabbable GitHub issues. Use when the user says "create issues from this plan", "break this into tickets", "file issues", or wants to distribute plan steps across a team. |
+| `/plan` | <task-description> [--output <path>] [--yes] [--spec-issue <url>] | [`plan/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/plan/SKILL.md) | Create a structured implementation plan with goal, acceptance criteria, incremental Code-First Small Batches steps, and a pre-PR quality gate. Use this for tasks that need a plan but not the full three-phase orchestration, or when the user says "plan this", "make a plan", "break this down", or "how should I implement this". |
+| `/specs` | no flags — run directly | [`specs/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/specs/SKILL.md) | Collaborative workflow for producing the three specification artifacts (intent, architecture notes, acceptance criteria) that describe a change and its goals before any implementation begins. Its value is resolving ambiguity with a human before build starts — not synthesizing edge cases. Use when starting any new feature or behavior change — do not write code until artifacts pass the consistency gate. BDD/Gherkin scenarios are authored later, per slice, in /plan. |
+
+
+## Build & Ship
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/autoship` | --max-issues N --max-cost-usd N [--dry-run] [--label LABEL] [--max-batch-size N] | [`autoship/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/autoship/SKILL.md) | Orchestrate a bounded round of automated issue processing: reclaim orphaned in-progress issues, discover eligible `autoship:ready` issues, and invoke `/ship` sequentially for each — stopping at cost or count caps and surfacing blocked items without halting the round. Requires `--max-issues` and `--max-cost-usd`. Use when you want a self-contained automated delivery round driven from the issue tracker. |
+| `/branch-workflow` | no flags — run directly | [`branch-workflow/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/branch-workflow/SKILL.md) | Clean branch completion workflow — PR creation, merge strategy, and cleanup. Use this skill when implementation is complete and it's time to ship — after Phase 3 human gate passes. Also use when the user says "create a PR", "merge this", "ship it", "finish this branch", or asks about merge strategy. |
+| `/build` | [--plan <path>] [--yes] [--backstop-review=skip] | [`build/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/build/SKILL.md) | Execute an approved implementation plan in small per-behavior batches. Reads the plan, implements each step one behavior at a time in the Code-First Small Batches cadence with a refactor on every green, runs inline review checkpoints, and produces verification evidence. Use when the user says "build this", "implement the plan", "start building", or after /plan has been approved. |
+| `/continue` | no flags — run directly | [`continue/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/continue/SKILL.md) | Resume work from a prior session by reading phase progress files in .claude/memory/ and active plans. Use this when starting a new session on in-progress work, or when the user says "continue", "pick up where I left off", "resume", or "what was I working on". |
+| `/pr` | [--skip-review] [--draft] [--base <branch>] | [`pr/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/pr/SKILL.md) | Run a pre-PR quality gate (tests, typecheck, lint, code review) and then create a pull request with a structured summary. Use when the user says "create a PR", "open a PR", "submit for review", or "I'm done with this feature". |
+| `/ship` | <feature-description> [--skip-spec] [--no-auto-merge] [--force-restart] [--issues <n1,n2>] | [`ship/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/ship/SKILL.md) | Run the full spec-to-merge pipeline as one command: spec, plan, small-batch build, code review, and a PR with auto-merge — pausing at the existing human gates. Idempotent per issue — a re-invocation for work already shipped or in-flight resumes/monitors instead of re-running the pipeline. Use when the user says "ship this", "take this feature end to end", "implement this issue", "we need to build", or wants the spec->plan->build->PR flow without re-assembling it each time. |
+| `/test-driven-development` | no flags — run directly | [`test-driven-development/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-driven-development/SKILL.md) | Advisory reference for the Classic RED-GREEN-REFACTOR TDD discipline with hard gates — not a build cadence toggle. The plugin's single build cadence is Code-First Small Batches (docs/experiments/RECOMMENDATIONS.md Rec 3); /build does not dispatch into this skill. Use on explicit user request when someone wants test-first discipline for the code being written, or when reviewing code to verify TDD discipline was followed by hand. |
+
+
+## Code Review & Static Analysis
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/apply-fixes` | <corrections-dir> [--dry] [--skip-tests] [--skip-build] [--skip-lint] | [`apply-fixes/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/apply-fixes/SKILL.md) | Apply correction prompts generated by /code-review. Use this whenever the user wants to apply, fix, or action the results of a code review — phrases like "apply the fixes", "fix the issues", "apply corrections", or after /code-review has run and produced a corrections/ directory. |
+| `/code-review` | [--agent <name>] [--since <ref>] [--path <dir>] [--all] [--json] [--expand <finding-id>\|all] [--internal] [--force --reason "<text>"] [--static-analysis\|--no-static-analysis] [--init-risks] [--background] [--pdf] | [`code-review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/SKILL.md) | Run all enabled review agents against target files. Use this whenever the user asks for a code review, wants feedback on their code, says "review my code", "check this before I PR", "what's wrong with this", "run the agents", or has just finished implementing a feature. Use proactively before commits and pull requests. |
+| `/frontend-architecture` | [--path <dir>] [--since <ref>] [--all] [--json] | [`frontend-architecture/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/frontend-architecture/SKILL.md) | Frontend component architecture review — dispatch the component-architecture-review agent over the frontend component files to catch reusable components that should be extracted, duplicated UI patterns, prop drilling, component-granularity problems, and inconsistent component APIs as a frontend evolves. Use when the user says "review the frontend architecture", "are my components reusable", "is this UI duplicated", "should this be a shared component", "check for prop drilling", or before extracting a component library. Advisory — it recommends, it does not edit. |
+| `/review` | [--agent <name>] [--since <ref>] [--path <dir>] [--all] [--json] [--internal] [--force --reason "<text>"] [--static-analysis\|--no-static-analysis] [--init-risks] [--background] | [`review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/review/SKILL.md) | Alias for /code-review. Run all enabled review agents against target files. Use this whenever the user asks for a code review, wants feedback on their code, says "review my code", "check this before I PR", "what's wrong with this", "run the agents", or has just finished implementing a feature. |
+| `/review-agent` | <agent-name> [--since <ref>] [--path <dir>] [--internal] [--json] | [`review-agent/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/review-agent/SKILL.md) | Run a single named review agent against target files. Use this when the user names a specific agent (e.g. "run security-review", "check for test issues", "run js-fp-review on this file") rather than wanting the full suite. Prefer this over /code-review when only one concern is relevant or speed matters. Also used by the orchestrator for inline review checkpoints during Phase 3 implementation. |
+| `/review-summary` | [--from <json-file>] | [`review-summary/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/review-summary/SKILL.md) | Generate a compact summary of the most recent code review results and save it for future sessions. Use this at the end of a coding session after /code-review has run, or when the user says "summarize the review", "save the results", "generate a summary", or wants to preserve review context before closing a session. |
+| `/semantic-duplication-scan` | no flags — run directly | [`semantic-duplication-scan/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/semantic-duplication-scan/SKILL.md) | Detect business logic reimplemented in multiple architectural layers. Builds a persistent computation-register.json by annotating non-trivial computation functions with structured semantic descriptions, then clusters entries to surface duplicate domain concepts. Runs in full-scan mode on first use, incremental (git-diff-based) mode on subsequent runs. Use when the user wants to find logical duplication that linters and diff-scoped review agents miss — the same domain calculation independently reimplemented across layers. |
+| `/semantic-scan` | [path] [--full] [--no-opus] | [`semantic-scan/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/semantic-scan/SKILL.md) | Build a computation register and detect semantic duplicates across architectural layers. Finds business logic reimplemented multiple times in different layers — the same domain calculation independently appearing in domain services, client adapters, and presentation components. Runs incrementally (git-diff-based) after the first scan. Produces a structured duplicate report with file:line references and canonical location suggestions. |
+| `/semgrep-analyze` | [path] [--rules <ruleset>] | [`semgrep-analyze/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/semgrep-analyze/SKILL.md) | Run Semgrep static analysis on target files and return structured findings. Use this when the user wants static analysis, SAST scanning, or security scanning — phrases like "run semgrep", "scan for vulnerabilities", "static analysis on this code", or as a pre-review gate when security findings are needed before AI agents run. |
+| static-analysis-integration | agent-loaded — not directly invocable | [`static-analysis-integration/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/SKILL.md) | SARIF-first pre-pass stage for /code-review that runs available static analysis tools and normalizes their output to the unified finding envelope defined in security-primitives-contract v1.0.0. Deduplicates findings across tools and passes confirmed issues to AI agents so they can focus on semantic concerns. |
+
+
+## Testing & Coverage
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/apply-test-doubles` | [<report-path-or-target>] [--component <name>] [--yes] | [`apply-test-doubles/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/apply-test-doubles/SKILL.md) | Apply `/cd-test-architecture`'s Step 4b build-vs-document decision logic against an existing, saved assessment report — or, when no valid report path is given, against a target to assess first — without re-running the full Steps 0-6 assessment each time. Use when the user wants to revisit or change a component's Build/Document choice from a saved cd-test-architecture report, says "apply the test doubles", "re-run Step 4b", "change the build-vs-document decision", or cites the `/apply-test-doubles <path>` command from a test-double setup guide. |
+| `/cd-test-architecture` | [--component <name>] [--ci <path>] [--external-tests <path>] [--stack <id>] [--pdf] [--yes] | [`cd-test-architecture/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/cd-test-architecture/SKILL.md) | Evaluate an existing application's tests and recommend a CD-pipeline-aligned test architecture — fast, deterministic tests with minimal tooling that fully validate behavior (including cross-service interaction) and run in CI without configuring the rest of the system. Use when the user says "evaluate how this app is tested", "design a test architecture", "align our tests for CD", "make our CI tests deterministic", "our tests need the whole system configured", "our tests live in another repo / Postman / manual scripts", or asks for UI/service/batch test patterns. |
+| `/coverage-baseline` | <repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] | [`coverage-baseline/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/coverage-baseline/SKILL.md) | Multi-workflow coverage baseline worker. Detects the repo's coverage tool from its build manifest, runs it, records the resulting line+branch percentages as the baseline, and posts the number to the parent issue (or local `FEATURE.md`). This number is the floor every later phase must improve on. Called by `/test-improve` (Phase 2) via `--workflow test-improve`. |
+| `/coverage-delta` | <repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--story <id-or-path>] [--story-files <glob-or-comma-list>] | [`coverage-delta/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/coverage-delta/SKILL.md) | Multi-workflow coverage delta worker. Reads the baseline coverage, re-runs the same coverage tool against the current suite, computes the delta on line+branch percentages, and posts it to the parent issue (or local `FEATURE.md`). Called after each Story so the operator sees coverage move with every test added. Called by `/test-improve` (Phase 5) via `--workflow test-improve`. |
+| `/exploratory-testing` | no flags — run directly | [`exploratory-testing/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/exploratory-testing/SKILL.md) | Charter-driven exploratory testing — probe a running feature/endpoint with structured heuristics, evaluate charter quality, run adversarial expansion, classify defects, and auto-triage critical findings into an incremental report. Use when the user runs /explore, says "explore this endpoint", "poke at this feature", "find bugs in the running app", or wants hands-off exploratory testing of a live target. |
+| `/explore` | --charter '<goal>' [target] [--probe-budget <n>] [--invariants '<expr,...>'] [--no-adversarial] [--force] | [`explore/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/explore/SKILL.md) | Charter-driven exploratory testing of a running feature or endpoint. Dispatches the QA Engineer in "Chaos Specialist" mode to probe with structured heuristics (Goldilocks, Happy-Path Divergence, Telemetry Deepening, Invariant Probing, CRUD Sweep), run adversarial expansion, and auto-triage critical defects into an incremental report. Use when the user says "explore this endpoint", "poke at this feature", or wants hands-off exploratory testing of a live target. |
+| `/farley-score` | no flags — run directly | [`farley-score/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/farley-score/SKILL.md) | Evaluate test quality using Dave Farley's 8 properties with a weighted Farley Score. Use when reviewing test suites, after writing tests, or when the user says "score my tests", "test quality", "Farley score", or "how good are my tests". |
+| `/legacy-code` | no flags — run directly | [`legacy-code/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/legacy-code/SKILL.md) | Safely modify code that lacks tests. Use whenever tasked with changing code without test coverage — apply characterization tests and dependency-breaking techniques before making any behavioral changes. |
+| `/mutation-testing` | no flags — run directly | [`mutation-testing/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/mutation-testing/SKILL.md) | Validate test suite quality by running a real mutation testing tool and triaging surviving mutants. Use after writing tests to verify assertions catch behavioral changes, when evaluating test coverage quality, or as a CI quality gate on critical modules. The AI value here is triage — classifying survivors, writing fix tests — not generating or estimating mutations. |
+| `/quality-targets-converge` | <repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--max-iterations <n>] [--refactor-mode <no-refactor\|refactor-allowed>] | [`quality-targets-converge/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/quality-targets-converge/SKILL.md) | Multi-workflow convergence worker. Closes the gap between the current test suite and the four quality targets (line+branch coverage ≥ 90%, zero surviving mutants, 100% deterministic, fastest pre-merge wall-clock achievable on-machine). Each iteration reads the latest measurements, picks the largest gap, and dispatches the smallest action that moves it. Stops only when all four targets are green or each gap is explicitly waived by the operator with a recorded reason. Called by `/test-improve` (Phase 8) via `--workflow test-improve`. |
+| `/test-audit-disable` | <repo-path> [--repo-slug <slug>] [--dry-run] | [`test-audit-disable/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-audit-disable/SKILL.md) | Standalone worker. Audits the existing test suite for tests that cannot fail — no assertions, assertions on constants, expect-true, swallowed exceptions, self-equality — and disables each one by skip-and-tag (never deletes). Records each disabled test plus its reason in a JSON log under `.claude/memory/<workflow>/<slug>/` so a later phase can repair them. Pairs with `/coverage-baseline` to produce a true baseline coverage number. |
+| `/test-design` | [--path <dir>] [--since <ref>] [--advise] | [`test-design/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-design/SKILL.md) | Deep test-design review and forward-design advisor. Dispatches test-review (tactical quality) and test-smell-review (xUnit smells, double selection, pyramid placement) in parallel, and runs the test-design-advisor worker to recommend how to test hard-to-test code. Use when the user says "review my tests", "how should I test this", "is this testable", "design tests for this", "what's the right test for X", "test design review", or before writing a suite for an untested module. For a single unit, pass --advise --path <file>. Advisory — it recommends, it does not edit. |
+| test-design-advisor | agent-loaded — not directly invocable | [`test-design-advisor/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-design-advisor/SKILL.md) | Worker skill — assess testability, recommend the right test-pyramid layer and test-double strategy, and propose a behavior-preserving refactor sequence to make hard-to-test code testable. Invoked by /test-design and /test-health; not user-invocable. For a user-facing entry point use /test-design (add --advise --path <file> for forward-design on a single unit). |
+| `/test-health` | [--path <dir>] [--pdf] [--no-mutation] | [`test-health/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-health/SKILL.md) | Project-wide test-strategy audit — derive the suite's shape and shape-vs-architecture fit, map coverage to the Agile Testing Quadrants, roll up coverage + mutation health, flag flaky tests and automation maturity, and produce an ordered improvement plan. Delegates CD-determinism + pipeline assessment to cd-test-architecture. Use when the user says "audit our tests", "how healthy is our test suite", "test strategy review", or runs /test-health. Advisory — writes a report, does not edit. |
+
+
+## Security
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/docker-image-audit` | no flags — run directly | [`docker-image-audit/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/docker-image-audit/SKILL.md) | Audit Docker images and Dockerfiles for security vulnerabilities, bloat, and best-practice violations using hadolint, Trivy, and Grype. Produces a structured severity report with actionable fixes. Use this skill whenever the user wants to check a Docker image for security issues, scan a container for vulnerabilities, audit a Dockerfile, harden a Docker image, reduce image size, minimize attack surface, check for CVEs in a container, or says things like "is this Dockerfile secure?", "scan my image", "check my container for vulnerabilities", "how can I make this image smaller?", "audit my Docker setup", or "harden this container". Also trigger when the user has just created or modified a Dockerfile and wants validation before shipping it. |
+| `/governance-compliance` | no flags — run directly | [`governance-compliance/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/governance-compliance/SKILL.md) | Audit logging, quality gates, and ethics procedures for the agent team. Use for periodic compliance reviews, when logging task completion events, or when an ethical concern arises that requires human escalation. |
+| `/threat-modeling` | no flags — run directly | [`threat-modeling/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/threat-modeling/SKILL.md) | Structured STRIDE security analysis for identifying threats, attack surfaces, and mitigations. Use before implementing any new API, service, authentication change, or data flow crossing trust boundaries — security analysis belongs in the design phase, not after. |
+
+
+## Architecture & Domain Modeling
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/adr-tools` | no flags — run directly | [`adr-tools/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/adr-tools/SKILL.md) | Create and manage Architecture Decision Records using the npryce adr-tools CLI. Use when the user asks to "add an ADR", "record this decision", "create an ADR", "supersede ADR N", "link ADRs", "generate the ADR table of contents", or any request involving the `adr` command. Pairs with the adr-author agent — this skill is the mechanics (commands, files, links); adr-author is the decision framework (when an ADR is warranted) and the prose authoring. |
+| `/domain-analysis` | no flags — run directly | [`domain-analysis/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/domain-analysis/SKILL.md) | Strategic DDD health assessment of an existing system. Use whenever someone asks to analyze their architecture, assess domain health, find coupling problems, map bounded contexts, trace event flows across services, or understand what is slowing down delivery. Trigger on phrases like "what's wrong with our architecture", "where is the coupling", "assess our domain", "event storming", "value stream", "friction report", "bounded contexts", or "why is everything so tangled". Apply to existing codebases — use domain-driven-design skill for greenfield modeling. |
+| `/domain-driven-design` | no flags — run directly | [`domain-driven-design/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/domain-driven-design/SKILL.md) | Model software around the business domain. Use when designing bounded contexts, defining aggregates and value objects, mapping context relationships, or working with complex business logic. Apply before implementation to prevent model drift. |
+| `/hexagonal-architecture` | no flags — run directly | [`hexagonal-architecture/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/hexagonal-architecture/SKILL.md) | Design with ports and adapters to separate business logic from infrastructure. Use when designing a new service, reviewing structural compliance, or deciding how to introduce a new external dependency without coupling the domain. |
+| `/mermaid-diagramming` | no flags — run directly | [`mermaid-diagramming/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/mermaid-diagramming/SKILL.md) | Create Mermaid diagrams using the project's blue-gray theme. Use whenever the user asks to draw a diagram, create a flowchart, visualize a process, document architecture, or add any Mermaid diagram to a markdown file. Trigger on phrases like "draw a diagram", "create a flowchart", "visualize this", "add a mermaid diagram", "document the flow", "sequence diagram", "architecture diagram", or any request to diagram a process or system. |
+| `/ubiquitous-language` | [path-to-source-root] | [`ubiquitous-language/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/ubiquitous-language/SKILL.md) | Build or refresh the project's ubiquitous language glossary — one markdown file per business concept at `.plans/domain/<Concept>.md` plus a `_index.md`. Mines grep-based signals (class names, enum values, interface names, domain-event names, BDD scenario names, validator rules) and applies a four-gate filter to keep only genuine business concepts. Optional interactive interview phase to refine definitions and capture behavior (state transitions, invariants, synonyms to avoid). Language-agnostic — works for JS/TS, C#, Java, Python, Go, or any mix. Use whenever the user says "build the glossary", "extract domain terms", "document the ubiquitous language", "what are the domain concepts", or when domain-review surfaces pervasive terminology inconsistency (3+ names for the same concept). |
+
+
+## Performance, Containers & Browser
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/benchmark` | <url> [--baseline] [--budget] [--trend] [--mobile] [--3g] [--runs <n>] | [`benchmark/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/benchmark/SKILL.md) | Capture runtime performance metrics (Core Web Vitals, resource sizes, load times) for web pages. Compare against baselines and performance budgets. Use when the user says "benchmark", "check performance", "page speed", "web vitals", "performance regression", or "how fast is this page". |
+| `/browse` | <url> [--screenshot <path>] [--click <selector>] [--fill <selector> <value>] [--wait <ms>] [--viewport <WxH>] | [`browse/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/browse/SKILL.md) | Launch a browser to navigate URLs, take screenshots, click elements, and fill forms. Use for visual verification, e2e testing, and interactive debugging. |
+| browser-testing | agent-loaded — not directly invocable | [`browser-testing/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/browser-testing/SKILL.md) | Patterns and templates for browser-based QA using Playwright. Covers navigation, form interaction, screenshot capture, visual verification, and CAPTCHA/auth handoff. |
+| `/docker-image-create` | no flags — run directly | [`docker-image-create/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/docker-image-create/SKILL.md) | Generate production-ready Dockerfiles from project source code. Detects language/framework automatically and produces multi-stage builds with minimal, distroless, or slim base images. Use this skill whenever the user wants to containerize an application, create a Dockerfile, dockerize a project, build a Docker image, or says things like "make this run in Docker", "create a container for this app", "I need a Dockerfile", "package this for deployment", or "containerize this service". Also trigger when the user has an existing Dockerfile and wants it rewritten for production use, or when they ask about Docker best practices for their project. |
+| performance-benchmark | agent-loaded — not directly invocable | [`performance-benchmark/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/performance-benchmark/SKILL.md) | Capture runtime performance metrics (Core Web Vitals, resource sizes, load times) against defined budgets. Compare to baselines, flag regressions, and maintain trend history. Complements the code-level performance-review agent with actual runtime measurement. |
+
+
+## Debugging & Diagnostics
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/ci-debugging` | no flags — run directly | [`ci-debugging/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/ci-debugging/SKILL.md) | Systematic CI/CD failure diagnosis with hypothesis-first approach, environment delta analysis, and anti-patterns. Use when CI fails, pipelines break, or the user says "CI is failing", "build broke", "pipeline error", or "tests pass locally but fail in CI". |
+| `/fix` | <bug description> [--triage-record <path>] | [`fix/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/fix/SKILL.md) | Investigate a bug via /triage (or reuse an existing triage record), prove the defect reproduces, then implement the record's TDD Fix Plan one RED/GREEN cycle at a time with a regression check after each cycle, close the record, and delegate to /pr for a reviewed pull request. Use when the user reports a bug and wants it fixed end-to-end, says "fix this bug", or wants a hands-off defect fix that closes the loop /triage leaves open. |
+| `/systematic-debugging` | no flags — run directly | [`systematic-debugging/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/systematic-debugging/SKILL.md) | Four-phase debugging protocol (reproduce, investigate, root-cause, fix) that prevents guess-and-fix thrashing. Use this skill whenever a test fails, a bug is reported, an error occurs during implementation, or any unexpected behavior is encountered. Prevents the common LLM failure mode of guessing at fixes without understanding the problem. |
+| `/triage` | <bug description or error message> [--pdf] | [`triage/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/triage/SKILL.md) | Investigate a bug, find its root cause, and write a portable triage record to .dev-team-reports/triage/<slug>.md with a TDD fix plan. Use when the user reports a bug and wants it triaged, says "triage this", "investigate and write it up", or wants a hands-off bug investigation that produces an actionable record. |
+
+
+## Setup, Config & Plugin Management
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/help` | [--all] | [`help/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/help/SKILL.md) | List the main dev-team workflows, with an option to show every user-invocable slash command. |
+| `/project-init` | [--yes] [--force] | [`project-init/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/project-init/SKILL.md) | Get a repository ready for the dev-team toolchain in one command — detect the tech stack (JS/TS, Python, C#, Java), inventory the static-analysis tools the project already has, confirm a plan, and install only what's missing, repo-level. This is the canonical source of truth for tech-stack detection and toolchain installation — NOT dev-team-specific config (CLAUDE.md generation, agent template activation, PostToolUse hooks, the generated `/pr` command all live in `/setup`, which invokes this skill first for the stack signal). Also installs the detection-gated capability tools other skills depend on — semgrep, Playwright + Chromium, adr, gh, and the docker scanners (hadolint/trivy/grype). For JavaScript it scaffolds a new project with ES modules, functional style, prettier, oxlint, editorconfig, vitest, and gitignore. Use this skill whenever the user wants to start a new JS project, scaffold a Node.js app, create a new package, bootstrap a JavaScript repo, or says things like "init a new project", "set up a JS project", "create a new node app", "start a new frontend project", or "bootstrap a new package". Also trigger when the user says "set up my project's toolchain", "install the linters for this repo", "get this repo ready for the plugin", or asks to add standard tooling (linting, formatting, testing) to a new or existing project in any supported language. |
+| `/setup` | [--yes] [--dry-run] [--autocompact-pct N] [--no-autocompact] | [`setup/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/setup/SKILL.md) | Provision a repo for the dev-team plugin end to end — install the plugin's own prerequisites (jq, python3, per-language mutation tooling — Stryker, pitest, Stryker.NET), then generate dev-team-specific project configuration — project-level CLAUDE.md, the PostToolUse formatting hook, language-specific agent template activation, and a generated `/pr` command — from the stack signal `/dev-team:project-init` establishes. This is NOT where toolchain detection/installation itself lives (that's `/project-init`); `/setup` only consumes it. Use this when onboarding a new project to the dev-team plugin, when the mutation gate reports a missing tool, or when the user says "setup", "bootstrap", "configure this project for dev-team", "install required tools for the dev-team plugin", or "activate agent templates". |
+| `/upgrade` | no flags — run directly | [`upgrade/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/upgrade/SKILL.md) | Check for and apply plugin updates using the official Claude Code plugin update mechanism. |
+| `/version` | no flags — run directly | [`version/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/version/SKILL.md) | Report the installed version of the dev-team plugin. |
+
+
+## Session, Context & Telemetry
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/artifact-lifecycle` | no flags — run directly | [`artifact-lifecycle/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/artifact-lifecycle/SKILL.md) | Report on skill and agent usage data from ~/.claude/metrics/artifact-usage.json, classifying each artifact as active, stale (>= 30 days unused), or an archive candidate (>= 90 days unused). Proposes CLAUDE.md overrides for stale artifacts and exclusions for archive candidates. Pinned skills are always exempt. Use when the user asks to "review artifact lifecycle", "find stale skills", or "/artifact-lifecycle". |
+| `/context-loading-protocol` | no flags — run directly | [`context-loading-protocol/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/context-loading-protocol/SKILL.md) | Decide which agents and skills to load for a given task. Use at the start of every task to select the minimum viable context load, calculate the token budget, and stay below the 40% utilization ceiling. |
+| `/cost-report` | [--transcript <path>] [--tolerance <n>] | [`cost-report/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/cost-report/SKILL.md) | Report actual token spend and dollar cost of dispatched work — per agent and total — and flag cost regressions. Use when the user asks "how much did that cost", "token spend", "cost of this run", "cost report", or wants to check for a cost regression after /code-review or an orchestration run. |
+| `/handoff` | no flags — run directly | [`handoff/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/handoff/SKILL.md) | Compress or split off context for another session to pick up. Use to compress conversation history when context utilization approaches 40% (continue mode), or to split off a distinguishable out-of-scope side-task to an independent session (fork mode) — write a structured artifact for the other session and free the current one. |
+| `/performance-metrics` | no flags — run directly | [`performance-metrics/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/performance-metrics/SKILL.md) | Log task completion data to .claude/metrics/. Use at the end of every task to record tokens, cost, agents used, rework cycles, and hallucination events. Also use for periodic reporting to identify efficiency and quality trends. |
+| `/session-review` | [--cwd <path>] [--transcript <file>] [--out <report>] [--cross-machine] | [`session-review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/session-review/SKILL.md) | Mine real Claude Code session transcripts to suggest plugin improvements that cut token spend, reduce re-work, and improve accuracy. Use when the user asks to "review my sessions", "where am I wasting tokens", "why does this keep re-doing work", or "/session-review". |
+| `/telemetry` | [on\|off\|status\|report] | [`telemetry/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/telemetry/SKILL.md) | Manage and report the opt-in, privacy-clean usage telemetry beacon. Use when the user asks to "enable/disable telemetry", "show telemetry", "usage stats", "which commands do I use", or "how often is the commit gate bypassed". |
+
+
+## Safety Modes
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/careful` | [off] | [`careful/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/careful/SKILL.md) | Toggle careful mode. When active, destructive commands (rm -rf, force-push, DROP TABLE, etc.) are blocked instead of just warned about. |
+| `/freeze` | <glob-pattern> | [`freeze/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/freeze/SKILL.md) | Scope-lock file editing to a specific glob pattern. Only files matching the pattern can be edited until /unfreeze is called. |
+| `/guard` | <glob-pattern> | [`guard/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/guard/SKILL.md) | Activate both careful mode and freeze mode together. Blocks destructive commands and scope-locks editing to the specified pattern. Use for production-critical debugging sessions. |
+| `/unfreeze` | no flags — run directly | [`unfreeze/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/unfreeze/SKILL.md) | Lift the scope lock set by /freeze. All files become editable again. |
+
+
+## Harness Governance & Tuning
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/agent-audit` | [file-path \| --all] [--fix] | [`agent-audit/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/agent-audit/SKILL.md) | Audit code-review agents, skills, and hooks for structural compliance. Use this when adding or modifying any agent, skill, or hook file, or for a periodic health check of the toolkit. Trigger phrases: "audit the agents", "check compliance", "validate the skills", "are the agents correct", or any time agent/skill files change. |
+| `/agent-eval` | [--agent <name>] [--skill <name>] [--fixture <name>] [--trials <n>] [--in-session] [--integration] [--ablation <agent>] [--no-cache] [--verbose] | [`agent-eval/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/agent-eval/SKILL.md) | Run eval fixtures against review agents and grade results. Use this after adding or modifying a review agent, to validate detection accuracy, or when the user says "run the evals", "test the agents", "check for regressions", or "how accurate is the agent". |
+| `/agent-readiness` | [repo-path] [--json <file>] [--markdown <file>] | [`agent-readiness/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/agent-readiness/SKILL.md) | Score how ready the current repository is for AI-assisted development against the Agent-Readiness Scorecard. Use when the user asks "how agent-ready is this repo", "score this repo for agents", "agent readiness", or wants a tiered readiness report. Scores YOUR project repo's readiness — not the dev-team plugin's own review agents and routing (for that, use /harness-audit). |
+| `/competitive-analysis` | no flags — run directly | [`competitive-analysis/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/competitive-analysis/SKILL.md) | Compare this plugin against external plugins, tools, feature sets, or ideas to find gaps and weaknesses. Produces a structured gap analysis report with rough specs for closing each gap. Use this skill whenever the user references capabilities from OUTSIDE the plugin — another plugin they found, a competitor's tool, a feature list from a different project, a repo URL, or a hypothetical concept for capabilities we lack. Trigger phrases include "how do we compare to X", "what does Y have that we don't", "what are we missing", "gap analysis", "competitive analysis", "weaknesses compared to", "stack up against", "where do we fall short", and "should we add X — I saw it in another tool". Also trigger when the user pastes a feature list or describes capabilities they saw elsewhere and asks whether we should have them. Do NOT trigger for internal operations like running reviews, auditing our own agents, adding skills, threat modeling, domain analysis, or debugging — those use other skills. |
+| `/feedback-learning` | no flags — run directly | [`feedback-learning/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/feedback-learning/SKILL.md) | Capture amend/learn/remember/forget keywords from the user and update agent or skill configurations. Invoke immediately when the user issues any of these trigger words — parse the change, preview a diff, apply it, and log it to the audit trail. |
+| `/harness-audit` | [--output <path>] [--pdf] | [`harness-audit/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/harness-audit/SKILL.md) | Analyze review agent effectiveness, model routing, and orchestration complexity against actual usage data. Produces a report of harness components that may be candidates for simplification or removal. Use periodically to prevent harness staleness as model capabilities improve. Audits the dev-team plugin's OWN harness from runtime metrics — not your project repo's readiness (for that, use /agent-readiness). |
+| `/human-oversight-protocol` | no flags — run directly | [`human-oversight-protocol/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/human-oversight-protocol/SKILL.md) | Approval gates, intervention commands, and transparency requirements. Use to classify any agent action as autonomous/notify/approve, respond to override/pause/stop commands, or structure a plan review before the implementation phase begins. |
+| `/quality-gate-pipeline` | no flags — run directly | [`quality-gate-pipeline/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/quality-gate-pipeline/SKILL.md) | Unified quality gate for agent output — self-validation, verification evidence, and review-correction loops. Consolidates accuracy-validation, verification-before-completion, and task-review-correction into a single three-phase pipeline. Use before delivery, at completion, and during rework. |
+
+
+## Other
+
+| Skill | Options | File | Description |
+| --- | --- | --- | --- |
+| `/claude-setup-review` | [--path <dir>] [--json] | [`claude-setup-review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/claude-setup-review/SKILL.md) | Audit this project's Claude Code harness — CLAUDE.md completeness, rule clarity, skill and agent wiring, path accuracy, and agent frontmatter schema compliance. Use when the user says "review my CLAUDE.md", "audit my Claude setup", "is my Claude config right", "check my agent frontmatter", "are my skill paths correct", or after adding or restructuring CLAUDE.md, agents, or skills. Advisory — it recommends, it does not edit. |
+| `/co-evolution-audit` | [--since <date\|N-days>] [--max-commits <N>] [--min-churn <N>] [--max-test-churn <N>] | [`co-evolution-audit/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/co-evolution-audit/SKILL.md) | Flag production files that churn repeatedly while their paired test files do not change — the "Red Queen" co-evolution gap. Uses git log --stat to compute per-file change frequency over a configurable window, applies language-aware pairing heuristics (Python, JS/TS, Go, Java, C#), and produces a ranked table of stale-coverage pairs. Feeds test-health and test-improve as prioritization input, not a standalone gate. Use when you want to find high-churn files whose tests have gone stale, or before running /test-improve to identify the highest- leverage targets first. |
+| `/harness-e2e-check` | [--item N] [--output <path>] | [`harness-e2e-check/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/harness-e2e-check/SKILL.md) | On-demand end-to-end integration check of the dev-team plugin's own harness mechanisms — failure-class routing, dead-end detection, evidence bundles, invariants/rollback, the REFACTOR-phase test-freeze guard family, lesson-validation weighting, and the handoff rename — running each live rather than trusting a per-PR test result. Originated as issue #907's post-merge integration test plan; this is that plan made repeatable. Use when the user says "run the harness e2e check", "re-run 907", "smoke-test the harness", or after any batch of harness-mechanism changes lands on main. |
+| `/headless-run` | <prompt-or-slash-command> [--cwd DIR] [--model MODEL] [--timeout SECS] | [`headless-run/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/headless-run/SKILL.md) | Run a Claude Code skill or command headlessly in an isolated subprocess — fresh session id, clean HOME and config dir, scrubbed env, JSON result, timeout. Use for scripted one-shot invocations and benchmark-harness cases (e.g. running /code-review once per case), to run an isolated claude -p, or to avoid a nested run reusing the parent Remote session identity or tool surface. Trigger phrases include "run a skill headlessly", "isolated claude -p", "benchmark harness invocation", "run /code-review headlessly", "run it once per case", and "avoid nested session reuse". |
+| `/long-eval` | [status\|ensure-alive] --module <file> --out <dir> | [`long-eval/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/long-eval/SKILL.md) | Run an eval that takes longer than one cloud-session container lifetime — agent calibration, prompt A/B sweeps, judge-panel scoring — so it survives the frequent container recycles that kill in-process work. Use when the user says "run this long eval", "the eval keeps dying on restart", "make the eval survive restarts", "resume the eval", "keep the eval alive", or when a full-corpus calibration/benchmark will clearly outlast a single session. Ships a restart-durable engine + CLI so nothing is re-invented per eval. |
+| `/mutation-night-watch` | no flags — run directly | [`mutation-night-watch/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/mutation-night-watch/SKILL.md) | Launch, schedule, and hand off an unattended, LLM-free overnight mutation night-watch run. Use when the user wants a mutation-score baseline waiting each morning without paying LLM cost or blocking a session overnight, says "run mutation testing overnight", "schedule a nightly mutation scan", "set up a mutation night watch", or asks how to get an unattended mutation baseline. Wraps mutation_nightwatch.py — report-only measurement, never generation. |
+| `/orchestration-benchmark` | [--task-class <trivial\|standard\|complex>] [--runs <n>] [--dry-run] | [`orchestration-benchmark/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/orchestration-benchmark/SKILL.md) | Run the pre-registered solo-vs-coordinated A/B benchmark: three arms (solo session, current orchestration, delegation-only sweep) over the same task matrix at matched verification rigor, measuring dollar cost, token band shift, quality, rework, and wall-clock. Use when the user asks "is orchestration worth it", "benchmark the pipeline against a solo run", "measure delegation value", "orchestration benchmark", or wants the crossover threshold below which a solo session beats delegation. |
+| `/property-based-testing` | <module_path> <function_name> | [`property-based-testing/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/property-based-testing/SKILL.md) | Generate a runnable property-based test for a target function from its signature/docstring — a round-trip test when an encode/decode pair exists, or an invariant test when the docstring documents a postcondition (e.g. "returns sorted", "is idempotent"). Detects the project's language via project-init's stack detection, uses Hypothesis for Python and fast-check for JavaScript/TypeScript, and recommends running /mutation-testing against the generated suite afterward. Use when the user says "generate a property test", "property-based test this function", "add Hypothesis/fast-check tests", or wants round-trip/invariant coverage for a pure function rather than hand-written example-based tests. |
+| `/proxy-resilience` | no flags — run directly | [`proxy-resilience/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/proxy-resilience/SKILL.md) | Bounded backoff, retry ceiling, and escalation convention for repeated failures against a corporate Anthropic proxy. Use when you observe repeated HTTP 429 rate-limit responses or connection-refused errors that reference a proxy host, or the user says "proxy is rate-limiting", "429 from the proxy", "proxy connection refused", or "corporate proxy is flaky". |
+| `/repo-review` | [--path <dir>] [--json] [--pdf] | [`repo-review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/repo-review/SKILL.md) | Whole-repository drift review for the review agents that a per-diff /code-review pass cannot meaningfully evaluate — accumulated file/CLAUDE.md size drift, AI-provenance verification debt, harness-config completeness, and cross-file frontend component duplication. Use when the user asks for a "repo review", "drift review", "whole-tree review", wants to check accumulated size/token drift, verification debt, or duplicated frontend components across the WHOLE codebase rather than a single diff, or periodically (e.g. every N merged PRs) to catch drift no single diff-scoped review would surface. Report-only — never gates a commit. |
+| `/report-pdf` | <path.md> [--out <path>] | [`report-pdf/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/report-pdf/SKILL.md) | Render a dev-team Markdown report to a polished, shareable PDF. Use when the user says "make a PDF of the report", "export the code-review report as PDF", "turn .dev-team-reports/code-review.md into a PDF", or wants any .dev-team-reports or reports Markdown file as a styled document to attach to a ticket or hand to a non-terminal stakeholder. |
+| `/run-report` | [--session <id>] | [`run-report/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/run-report/SKILL.md) | Report one orchestrated run's timeline — per-state dwell time, rejection count, hook denials/bypasses grouped by cause, and cost — joined from boundary-events.jsonl, cost-metering.jsonl, and workflow-states.jsonl for a given session_id (default: most recent). Use when the user asks "how did that run go", "show the run report", "/run-report", or wants a single view of a `/ship`/`/autoship`/`/build` run instead of cross-referencing streams by hand. |
+| `/source-verification` | no flags — run directly | [`source-verification/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/source-verification/SKILL.md) | Extract and verify factual claims in generated content (docs, diffs, review comments) against this repo's own code and, where needed, external sources. Use before publishing content that asserts specific behavior, version numbers, or API details — anywhere a wrong claim would mislead a reader. Flags every claim as verified, contradicted, or unverifiable; never silently drops one or defaults it to "verified". |
+| `/stryker-xunit-v2-shim` | no flags — run directly | [`stryker-xunit-v2-shim/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/stryker-xunit-v2-shim/SKILL.md) | Build a xunit.v2 Stryker shim so Stryker.NET produces a valid mutation score for a xunit.v3 test project. Stryker.NET cannot observe mutant kills through xunit.v3 (it runs on the Microsoft Testing Platform), so a normal run reports a false near-zero score with almost every mutant reported Survived. Use this BEFORE running Stryker whenever the target .NET test project references xunit.v3 — including when mutation is enabled via /test-improve or /mutation-testing, or you are about to run dotnet-stryker — and as a rescue when a run already reported ~0% or everything Survived or the user says the score looks suspiciously low. When Stryker and xunit.v3 both appear, build the shim first. |
+| `/test-improve` | <repo-path> [--parent <url>] [--analyze-only] [--from-phase [<n>]] [--stack <id>] | [`test-improve/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-improve/SKILL.md) | Consolidated analyze-then-improve test orchestrator. Defaults to lightweight ceremony; opts into heavier capabilities (Gherkin extraction, mutation testing, refactor-for-testability) only when the operator asks. Always baselines coverage (and mutation, when enabled) before any test change, runs the end-of-phase review loop after Phases 5 and 7, and produces a stable 10-section executive-summary report. Use when the user says "improve our tests", "modernize the test suite", "upgrade our tests", or runs /test-improve. |

package/docs/upstream/team-structure.md

@@ -0,0 +1,21 @@
+# Team Organization
+
+This document is a visual index of the agent team. For behavioral details of each agent, see [Agents](agent_info.md). For orchestration mechanics, see [Architecture](agent-architecture.md).
+
+## Team Agents
+
+![Org chart showing the Orchestrator at the top, dispatching to ten team agents: Software Engineer, QA Engineer, UI/UX Designer, Architect, Product Manager, Technical Writer, Security Engineer, Platform Engineer, ADR Author, and Codebase Recon.](diagrams/team-agents.svg)
+
+The Orchestrator sits at the root and routes every request to one or more of the ten team agents based on task classification. Only the Orchestrator spans phases; the other agents are loaded on demand when their phase begins and unloaded via summarization before the next phase starts. Full roster: [Agents → Team Agents](agent_info.md#team-agents).
+
+## Review Agent Dispatch (Phase 3 Inline Checkpoints)
+
+![Dispatch diagram: a unit of work on the left, a file-type decision layer in the middle, and fan-out to targeted review agents on the right (e.g., JS/TS files → naming-review; any change → structure-review; security surface → security-review).](diagrams/review-dispatch.svg)
+
+The Orchestrator selects review agents based on what changed in each unit of work. Language-agnostic agents (doc-review, arch-review) always run; language-specific agents run only when matching file types are present. `claude-setup-review`, `token-efficiency-review`, and `ai-provenance-review` are not in this fan-out (#1733) — their findings are properties of the whole repository, not any single unit of work, so they run instead in the whole-tree `/repo-review` command; `claude-setup-review` also stays reachable on demand via `/claude-setup-review`. Full list of review agents and their scopes: [Agents → Review Agents](agent_info.md#review-agents).
+
+## Special-purpose review agents
+
+`progress-guardian` is a process gate-keeper, not a code reviewer — it is not in the standard review-dispatch fan-out above. It tracks plan-step completion and commit discipline, and is invoked by its owning orchestrator, never by `/code-review`.
+
+`/test-improve` does **not** use a separate phase-gate agent; its per-phase progress files under `.claude/memory/test-improve/<slug>/phase-<n>.md` and its end-of-phase review loop (Phase 5 and Phase 7) carry the equivalent evidence contract.