pi-dev-team 0.2.0

package/skills/report-pdf/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: report-pdf
+description: >-
+  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.
+argument-hint: "<path.md> [--out <path>]"
+user-invocable: true
+allowed-tools: Bash
+---
+
+# Report PDF
+
+Role: worker. This command renders one Markdown report to a styled PDF via the
+shared render module. It is a mechanical wrapper — no reasoning, no file-by-file
+searching. It never modifies the source Markdown.
+
+You have been invoked with the `/report-pdf` command.
+
+## Arguments
+
+- `<path.md>` (required) — path to the Markdown report to render (for example
+  `.dev-team-reports/code-review.md` or `.dev-team-reports/test-health-2026-07-16.md`).
+- `--out <path>` (optional) — output PDF path. Defaults to the source path with
+  a `.pdf` extension, next to the source. A missing parent directory is created.
+
+If no path argument is supplied, report `path required — usage: /report-pdf <path.md> [--out <path>]` and stop.
+
+## Steps
+
+Invoke the shared render module through `hooks/py.sh` (never `python3`
+directly — the shim resolves a real Python 3 on Windows too), passing the
+arguments through verbatim:
+
+```bash
+sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/report_pdf.py" <path.md> [--out <path>]
+```
+
+The module detects a PDF engine (fallback order: pandoc + headless
+Chrome/Chromium → pandoc + weasyprint → pandoc + wkhtmltopdf → md-to-pdf) via
+runtime probes, converts the report with the bundled `report-print.css`, and
+prints a `Rendering PDF via <engine>…` progress line followed by one result
+line. Report its output as-is:
+
+- **Exit 0, `PDF written: …`** — the styled PDF was produced; report the output
+  path and engine verbatim.
+- **Exit 0, skip message (`No PDF engine found. Install one, …`)** — no engine
+  was available. Report the skip message verbatim, including the single install
+  hint. This is non-fatal: the source Markdown is untouched.
+- **Exit 1, `PDF not rendered: …`** — the source file was missing, or an engine
+  was present but conversion failed. Surface the stderr message verbatim.
+- **Exit 2** — usage error (argparse); surface the message verbatim.
+
+Do not add commentary beyond the module's own lines.
+
+## Related
+
+- `hooks/lib/report_pdf.py` — the shared render module this command wraps; the
+  same module backs the `--pdf` flag on report-producing skills (see
+  [`../../knowledge/report-pdf-integration.md`](../../knowledge/report-pdf-integration.md)).
+- [`../../knowledge/report-to-pdf.md`](../../knowledge/report-to-pdf.md) — the
+  underlying pandoc + headless-Chrome recipe and why this toolchain.
+- [`../../knowledge/report-output-location.md`](../../knowledge/report-output-location.md)
+  — where each report-producing skill writes its Markdown.

package/skills/review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: review
+description: >-
+  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.
+argument-hint: >-
+  [--agent <name>] [--since <ref>] [--path <dir>] [--all] [--json]
+  [--internal] [--force --reason "<text>"]
+  [--static-analysis|--no-static-analysis] [--init-risks] [--background]
+user-invocable: true
+allowed-tools: >-
+  Read, Write, Edit, Grep, Glob, AskUserQuestion, Agent,
+  Bash(git diff *), Bash(npx *), Bash(npm run *),
+  Bash(pnpm *), Bash(yarn *), Bash(tsc *), Bash(eslint *),
+  Bash(git log *), Bash(gh run *), Bash(semgrep *),
+  Bash(ruff *), Bash(mypy *), Skill(review-agent *)
+---
+
+# Review (alias)
+
+Role: orchestrator.
+
+## Orchestrator constraints
+
+1. Pure alias — change no behavior.
+2. Pass all arguments through to /code-review unchanged.
+3. **Be concise.** Defer all output to code-review.md.
+
+This is an alias for `/code-review`. Read and follow
+`skills/code-review/SKILL.md` with all arguments passed through.
+
+> **Keep frontmatter in sync.** This alias delegates the entire `/code-review`
+> flow, so its `allowed-tools` and `argument-hint` MUST mirror
+> `skills/code-review/SKILL.md`. `allowed-tools` is an allowlist — omitting a tool
+> the canonical command needs (e.g. `Edit` for the fix loop, `AskUserQuestion`
+> for the fix/report prompt, `Bash(ruff *)` for Python lint) silently breaks
+> that capability under `/review`.
+
+Arguments: $ARGUMENTS
+
+## Steps
+
+### 1. Pass through
+
+Read and follow `skills/code-review/SKILL.md` with `$ARGUMENTS` unchanged.

