@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/setup-workflow/issue-tracker-github.md

@@ -0,0 +1,35 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body-file <file>` — body always via `--body-file` (inline `--body` with backticks/parens crashes bash). Use a heredoc to build the file for multi-line bodies.
+  <!-- setup-workflow: when board-sync.md ends at mode=github-projects-v2, insert the managed-board routing line here — "Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through scripts/board-sync.py, not bare `gh issue create`/`gh project item-*`." Omit for GitLab / local / other / mode=none. -->
+- **Sync to the board** (managed-board projects only): route board writes through the board-sync helper, not bare `gh issue create`/`gh project item-*` — see `docs/agents/board-sync.md` once `/setup-workflow` has filled it.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation and the blocking SSOT. Set an edge via the board helper, which encapsulates the database-id resolution AND maintains the `## Blocked by` body mirror: `python3 scripts/board-sync.py dep-add --issue <child#> --blocked-by <blocker#>` (remove: `dep-remove`; read: `deps <#>`). Never a bare `gh api` on the dependencies endpoints — the helper is the only writer, same rule as sub-issues. *(Raw shape, for repos without the helper: `POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>` with the blocker's numeric **database id** — `gh api repos/<owner>/<repo>/issues/<n> --jq .id`, not the `#number`/`node_id`.)* GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `python3 scripts/board-sync.py frontier <map#>` — classifies each native child `FREI` / `BLOCKED by #…` / `done` from the native edges; the first `FREI` unassigned child in map order wins. Without the helper: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/.agents/skills/setup-workflow/issue-tracker-gitlab.md

@@ -0,0 +1,34 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/.agents/skills/setup-workflow/issue-tracker-local.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/.agents/skills/setup-workflow/orchestrate-wave-seed.md

@@ -0,0 +1,44 @@
+# Project layer — orchestrate-wave
+
+The generic `orchestrate-wave` skill ships the full wave-landing **mechanics**
+(disjointness recon → parallel implementers → serial integration → central verify
+→ land) with no project tooling in the body. This file is the **project layer**:
+it carries your project's exact commands, setup, verify recipe, login and deploy
+detail. The skill probes it at runtime (Phase 0); with the sections below
+**filled** it runs your project recipe instead of the generic fallback.
+
+> **Section contract.** The skeleton refers to these exact headings by name.
+> Keep them; fill each with your project's real detail. While a section is empty
+> the skill treats the whole layer as absent (Phase-0 sentinel-stub rule) and
+> falls back to generic instructions — so fill them before relying on the recipe.
+
+## §Setup
+<!-- Project setup steps Phase 0 runs before verify: DB/tunnel/services the
+     live-verify depends on, dependency install, your worktree-setup command. -->
+
+## §Builder Commands
+<!-- Exact test / typecheck / fast-gate commands per package for the builder
+     contract and integration. State the exact invocation; note any false-red
+     traps (a test-runner arg that silently filters, a composite-typecheck flag). -->
+
+## §Builder Hard Rules
+<!-- UI-text language/Umlaut rules, design tokens, formatters, size gates —
+     whatever a delegated implementer must obey in this repo. -->
+
+## §Integration Suites
+<!-- Every test framework the wave's files can belong to: the main suite plus any
+     separate unit-test or script-test runner the main suite does NOT cover. -->
+
+## §Verify Recipe
+<!-- The central verify gate you re-run yourself: full CI command (+ any
+     coordinator-branch skip/override), combined integration suite for schema/reader
+     waves, the one-dev-server rule, design/brand checks, DB-compare coercion traps,
+     console-clean command. -->
+
+## §Headless Login
+<!-- The AFK login recipe for the session-MCP browser profile: which profile,
+     where it resolves, the login script, port lore — no password in the transcript. -->
+
+## §Landing
+<!-- Deploy trigger (auto-deploy-on-merge?), prod-migration command + lockstep
+     window, the deploy-done signal, anchor-sync mechanics pointer. -->

package/.agents/skills/setup-workflow/spec-completeness-seed.md

