add report generation skills

hypaware-core/plugins-workspace/claude/hypaware.plugin.json

@@ -34,7 +34,11 @@
     "skills": [
       { "name": "hypaware-query", "clients": ["claude"] },
       { "name": "hypaware-ignore", "clients": ["claude"] },
-      { "name": "hypaware-unignore", "clients": ["claude"] }
+      { "name": "hypaware-unignore", "clients": ["claude"] },
+      { "name": "hypaware-ai-adoption-report", "clients": ["claude"] },
+      { "name": "hypaware-ai-improvement-report", "clients": ["claude"] },
+      { "name": "hypaware-ai-security-report", "clients": ["claude"] },
+      { "name": "hypaware-ai-spend-report", "clients": ["claude"] }
     ],
     "agents": [
       { "name": "hypaware-analyst", "clients": ["claude"] }

hypaware-core/plugins-workspace/claude/skills/hypaware-ai-adoption-report/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: hypaware-ai-adoption-report
+description: AI Adoption Profile for a HypAware server — descriptive "who's using the fleet and how": per-gateway utilization (volume + focus — top models, tools, repos, themes) and parallelism/fan-out (multi-agent adoption, concurrency, main-vs-subagent split, payoff).
+---
+
+# AI Adoption Profile
+
+The one **descriptive** report on *who's using the fleet and how* — no actions, just a clear
+picture. Two lenses over one window:
+
+- **Utilization** — per `gateway_id` (≈ one machine/user): *how much* (messages, sessions,
+  active days, tokens, cache-read ratio) and *what it's focused on* (top models, tools, repos,
+  work themes).
+- **Parallelism / fan-out** — *how sophisticated*: multi-agent adoption, fan-out breadth/depth,
+  true concurrency vs serial, the main-loop-vs-subagent token split, and whether fan-out appears
+  to earn its cost.
+
+IMPORTANT: Don't assume which logs to read — **ask first.** Start by listing the data sources
+and let the user choose which to query: **local logs** (this machine's own recordings —
+`hyp query sql …`, no `--remote`) and **each remote HypAware server** (every target from
+`hyp remote list`, plus any hypaware MCP server already available to you as MCP tools (a
+`query_sql` / `graph_neighbors` tool in your toolset); the same server can appear both ways —
+list it once). Present the options,
+ask which one (or more) to profile, then proceed against the chosen source.
+
+**Descriptive only** — route every *action* out: "fan out more/less" and tooling go to
+**hypaware-ai-improvement-report**, token waste to **hypaware-ai-spend-report**. Query mechanics
+live in the **hypaware-query** skill; reuse hypaware-ai-spend-report's deduped token spine for
+any token figure.
+
+## Procedure
+1. **Scope + coverage.** Distinct `gateway_id` (the unit — `user_id` is ~always null, so don't
+   measure reach by it); window; coverage of `gateway_id`, token usage, and subagent provenance
+   (`agent_id` / `is_sidechain` / `parent_thread_id` — transcript-enriched, may not survive
+   ingest). Decide cost-capable vs volume-only, and which parallelism dimensions are real vs
+   proxied (the `Task`-call proxy). State N; if it's effectively one gateway / dogfood, say so.
+2. **Per-gateway utilization.** One row per gateway: volume (messages, sessions, active days,
+   first/last seen), tokens + cache-read ratio `cache_read/(cache_read+input)`, then its focus —
+   top models (+ `(unknown)`), tools (Bash dominance + top commands), repos, client
+   (claude/codex), and 2–4 recurring work themes (sampled, redacted). Distill each into a
+   one-line **focus label**. Use the activity graph for structural focus (Session→Repo/PR via
+   GitHub enrichment) where projected.
+3. **Parallelism / fan-out.** Adoption (% conversations with ≥1 subagent, incl. the zero
+   bucket); breadth (subagents per parent) and depth (`parent_thread_id` chains); concurrency
+   (do subagent time-spans actually *overlap*, or is it serial?); cost split (token share main
+   loop vs subagent). Read the payoff *descriptively* — fan-out vs tokens-to-resolution — and
+   route the "fan out more/less" recommendation to hypaware-ai-improvement-report.
+
+## Output — SAVE A MARKDOWN FILE
+- **Path:** `hypaware-reports/<YYYY-MM-DD>-adoption-profile.md` (create the dir if needed).
+  Dated so reports accumulate.
+- **Bottom line (1 sentence):** how many gateways are active, the busiest one and its focus, and
+  the headline fan-out adoption %.
+- **Per-gateway profile (sortable table):** one row per gateway — **gateway** · **volume**
+  (messages / sessions) · **tokens** · **cache-read %** · **fan-out** (adoption + main-vs-subagent
+  split) · **focus label**. Busiest first — this table is the spine.
+- **Then the detail**, in these sections: **Scope & coverage · Per-gateway utilization ·
+  Per-gateway focus · Parallelism & fan-out · Payoff (descriptive) · Fleet view · Caveats**.
+- **Formatting (human-readable):** open each section with its takeaway; **bold** headline
+  numbers; one sortable footprint table as the centerpiece; keep the bottom line + table a
+  ~1-minute read.
+- **Capture-health note:** if subagent provenance doesn't reach the server, the standing #1
+  caveat is "subagent identity must survive ingest" — run adoption off the sub-agent-invocation
+  proxy (the tool calls that spawn sub-agents) and flag it.