package/skills/review-agent/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: review-agent
+description: >-
+  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.
+argument-hint: "<agent-name> [--since <ref>] [--path <dir>] [--internal] [--json]"
+user-invocable: true
+allowed-tools: Read, Write, Grep, Glob, Bash(git diff *)
+---
+
+# Review Agent
+
+Role: worker. This skill performs the actual review using the agent
+definition as its specification.
+
+You have been invoked with the `/review-agent` skill. Run a single named review agent.
+
+This command is executed under orchestrator direction. Pass the named
+agent's `model:`/`effort:` frontmatter as declared — the harness resolves
+both fields natively before dispatch, per Model/Effort Resolution in
+`.claude/agents/orchestrator.md` (ADR 0026).
+
+## Worker constraints
+
+1. **Follow the agent definition exactly.** The agent file is your
+   specification — detect what it says to detect, skip what it says
+   to skip.
+2. **Respect context needs.** When reviewing uncommitted changes or `--since`,
+   honor the agent's `Context needs` field (diff-only, full-file, or
+   project-structure).
+3. **Do not add findings beyond the agent's scope.** If the agent
+   says "Ignore: naming, tests" — do not flag naming or test issues.
+4. **The structured JSON result (step 3) is the canonical output.**
+   In `--json` mode it is the *only* thing written to stdout — no
+   formatted summary, no report, no prose (see step 3c). Otherwise it is
+   also rendered as a formatted summary (step 4) and written to the durable
+   report (step 4b).
+5. **Be concise.** Issue messages should be one sentence. Suggested
+   fixes should be actionable, not explanatory. No preambles or
+   filler.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+Required: agent name (`$0`, e.g., `test-review`, `js-fp-review`, `security-review`)
+
+Optional:
+
+- `--since <ref>`: Review files changed since a git ref
+- `--path <dir>`: Target directory (default: current working directory)
+- `--internal`: This is an orchestrator-internal dispatch (e.g. `/build`'s
+  Phase 3 inline checkpoints) — skip the `.dev-team-reports/` report write in
+  step 4b. `/build` is the only sanctioned caller of this flag today.
+- `--json`: Machine-readable mode. Emit **only** the step-3 JSON result to
+  stdout and nothing else — skip the formatted summary (step 4), skip the
+  `.dev-team-reports/` report write (step 4b), and print no confirmation line,
+  preamble, or trailing prose. Used by subprocess callers such as
+  `/agent-eval --calibrate` that parse stdout and need a deterministic,
+  model-independent result. See step 3c.
+
+## Steps
+
+### 1. Load agent definition
+
+Read `.claude/agents/<name>.md` (project override) or else `${CLAUDE_PLUGIN_ROOT}/agents/<name>.md`. If neither exists, list available
+review agents from `${CLAUDE_PLUGIN_ROOT}/agents/` (the Review Agents section of
+`knowledge/agent-registry.md` is the roster) and ask the user to pick one.
+
+### 2. Determine target files
+
+Same auto-scope logic as `/code-review`:
+
+- If uncommitted changes exist: review those files
+- If working tree is clean: review all source files
+- `--since <ref>`: `git diff --name-only <ref>...HEAD`
+- `--path <dir>`: review files in that directory
+
+### 3. Run review
+
+Follow the agent definition to review each target file. Produce a JSON result
+per the shared contract in
+[`knowledge/review-agent-output-contract.md`](../../knowledge/review-agent-output-contract.md),
+wrapped with `agentName`:
+
+```json
+{
+  "agentName": "<name>",
+  "status": "pass|warn|fail|skip",
+  "issues": [
+    {
+      "severity": "error|warning|suggestion",
+      "confidence": "high|medium|none",
+      "file": "<path>",
+      "line": 0,
+      "message": "<description>",
+      "suggestedFix": "<fix>"
+    }
+  ],
+  "summary": "<summary>"
+}
+```
+
+### 3b. Apply ACCEPTED-RISKS.md suppression
+
+Before reporting, consult `ACCEPTED-RISKS.md` at the repo root if present. For each issue, check rules in declaration order per `knowledge/accepted-risks-schema.md`. The first matching rule suppresses the issue from the displayed result and emits an audit entry of the form `SUPPRESSED: <file>:<line> [<rule_id>] by ACCEPTED-RISKS rule <rule.id>`. Expired rules become inert (stop suppressing). Schema-invalid rules fail the run with a specific parse error. Absent file: skip silently.
+
+### 3c. `--json` mode (machine-readable output)
+
+When `--json` is passed, your **entire stdout response MUST be exactly one
+JSON object** matching the step-3 schema — nothing before it, nothing after
+it. Do **not** render the formatted summary (step 4), do **not** write the
+`.dev-team-reports/` report (step 4b), do **not** print a `Report written:`
+line, do **not** wrap the object in a code fence, and do **not** add any
+prose, preamble, or trailing commentary. ACCEPTED-RISKS suppression (step 3b)
+still applies — emit the post-suppression result. This mode exists so that
+subprocess callers (e.g. `/agent-eval --calibrate`) can parse the result
+deterministically across every model; any extra text breaks that contract.
+
+### 4. Report
+
+**Skip this step entirely when `--json` was passed** (see step 3c) — stdout
+must be exactly the JSON object. Otherwise, display the result as a formatted
+summary with issues grouped by file. Include suggested fixes inline. If any
+issues were suppressed by ACCEPTED-RISKS, list them in a dedicated trailing
+section with rule ids for audit.
+
+### 4b. Write the durable report (skip when `--internal` or `--json`)
+
+See `knowledge/report-output-location.md` for the shared write-scope
+convention this step follows.
+
+When neither `--internal` nor `--json` was passed, write the same formatted
+summary shown in step 4 to `.dev-team-reports/<agent-name>.md` in the target repository's
+working directory (creating `.dev-team-reports/` if absent), overwriting any
+existing file at that path — write it even when the review found zero
+issues. Print one confirmation line after the chat summary: `Report
+written: .dev-team-reports/<agent-name>.md`, or `Report written:
+.dev-team-reports/<agent-name>.md (replaced previous run)` when a file
+already existed at that path. If the write fails (permission/read-only):
+report `Cannot write .dev-team-reports/<agent-name>.md: <error>` to chat, and
+still return the JSON result and chat summary unchanged — the write failure
+is non-fatal and never blocks or alters the primary output.
+
+When `--internal` **was** passed (but not `--json`), skip this step entirely —
+behavior stays exactly as today (JSON + chat summary only). When `--json` was
+passed, this step is likewise skipped and stdout is the JSON object alone
+(step 3c).