@@ -0,0 +1,44 @@
+# Convention — Spec completeness before implementation
+
+Specs should reach structural completeness before implementation, so that avoidable bugs are caught at spec time rather than during live-verify. This is the project's seed convention; grow it over time (via `/retro`) by adding more `## Self-Critique-Check` blocks below.
+
+`spec-self-critique` point 8 iterates every `docs/conventions/*.md` file and runs the `## Self-Critique-Check` block it finds (format: **Trigger / Check / Korrektur**). A convention file without such a block is skipped with a warning — so this seed ships one valid block.
+
+## Self-Critique-Check
+
+**Trigger:** the spec states any concrete count, quantity, or "N of M" claim (number of callers, tests, rows, files, occurrences).
+
+**Check:** is each such number empirically verified against the source (a `grep -c`, a query, a file listing) rather than estimated or recalled?
+
+**Korrektur:** re-derive every concrete number from the source before finalizing the spec; replace estimates with the verified count, or mark the claim as an explicit assumption to confirm during implementation.
+
+## Vertikal-Slice-Vollständigkeit (decompose-readiness)
+
+The convention section `to-issues` reads at runtime (it references `spec-completeness.md` §Vertikal-Slice-Vollständigkeit). Seeded project-neutral; grow it with your project's incidents over time.
+
+**Trigger:** an artefact is about to be decomposed by `to-issues` — regardless of entry point (a `to-prd` PRD, an external PRD, a raw issue, a mechanical file bundle).
+
+**Provenance-independent:** the contract checks the artefact's **form**, never which tool produced it. Grill depth (none / light / adversarial) is the entering person's choice — `to-issues` re-derives readiness from the artefact, it does not require a specific upstream step to have run.
+
+**Decompose-readiness — always (every artefact class):**
+- Each user-facing slice is a tracer-bullet outcome sentence ("<user action> → <visible result>"), not a layer name ("Config UI", "Backend resolver").
+- ≥1 acceptance criterion per slice.
+- Blast radius estimated per slice (~N files from recon/grep, not a guess).
+- Seam-ownership flagged: does a slice replace/unify/retire a central mechanism? → its own grill-needed (HITL) slice, never hidden in a behavior-preserving tweak.
+- Each byte-neutral/prep slice names the half it defers + the later slice that closes it.
+
+**Mechanical-bundle minimum** (a file-list / refactor with no domain scope — e.g. shrinking files under a size/lint gate):
+- Anchor/leaf header = one sentence *why* (e.g. "bring files over the size gate under it, behavior-neutral").
+- Per file-slice: outcome title + short what + AC (usually "behavior unchanged + gate satisfied + tests green") + blast radius.
+- Seam-check explicit ("no central mechanism replaced", or name it → then grill that slice).
+- The domain grill is **skippable only** when the blast radius is estimable **and** small **and** no seam is touched; otherwise the slice is HITL with the open structural questions. No open-questions section is needed when nothing is open.
+
+**Anti-pattern:** `to-issues` rubber-stamping a pre-cut table — the table is only "done" when every user-facing row passes the trace against the code.
+
+## Self-Critique-Check
+
+**Trigger:** the spec/PRD contains a slice/phase table or decomposes into multiple PRs/issues.
+
+**Check:** is every user-facing slice a tracer-bullet outcome (not a layer name)? Does every byte-neutral slice name its deferred half + closing slice? Is blast radius estimated and seam-ownership flagged per slice?
+
+**Korrektur:** reformulate layer-only slices as outcomes or split them; carve a new slice for any uncovered half; mark a seam-replacing slice as its own HITL slice.

package/.agents/skills/setup-workflow/spec-self-critique-seed.md

@@ -0,0 +1,43 @@
+# Project layer — spec-self-critique
+
+The generic `spec-self-critique` skill ships the 12-point checklist (the check *intents* + the structure). This file is the **project layer**: it enriches each point with project-specific incidents, grep patterns, conventions, and extra sub-checks. The skill reads it at runtime; with this file present it runs the full pass instead of warning that the layer is absent.
+
+> **Authoritative `/retro` sink.** This is the **only** home for project-specific `spec-self-critique` checks. `/retro` appends new rules/incidents **here**, below the relevant point — never into the generic skill skeleton. The skeleton stays portable.
+
+The headings below are stable append anchors (points 1–12, matching the generic checklist). They start empty; they fill in over time via `/retro`.
+
+## Point 1
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 2
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 3
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 4
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 5
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 6
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 7
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 8
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 9
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 10
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 11
+<!-- /retro appends project-specific checks for this point here -->
+
+## Point 12
+<!-- /retro appends project-specific checks for this point here -->