hypaware-core/plugins-workspace/claude/skills/hypaware-ai-improvement-report/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hypaware-ai-improvement-report
+description: Analyze AI agent logs and generate a markdown report identifying additions or modifications to skills, subagents, and AGENTS.md/CLAUDE.md, to improve quality and efficiency of the AI agent performance.
+---
+
+# AI Improvement Review
+
+Read how the team's agents actually behave in the logs, then propose the **additions and
+edits to skills, subagents, and AGENTS.md/CLAUDE.md** that make them do **better work
+(quality)** with **less wasted effort and spend**.
+
+IMPORTANT: Don't assume which logs to read — **ask first.** Start by listing the data sources
+and let the user choose which to query: **local logs** (this machine's own recordings —
+`hyp query sql …`, no `--remote`) and **each remote HypAware server** (every target from
+`hyp remote list`, plus any hypaware MCP server already available to you as MCP tools (a
+`query_sql` / `graph_neighbors` tool in your toolset); the same server can appear both ways —
+list it once). Present the options,
+ask which one (or more) to run the review against, then proceed against the chosen source.
+Query mechanics live in the **hypaware-query** skill; read it first.
+
+Focus on these signals:
+
+- **Repeated work** — work the team repeats successfully → package it once (skill / subagent).
+- **Sticking points** — where agents get stuck or redo work (errors, loops, refusals,
+  abandonment) → the missing or too-weak instruction that would prevent it (an AGENTS.md
+  rule, or a skill).
+- **Inefficiency** — expensive patterns (model over-spec, context bloat, low cache-read,
+  retry loops) → the setup change that costs less (right-size the model in AGENTS.md / a
+  subagent, a context-hygiene rule, a skill that avoids the redo).
+
+## Procedure
+1. **Footprint + basis.** Window; distinct contributors (`gateway_id`), repos, sessions;
+   claude/codex mix. State N and breadth; flag if single-contributor.
+2. **Scan the signals for possible improvements.** Work the three signals above; each turns
+   up candidates. Note frequency (sessions, distinct gateways) and redact examples.
+   - **Repeated work** — cluster sessions by shared-file overlap and tool-set signature into
+     recurring kinds of work (reuse a recent `hypaware-reports/` *Leverage candidates*
+     handoff if present). Flag parallelizable work done serially (low `is_sidechain`, few
+     `agent_id`), and recurring asks / multi-step workflows / re-sent instructions in
+     sampled prompts + `system_text`.
+   - **Sticking points** — where agents got stuck or redid work, ranked by impact: failing
+     tools (`is_error` by `tool_name`), retry loops (same tool + first `tool_args` token
+     ≥3×/session), refusals/truncations (stop-reason), abandoned costly sessions,
+     repeatedly-violated conventions.
+   - **Inefficiency** (reuse the spend spine) — model over-spec, context bloat (no
+     `is_compact_summary`), low cache-read (`cache_read/(cache_read+input)`), redo loops.
+3. **Collect, dedup, prioritize.** Gather the candidates into a list of possible
+   improvements; drop anything an existing artifact already covers — a quick scan of the
+   repo's `.claude/skills/`, subagents, and AGENTS.md/CLAUDE.md (the only repo read — every
+   other signal is the logs), used to dedup and to mark each survivor **new** vs **edit to
+   an existing artifact**. For each, suggest a likely form
+   where one obviously fits — a **skill**, a **subagent**, or an **AGENTS.md/CLAUDE.md
+   edit** (propose the concrete line(s) as a diff, not "consider documenting") — but don't
+   force a mapping. Attach evidence (frequency/impact + distinct gateways + token prize) and
+   rank by it.
+   - **Size the token prize** off the spend spine (deduped `max()` per `message_id`; a plain
+     `SUM` overcounts ~3×). Give two numbers, kept distinct: **exposure (measured)** — tokens
+     currently flowing through the issue (sum across a repeated cluster, or tokens in
+     error/retry/abandoned turns) — and **est. saving (assumption)** only where the
+     counterfactual is clean (cache-read ratio, model right-size). Both are floors — capture
+     is partial; never present a saving as if it were measured.
+
+## Output — SAVE A MARKDOWN FILE
+- **Path:** `hypaware-reports/<YYYY-MM-DD>-improvement-review.md` (create the dir
+  if needed). Dated so reviews accumulate.
+- **Bottom line (1 sentence):** "Create/edit these N things and what it will improve.".
+- **Improvements (ranked table):** one row per improvement — **what** · **suggested form**
+  (skill / subagent / AGENTS.md edit, where one fits) · **evidence** (recurs N× across G
+  gateways, sticking-point impact) · **token prize** (exposure measured / est. saving,
+  labeled) · **where it lands**. Highest-leverage first.
+- **Then the detail**, in these sections: **Basis · Skill candidates · Subagent candidates
+  (fan-out + roles) · AGENTS.md/CLAUDE.md edits · Efficiency → setup changes · Caveats** —
+  plus the proposed AGENTS.md lines verbatim. Each candidate is marked **new** or **edit to
+  <artifact>**; don't list artifacts that aren't being changed.
+- **Formatting (human-readable):** every candidate states its evidence inline; show
+  AGENTS.md edits as real diffs/code blocks, not prose; **bold** the artifact type; keep
+  it a ~1-minute read.