package/skills/review-summary/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: review-summary
+description: >-
+  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.
+argument-hint: "[--from <json-file>]"
+user-invocable: true
+allowed-tools: Read, Write, Glob, Bash(date *), Bash(git rev-parse *), Bash(git branch *), Bash(mkdir *)
+---
+
+# Review Summary
+
+Role: orchestrator. This skill summarizes and persists review results — it does not review code.
+
+You have been invoked with the `/review-summary` skill. Generate a compact summary of the most recent code review.
+
+## Orchestrator constraints
+
+1. **Do not re-analyze code.** Summarize existing review results only.
+2. **Keep summaries under 150 words.** Compact summaries replace
+   full conversation history for future sessions (per
+   [Minimum CD session closure](https://migration.minimumcd.org/docs/agentic-cd/agent-configuration/)
+   pattern).
+3. **Use the template exactly.** Structured output enables machine parsing.
+4. **Be concise.** The 150-word limit is a ceiling, not a target. Shorter is better. No filler phrases.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- `--from <json-file>`: Read review results from a JSON file (output
+  of `/code-review --json`). If not provided, summarize from the
+  most recent `/code-review` output in the conversation.
+
+## Steps
+
+### 1. Gather review data
+
+If `--from` is specified, read the JSON file. Otherwise, look for
+the most recent code review results in the current conversation
+context.
+
+Extract: overall status, agent statuses, issue counts by severity, and top issues.
+
+### 2. Generate compact summary
+
+Write a summary under 150 words following this template:
+
+```markdown
+## Review: <branch> @ <short-sha> — <date>
+
+**Status**: <PASS|WARN|FAIL> (<N> agents, <N> issues)
+
+**Findings**:
+- <top 3-5 findings, one line each, severity prefix>
+
+**Blocked by**: <agent names that returned fail, or "none">
+
+**Action items**: <1-3 concrete next steps>
+```
+
+### 3. Save summary
+
+Write the summary to `.claude/review-summaries/<date>-<short-sha>.md`.
+
+Create the `.claude/review-summaries/` directory if it doesn't exist.
+
+### 4. Report
+
+Display the summary to the user. Note that it will be available as context in future sessions.

package/skills/run-report/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: run-report
+description: >-
+  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.
+argument-hint: "[--session <id>]"
+user-invocable: true
+allowed-tools: >-
+  Bash(python3 *, jq *, tail *, cat *, ls *, test *)
+---
+
+# Run Report (#1167)
+
+Role: worker. Reports one `session_id`'s composed run timeline by joining the
+existing deterministic metrics streams — no model tokens spent parsing
+transcripts.
+
+`workflow-states.jsonl` (#1166) records only state *transitions*; current
+state and per-state dwell time are always derived by replay
+(`hooks/lib/workflow_state.py::derive_current_state()` /
+`compute_dwell_times()`). `boundary-events.jsonl` records every guard hook's
+block/warn/bypass decision. `cost-metering.jsonl` records per-session token
+spend, but is keyed by transcript filename, not `session_id` — see Join
+limitations below.
+
+## Steps
+
+1. **Run the report.** If the user passes `--session <id>`, use it; otherwise
+   let the library auto-detect the most recent `session_id` seen across
+   `boundary-events.jsonl` and `workflow-states.jsonl`:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/run_report.py" report --session <id>
+   ```
+
+2. **Present a readable summary, not raw JSON.** Render the JSON the library
+   prints as a short table/summary:
+   - `session_id` and `current_state`
+   - a `dwell_seconds` table, one row per state
+   - `rejection_count` and `bypass_count`
+   - `denials_by_cause` as a table of `matched_rule -> count`
+   - the `cost` section: if `joinable` is `false`, say so plainly and show
+     `reason` plus the `most_recent_entry` (if any) labeled as a rough,
+     unattributed proxy — never present it as this session's actual cost.
+
+3. If a stream file is absent, its section is simply empty (zero counts, no
+   dwell times) — that is not an error; say so rather than treating it as a
+   failure.
+
+## Join limitations
+
+`cost-metering.jsonl` entries are written by the `Stop` hook
+(`hooks/cost_meter.py` → `hooks/lib/cost_meter.py::cmd_record()`) keyed by
+transcript filename — the hook never learns the session ID, so there is no
+reliable per-session join key today. Rather than guess an attribution the
+data doesn't support, the report marks `cost.joinable: false` and surfaces
+only the most recent recorded entry as an unattributed reference point. A
+future stream-schema change adding `session_id` to `cost-metering.jsonl`
+would let this become a real join.
+
+## Privacy boundary
+
+This report composes only fields the underlying streams already document in
+`knowledge/telemetry-schema.md` (rule IDs, counts, state names, token/dollar
+totals) — never command text, prompt text, or file contents.