package/.agents/skills/setup-workflow/triage-labels.md

@@ -0,0 +1,18 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles, but only two are ever applied as issue labels. This file maps those two roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| --------------------------- | --------------------- | ----------------------------------------- |
+| `needs-info`                 | `needs-info`           | Waiting on reporter for more information |
+| `ready-for-agent`            | `ready-for-agent`      | Fully specified, ready for an AFK agent  |
+
+**Board status is authoritative** for the remaining three canonical roles — they are never applied as labels:
+
+- `needs-triage` — the tracker's initial/backlog status covers this.
+- `ready-for-human` — most AFK-agent workflows don't split human-work out as a label; if yours does, add it back as a third row.
+- `wontfix` — close the issue instead of labelling it.
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from the table above if it's one of the two active roles; for any other role, use the tracker's status field or close the issue instead of adding a label.
+
+Edit the right-hand column, or re-add a row, to match whatever vocabulary you actually use.

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -0,0 +1,33 @@
+# Workflow
+
+Use this section as the entry-point map for agent-assisted work. The individual skills carry the detailed mechanics; this overview helps choose the right starting point.
+
+## Entry Points
+
+- **Unsure which skill fits?** Ask `ask-matt` — a router over every skill in this list, with a recommended starting point and why.
+- **A new build whose size is unclear** (a new app, a big cross-cutting feature, an unclear where-to-start): run `scale-check` — a short plain-language dialog that routes it to a program, a feature, a single slice, or a bug, and hands back a paste-ready start prompt.
+- **New capability or unclear change:** start with `grill-with-docs` when the domain language or decisions need sharpening, then publish the agreed shape with `to-prd`.
+- **A slice hinges on an unresolved fact or trade-off before it can be built:** clear it first — a binary yes/no question against real code/runtime/platform with `verify-spike`, a bounded "which option" choice with `decision-gate`.
+- **Existing plan, PRD, or ready issue:** use `to-issues` to split it into independently buildable tracer-bullet slices.
+- **A Program-PRD with a wave plan:** use `to-waves` to unfold it into named wave stubs + slice leaves on the board, after a chat preview gate that shows the whole plan before any write.
+- **A backlog of open issues needs clustering into themed waves:** use `board-to-waves`.
+- **A whole wave anchor (file-disjoint slices, specs already locked) to build, verify and land end-to-end — often AFK:** use `orchestrate-wave` — it dispatches implementers per slice, integrates serially, verifies centrally, and lands. (A single slice just goes to `tdd`.)
+- **Bugs or requests piling up that you didn't create:** use `triage` to move them into agent-ready issues.
+- **Bug or regression:** use `diagnose` to reproduce, minimize, hypothesize, instrument, fix, and regression-test.
+- **A design question needs a runnable answer (state, business logic, a UI you have to see):** spike it with `prototype`, then fold what you learned back in.
+- **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
+- **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
+- **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
+- **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
+
+## Routing Rule
+
+Prefer the smallest workflow that produces a clear next action. A tiny fix can go straight to `tdd`; a cross-cutting feature should become a PRD and then slices before implementation. When a skill reports missing project context, run `setup-workflow` again and fill only the missing stub.
+
+## Depth Ladder
+
+- **Light:** direct `tdd` for a small, well-understood change.
+- **Medium:** `to-issues` for a ready artefact that needs slicing.
+- **Deep:** `grill-with-docs` followed by `to-prd` and `to-issues` when terminology, contracts, rollout order, or ownership are still uncertain.
+- **Gate:** insert `verify-spike` or `decision-gate` before any depth level when a slice hinges on an unresolved fact or trade-off.