hypaware-core/plugins-workspace/claude/skills/hypaware-ai-security-report/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: hypaware-ai-security-report
+description: Security & Risk Review for a HypAware server — audits gateway logs for risky autonomous activity (destructive commands, remote-exec, privilege escalation, secret reads, network egress, package installs), severity-ranks findings, and recommends guardrails. Saves a dated report under hypaware-reports/; first asks which HypAware source to query (local logs or a remote server) via the hypaware-query skill. Audits recorded logs, NOT pending code — for a code diff use a dedicated code-review tool.
+---
+
+# Security & Risk Review
+
+Turn a window of central AI-gateway logs into a severity-ranked picture of **what agents did
+unsupervised that carries risk**, and the guardrails to contain it. This audits *recorded
+activity*, not pending code (for a diff, use a dedicated code-review tool). Be
+proportionate: separate "ran a risky command" from "caused harm".
+
+IMPORTANT: Don't assume which logs to read — **ask first.** Start by listing the data sources
+and let the user choose which to query: **local logs** (this machine's own recordings —
+`hyp query sql …`, no `--remote`) and **each remote HypAware server** (every target from
+`hyp remote list`, plus any hypaware MCP server already available to you as MCP tools (a
+`query_sql` / `graph_neighbors` tool in your toolset); the same server can appear both ways —
+list it once). Present the options,
+ask which one (or more) to audit, then proceed against the chosen source.
+
+**REDACT everything** — never echo a secret, token, key, or credential value in the report,
+even one you found in `tool_args`; a raw secret appearing in args is itself a capture finding
+(flag it, don't reproduce it). Query mechanics live in the **hypaware-query** skill; read it first.
+
+## Risk classes (match over the FULL command text, not just the first token)
+| Class | Match signals | Why it matters |
+| --- | --- | --- |
+| Destructive | `rm -rf`, `git reset --hard`, `git push --force`, `drop`/`truncate`, `dd`, `mkfs` | irreversible data/history loss |
+| Remote-exec | `curl`/`wget … \| sh`/`bash`, piped installers | runs unreviewed remote code |
+| Privilege | `sudo`, `su`, `chmod 777`, writing system paths | escalation beyond the workspace |
+| Secret read | `.env`, `id_rsa`, `.ssh`, `.aws`, `.netrc`, `AWS_*`, `*token*`, `credentials` | credential exposure |
+| Network egress | outbound `curl`/`scp`/`nc` POSTs to external hosts | potential exfiltration |
+| Package install | `npm i`, `pip install`, `brew install`, `apt` | supply-chain surface |
+
+Risk is **amplified by autonomy** — weight anything that ran under `bypassPermissions` higher
+than the same command in a gated session.
+
+## Procedure
+1. **Coverage + autonomy baseline.** Window; coverage of `tool_args` on Bash calls and of
+   `permission_mode` (bound the read if sparse); distinct `gateway_id` (the unit — `user_id` is
+   ~always null). Total tool calls, % Bash, % conversations in `bypassPermissions`. State N; if
+   it's a dogfood window, say so.
+2. **Scan + rank.** Histogram the first token of each Bash command (top 30 = the normal), then
+   match the full text against each risk class: count, ONE redacted example, and the
+   `gateway_id`/`git_branch` where it ran. Rank by frequency × blast radius × autonomy; keep
+   "ran" vs "caused harm" distinct, and note anything that ran in a *gated* (non-bypass) session.
+3. **Guardrails.** For each top risk, a concrete control + estimated coverage: a tool-exec
+   **guardrail** (a pre-exec hook or approval policy, deny/allow), a **permission / allowlist
+   policy**, an **agent-instructions rule** (AGENTS.md / CLAUDE.md), or a **gateway redaction**
+   fix for any secret seen in args.
+
+## Output — SAVE A MARKDOWN FILE
+- **Path:** `hypaware-reports/<YYYY-MM-DD>-security-review.md` (create the dir if needed).
+  Dated so reports accumulate.
+- **Bottom line (1 sentence):** the posture — how autonomous the fleet is (% `bypassPermissions`)
+  and whether anything needs urgent attention.
+- **Findings (severity-ranked table):** one row per finding — **risk class** · **severity**
+  (high / med / low) · **count** · **example (redacted)** · **guardrail** · **where it ran**.
+  Highest severity first.
+- **Then the detail**, in these sections: **Autonomy baseline · Command profile · Risk findings
+  · Guardrails · Trends · Capture caveats**. **All examples redacted.**
+- **Formatting (human-readable):** open each section with its takeaway; **bold** severities; one
+  severity-ranked findings table as the centerpiece; keep the bottom line + table a ~1-minute read.
+- **Capture-health note:** if raw credentials appear in `tool_args`, the standing #1 finding is
+  "gateway must redact secrets in tool_args" — put it in Capture caveats without reproducing it.