@ikon85/agent-workflow-kit 0.10.0

package/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/skills/skill-manifest.json

@@ -0,0 +1,389 @@
+{
+  "schema_version": 1,
+  "description": "Public skill classification and publishing SSOT.",
+  "skills": {
+    "to-prd": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "to-issues": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "grill-with-docs": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "grill-me": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "retro": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "wrapup": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "verify-spike": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "decision-gate": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "spec-self-critique": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "code-review": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "setup-workflow": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "board-to-waves": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "scale-check": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "to-waves": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "tdd": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "diagnose": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "zoom-out": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "improve-codebase-architecture": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "prototype": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "triage": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "codebase-design": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "domain-modeling": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "implement": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "resolving-merge-conflicts": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "write-a-skill": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "ask-matt": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "wayfinder": {
+      "class": "vendored",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "research": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "git-guardrails-claude-code": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "matt-pocock"
+    },
+    "setup-pre-commit": {
+      "class": "generic",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "own"
+    },
+    "grill-me-codex": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "chase"
+    },
+    "grill-with-docs-codex": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "chase"
+    },
+    "codex-review": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "chase"
+    },
+    "codex-build": {
+      "class": "vendored",
+      "publish": true,
+      "surfaces": [
+        "claude"
+      ],
+      "provenance": "chase"
+    },
+    "codex-adapter-sync": {
+      "class": "adapter",
+      "publish": true,
+      "surfaces": [
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "audit-skills": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": false,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "local-ci": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": false,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "orchestrate-wave": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "git-worktree-recover": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": false,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "security-audit": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": false,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
+    "kit-release": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    }
+  }
+}