package/.agents/skills/spec-self-critique/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: spec-self-critique
+"description": "Use AFTER writing or editing a spec (a `SPEC.md`/`PLAN.md` or any spec/design doc), BEFORE asking the user to review — runs a 12-point structural Self-Critique checklist, fixes issues inline, and emits a visible summary. Enriches each check from a project layer if one is present. Triggers right after a spec has been written. NOT for reviewing finished code/diffs (code-review) — this pass runs on the spec text itself."
+---
+
+# Spec Self-Critique
+
+A portable, structural self-review pass over a freshly written spec/plan. The **generic 12-point skeleton** below ships as-is; a **project layer** (if present) enriches each point with project-specific incidents, grep patterns, conventions, and extra sub-checks.
+
+## When to invoke
+
+- After a spec was written/edited (a `SPEC.md` / `PLAN.md`, or a spec/design doc), BEFORE the user-review gate.
+
+## Step 0 — Project-layer probe
+
+First, check whether a project layer exists: from the project root, look for `docs/agents/skills/spec-self-critique.md`.
+
+- **Present** → **full pass**: run the 12 generic checks AND apply the per-point enrichment that file defines (incidents, grep patterns, extra sub-checks).
+- **Absent** → **base pass**: run the 12 generic checks only, then add this one-line warning to the summary:
+  > ⚠ No project layer found (`docs/agents/skills/spec-self-critique.md`) — only the generic base checks ran. `/setup-workflow` creates the layer; it fills in project-specific content via `/retro`.
+
+> **Routing — keep this skeleton clean.** Project-specific checks, incidents, and grep patterns belong in the project layer (`docs/agents/skills/spec-self-critique.md`), **NOT here**. `/retro` appends new project-specific lore to the project layer, never into this generic skeleton.
+
+## Altitude — a portable kit concept
+
+The generic skeleton recognizes two spec altitudes: a **Feature-PRD** (the
+default — every point above and below assumes this) and a **Program-PRD**
+(marked `<!-- prd: program -->`, produced by the kit's `scale-check` →
+`grill-with-docs` → `to-prd` program route — a native anchor over a
+multi-wave `## Wellenplan`). This is a **portable kit concept**, not a
+project-specific rule, so it stays **in this generic skeleton** — the
+"project-specific → project layer" routing rule above is about *this
+project's* incidents/grep patterns, not about a kit-wide spec shape the
+skill itself already knows.
+
+Two points read differently at Program-Altitude — both get a dedicated
+fixture in `scenarios.md`:
+
+- **Point 3 (Scope)** at `prd: program`: scope is not "small enough for one
+  plan" — it is "each wave holds 2–7 slices; the program splits via its wave
+  plan, the PRD itself is never split."
+- **Point 12 (Vertical-slice completeness)** at `prd: program`: reads against
+  **Wellenplan rows**, not a slice/PR table — each wave is an outcome
+  cut/tracer, never a layer cut ("a backend wave" is the anti-pattern); an
+  enabler wave names the half it cuts off and the outcome wave that closes it.
+
+Every other point runs unchanged at either altitude.
+
+## How to invoke
+
+Read the most recently written/edited spec in full. Walk the 12-point checklist (points 1–12; **8b/8c are sub-checks of point 8**, not main points). Per point:
+
+1. Decide: does the spec trigger this rule?
+2. If yes: run the check.
+3. If violated: fix the spec inline (Edit tool, not "TODO later").
+4. Note the correction for the summary.
+
+End with a visible summary in the chat:
+
+```
+Self-Critique complete — <N> corrections:
+- Point <X>: <short description>
+- ...
+```
+
+or, if none were needed: `Self-Critique complete — no corrections needed.` (append the Step-0 layer-absent warning if it applied). THEN ask the user-review question.
+
+## The 12-point checklist
+
+**1. Placeholder scan + empirical re-check**
+Scan for `TBD` / `TODO` / "später" / "fill in details" / vague requirements → fix inline. Plus, when applicable:
+- **Cited counts** ("24 call-sites: 6 start, 8 succeed, …") → re-verify each empirically (`grep`); recon from the brainstorming phase can be stale, and wrong numbers mislead the effort estimate.
+- **Folder move / rename** → broaden the caller-audit grep (search the path-segment without a `from …`-anchor, to catch mocks, dynamic imports, type-only imports) AND require a typecheck-backstop step right after the move (path-depth breaks inside the moved files aren't found by a caller grep).
+- **Cited prior diagnosis** (issue body, investigation, memory snapshot, earlier plan) → verify each core claim empirically before finalizing. Such artifacts are hypotheses, not validated facts; drift compounds if left unchecked.
+- **Risk mitigation** → it must name a concretely checkable **output string**, not just an action ("rowCount is 2307" is checkable; "rowCount > 1000" is a claim about a claim).
+Skip only if none of these apply.
+
+**2. Internal consistency**
+Do sections contradict each other? Does the architecture match the feature description? Do numbers/orders agree between tables and prose?
+
+**3. Scope check**
+Small enough for **one** implementation plan, or must it split into sub-specs?
+**At Program-Altitude** (`prd: program`) this reads differently — see
+"Altitude" above: each wave holds 2–7 slices, the program splits via its wave
+plan, and the PRD itself is never split.
+
+**4. Ambiguity check**
+Could a requirement be read two ways? If so, pick one interpretation and make it explicit.
+
+**5. State transitions**
+*Trigger:* the spec mentions "Live", "SSE", "WebSocket", "Polling", "EventSource", "Realtime", "Stream", or incoming updates.
+*Check:* are all transitions played through — `idle → running → awaiting_decision → succeeded | failed` — plus `mid-flight reload`, `multi-tab parallel`, `connection-loss + reconnect`, `aborted`?
+
+**6. Convention scope**
+*Trigger:* the spec introduces a new pattern, convention, single-entry broker, wrapper, or consistency layer.
+*Check:* is it explicitly scoped — applied app-wide vs only touched surfaces? Does the spec require a follow-up item for the untouched surfaces (in the spec body, not retroactively)?
+
+**7. User walk-through**
+*Trigger:* the spec has UI stages, wizards, or multi-step user interactions.
+*Check:* are the sub-steps per UI stage walked through — what does the user see at each stage — not just the data model?
+
+**8. Project-convention check**
+*Trigger:* always.
+*How:* iterate your project's documented conventions. Default location: from the project root, `docs/conventions/*.md`. For each convention file that carries a `## Self-Critique-Check` block (format: **Trigger / Check / Korrektur**):
+1. Evaluate its Trigger against the current spec.
+2. On match: run its Check. On violation: fix the spec inline + note it.
+3. A convention with no such block → skip it non-blocking + collect a warning ("convention `<file>` is missing a `## Self-Critique-Check` block").
+No conventions directory / no blocks (e.g. a fresh project) → **soft skip** (non-blocking). Emit collected warnings at the end of the pass.
+
+**8b. Marker-wording check**
+*Trigger:* a convention mandates a header marker comment.
+*Check:* the spec's marker must be copied **verbatim** from the convention, not paraphrased. Open the convention, compare the marker block 1:1, fix inline on any drift (drift makes the convention worthless as the single source of truth).
+
+**8c. Structurally-trivial post-invariant**
+*Trigger:* the spec has aggregation functions with post-invariants.
+*Check:* for each post-invariant, can it ever fire under the current code path? Play the path through (all branches, all math ranges). If it is structurally impossible to violate under the current code, drop it or replace it with a property test (a property fires on every regression; a structurally-true post never does).
+
+**9. Primitive recon (DRY)**
+*Trigger:* the spec introduces a new UI primitive, hook, component, helper, repo function, or service — OR substantially touches (≥30 LOC) an existing file.
+*Check:* did you `grep`/`ls` for an existing primitive/helper with overlapping responsibility (including in callers/pages, not just component dirs)? If one exists → switch the spec to reuse it. If a pattern is replicated 3+× → require a helper-extraction acceptance-criterion.
+
+**10. User-action feedback**
+*Trigger:* the spec describes a user action (click, submit, import, bulk op, setup run) that triggers a ≥2-step process.
+*Check:* does the spec document, per sub-step, what the user sees on screen — progress, retry/throttle visibility (esp. external APIs or long waits), mode-switch visibility (e.g. bulk → per-item fallback), and a "why is this counter stalled" hint for per-resource paths?
+
+**11. Live-verify bug-plausibility**
+*Trigger:* the spec has a live-verify block with a bug-variant + an expected property failure.
+*Check:* play the bug-variant through — does it actually change the target property (e.g. does it break the asserted ordering/monotonicity)? Is only one direction sharp? If the variant does NOT violate the property, pick a variant that does and fix the spec inline (a wrong variant yields a passing live-verify that catches no real regression).
+
+**12. Vertical-slice completeness**
+*Trigger:* the spec/PRD has a slice/phase table or splits into multiple PRs.
+*Check:*
+- (a) each *user-facing* slice = a tracer bullet "`<user action> → <visible result>`", **not** a layer name ("config UI", "backend resolver");
+- (b) each byte-neutral/infra slice names its **omitted half** + the **closing follow-up slice** (otherwise the connecting path falls between two slices);
+- (c) the first outcome slice after ≥1 prep slice is traced against the code with a concrete value (`grep`/Read), not trusted as "config-driven".
+*Correction:* reword/split a layer-only slice; pull in a new slice for an uncovered half.
+**At Program-Altitude** (`prd: program`), apply (a)–(c) analogously to
+**Wellenplan rows** instead of a slice table — see "Altitude" above: each wave
+is an outcome cut/tracer, never a layer cut, and an enabler wave names both
+the half it omits and the outcome wave that closes it.
+
+**Gate home.** This skill runs **automatically as the mandatory last step of `to-prd`** (on the Draft-PRD) — the visible two-line summary is required **before** the user-review question. The **slice-completeness gate (point 12)** additionally sits in `to-issues`. The skill stays **standalone-callable** for manual spec/PLAN reviews.
+
+## Anti-patterns of this skill
+
+- **"Skipped self-critique because the spec is small"** — it runs on mini-specs too. Cost: 2–3 min; payoff: structural bugs caught in the spec phase.
+- **"Made corrections silently inline, no summary"** — the visible summary is part of acceptance. A silent pass is indistinguishable from a skipped one.
+- **"Improvised what a convention would say"** — if a convention file has no `## Self-Critique-Check` block, skip it non-blocking + collect a warning. Do not invent the rule.
+
+## Verification fixtures
+
+See `scenarios.md` in this skill dir for project-neutral fixtures (one per check) — walk them when refactoring the checklist. If a project layer is present, it may carry richer, project-specific scenarios.

package/.agents/skills/spec-self-critique/scenarios.md

@@ -0,0 +1,82 @@
+# Verification fixtures — spec-self-critique (generic)
+
+**Fixtures only — no new rules here.** Each fragment is a synthetic, project-neutral spec snippet that violates **exactly one** check. When the skill works, it should trigger the named point and name it in the summary. Walk these when refactoring the checklist. New *project-specific* checks/scenarios go in the project layer (`docs/agents/skills/spec-self-critique.md`), never here.
+
+## Point 1 — placeholder / unverified count
+> "Rename `oldUtil` → `newUtil` across the 9 call-sites and update imports."
+
+Violates 1 (cited count not re-verified; rename = caller-audit + typecheck-backstop). Expected: *"Punkt 1: '9 call-sites' nicht empirisch belegt — grep + breiter Caller-Audit + Typecheck-Backstop nach dem Move ergänzt."*
+
+## Point 2 — internal consistency
+> "Section A: the cache TTL is 60s. Section B's diagram labels the same cache 600s."
+
+Violates 2. Expected: *"Punkt 2: widersprüchliche TTL (60s vs 600s) — vereinheitlicht."*
+
+## Point 3 — scope
+> "This spec covers: new auth provider, a billing rewrite, a dashboard redesign, and a data migration."
+
+Violates 3. Expected: *"Punkt 3: zu groß für einen Plan — in Sub-Specs zerlegen."*
+
+## Point 3 (Program-Altitude) — a wave outgrows the band
+> "`<!-- prd: program -->` Program-PRD. Wellenplan: Welle 1 covers 9 slices
+> across two subsystems; Welle 2 covers 3 slices."
+
+Violates 3 at Program-Altitude (a wave over the 2–7 slice band needs
+splitting into two waves; the PRD itself stays unsplit). Expected: *"Punkt 3
+(Programm-Altitude): Welle 1 mit 9 Slices sprengt den 2–7-Rahmen — in zwei
+Wellen aufgeteilt; das PRD selbst bleibt ungesplittet."*
+
+## Point 4 — ambiguity
+> "When the request fails, retry it a few times before giving up."
+
+Violates 4. Expected: *"Punkt 4: 'a few times' mehrdeutig — auf konkrete Zahl + Backoff festgelegt."*
+
+## Point 5 — state transitions
+> "New live progress indicator: on start a spinner appears, on finish a green check."
+
+Violates 5 (only `running → succeeded`). Expected: *"Punkt 5: Live-Feature, nur Erfolgs-Pfad — failed / reload / multi-tab / connection-loss / aborted ergänzt."*
+
+## Point 6 — convention scope
+> "Introduce a `withRetry()` wrapper. Apply it in `serviceA.fetch()` and `serviceB.fetch()`."
+
+Violates 6 (no app-wide-vs-touched scope, no follow-up). Expected: *"Punkt 6: Pattern-Scope nicht erklärt — explizit nur diese 2 + Followup für den Rest."*
+
+## Point 7 — user walk-through
+> "New multi-step onboarding wizard at `/onboarding`. Data model: a 3-field form posted to `/api/onboard`."
+
+Violates 7 (only data model). Expected: *"Punkt 7: kein User-Walk-Through der Wizard-Stufen — pro Stufe ergänzt, was der User sieht."*
+
+## Point 8 — project convention (+ 8b marker, 8c trivial post)
+> "Refactor an aggregation module. Pre-invariant: `typeof rows[0]?.id === 'string'` (already guaranteed by the typed signature). Post-invariant: `out.length === rows.length` where the body is `for (const r of rows) out.push(...)`."
+
+Violates 8c (post structurally guaranteed by the loop) + 8b-style trivial pre. Expected: *"Punkt 8c: Post strukturell durch den Loop garantiert — gestrichen / Property-Test; triviale Pre entfernt."* (With a project layer present, point 8 also iterates that project's `## Self-Critique-Check` convention blocks.)
+
+## Point 9 — primitive recon (DRY)
+> "Build a new `FilterableList` component with sort + filter."
+
+Violates 9 (no recon for an existing list/table primitive). Expected: *"Punkt 9: neues Primitiv ohne DRY-Recon — auf Wiederverwendung des Bestehenden geprüft/umgestellt."*
+
+## Point 10 — user-action feedback
+> "A 'Rebuild caches' button kicks off a 4-stage backend job (~2 min). On error: a toast."
+
+Violates 10 (no per-step feedback). Expected: *"Punkt 10: ≥2-Schritt-Prozess ohne Sub-Step-Feedback — Schritt-Labels / Progress / Retry- bzw. Modus-Sichtbarkeit ergänzt."*
+
+## Point 11 — live-verify bug-plausibility
+> "Live-verify for percentile indices. Bug-variant: change `p80 = 0.8*n` to `0.6*n`. Expect the ordering check `p10 < p50 < p80 < p90` to fire."
+
+Violates 11 (`0.5 < 0.6 < 0.9` stays monotone → property does NOT fire). Expected: *"Punkt 11: Variante erhält die Monotonie — Property feuert nicht; korrekte Variante (z.B. 0.8→0.95, bricht p80>p90) gewählt."*
+
+## Point 12 — vertical-slice completeness
+> "Slices: 1) Config UI · 2) Backend resolver · 3) Wire-up."
+
+Violates 12 (layer names, no tracer-bullet, no traced outcome slice). Expected: *"Punkt 12: Layer-Namen statt Tracer-Bullets — als '<Aktion> → <sichtbares Ergebnis>' umformuliert; erste Outcome-Slice gegen Code getrace't."*
+
+## Point 12 (Program-Altitude) — layer-cut waves
+> "`<!-- prd: program -->` Program-PRD. Wellenplan: Welle 3 — 'Backend-Migration'. Welle 4 — 'Frontend-Rollout'."
+
+Violates 12 at Program-Altitude (layer-cut waves, not outcome tracers; no
+enabler/closing pairing named). Expected: *"Punkt 12 (Programm-Altitude):
+'Backend-Migration'/'Frontend-Rollout' sind Layer-Schnitte, keine
+Outcome-Tracer — Welle 3 als Enabler benannt (abgeschnittene Hälfte:
+sichtbares Frontend-Verhalten) mit Welle 4 als schließender Outcome-Welle,
+oder zu echten Outcome-Wellen umgeschnitten."*