pi-dev-team 0.2.0

package/skills/coverage-delta/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: coverage-delta
+description: >-
+  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`.
+argument-hint: "<repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--story <id-or-path>] [--story-files <glob-or-comma-list>]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write
+---
+
+# Coverage Delta
+
+Role: worker. Reports coverage change vs. the captured baseline. One snapshot per Story so the operator can see whether each add actually moved the needle. Callers with a phase model (such as `/test-improve`, where the baseline lands in Phase 2 and per-Story deltas fire in Phase 5) label snapshots by phase; phase-less workflows omit that label.
+
+You have been invoked with the `/coverage-delta` command.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<repo-path>`.
+- `--parent <issue-url>` — parent issue URL (or empty for local-files).
+- `--repo-slug <slug>` — `.claude/memory/<workflow>/` namespace.
+- `--workflow <name>` — the workflow namespace under `.claude/memory/`. Defaults to `test-improve`. Orchestrators pass their own namespace (e.g. `/test-improve` passes `test-improve` for its Phase-5 per-Story deltas).
+- `--story <id-or-path>` — optional Story this delta is attributed to. Used as the snapshot label.
+- `--story-files <glob-or-comma-list>` — production-code files the Story touched (typically from `/build`'s commit diff, tests filtered out). When both `--story` AND a non-empty `--story-files` are present, Step 2b runs scoped mutation; otherwise it is a no-op so `/quality-targets-converge` can keep calling this worker without `--story-files` exactly as before.
+
+## Steps
+
+### 1. Load the baseline
+
+Read `.dev-team-reports/<workflow>/<slug>/data/baseline-coverage.json`. If missing, tell the operator the baseline has not been captured (`/coverage-baseline` must run first; for `/test-improve` that is Phase 2) and stop.
+
+### 2. Re-run coverage
+
+Use the same coverage **tool** `/coverage-baseline` recorded — DO NOT switch tools mid-workflow, or the delta is meaningless. This governs the tool only, never the project/package list: for a multi-project repo (Step 2a below), the set of included projects/packages is re-derived from fresh discovery on every call, never reused from a prior run — a frozen, never-revisited list is exactly what caused issue #1759's ~30x underreported delta.
+
+For a multi-project repo, load the persisted `coverage-config.json` first (Step 2a) and print `coverage_config.measurement_basis_notice(config.get("bootstrapped_at"), baseline["captured_at"])`'s result verbatim when non-`None` — a non-blocking notice that the comparison baseline predates multi-project discovery, so a reported delta may reflect a widened measurement scope rather than a real coverage change.
+
+Capture exit code + stdout + stderr.
+
+If the run fails, surface the first error and stop. Do not post a delta from a broken run.
+
+### 2a. Multi-project re-derivation (.NET solutions, JS/TS workspaces & Java multi-module builds)
+
+When a `.sln` file exists at the repo root (.NET), a workspace signal is present (JS/TS), or a multi-module signal is present (Java) — the same triggers `coverage-baseline`'s Step 1a uses — re-run the appropriate discovery script **fresh, every call**, never reusing a project/package/module list recorded by a prior run:
+
+- **.NET**: `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_dotnet.py`'s `discover_dotnet_projects(repo_root)`
+- **JS/TS**: `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_js.py`'s `discover_js_packages(repo_root)`
+- **Java**: `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_java.py`'s `discover_java_modules(repo_root)` — a root `pom.xml` declaring `<modules>` (Maven, which wins when both are present) or a `settings.gradle`/`settings.gradle.kts` declaring `include(...)` (Gradle)
+
+Implementation mechanics (the bootstrap/drift-check contract, weighted-merge, and the exact message templates): [`../coverage-baseline/references/multi-project-discovery.md`](../coverage-baseline/references/multi-project-discovery.md) — this section pins the contract surface only, mirroring how `coverage-baseline`'s own Step 1a links the same file rather than re-deriving the mechanics a second time.
+
+**Config path.** `coverage-config.json` is read from the exact resolved path `.dev-team-reports/<workflow>/<slug>/data/coverage-config.json` — the SAME path `coverage-baseline`'s Step 5 persists to, and the SAME path `load_or_bootstrap` reads/writes in `coverage-baseline`'s Step 1a. There is no ambiguity: both skills operate on the identical file.
+
+**Absent/malformed `coverage-config.json`.** Before calling `drift_check`, check whether that path exists and parses. If missing (the baseline predates this feature, or was captured on the single-project path with no config ever persisted) or malformed, stop with a named message telling the operator to re-run `/coverage-baseline` first — mirroring Step 1's existing missing-baseline branch. Do **not** silently bootstrap a config in-memory here: this worker is read-only on the repo's source (see Notes), and a delta is only ever meaningful against a config `/coverage-baseline` itself persisted.
+
+**Discovery-signal check.** Before calling `drift_check`, check the fresh discovery call's return value — the same two branches `coverage-baseline`'s Step 1a already carries:
+
+- `coverage_config.DISCOVERY_NOT_APPLICABLE` — should not occur here (this step only runs when the `.sln`/workspace/multi-module trigger already fired); if it somehow does, treat it like the missing-config branch above: stop, post no delta.
+- `coverage_config.discovery_error(...)` — surface `message`, post no delta, stop — the same treatment as an existing Step 2 run-failure (a genuine tool failure, not the actionable config gap the hard-failure block below describes).
+
+Never let `discovered` reach `drift_check` unchecked.
+
+**Zero-real-test-project guard.** Before calling `drift_check`, apply the same `any(coverage_config.needs_accounting(entry["classification"]) for entry in discovered)` check `coverage-baseline`'s Step 1a already carries. If `False` (every discovered project/package classifies `NOT_TEST`), stop immediately with the exact message `coverage-baseline`'s Step 1a uses, worded for a delta: `"Coverage capture stopped: no real test project was discovered in this <solution|workspace|multi-module build> — cannot establish a coverage floor. If this repo has test projects, verify they reference Microsoft.NET.Test.Sdk (for .NET), use jest/vitest/mocha+nyc/c8 (for JS/TS), or declare a JUnit/TestNG dependency alongside a src/test/java|kotlin directory (for Java) so discovery can recognize them; otherwise there is no coverage floor to capture."` Post no delta.
+
+Read the persisted `.dev-team-reports/<workflow>/<slug>/data/coverage-config.json` (written by the prior `/coverage-baseline` run) and call `coverage_config.drift_check(config, discovered)` against it:
+
+- If `drift_check` raises `ValueError` (a malformed-but-parseable `included`/`excluded` shape — e.g. present but not a list), print the exception's message **verbatim, as its own named block**, and stop without posting a delta.
+- `drift["hard_failure"]` is `True` (an unaccounted-for or conflicting project/package) — print `drift["hard_failure_message"]` **verbatim, as its own distinct, named block** headed `Coverage capture stopped:` — the same hard-failure rule and message `coverage-baseline` applies, never folded into or reusing this skill's own generic run-failure wording above. Stop; post no delta.
+- `drift["hard_failure"]` is `False` — run the coverage command per included project/package (never once for the whole repo) and merge the results with `coverage_config.weighted_merge(project_reports)`, same as `coverage-baseline` Step 1a.
+
+`drift["stale_warning_message"]` is carried forward regardless of `hard_failure` — see Step 5 (Report) for where it surfaces.
+
+Single-project and mixed-stack repos (`coverage-baseline`'s Step 1b unaffected cases) never reach this step — Step 2's single-command path runs unchanged, and no `coverage-config.json` is ever read here for them.
+
+### 2b. Measure scoped mutation (only when both `--story` AND `--story-files` are present)
+
+**Worker boundary.** This worker measures and reports; it does NOT halt the workflow on net-new survivors. Policy enforcement is the orchestrator's job (`/test-improve` Phase 5 reads the structured `status` field this step emits and decides whether to pause Story close via the mutation-kill agent's `[c/r/w/q]` prompt).
+
+**Implementation detail** — baseline-of-record lookup, equivalent-mutant filter, classification table, atomic-write idiom: [`references/mutation-gate.md`](references/mutation-gate.md). This section pins the contract (flags, status enum, exit-code rule, schema keys); the reference holds the mechanics.
+
+Gating: skip this whole step unless BOTH `--story <id>` AND a non-empty `--story-files <files>` are supplied. `--story` alone (the call path `/quality-targets-converge` uses) triggers no mutation run and no `mutation-history.json` write — the result block on stdout carries `"mutation": null`.
+
+When the gate fires:
+
+1. Invoke `/mutation-testing --scope <expanded --story-files> --emit-json <tmp> --workflow-managed-approval`. The `--workflow-managed-approval` flag is allowed here because `/test-improve` Phase 0 captured operator approval at the workflow boundary (see `mutation-testing` `## Constraints` carve-out).
+2. **Baseline-of-record per file.** For each file in `--story-files`, look up the most recent entry in `.dev-team-reports/<workflow>/<slug>/data/mutation-history.json`; that entry's `survivors_after` is the baseline-of-record. If no prior entry exists, the file's status is `first_measurement` (`survivors_before: null`, `delta: null`).
+3. **Filter `status: "equivalent"` AND `status: "accepted"` survivors** from the `/mutation-testing` output before computing delta — reclassifications between runs, and documented rationale-bearing deferrals, must not show up as regressions.
+4. Compute `delta = survivors_after - survivors_before` (skip when `first_measurement`) and assign a status per file:
+   - `ok` — `delta <= 0`.
+   - `net_new_survivors` — `delta > 0`. The result block lists each new survivor by `file:line:operator`.
+   - `first_measurement` — no prior entry.
+   - `tool_unavailable` — `/mutation-testing` returned the `no_tool_installed` envelope. The result block names `/setup` as the install path and includes `language: "<detected>"`. If a prior history entry recorded a different tool, surface that as `prior_tool: "<name>"` so the operator sees the disappearance.
+   - `skipped_empty_scope` — `--story-files` expanded to zero files. No mutation run; one history entry recorded with this status.
+5. Append per-file entries to `mutation-history.json` via **temp-file-then-rename** (write to `<path>.tmp` then `mv -f <path>.tmp <path>`). This keeps parallel `/coverage-delta` writes from interleaving when two Phase-5 Stories close within the same second. Direct overwrite of `mutation-history.json` is forbidden.
+
+**Exit code.** This step's exit code is `0` on every status above, including `net_new_survivors` — the worker carries the signal in the status field, not the exit code. The exit code is non-zero ONLY on tool execution failure (a crash inside `/mutation-testing`, an unwritable history path, malformed JSON from the underlying tool). This is the worker/policy boundary: orchestrator reads `status`, worker reports cleanly.
+
+**Result block on stdout** — a single JSON object the orchestrator can parse:
+
+```json
+{
+  "status": "ok | net_new_survivors | first_measurement | tool_unavailable | skipped_empty_scope",
+  "story": "<id>",
+  "story_files": ["src/order.ts"],
+  "mutation": {
+    "tool": "stryker",
+    "files": [
+      { "file": "src/order.ts", "survivors_before": 8, "survivors_after": 3, "delta": -5, "status": "ok" }
+    ]
+  }
+}
+```
+
+When the step is skipped (no `--story-files`), the block is `{"status": "ok", "mutation": null, ...}`.
+
+### 3. Parse + compute the delta
+
+Parse line + branch percentages with the same logic `/coverage-baseline` used. Compute:
+
+```json
+{
+  "phase": <phase-number-or-null>,
+  "captured_at": "<ISO-8601>",
+  "story": "<id-or-path-or-null>",
+  "line_pct": <current>,
+  "branch_pct": <current>,
+  "line_delta": <current - baseline>,
+  "branch_delta": <current - baseline>,
+  "baseline_line_pct": <from baseline.json>,
+  "baseline_branch_pct": <from baseline.json>
+}
+```
+
+`phase` is the calling workflow's phase number when it has one (`/test-improve` supplies `5`); workflows without a phase model supply `null`.
+
+Append to `.dev-team-reports/<workflow>/<slug>/data/coverage-history.json` (array of snapshots, newest last).
+
+### 4. Post the snapshot
+
+Append a markdown row to the parent's `## Metrics history` section (tracker mode) or to `.claude/plans/<workflow>/FEATURE.md` (local-files mode):
+
+```markdown
+| <ISO-8601> | Phase <n> | <story-id-or-—> | Line <pct>% (Δ <+/-pct>) | Branch <pct>% (Δ <+/-pct>) | Mutants <count> (Δ <+/-n>) |
+```
+
+Create the table header on first call if it doesn't exist:
+
+```markdown
+## Metrics history
+
+| Captured | Phase | Story | Line | Branch | Mutants |
+|---|---|---|---|---|---|
+```
+
+The Mutants column is `—` when Step 2b was a no-op (no `--story-files`); otherwise it carries the aggregate `survivors_after` across the Story's files and `Δ` vs. the prior history entries.
+
+Use the resolved CLI pattern from Phase 1 (same edit-the-parent invocation `/coverage-baseline` used).
+
+### 5. Report
+
+Print:
+
+- Line + branch percentages and deltas.
+- The destination (parent issue URL or `FEATURE.md`).
+- The path to `coverage-history.json` for `/continue`.
+- **Multi-project repos only**: when Step 2a's `drift["stale_warning_message"]` is non-`None` (an `excluded` entry that no longer matches any freshly-discovered project/package), print it **verbatim, as a named, non-blocking warning line** — it never blocks the run and never overrides the reported delta.
+- **Multi-project repos only, every run**: print `coverage_config.format_active_exclusions(config)`'s result **verbatim** whenever it is non-`None` — one line per currently-excluded project/package naming its path and reason. This is informational context shown on every run (not a warning, not blocking), distinct from the stale-warning line above: it surfaces what is currently excluded and why, regardless of whether that exclusion has gone stale.
+
+If the delta is **negative** (a Story made coverage worse), surface that as a warning so the operator can decide whether to keep the Story.
+
+## Notes
+
+- This worker is read-only on the repo's source — it runs the coverage command and parses the report. It does not modify tests or production code.
+- Snapshots accumulate; nothing is overwritten. The full history feeds `/quality-targets-converge` in Phase 7.
+- Wall-clock for the coverage run is not tracked here — that's `/quality-targets-converge`'s job.

package/skills/coverage-delta/references/mutation-gate.md

@@ -0,0 +1,70 @@
+# `/coverage-delta` mutation gate — implementation detail
+
+`/coverage-delta` `### 2b. Measure scoped mutation` is the **contract surface**: when invoked with both `--story` AND a non-empty `--story-files`, it runs scoped mutation against the Story's production-code files, emits a structured status, and writes per-file history without ever halting the workflow.
+
+This file holds the implementation detail of Step 2b so the SKILL.md stays a thin orchestrator of two sub-operations (coverage delta + mutation gate), not a deep implementation of both. The contract surface — flag names, status enum, exit-code rule, schema keys — lives in `SKILL.md` because that is what reviewers, bats tests, and callers depend on. The mechanics live here.
+
+## Baseline-of-record per file
+
+For each file in `--story-files`, the baseline is the most recent entry in `.dev-team-reports/<workflow>/<slug>/data/mutation-history.json` for that file (with `<workflow>` resolved from the calling orchestrator's `--workflow` value — e.g. `test-improve`). Lookup procedure:
+
+1. Read `mutation-history.json` (if absent, every file is `first_measurement`).
+2. For each file `F`, filter entries where `entry.file == F`; pick the entry with the largest `captured_at` (ISO-8601 lexicographic sort).
+3. `baseline = entry.survivors_after` if found; else `null` (status `first_measurement`).
+
+When two `/coverage-delta` invocations close within the same second, both append entries — neither overwrites the other. The status logic uses the largest `captured_at`, so the most recent close wins.
+
+## Equivalent- and accepted-mutant filter
+
+`/mutation-testing` emits each survivor with `status: "survived"`, `status: "equivalent"`, or `status: "accepted"` (the latter two always carry a `reason` string). Filter both `status: "equivalent"` and `status: "accepted"` survivors before computing the delta — reclassifications between runs, and documented, rationale-bearing deferrals, must not show up as regressions.
+
+Implementation: `jq '.survivors | map(select(.status == "survived")) | length'` on the `--emit-json` document. Selecting only `"survived"` already excludes both `"equivalent"` and `"accepted"` — no additional exclusion logic is needed when a new status value is added to the enum.
+
+## Status classification (per file)
+
+After computing `survivors_after`, classify each file:
+
+| Status | When | Action |
+| --- | --- | --- |
+| `first_measurement` | baseline is `null` | Record entry with `survivors_before: null, delta: null`. |
+| `ok` | `survivors_after <= baseline` | Record entry with `delta = survivors_after - baseline`. |
+| `net_new_survivors` | `survivors_after > baseline` | Record entry with positive `delta`. The result block lists each new survivor (`file:line:operator`). |
+| `tool_unavailable` | `/mutation-testing` returned `error: "no_tool_installed"` | Record entry with `prior_tool` (if the most recent history entry recorded a tool name); the result block names `/setup`. |
+| `skipped_empty_scope` | `--story-files` glob expanded to zero files | Record one history entry per Story (not per file) with this status. |
+
+## Atomic-write semantics
+
+`mutation-history.json` is written via temp-file-then-rename to keep parallel `/coverage-delta` writes from interleaving:
+
+```bash
+HISTORY=".dev-team-reports/<workflow>/<slug>/data/mutation-history.json"
+TMP="$(mktemp "${HISTORY}.XXXXXX")"
+jq '. + [$new]' --argjson new "$NEW_ENTRY" "$HISTORY" > "$TMP" && mv -f "$TMP" "$HISTORY"
+```
+
+Direct overwrite of `mutation-history.json` is forbidden — `>` or `tee` would let one writer truncate the other's bytes during a concurrent close.
+
+## Result-block schema on stdout
+
+The block matches the schema documented in `SKILL.md` `### 2b`. Restated here for grep-ability:
+
+```json
+{
+  "status":      "ok | net_new_survivors | first_measurement | tool_unavailable | skipped_empty_scope",
+  "story":       "<id>",
+  "story_files": ["<file>", ...],
+  "mutation": {
+    "tool":  "<stryker|pitest|mutmut|stryker-net|null>",
+    "files": [
+      { "file": "<path>", "survivors_before": <n|null>, "survivors_after": <n|null>, "delta": <n|null>, "status": "<status>" },
+      ...
+    ]
+  }
+}
+```
+
+When the step is skipped (no `--story-files`), the block is `{"status": "ok", "mutation": null, ...}` — the orchestrator interprets that as "no mutation signal this run, continue".
+
+## Worker/policy boundary
+
+The worker never halts on a status value. The exit code is `0` on every status above (including `net_new_survivors`) and non-zero ONLY on tool execution failure. The orchestrator (`/test-improve` Phase 5) reads `status` from the result block and decides whether to pause Story close (typically via the `mutation-kill` agent's `[c/r/w/q]` prompt). This is the worker/policy separation `plugins/dev-team/CLAUDE.md` describes — measurement here, policy upstream.

package/skills/design-doc/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: design-doc
+description: 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".
+role: orchestrator
+user-invocable: true
+---
+
+# Design Document
+
+Role: orchestrator. This command produces a design document and gates
+progression to Phase 2 (Plan) — it does not write implementation code,
+scaffold a project, or take any implementation action.
+
+## Overview
+
+The Research phase explores what exists. This skill adds a structured output: a design document that captures the proposed approach and gets human approval before the Plan phase begins. Misunderstandings caught at design time cost minutes; misunderstandings caught at implementation time cost hours.
+
+## Constraints
+- Do not begin Phase 2 (Plan) without an approved design doc for non-trivial features
+- Do not treat the design doc as a plan — it captures intent and approach, not file-level changes
+- Do not skip alternatives analysis — a design doc with one option isn't a design doc, it's a plan
+- The human must explicitly approve the design doc before proceeding
+- **Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action** until the design doc is approved. The design doc is a gate, not a suggestion.
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "This is too simple to need a design doc" | Simple projects harbor unexamined assumptions. The design doc will be short — just write it. |
+| "I already know the approach" | Then it'll take 5 minutes to write down. And the human might disagree. |
+| "Writing a spec slows us down" | Misunderstandings caught at design time cost minutes. Misunderstandings caught at implementation time cost hours. |
+| "The requirements are clear enough" | Clear to you. The human may interpret them differently. Write it down and verify. |
+
+## When to Produce a Design Doc
+
+| Task Type | Design Doc Required? |
+|-----------|---------------------|
+| New feature | Yes |
+| Architectural change | Yes |
+| Cross-cutting refactor | Yes |
+| API design or redesign | Yes |
+| Bug fix | No (unless the fix requires design decisions) |
+| Typo/config/doc fix | No |
+| Single-file change | No (unless it changes behavior significantly) |
+
+## Document Structure
+
+Save to `docs/specs/{feature-name}.md`:
+
+```markdown
+# {Feature Name} — Design Document
+
+## Problem Statement
+What problem are we solving? Who experiences it? What happens if we don't solve it?
+
+## Proposed Approach
+High-level description of the solution. How does it work? What are the key components?
+
+## Alternatives Considered
+| Approach | Pros | Cons | Why rejected |
+|----------|------|------|-------------|
+
+At least two alternatives. "Do nothing" counts as one.
+
+## Key Decisions
+Decisions that constrain the Plan phase. For each:
+- What was decided
+- Why
+- What trade-off was accepted
+
+## Open Questions
+Things that need answers before or during planning. Tag each with who should answer (human, architect, domain expert).
+
+## Scope Boundaries
+What's explicitly in scope and out of scope. This prevents scope creep during planning and implementation.
+
+## Visual Artifacts (optional)
+Diagrams, mockups, data flow sketches — anything that clarifies the design. Use Mermaid for diagrams when possible.
+```
+
+## Process
+
+1. **Research**: Explore the codebase, understand the problem space
+2. **Draft**: Write the design doc based on research findings
+3. **Present**: Show the design doc to the human at the Research phase gate
+4. **Approve/Revise**: Human approves, requests changes, or redirects
+5. **Proceed**: Approved design doc feeds into Phase 2 (Plan) as input alongside the research progress file
+
+## Integration with Phases
+- **Phase 1 output**: Research progress file + approved design doc
+- **Phase 2 input**: Design doc provides intent and constraints; Plan phase specifies exact file changes
+- **Agent-Assisted Specification**: Design doc complements BDD scenarios — design doc captures the "why" and "how", scenarios capture the "what"
+
+## Output
+A design document at `docs/specs/{feature-name}.md` reviewed and approved by the human before the Plan phase begins.

package/skills/design-interrogation/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: design-interrogation
+description: >-
+  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.
+role: worker
+user-invocable: true
+---
+
+# Design Interrogation
+
+## Overview
+
+Walk every branch of a decision tree until all decisions are resolved. The goal is not to produce an artifact — it's to force the developer to think through decisions they'd otherwise skip. Good designs fail not from what was considered, but from what wasn't.
+
+## When to Use
+
+- Before committing to a plan (Research phase, before `/plan`)
+- After a design doc is drafted but before implementation
+- When the user says "grill me" or "stress-test this"
+- When a plan has implicit assumptions that need to be surfaced
+
+## How It Works
+
+### 1. Identify the Decision Surface
+
+Read the plan, design doc, spec, or description. Identify every decision point — explicit ones the user already made, and implicit ones hiding behind assumptions. Look for:
+
+- **Unstated assumptions**: "We'll use X" without explaining why not Y
+- **Vague scope boundaries**: "We'll handle that later" — when is later?
+- **Missing error paths**: What happens when the happy path breaks?
+- **Integration seams**: Where does this design touch other systems?
+- **Scale implications**: Does this work for 10 users? 10,000? 10 million?
+- **Migration paths**: How do you get from the current state to the proposed state?
+
+### 2. Walk the Decision Tree
+
+Ask questions **one at a time**. For each question:
+
+1. State the decision that needs to be made
+2. Provide your recommended answer with reasoning
+3. If the question can be answered by exploring the codebase, explore it yourself instead of asking the user
+4. Wait for the user's response before moving to the next question
+
+Follow dependency order — resolve foundational decisions before asking about things that depend on them. If an answer to one question invalidates a previous decision, flag it.
+
+### 3. Go Deep, Not Wide
+
+Don't ask surface-level questions. Push into the uncomfortable territory:
+
+- "You said you'd use a queue here — what happens when the queue fills up?"
+- "This assumes the API is always available. What's the degradation strategy?"
+- "You've designed for creation but not deletion. Is that intentional?"
+- "Three services share this model. Who owns the schema?"
+
+If the user gives a hand-wavy answer, push back: "That's a direction, not a decision. What specifically would you build?"
+
+### 4. Know When to Stop
+
+Stop when:
+- Every branch of the decision tree has a concrete answer
+- The user says "that's enough" or "I'm confident now"
+- You've circled back to the same questions — all paths are resolved
+
+### 5. Summarize
+
+After the interrogation, provide a brief summary:
+- **Decisions made**: numbered list of resolved decisions
+- **Open items**: anything the user explicitly deferred (with the reason)
+- **Risks identified**: concerns that surfaced during questioning
+
+This summary can feed directly into `/plan` or a design doc.
+
+## Tone
+
+Be direct and constructive, not adversarial. The goal is partnership in finding gaps, not scoring points. Think of a senior engineer doing a design review — rigorous but respectful. Provide your own recommended answer for every question so the user has something to react to, not just a blank to fill.
+
+## Anti-Patterns
+
+- Don't ask questions you could answer by reading the codebase
+- Don't ask rhetorical questions — every question should need a decision
+- Don't ask more than one question at a time
+- Don't accept "we'll figure it out later" without pressing for when and how
+- Don't turn this into a requirements document — that's what `/specs` does

package/skills/design-it-twice/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: design-it-twice
+description: >-
+  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.
+role: worker
+user-invocable: true
+---
+
+# Design It Twice
+
+## Overview
+
+Your first design idea is rarely your best. This skill generates multiple radically different interface designs for a module by dispatching parallel sub-agents with divergent constraints, then compares them so the user can make an informed choice. Based on "Design It Twice" from John Ousterhout's *A Philosophy of Software Design*.
+
+This skill is about **interface shape**, not implementation. Don't write code — design the contract.
+
+## When to Use
+
+- Designing a new module, service, or API boundary
+- Refactoring an existing interface that feels wrong
+- Any time there's a non-obvious choice about how to expose functionality
+- When the Architect agent identifies a new module boundary during planning
+
+## Process
+
+### 1. Gather Requirements
+
+Before designing, understand the constraints:
+
+- What problem does this module solve?
+- Who are the callers? (other modules, external users, tests)
+- What are the key operations?
+- What should be hidden inside vs exposed?
+- Any hard constraints? (performance, compatibility, existing patterns in the codebase)
+
+Explore the codebase to find existing patterns and conventions. Ask the user only for what you can't determine from the code.
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using the Agent tool. Each must produce a **radically different** approach — not variations on a theme.
+
+Assign each agent a different design constraint:
+
+| Agent | Constraint | Optimizes for |
+|-------|-----------|---------------|
+| 1 | "Minimize the interface — aim for 1-3 methods max" | Simplicity, deep module |
+| 2 | "Maximize flexibility — support many use cases and extension" | Generality, future-proofing |
+| 3 | "Optimize for the most common caller — make the default case trivial" | Ergonomics, productivity |
+| 4 | (optional) "Design around ports & adapters for cross-boundary deps" | Testability, isolation |
+
+Each sub-agent produces:
+1. **Interface signature** — types, methods, parameters
+2. **Usage example** — how a real caller would use it
+3. **What it hides** — complexity kept internal
+4. **Trade-offs** — what you gain and what you give up
+
+### 3. Present Designs
+
+Show each design sequentially so the user can absorb one before seeing the next. Don't use comparison tables for the designs themselves — prose is better for understanding trade-offs.
+
+### 4. Compare
+
+After presenting all designs, compare them on these dimensions:
+
+- **Interface simplicity**: fewer methods and simpler params = easier to use correctly
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+- **Implementation efficiency**: does the interface shape allow efficient internals?
+- **Testability**: can callers test against this interface without mocking internals?
+
+Give your own recommendation — which design is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated.
+
+### 5. Synthesize
+
+Ask the user:
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+The final design often combines insights from multiple options.
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs — enforce radical difference via constraints
+- Don't skip the comparison step — the value is in the contrast
+- Don't implement — this is purely about interface shape
+- Don't evaluate based on implementation effort — that's a separate concern

package/skills/docker-image-audit/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: docker-image-audit
+description: 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.
+role: worker
+user-invocable: true
+---
+
+# Docker Image Audit
+
+Audit Dockerfiles and container images using three complementary tools — hadolint (static Dockerfile linting), Trivy (CVE scanning), and Grype (second-opinion CVE scanning) — plus manual structural analysis for architectural issues the tools miss. Synthesize all findings into a single severity-ranked report with concrete fixes.
+
+## Prerequisites
+
+```bash
+command -v hadolint && command -v trivy && command -v grype
+```
+
+| Tool | Quick install (macOS) | Purpose |
+|------|----------------------|---------|
+| **hadolint** | `brew install hadolint` | Static Dockerfile analysis |
+| **trivy** | `brew install trivy` | Vulnerability scanning |
+| **grype** | `brew install grype` | Second-opinion CVE scanning |
+
+If any tool is missing, run `/project-init` to set up this repo's tooling — it installs hadolint/trivy/grype as capability tools when a Dockerfile is present (see its `${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/capability-tools.md`) — or install these Docker tools directly per `references/install-guide.md` (multi-platform; the install-guide is the fallback). The skill degrades gracefully — hadolint alone covers static analysis; Trivy + Grype require a built image. **If no tools are installed, still run the structural analysis (Step 2b). A tool-free audit is better than no audit.**
+
+## Workflow
+
+### Step 1: Identify the Target
+
+- **Dockerfile only** — hadolint + structural analysis (no built image needed)
+- **Built image** — Trivy + Grype (image must exist locally or in a registry)
+- **Both** — all steps (default when both are available)
+
+If the user points to a Dockerfile but no built image exists, offer to build it or proceed with Dockerfile-only analysis.
+
+### Step 2: Hadolint
+
+```bash
+hadolint --format json Dockerfile
+```
+
+Catches base image issues (`:latest` tag, unpinned versions), security anti-patterns (`ADD` vs `COPY`, running as root), efficiency problems (missing `--no-cache`, uncleaned apt cache), and shell issues in `RUN` instructions via integrated ShellCheck. Note: hadolint flags `:latest` (`DL3007`) but not other unpinned tags like `:10.0` without a digest — call those out in Step 2b (Structural Analysis) if the base image lacks a specific patch version or SHA digest.
+
+### Step 2b: Structural Analysis
+
+Hadolint catches per-instruction issues but misses architectural problems. Read the Dockerfile and check for these patterns — they are **not optional** and often represent the most impactful findings.
+
+| Check | What to look for | Severity |
+|-------|-----------------|----------|
+| **"God Dockerfile"** | CI/CD baked into the build: SonarQube, Black Duck, Snyk, Helm packaging, `curl` uploads to Nexus/Artifactory, `npm publish`, `git clone`. The Dockerfile should produce a runnable image — everything else belongs in CI pipeline definitions. | **HIGH** |
+| **Secrets in ARGs** | `ARG` names matching `*_TOKEN`, `*_SECRET`, `*_KEY`, `*_PASSWORD`, `*_CREDENTIALS`. ARGs persist in image layer metadata (`docker history --no-trunc`). Fix: use `RUN --mount=type=secret`. If secrets are only for CI stages, the better fix is moving those stages out of the Dockerfile. | **HIGH** |
+| **Missing .dockerignore + broad COPY** | `COPY . .` without a `.dockerignore` sends `.git/`, `node_modules/`, `bin/`, `obj/`, IDE config, and local secrets into the build context. | **HIGH** |
+| **Config mismatch** | Building/testing in Debug but publishing in Release (or vice versa). Tests should validate the exact bits that ship. Also flag post-build `jq`/`sed`/`awk` patching of output files — suggests misconfigured build flags. | **MEDIUM** |
+| **Redundant COPY** | Broad `COPY . .` followed by selective copies (redundant); same files re-copied across stages; `COPY . .` before `RUN <restore>` busting the dependency cache. Fix: copy manifests first (`*.csproj`, `package-lock.json`, `go.sum`), restore, then copy source. | **MEDIUM** |
+| **TLS verification disabled** | `--insecure-skip-tls-verify`, `curl -k`, `NODE_TLS_REJECT_UNAUTHORIZED=0`, `GIT_SSL_NO_VERIFY=true`. Vulnerable to MITM. Fix: configure proper CA certs. | **MEDIUM** |
+| **Missing HEALTHCHECK** | Final stage has no `HEALTHCHECK` instruction. Orchestrators can't detect unhealthy containers. | **MEDIUM** |
+| **Baked-in configuration** | Hardcoded environment-specific URLs, API keys, database connection strings, or service endpoints in `ENV` or config files copied into the image. These should be injected at runtime via environment variables, orchestrator secrets, or ConfigMaps. | **MEDIUM** |
+| **Swiss Army Knife image** | Build tools, compilers, test runners, or dev dependencies present in the final production stage. Check the final `FROM` base (full SDK vs. runtime/slim/distroless) and look for `COPY --from=build` that pulls more than just the application binaries. Fix: multi-stage build where the final stage contains only the runtime and published output. | **MEDIUM** |
+| **Stateful container** | Writing logs, uploads, temp files, or session data to the container's writable layer (`VOLUME` pointing to local paths, `RUN mkdir /data`). Containers should be ephemeral — use external volumes, object storage, or centralized logging. Flag `VOLUME` instructions that suggest local state. | **MEDIUM** |
+| **Dead-end stages** | Stages copying to `scratch` that aren't targeted, or stages whose output (reports, charts) is never referenced by the final stage. Wastes build time. | **LOW** |
+| **UID/GID mismatch** | `--chown=<uid>` doesn't match the `USER` in the same stage. Verify the UID maps to the expected user in the base image. | **LOW** |
+| **Language-specific anti-patterns** | **Python**: `pip install` without `--no-cache-dir`; unpinned versions. **Node**: `npm install` instead of `npm ci`; missing `NODE_ENV=production`. **Go**: missing `CGO_ENABLED=0` for scratch/distroless. **.NET**: missing `--locked-mode` on restore; copying `bin/`/`obj/`. **Java**: full JDK as runtime base when JRE suffices. **Multi-platform**: missing `--platform` in `FROM`. | **MEDIUM** |
+
+### Step 3: Trivy
+
+Run if a built image or project filesystem is available:
+
+```bash
+trivy image --format json --severity CRITICAL,HIGH,MEDIUM,LOW --output trivy-report.json <image>
+trivy fs --format json --severity CRITICAL,HIGH,MEDIUM,LOW --output trivy-fs-report.json .
+```
+
+The image scan catches OS package CVEs; the filesystem scan catches application dependency CVEs (npm, pip, Go, Maven, etc.). Also supports `--scanners misconfig,secret` for bonus coverage.
+
+### Step 4: Grype
+
+```bash
+grype <image> -o json > grype-report.json
+```
+
+Cross-validates against Anchore's vulnerability database. When both Trivy and Grype flag a CVE, confidence is high. When only one flags it, note the disagreement — the user should investigate.
+
+### Step 5: Image Size & Layers
+
+```bash
+docker image inspect <image> --format '{{.Size}}'
+docker history <image> --no-trunc --format '{{.Size}}\t{{.CreatedBy}}'
+```
+
+Flag layers over 100MB, build artifacts in the final image (compilers, dev headers), package manager caches, and opportunities to switch to distroless/slim bases.
+
+### Step 6: Write the Report
+
+Write findings to `docker-audit-report.md` in the project root (not chat). Use the template in `references/report-template.md` for structure. Every finding needs a source, severity, description, and concrete fix.
+
+## Severity Classification
+
+| Severity | Criteria |
+|----------|----------|
+| **CRITICAL** | Actively exploited CVE, RCE, exposed secrets in final image |
+| **HIGH** | Known CVE with public exploit, secrets in ARGs, "God Dockerfile", missing .dockerignore + broad COPY, root in final stage |
+| **MEDIUM** | Known CVE without public exploit, missing HEALTHCHECK, unpinned base, config mismatch, redundant COPY, TLS disabled, baked-in configuration, Swiss Army Knife image, stateful container patterns, language-specific anti-patterns |
+| **LOW** | Informational CVE, dead-end stages, UID/GID mismatch, root in build-only stages |
+| **INFO** | Style suggestions, layer consolidation opportunities |
+
+## Quick Audit Mode
+
+For fast passes (e.g., "quick check on this Dockerfile"), run Step 2 (hadolint) + Step 2b (structural analysis) and report findings conversationally — no report file. Skip Steps 3-5. Mention that a full image scan with Trivy + Grype is available for deeper CVE analysis.