@groupby/ai-dev 0.5.16 → 0.5.17

package/teams/firstspirit-caas/skills/handle-weekly-cve-plans/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: handle-weekly-cve-plans
+description: Use when the user asks to check, triage, or fix the weekly CVE Bamboo plans across the known service repos — phrases like "handle the weekly CVE plans", "check the weekly sonatype builds for CVE reds", "run the weekly CVE sweep", "fix this week's dependency-check reds". Assumes it is invoked from a folder containing the target repos. Distinct from handle-red-cve-plan, which fixes one repo from one Bamboo URL.
+---
+
+# handle-weekly-cve-plans
+
+One-shot orchestrator. Checks a fixed set of weekly Bamboo plans, finds the ones that are red
+**because of CVEs**, and fans out one `handle-red-cve-plan` subagent per affected repo. All
+remediation logic lives in `handle-red-cve-plan`; this skill only **routes, summarizes, and
+gates the final push**. Runs the detection, ticket handling, and dispatch autonomously. It
+stops for the user only twice: **immediately** when a target repo is blocked (tracked edits, or
+an ambiguous ticket branch — a per-repo decision at dispatch, step 5.2), and the **push question** at the end
+(step 7). Clean repos never wait on a blocked one.
+
+## Parameters
+
+- **existing ticket** (optional) — a JIRA key (e.g. `PX-1234`) named at invocation ("handle
+  the weekly CVE plans PX-1234"). When supplied, that ticket is used as the tracking ticket and
+  **no new ticket is created**. When omitted, the skill creates one (step 3).
+
+## When NOT to use
+
+- A single repo / single Bamboo URL → use `handle-red-cve-plan` directly.
+- A local JSON dependency-check report in hand → use `handle-cve`.
+
+## Plan table (source of truth)
+
+Repo name = expected sub-directory name under the invocation folder.
+
+| Repo | Bamboo plan URL |
+|---|---|
+| caas-connect | https://ci.e-spirit.de/browse/CAASCAASCONNECT-WEEKLYMASTERBUILDUSINGSONATYPEOSS/latest |
+| caas-fsm | https://ci.e-spirit.de/browse/CAASCAASFSM-WEEKLYMASTERBUILDUSINGSONATYPEOSS/latest |
+| caas-platform | https://ci.e-spirit.de/browse/CAASCAASPLATFORM-WEEKLYCVECHECKUSINGSONATYPEOSS/latest |
+| caas-platform-mcp | https://ci.e-spirit.de/browse/CAASCAASPLATFORMMCP-WEEKLYCVECHECKUSINGSONATYPEOSS/latest |
+| navigation-service-fsm | https://ci.e-spirit.de/browse/NAVNAVIGATIONSERVICEFSM-WEEKLYMASTERBUILDUSINGSONATYPEOSS/latest |
+| navigation-service-micronaut | https://ci.e-spirit.de/browse/NAVNAVIGATIONSERVICEMICRONAUT-WEEKLYCVECHECKUSINGSONATYPEOSS/latest |
+| videomanagementpro | https://ci.e-spirit.de/browse/VIDVIDEOMANAGEMENTPRO-WEEKLYMASTERBUILDUSINGSONATYPEOSS/latest |
+| smartsearch-connect | https://ci.e-spirit.de/browse/ZTSMARTSEARCHCONNECT-WEEKLYMASTERBUILDUSINGSONATYPEOSS/latest |
+| haupia | https://ci.e-spirit.de/browse/SMASE-WDCS/latest |
+
+Every plan is a Sonatype-OSS build → every dispatched subagent gets `useSonatype`.
+
+## Workflow
+
+### 1. Locate the repos
+For each repo name, resolve its directory:
+- Direct sub-directory of the invocation folder matching the name → use it.
+- Miss → search the invocation folder and one level up.
+- Still missing → collect the misses and **ask the user** for the path(s) before dispatching.
+  Repos the user cannot supply are recorded as `skipped: not found` and do not block the rest.
+
+### 2. Detect CVE-red plans (main thread, per plan)
+Resolve each plan's latest build, then classify from state + log — **do not** download or
+parse the dependency-check report artifact:
+
+```
+get_bamboo_build(<PLAN>-latest)
+  state != Failed          -> skip: green/ok
+  state == Failed:
+    get_bamboo_build_log(<build_key>)
+      log contains the marker line
+        "One or more dependencies were identified with vulnerabilities
+         that have a CVSS score greater than '7.0': CVE-..., CVE-..."
+                            -> DISPATCH (capture the listed CVE ids for the report)
+      else                  -> skip: red, non-CVE reason
+```
+
+The first `get_bamboo_build` failing on auth → **hard stop** (token/config problem): report and
+dispatch nothing. A per-plan error after that (one build/log unreadable) is **isolated** — mark
+that plan `skipped: <reason>` and continue with the others.
+
+### 3. Ensure a tracking ticket
+Only if step 2 produced **at least one** dispatch target. No targets → skip this step entirely
+(create no ticket).
+
+- **User named an existing ticket at invocation** → use that key as `<TICKET>`. Create nothing,
+  add no label, do not transition it — leave the user's ticket as-is.
+- **No ticket named** → create, label, and transition a new ticket. All of the following is
+  **pre-approved by the skill invocation** — do not pause for separate confirmations; print
+  each user-visible action (the create fields, and each `from -> to` status move) as you do it.
+
+  1. **Create.** Call `mcp__plugin_planetexpress_jira-tools__create_jira_ticket`:
+     - `project_key`: `PX`
+     - `issue_type`: `Escaped Bug`
+     - `summary`: `Handle Weekly CVEs <date>` (today's date, `YYYY-MM-DD`)
+     - `labels`: `SIZE_XS`
+     - `description` (Jira wiki markup): one row per dispatch target — repo name, the CVE ids
+       from the log marker, and a link to that repo's Bamboo plan (the plan URL from the table).
+       E.g. `* [caas-connect|<plan-url>] — CVE-2026-54428, CVE-2026-54399`.
+     - Capture the returned key as `<TICKET>`.
+
+  2. **Transition** through this target-status sequence, in order:
+     `Backlog → Committed → Specify → In Implementation` (the workflow's "Implement" state).
+     Status names and available transitions are **state-dependent — never hardcode ids**. For
+     each target in the sequence:
+     - If the ticket is already in that status, skip it.
+     - Otherwise call `mcp__plugin_planetexpress_jira-tools__transition_jira_ticket` with
+       `status` = the target name (it matches case-insensitively on target status or transition
+       name, one hop per call).
+     - If that errors because the target isn't directly reachable, the error lists the
+       transitions that *are* available — call `get_jira_transitions`, take the single hop that
+       advances toward the sequence, then retry the target. Repeat until the target is reached.
+     - Stop the walk at the first target that cannot be reached even via an intermediate hop:
+       report how far it got (`<TICKET>` reached status X) and continue to dispatch — a
+       not-fully-transitioned ticket does not block the CVE work.
+
+`<TICKET>` (named or created) is passed to every subagent in step 5.
+
+### 4. Pre-flight cleanliness check (main thread, per dispatch target)
+A blocker (tracked edits, or an ambiguous ticket branch) is **knowable up front with plain git** —
+detect it here, in the main thread, before spending a subagent on it. A subagent cannot prompt
+the user, and parallel subagents hand control back only after **all** finish; leaving this check
+inside the subagent means a blocker surfaces (as `failed`) only once every other repo's build is
+done. Catch it first instead.
+
+For each target from step 2, run in the main thread (no build, seconds each):
+
+```
+git -C <repo> fetch origin
+git -C <repo> symbolic-ref refs/remotes/origin/HEAD   # derive <default> (never assume master)
+git -C <repo> status --porcelain -uno         # tracked edits only; untracked files ignored (never blocking)
+git -C <repo> branch --show-current          # current branch
+git -C <repo> branch -a --list "*<TICKET>*"  # ticket-branch matches
+```
+
+Classify each target. Two things are **not** blockers, because the subagent handles them itself:
+- **Untracked files** — not touched by a branch switch or by the subagent, so a stray
+  unstaged/untracked file is irrelevant. Only *tracked* modifications (staged or unstaged edits
+  to tracked files) count as dirty.
+- **The current branch** — `handle-red-cve-plan` step 4 switches off the latest default branch
+  (reusing the ticket branch if one exists, else creating one off `origin/<default>`) from
+  whatever branch is checked out. A clean tree on an unrelated branch is safe to switch away
+  from — no WIP is lost (committed work stays on its branch).
+
+- **clean** — no tracked modifications (empty `status --porcelain -uno`) **and** at most one
+  branch matches `<TICKET>`. Dispatch as-is (step 5.1). Untracked files and the current branch
+  identity are irrelevant — dispatch anyway.
+- **blocked** — tracked edits, **or** more than one branch matches `<TICKET>` (a genuine
+  ambiguity the subagent cannot resolve — `handle-red-cve-plan` step 4 hard-stops on it, so catch
+  it here before wasting a dispatch). Needs a user decision (step 5.2). Capture the blocking
+  evidence — the `status --porcelain -uno` lines and/or the matching branch list — to show the
+  user.
+
+### 5. Dispatch
+
+**5.1 — Dispatch every clean target first, in the background.** Spawn all clean-target
+subagents with `run_in_background: true` **before** raising any blocked repo, so their builds
+start immediately and run while blocked repos are being resolved. A clean repo never waits on a
+blocked one. Use the `general-purpose` agent type; prefix the description with `[opus]` per repo
+convention.
+
+**5.2 — Then resolve each blocked target interactively (main thread).** Only after the clean
+targets are dispatched, raise the blocked ones — one `AskUserQuestion` per blocked repo, showing
+its captured blocking evidence from step 4. The remedies depend on **why** it blocked:
+
+**Blocked by tracked edits (dirty tree).** Offer three remedies:
+
+- **Stash** — `git -C <repo> stash push -m "handle-weekly-cve pre-flight <date>"` parks the
+  tracked edits (no `-u`; untracked files are left in place, they never blocked). **Never pop it
+  automatically** — the subagent works on its own branch off the default; the stash stays parked
+  for the user to `git stash pop` manually later. Report the stash ref in step 6 so it is not
+  silently buried. Then dispatch the repo (background, same as 5.1).
+- **Discard** — destructive. State exactly what is deleted before running:
+  `git -C <repo> switch <default> && git -C <repo> reset --hard origin/<default> && git -C <repo> clean -fd`.
+  Then dispatch (background).
+- **Skip** — leave the repo entirely untouched; record `skipped: dirty tree (user chose skip)`
+  and do not dispatch.
+
+**Blocked by an ambiguous ticket branch (>1 branch matches `<TICKET>`).** A tree remedy does not
+apply, and `handle-red-cve-plan` has no parameter to pick a branch — it hard-stops on ambiguity.
+Offer two remedies:
+
+- **Skip** — record `skipped: multiple <TICKET> branches (<list>)` and do not dispatch.
+- **Resolve manually** — the user deletes/renames the stray branch(es) so exactly one matches,
+  confirms, then re-run the step-4 check for this repo only; once a single branch matches it is
+  **clean** — dispatch it (background). Do **not** delete branches automatically.
+
+Each subagent prompt (clean or resolved) must:
+- State the absolute repo path and instruct it to `cd` there first (that path is its working
+  directory for the whole run — `handle-red-cve-plan` operates on the current directory).
+- Instruct it to invoke the `handle-red-cve-plan` skill for that plan's Bamboo URL **with
+  `useSonatype`** and the tracking ticket **`<TICKET>`**, running fully autonomously (no
+  confirmation stops).
+- Require it to return a single structured result and nothing else:
+  - `repo` — the repo name
+  - `outcome` — one of `pr` | `unpushed-commit` | `nothing-to-do` | `failed`
+  - `link` — PR URL (for `pr`) or commit SHA + default-branch name (for `unpushed-commit`)
+  - `detail` — one line: CVEs bumped/suppressed, or the failure/hard-stop reason
+
+A subagent that dies or hard-stops → its repo is `failed` with the reason. It never blocks the
+other subagents or the final report. (The pre-flight guard in `handle-red-cve-plan` step 4
+remains a backstop: if a tree goes dirty between the check and dispatch, that subagent still
+`failed`s rather than committing over it.)
+
+### 6. Report
+Lead with the tracking ticket (`<TICKET>` — created or reused). Then print a summary table
+`repo | outcome | link/SHA/reason`, then group:
+- **PRs opened** (`pr`, Path B) — with URLs.
+- **Unpushed commits on default branch** (`unpushed-commit`, Path A suppressions-only) — repo,
+  SHA, branch. These are the only ones that still need pushing.
+- **Pre-flight resolutions** — any repo that was stashed, discarded, or skipped in step 5.2.
+- **Parked stashes (restore manually)** — every repo where the user chose **Stash**: repo +
+  stash ref/message. These are loose ends the user must `git stash pop` themselves — surface them
+  explicitly so nothing is buried.
+- **Skipped** — green, non-CVE red, not-found (with which), or user-skipped blocks (dirty tree
+  or ambiguous ticket branch).
+- **Failed** — repo + reason.
+
+### 7. Push gate (only stop)
+Path B branches are already pushed and PR'd by the subagent — nothing to do. Only the Path A
+`unpushed-commit` repos have local commits sitting on their default branch. Finish by asking
+the user whether to push those. On **yes**: for each such repo, push the exact commit that was
+reported (its default branch) and confirm each. On **no**: leave them local and stop.
+
+Restate any **parked stashes** from step 6 alongside the push gate — they still need a manual
+`git stash pop` and are easy to forget.
+
+## Hard stops (report, dispatch nothing)
+
+| Situation | Behaviour |
+|---|---|
+| Very first `get_bamboo_build` fails on auth | Token/config problem — report and stop before dispatching |
+| User cannot supply any repo path and asks to abort | Report what was found and stop |
+| Ticket creation fails (step 3, no existing ticket named) | Report and stop — do not dispatch subagents without a tracking ticket |
+
+## Constraints
+
+- Never merge PRs (subagent opens them; merge is the user's call).
+- Never push Path B branches (already pushed).
+- Never push a Path A commit before the user answers the push gate.
+- Never edit repo files in the main thread — all remediation happens inside subagents via
+  `handle-red-cve-plan`. The **only** main-thread git mutations allowed are the user-chosen
+  pre-flight remedies in step 5.2 (stash / discard), and only for the specific blocked repo the
+  user picked them for.
+- Never auto-pop a stash created in step 5.2 — park it, report it, leave restoration to the user.
+- Do not download/parse the OWASP report in the main thread; detection is log-based only.

package/teams/firstspirit-caas/skills/retrospect/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: retrospect
+description: Use when the user asks to review, retrospect, or post-mortem the current Claude Code session — phrases like "retrospect this session", "what went wrong this session", "analyse my prompts", "session retrospective", "/retrospect". Triggers on requests to look back over a session's prompts and find what could be improved in the harness.
+---
+
+# Retrospect
+
+## Overview
+
+Analyses a Claude Code session transcript and produces a structured HTML report listing **every** prompt the user sent, what each one led to, which ones went suboptimally (highlighted red), and — for the problematic ones — a **class-level** improvement to the harness so the same *type* of problem is avoided or reduced in future.
+
+**Core principle:** Completeness is mechanical, judgment is yours. A bundled script enumerates every prompt from the transcript (you can never drop or summarise one). Your job is only to judge each prompt and write improvements that generalise — never improvements that would fire only on the one exact situation.
+
+## When to Use
+
+- User asks to retrospect / post-mortem / review the current session.
+- User wants to know what could be improved in their setup based on how the session went.
+
+Not for: reviewing a PR or ticket (use `review`), or summarising work for JIRA (use `summarise-for-jira-comment`).
+
+## Workflow
+
+The extractor/renderer script `extract_prompts.py` lives in this skill's directory. Run it with `python3`.
+
+1. **Extract** — run `extract_prompts.py extract`. With no `--transcript` it auto-selects the newest `.jsonl` in the current project's transcript dir = the session you are in. Output goes to `.claude/retrospects/` by default; override with `--outdir DIR`. It writes `<stamp>-data.json` and prints `{data_file, analysis_file, html_file, count}` — use those exact paths in the later steps. `count` = N, the number of prompts you must analyse.
+2. **Read** the `data_file`. It holds `prompts: [{n, text, trace}]` — `trace` has a compact `assistant_summary` and the `tools` used after that prompt.
+3. **Analyse** every prompt. Build the analysis object (see schema below), keyed by prompt number as a string. Mark only genuinely suboptimal prompts/results as problems; the rest get a short `note`.
+4. **Write** the analysis object to the printed `analysis_file` path (JSON).
+5. **Render** — run `extract_prompts.py render --data <data_file> --analysis <analysis_file>`. It prints `{html_file, count, flagged, missing_analysis}`.
+6. **Verify gate** — `missing_analysis` MUST be `0`. If it is not, you skipped prompts; add the missing keys and re-render. Do not report until it is 0.
+7. **Report** — present the report as a **clickable link** plus a one-line tally (N prompts, X flagged). Resolve `html_file` to an absolute path and give it as a `file://` markdown link, e.g. `[Open retrospect](file:///abs/path/to/...-retrospect.html)`, so the user can click straight through. Stop. Do not edit CLAUDE.md, skills, or any config — this skill is report-only.
+
+## Analysis JSON Schema
+
+Object keyed by prompt number (string). Each value:
+
+| Field | When | Meaning |
+|-------|------|---------|
+| `topic` | every prompt, where applicable | Short group label (≤~40 chars). Prompts sharing a `topic` render together as one collapsible group, in first-appearance order. |
+| `problem` | suboptimal prompts only | What went wrong with the prompt or the result it produced. |
+| `suggestion` | with `problem` | The **class-level** improvement (see rule below). |
+| `location` | with `problem` | Where the improvement belongs (see taxonomy below). |
+| `impact` | with `problem` | Integer 1–5, how much value fixing this class would deliver (5 = high). Drives ranking of the top-of-document Suggestions list. |
+| `note` | OK prompts | One short line; why it was fine. Omit `problem`/`suggestion`. |
+
+Besides `topic`, a prompt has exactly one of: `{problem, suggestion, location}` OR `{note}`.
+
+**Topics / grouping:** assign a `topic` to each prompt so the report clusters related prompts (e.g. all prompts about one feature share `"topic": "Auth refactor"`). Group only where a genuine theme exists — don't force unrelated prompts together. Prompts you leave without a `topic` fall into a trailing "Ungrouped" bucket. Reuse the exact same string to put prompts in the same group.
+
+## Report Layout
+
+The rendered HTML gives the user, in this order: a sticky left **table of contents** (Suggestions + every group with its prompts; flagged prompts shown red), a **Suggestions** section at the top listing the **top 10 flagged prompts ranked by `impact`** (each a class-level fix with a link jumping to that prompt; if more than 10 are flagged the rest still show red inside their groups but are not in the headline list), then the prompts as **collapsible topic groups**, **collapsed by default** (each showing its prompt count and a red flag-count badge). A **Collapse/Expand all** button toggles every group; following a Suggestion or TOC link auto-expands the target group. This layout is produced entirely by `render`; you only supply `topic`, `impact`, and the rest of the analysis.
+
+**What counts as a problem:** avoidable friction attributable to the agent or the harness setup — wrong turns, rework, misread intent, work thrown away, missing verification. A user changing their mind, reversing scope, or steering mid-task is **not** a problem; it is normal collaboration — give it a `note`. If churn followed a user reversal, attribute the flag (if any) to whatever the agent did prematurely *before* the reversal (e.g. wrote a full spec for a heavyweight option that wasn't yet committed to), not to the user's prompt itself.
+
+A clean session can legitimately produce **zero** flags. Do not manufacture problems to fill the report — the generality rule already says a missing suggestion beats a useless one.
+
+## The Generality Rule (the hard part)
+
+Every suggestion must target a **class** of problem, not the single instance.
+
+**Test each suggestion:** *"Could this ever fire again on a different task, file, or ticket?"* If the honest answer is no — it only ever applies to this exact prompt — it is worthless. Rewrite it broader, or drop the flag entirely (a missing suggestion beats a useless one).
+
+| ❌ Too specific (worthless) | ✅ Class-level (keep) |
+|---|---|
+| "Remember HP-1234 needs the `link_jira_issues` MCP call." | "When a ticket references another ticket, check for a linking step before closing — add a linking check to the JIRA workflow." |
+| "Don't forget the `extract_prompts.py` script needs `command-args` stripped." | "When parsing transcripts, treat slash-command wrapper tags as non-content and skip empty turns." |
+| "You should have read foo.py line 42." | "Before claiming a causal 'X is handled by Y', cite file:line — verify before asserting." |
+
+A good suggestion describes a *trigger condition* + *behaviour*, both phrased so they recur.
+
+## Target-Location Taxonomy
+
+Pick the narrowest location that still catches the whole class:
+
+- **global CLAUDE.md** — cross-project habits (verification discipline, citation rules, commit style).
+- **project CLAUDE.md** (or a file it references) — conventions specific to this repo/tech stack.
+- **an editable skill** — name it — a `planetexpress` plugin skill or one of the user's personal `~/.claude/skills/`, when the class fits a workflow there that just needs a guard added.
+- **new skill** — when the class is a reusable technique/workflow with no current home; give it a one-line name + purpose.
+
+Prefer fixing an existing artifact over proposing a new skill; new skills are justified only when no existing location fits.
+
+**`planetexpress` is the only editable plugin.** Skills in any other plugin — `superpowers:`, `caveman:`, etc. — are installed copies we cannot edit, so they are never a valid fix `location`. The only valid fix targets are: global CLAUDE.md, project CLAUDE.md (or a file it references), the user's personal `~/.claude/skills/`, and the `planetexpress` plugin (this repo).
+
+When a problem genuinely originates in a non-editable skill, say so in `problem` (e.g. "the `superpowers:brainstorming` skill let a full spec be written before the approach was confirmed"), but the `suggestion` + `location` must point at one of those editable targets in a way that intercepts the same class: a guard line in global/project CLAUDE.md, or a `planetexpress` (or personal) skill that adds the missing check before/around the third-party skill runs.
+
+## Common Mistakes
+
+- **Summarising prompts instead of analysing all N.** The script already enumerated them; the `missing_analysis` gate will catch you. Never report with it > 0.
+- **Instance-level suggestions.** "Do X for this ticket" is noise. Apply the generality test to every one.
+- **Flagging everything.** Most prompts are fine. Red is for genuine friction — wrong turns, rework, misunderstood intent, avoidable back-and-forth.
+- **Editing config.** Report-only. Suggest locations; let the user act.
+- **Inventing prompts or reordering.** Use the script's data verbatim.
+- **Forgetting `impact` on a problem.** Without it the suggestion sorts last and may fall outside the top 10. Always set `impact` (1–5) when you set `problem`.