@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/setup-pre-commit/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: setup-pre-commit
+description: Set up a native, zero-dependency git pre-commit hook (via core.hooksPath) that runs your project's type checks, linting, tests, or formatting before each commit. Use when the user wants to add pre-commit hooks, gate commits on checks, or wire commit-time typecheck/lint/test/format — no Husky or Node deps required.
+---
+
+# Setup Pre-Commit Hooks (native git, zero-dep)
+
+## What This Sets Up
+
+A versioned hooks directory wired through git's own `core.hooksPath` — no Husky,
+no `lint-staged`, no extra dependencies, works in any repo regardless of stack:
+
+- a `.githooks/` dir tracked in the repo
+- a `pre-commit` hook (from the bundled template) that runs **your** checks
+- one git config line so every clone uses it
+
+## Why native over Husky
+
+`core.hooksPath` (git ≥ 2.9) points git at a tracked hooks dir directly. The
+hooks are plain scripts under version control — readable, debuggable, and
+stack-agnostic. Husky adds a Node devDependency and a `prepare` script just to
+do what one `git config` line does, and assumes a Node/npm project. For a kit
+that must work in any consumer repo, native is the robust default. (Husky
+remains a valid choice for Node-only teams — see the disclaimer at the end.)
+
+## Steps
+
+### 1. Create the hooks dir + drop in the template
+
+```bash
+mkdir -p .githooks
+cp scripts/pre-commit.template.sh .githooks/pre-commit   # this skill's bundled template
+chmod +x .githooks/pre-commit
+```
+
+The bundled template (`scripts/pre-commit.template.sh`) is a generic skeleton:
+a shebang, an optional toolchain preflight, and a clearly-marked gate block with
+commented per-stack examples. You fill the gate; you don't write the plumbing.
+
+### 2. Wire the dir (one line, every clone honours it)
+
+```bash
+git config core.hooksPath .githooks
+```
+
+- **Team-wide auto-setup (optional):** so a fresh clone wires itself without the
+  manual line, add it to an install step the repo already runs — e.g. a
+  `postinstall`/bootstrap script: `git config core.hooksPath .githooks`. Keep it
+  idempotent (the command is safe to re-run).
+
+### 3. Fill the gate — Refinement seam
+
+Open `.githooks/pre-commit`. Replace the `>>> your gate commands here <<<`
+block with **your** project's fast checks. Each command must exit non-zero on
+failure so the script's `set -e` blocks the commit. Examples by stack:
+
+| Stack | Example gate |
+|---|---|
+| JS/TS (pnpm) | `pnpm exec tsc -b && pnpm lint` |
+| Python | `ruff check . && mypy .` |
+| Go | `go vet ./... && gofmt -l .` |
+| Rust | `cargo fmt --check && cargo clippy -- -D warnings` |
+
+- **Keep it fast.** Pre-commit runs on every commit. A whole test suite or
+  type-check of a huge repo belongs in **pre-push** or CI, not here. Put only
+  the cheap, high-signal checks in pre-commit.
+- **Optional preflight.** If your checks need installed deps (`node_modules`,
+  a venv), keep the template's preflight block so a missing toolchain fails with
+  a clear message instead of a cryptic one. **Never instruct `--no-verify`** as
+  the fix — fix the deps.
+
+### 4. (Optional) add a pre-push hook for the heavy checks
+
+Same mechanism: drop a `.githooks/pre-push` script (already wired by step 2).
+Put the slower gate there — full test suite, build, or CI-mirror commands —
+so commits stay fast but pushes are still gated.
+
+### 5. Verify
+
+- [ ] `git config --get core.hooksPath` → `.githooks`
+- [ ] `.githooks/pre-commit` exists and is executable (`-x`)
+- [ ] the gate block holds your real commands (no leftover `>>> ... <<<` marker)
+- [ ] a deliberately-broken change is blocked by the hook (smoke test)
+
+### 6. Commit
+
+Stage the new `.githooks/` dir (and any bootstrap wiring) and commit. The commit
+runs through your new hook — a good smoke test that the gate works.
+
+## Alternative: Husky
+
+If your repo is Node-only and your team already standardises on Husky, you can
+use it instead (`npx husky init` + a `.husky/pre-commit`). It pulls a Node
+devDependency and a `prepare` script and assumes npm/pnpm/yarn — which is why
+this skill defaults to the native `core.hooksPath` scaffold above. Don't run
+both: pick one hooks mechanism per repo.
+
+## Notes
+
+- `core.hooksPath` is repo-local config; each clone runs the wiring once (step 2
+  or the optional bootstrap).
+- Hooks are just scripts — `echo`-debug them freely; nothing is hidden behind a
+  tool.
+- Exit non-zero = block the commit. Exit 0 = allow.

package/.claude/skills/setup-pre-commit/scripts/pre-commit.template.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# pre-commit — native git hook (zero-dep, stack-agnostic).
+#
+# This is a TEMPLATE. Copy it into your repo's hooks dir (default: .githooks/),
+# make it executable (chmod +x), and wire the dir with:
+#   git config core.hooksPath .githooks
+# Then fill the gate block below with YOUR project's checks.
+#
+# Exit non-zero to BLOCK the commit. Keep each check fast — it runs on every
+# commit. Slow/whole-suite checks belong in pre-push or CI, not here.
+
+set -euo pipefail
+
+# --- Optional preflight ----------------------------------------------------
+# Bail early with a clear message if the toolchain isn't installed, so the
+# real checks don't fail with cryptic errors. Adapt or delete for your stack.
+#
+#   if [ ! -d node_modules ]; then
+#     echo "❌ deps missing — run your install, then commit again. NEVER --no-verify."
+#     exit 1
+#   fi
+
+# --- Gate: fill in YOUR checks ---------------------------------------------
+# Replace the examples below with your real commands. Each must exit non-zero
+# on failure (the script's `set -e` then blocks the commit). Examples by stack:
+#
+#   # JS/TS (pnpm):   pnpm exec tsc -b && pnpm lint
+#   # Python:         ruff check . && mypy .
+#   # Go:             go vet ./... && gofmt -l .
+#   # Rust:           cargo fmt --check && cargo clippy -- -D warnings
+#
+# >>> your gate commands here <<<
+echo "⚠ pre-commit template not configured yet — add your checks in .githooks/pre-commit"
+
+echo "✅ pre-commit checks passed."

package/.claude/skills/setup-workflow/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: setup-workflow
+description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, GitHub-Projects board field-IDs, spec-self-critique + spec-completeness seeds, workflow overview, and the deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
+disable-model-invocation: true
+---
+
+# Setup Workflow
+
+Scaffold the **project layer** the portable workflow skills (`to-prd`, `to-issues`, `triage`, `spec-self-critique`, `retro`, `wrapup`, …) read at runtime. The generic skills ship the *how*; this skill writes the project-specific *what* into the consumer repo, where `retro`/`wrapup` then grow it over time.
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write — **one section at a time**, never dump everything at once. Assume the user does not know what these terms mean; each section opens with a short plain explainer.
+
+## Targets
+
+| File / block | What |
+|---|---|
+| `docs/agents/issue-tracker.md` | where issues live + how to read/write them (Section A) |
+| `docs/agents/triage-labels.md` | the triage label vocabulary (Section B) |
+| `docs/agents/domain.md` | `CONTEXT.md`/ADR layout the domain skills read (Section C) |
+| `docs/agents/board-sync.md` | GitHub-Projects field-IDs + board profile — **only meaningful for a GitHub tracker** (Section D) |
+| `docs/agents/skills/spec-self-critique.md` | per-point enrichment skeleton; `/retro` appends here (Section E) |
+| `docs/agents/skills/orchestrate-wave.md` | `orchestrate-wave` project layer (setup / commands / verify / login / landing) the wave-landing skill probes at runtime (Section E) |
+| `docs/conventions/spec-completeness.md` | a valid `## Self-Critique-Check` convention seed (Section E) |
+| `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
+| `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
+| `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
+
+## Idempotency contract — read before writing anything
+
+Every project-layer file this skill (or `npx init`) creates begins with **one sentinel line as its very first line**:
+
+```
+<!-- setup-workflow: state=<stub|filled|not-applicable>[; mode=<github-projects-v2|none>] -->
+```
+
+- `state=stub` — placeholder, awaiting fill (retryable). `state=filled` — populated, done. `state=not-applicable` — complete *by design* (e.g. board-sync for a non-GitHub tracker); never re-prompt. `mode=` appears **only** in `board-sync.md`.
+- **Per-file decision** when this skill runs:
+  - File missing → create it (write body + sentinel).
+  - First line is `state=stub` → fill it, flip the sentinel to `filled` (or `not-applicable`).
+  - First line is `state=filled` / `state=not-applicable` → **skip** (only the *first line* counts — a later mention of "setup-workflow" in the body does not).
+  - File exists, **non-empty, no sentinel** (legacy / pre-existing) → treat as **legacy-filled**, **skip**, report it.
+  - File exists but empty/whitespace, no sentinel → treat as fillable.
+- **CLAUDE.md / AGENTS.md carry no sentinel** (they are not ours) → reconcile **per section** via the block headers `## Workflow` / `## Agent skills` / `## Prod`: add a missing block, never overwrite an existing one or surrounding user content.
+- **Never overwrite filled content.** A re-run only fills what is missing/stub. End with a report: `<file>: created · filled · skipped (already filled / legacy / not-applicable)`.
+
+## Process
+
+### 1. Explore
+
+Read the current state; don't assume. For every target file, read its first line to classify it per the idempotency contract (missing / stub / filled / not-applicable / legacy).
+
+- `git remote -v` and `.git/config` — GitHub? GitLab? Which owner/repo?
+- `CLAUDE.md` and `AGENTS.md` at the repo root — which exist? Do they already have a `## Workflow` / `## Agent skills` / `## Prod` block?
+- `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
+- `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
+- `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
+
+### 2. Section A — Issue tracker
+
+> The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, and `to-prd` read from and write to it — they need to know whether to call `gh`, `glab`, write markdown under `.scratch/`, or follow a workflow you describe.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose GitHub; at GitLab, propose GitLab. Otherwise offer:
+
+- **GitHub** — GitHub Issues (`gh` CLI)
+- **GitLab** — GitLab Issues (`glab` CLI)
+- **Local markdown** — files under `.scratch/<feature>/` (solo projects / no remote)
+- **Other** (Jira, Linear, …) — ask the user to describe the workflow in one paragraph; record it as freeform prose.
+
+Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
+
+**Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
+
+### 3. Section B — Triage labels
+
+> When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
+
+Present the canonical roles from [triage-labels.md](./triage-labels.md); each role's string defaults to its name. Ask whether to override any. Seed `docs/agents/triage-labels.md` from the template.
+
+### 4. Section C — Domain docs
+
+> Some skills read `CONTEXT.md` for domain language and `docs/adr/` for past decisions. They need to know whether the repo has one global context or several.
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the root (most repos).
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+Seed `docs/agents/domain.md` from [domain.md](./domain.md).
+
+### 5. Section D — Board field-IDs (GitHub tracker only)
+
+> A GitHub-Projects board stores its fields (Status, and any workflow fields like a wave/cluster/spec-path) under opaque GraphQL IDs. The board-managed skills need those IDs. They differ per board and can't be typed by hand, so this skill discovers them.
+
+**Skip entirely if Section A is not GitHub** → write `board-sync.md` with `state=not-applicable`, `mode=none`, a one-line "this project does not use a GitHub-Projects board" note. Terminal; never re-prompts.
+
+**Preflight:** `gh auth status`. If `project`/`read:project` scope is missing, surface the exact remedy: `gh auth refresh -s project,read:project`, then fall through to the stub path below.
+
+**Discover (the success path):** `gh project list --owner <remote-owner> --format json`. If **exactly one** project clearly belongs to this repo's owner, read its fields: `gh project field-list <number> --owner <owner> --format json`. Record each field's `id`, `name`, `dataType` (single-select / number / text), and for single-selects the option `id`s. Write `board-sync.md` with `state=filled`, `mode=github-projects-v2`, the project node id + repo + the discovered field/option IDs, seeded from [board-sync.md](./board-sync.md). Fill the `<!-- board-sync:profile -->` **JSON block** (the machine SSOT `scripts/board_config.py` parses) — replace each `<…>` placeholder under `repo`/`project`/`fields` with the discovered value; leave the convention values (`labels`/`branchPrefixes`/`prMarkers`/`headings`) at their seeded defaults unless this project's conventions differ.
+
+**Map the status roles (`fields.status.roles`):** the seeded map carries the recommended English stage names (`Idea/Triaged/Spec/In Progress/Review/Done`). Reconcile it against the **discovered** Status option names: an exact (case-sensitive) match keeps its seeded entry; for every role whose seeded name is NOT among the discovered options, ask the user which of their actual option names plays that role (a stage they don't have may be omitted from the map — say so). Never guess a mapping from similarity. Finish with a validation pass: every role value in the map MUST appear in `fields.status.options`, else fix before writing `state=filled`.
+
+**Fallback (the single catch-all — no board / >1 / ambiguous / scope error / read failure):** do **not** auto-create a board (`gh project create` alone cannot provision the Status options + workflow fields a board needs). Write `board-sync.md` with `state=stub`, `mode=github-projects-v2`, and inline **instructions**: which fields the workflow profile needs (a Status single-select with your stage options; optionally a Wave number, a Cluster text, a Spec-Path / Plan-Path text), how to create the board in the GitHub UI / `gh`, and "then run `/setup-workflow` again — it will discover and fill the IDs." Retryable.
+
+**Optional — Phase field + saved Views (Program route only):** never auto-discovered or auto-created, unlike the fields above — a Phase field's option set is plan-specific. If this project plans to use the Program route (`scale-check` → `to-waves` → `validate-graph`), point the user at the seeded [board-sync.md](./board-sync.md)'s "Optional: the Program route" section for the `gh project field-create` command, the optional `fields.phase` / `labels.programType` profile keys, and the two saved Views to create by hand.
+
+### 6. Section E — Spec-layer seeds (non-interactive)
+
+These are **structured-but-empty** crusts that `/retro` grows; do not ask the user to fill them now.
+
+- `docs/agents/skills/spec-self-critique.md` — seed the 12 per-point headings from [spec-self-critique-seed.md](./spec-self-critique-seed.md) so `/retro` has stable append anchors and `spec-self-critique` finds its project layer (suppressing the "layer absent" warning) without inventing project content.
+- `docs/agents/skills/orchestrate-wave.md` — seed the named `§`-section headings from [orchestrate-wave-seed.md](./orchestrate-wave-seed.md) so the `orchestrate-wave` skill's Phase-0 probe finds its project layer. The sections ship **empty** (the exact commands / tunnel / login can't be guessed) → the skill treats an unfilled seed as "layer absent" and runs its generic fallback until the project fills them. A filled section is a manual project-maintenance edit, not something this run invents.
+- `docs/conventions/spec-completeness.md` — seed **one valid** `## Self-Critique-Check` block (Trigger/Check/Korrektur) from [spec-completeness-seed.md](./spec-completeness-seed.md). A convention file *without* a valid block makes `spec-self-critique` point 8 warn — an empty file is worse than none.
+
+> **Handoff drift-guard (`.claude/hooks/drift-guard.py`).** The repo ships a PreToolUse hook that blocks a `.handoff/*.md` Write when the linked issue's rooted graph is not execute-ready (it delegates all coherence to `scripts/execute-ready-check.py --mode handoff`). It self-filters to `.handoff/*.md` and fires **only once handoff docs exist** — a freshly scaffolded project carries the guard but has nothing to guard yet (silently inoperative until the first `.handoff/` write). This scaffold only **documents** the interplay; it does **not** build new mechanics. Once the project starts emitting handoffs, writes land in `.handoff/` and the guard activates automatically.
+
+### 7. Section F — Workflow overview
+
+> The workflow overview is a short entry-point map: which skill to start with for a feature, ready plan, bug, implementation slice, or finished branch. It should stay generic; the detailed mechanics live in the individual skills and the project-layer docs.
+
+Seed `## Workflow` from [workflow-overview.md](./workflow-overview.md) when the target CLAUDE.md/AGENTS.md file has no `## Workflow` block. If a `## Workflow` block already exists, leave it untouched and report `skipped (already present)`; it is likely repo-specific.
+
+### 8. Section G — Deploy target
+
+> `wrapup` and live-verify reference where this project deploys (host, command, URL). It lives in the `## Prod` block of CLAUDE.md/AGENTS.md, not a separate file.
+
+Ask for the deploy target in plain terms (where does this ship, how is it deployed, what's the live URL?). Record it for the `## Prod` block (Write step). If the user has no deploy target, skip — do not invent one.
+
+### 8b. Section H — Size-Profil (optional LoC-offender gate, non-interactive)
+
+> **Optional, opt-in.** The kit ships a LoC-offender drive gate (`scripts/loc_offender_gate.py`) — a stdlib-only helper that flags files over a line threshold (e.g. wire it into a pre-push hook). It reads a **single threshold SSOT**: `maxLines` in `max-lines-allowlist.json` at the repo root. Seeding that file is harmless even if you never wire the gate; without it the gate has no profile to read. (The SSOT repo additionally enforces the same threshold as a project-specific test-runner fitness check — that check is **not** shipped; the portable gate is the Python helper above.)
+
+Seed `max-lines-allowlist.json` **only if absent** (never overwrite — its `offenders` array is curated debt):
+```json
+{
+  "maxLines": 300,
+  "vendored": [],
+  "offenders": []
+}
+```
+Adjust `maxLines` only if the consumer asks for a different line limit. `vendored` = permanently-exempt third-party primitives; `offenders` = the shrinking known-debt set (files already over the limit at adoption). Report `created · skipped (already present)`.
+
+### 8c. Section I — Code-review project layer (non-interactive)
+
+> The `code-review` skill's Standards axis reads a project layer for exactly which docs count as this repo's conventions, and how the method relates to any other review tooling already running here. Seed it so the skill resolves that directly instead of guessing at the repo root.
+
+Seed `docs/agents/code-review.md` from [code-review.md](./code-review.md) — the same structured-but-empty philosophy as Section E: the two headings ("Standards sources in this repo" / "Adjacent review tooling") ship complete, but filling in this repo's real values is a manual edit (or a later pass), not something this run invents. Write at `state=filled` — the scaffold itself is the finished deliverable; nothing is pending from `/setup-workflow`'s side.
+
+### 8. Write
+
+For each `docs/...` file: obey the idempotency contract (the "Idempotency contract" section). Prepend the sentinel with the resolved `state` (and `mode` for board-sync).
+
+For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
+
+- If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).
+- If **one** exists → that one.
+- If **neither** exists → ask the user which surface(s) to create (**default `CLAUDE.md`**), then write there.
+- If a `## Workflow` block already exists → skip it; this block is often repo-specific.
+- If an `## Agent skills` / `## Prod` block already exists → update its contents in-place; never duplicate or clobber surrounding user content.
+
+`## Workflow` block:
+
+Use [workflow-overview.md](./workflow-overview.md) verbatim as the generic seed.
+
+`## Agent skills` block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+[one-line summary]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+[one-line summary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+[one-line summary — single- or multi-context]. See `docs/agents/domain.md`.
+```
+
+`## Prod` block (only if Section F produced a deploy target):
+
+```markdown
+## Prod
+
+[host / platform], deployed via [command/trigger]. Live: [URL].
+```
+
+### 9. Done
+
+Report the per-file outcome (`created · filled · skipped`), which surface(s) you wrote the blocks to, and which skills now read the layer. Note the user can edit `docs/agents/*.md` directly later, and that `/retro` grows the spec-layer seeds over time. Re-running this skill only fills what is missing or `state=stub`.

package/.claude/skills/setup-workflow/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/setup-matt-pocock-skills` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.claude/skills/setup-workflow/board-sync.md

@@ -0,0 +1,111 @@
+# Board sync — GitHub Projects field-IDs
+
+How the board-managed workflow skills (`to-prd`, `to-issues`, `board-to-waves`, …) address this project's GitHub-Projects board. A board stores its fields under opaque GraphQL IDs that differ per board, so they are recorded here rather than hardcoded in any skill.
+
+`/setup-workflow` writes this file in one of three states (see the sentinel on the first line):
+- **`state=filled`** — the IDs below were discovered from your board.
+- **`state=stub`** — no single board was found; fill the IDs by creating the board (below) and re-running `/setup-workflow`.
+- **`state=not-applicable`** (`mode=none`) — this project does not use a GitHub-Projects board.
+
+## Board profile — fields the workflow skills use
+
+| Field | Type | Required | Used for |
+|---|---|---|---|
+| Status | single-select | yes | workflow stage (the skills move items through your stage options) |
+| Wave | number | optional | grouping anchors into waves/campaigns |
+| Cluster | text | optional | thematic cluster tag |
+| Spec-Path | text | optional | link from an issue to its spec doc |
+| Plan-Path | text | optional | link from an issue to its plan doc |
+| Phase | single-select | optional | groups waves into phases for the Program route (`to-waves`/`validate-graph`) — only needed if this project uses it |
+
+## Machine profile (SSOT) — `scripts/board_config.py` reads this
+
+`/setup-workflow` fills the board-identity values (node id, field IDs, status options) from `gh project field-list`. The convention values (labels, branch prefixes, PR markers, headings) ship pre-filled to match the bundled skills — edit them only if you adapt those conventions. The IDs live **only** in this block (the table above is documentation), so the two cannot drift.
+
+The optional `wrapup` block is a wrapup-only switch, not a board field: `wrapup.remoteBranchSweep` (default `false`) gates `wrapup` Step 5d's remote-branch sweep — `false`/missing (the shipped default) means Step 5d only reports the count of stale merged-PR remotes it found; `true` lets it actually `git push origin --delete` them. Flip it to `true` once you trust the sweep in your repo.
+
+<!-- board-sync:profile -->
+```json
+{
+  "repo": "<owner>/<repo>",
+  "project": {
+    "number": 0,
+    "owner": "<owner>",
+    "nodeId": "<fill via /setup-workflow>"
+  },
+  "fields": {
+    "status": {
+      "id": "<fill>",
+      "options": { "<stage>": "<option-id>" },
+      "roles": {
+        "idea": "Idea",
+        "triaged": "Triaged",
+        "spec": "Spec",
+        "inProgress": "In Progress",
+        "review": "Review",
+        "done": "Done"
+      }
+    },
+    "wave": "<fill / omit>",
+    "cluster": "<fill / omit>",
+    "specPath": "<fill / omit>",
+    "planPath": "<fill / omit>",
+    "phase": {
+      "id": "<fill / omit whole block>",
+      "options": { "<phase-name>": "<option-id>" }
+    }
+  },
+  "labels": {
+    "readyForAgent": "ready-for-agent",
+    "typePrefix": "type:",
+    "clusterType": "type:cluster",
+    "waveStub": "wave-stub",
+    "programType": "type:program"
+  },
+  "branchPrefixes": ["feat", "fix", "chore", "docs"],
+  "prMarkers": {
+    "partOf": "Part of",
+    "retroMarker": "**Retro:**",
+    "retroValues": ["ran", "skipped"]
+  },
+  "headings": {
+    "vorBau": "Clarify Before Build"
+  },
+  "wrapup": {
+    "remoteBranchSweep": false
+  }
+}
+```
+
+### Status roles (`fields.status.roles`)
+
+The scripts and skills never hardcode status option NAMES — they address stages
+by semantic **role** (`idea` / `triaged` / `spec` / `inProgress` / `review` /
+`done`) and resolve the name via this map (e.g. `board-sync.py add
+--status-role spec`, the SessionStart auto-transition, the wave/anchor status
+icons). The seeded values above are the **recommended English defaults**: name
+your board's Status options exactly like that and nothing needs editing. A
+board in another language (or with different stage names) maps each role to
+its own option name once — e.g. `"inProgress": "En cours"` — and everything
+follows; renaming an option later is one edit here. A role you don't have
+(e.g. no `idea` stage) may simply be omitted. A profile **without** the whole
+`roles` map keeps loading: the auto-transition hook and status icons degrade
+with a visible hint, and `--status-role` commands fail with the exact snippet
+to add.
+
+## If the IDs are not yet filled (stub)
+
+1. Create a GitHub-Projects (v2) board for this owner and add the fields above (at minimum a `Status` single-select with your stage options — the recommended stage names are `Idea, Triaged, Spec, In Progress, Review, Done`, matching the seeded `roles` defaults).
+2. Ensure `gh` has the scopes: `gh auth refresh -s project,read:project`.
+3. Re-run `/setup-workflow` — it discovers the board (`gh project field-list`) and fills the IDs here automatically.
+
+## Optional: the Program route (Phase field + saved Views)
+
+Skip this section entirely unless this project actually plans to use the Program route (`scale-check` → `to-waves` → `validate-graph`) — `fields.phase` / `labels.programType` are never auto-discovered or auto-created (a Phase field's option set is plan-specific, not something `/setup-workflow` can guess), and a profile without them keeps loading unchanged.
+
+1. **Create the Phase field:** `gh project field-create <number> --owner <owner> --name Phase --data-type SINGLE_SELECT --single-select-options "P1,P2,P3"` (name the options after this project's actual phases).
+2. **Fill `fields.phase`** in the `<!-- board-sync:profile -->` block above with the same `{id, options}` shape as `fields.status` — read both back via `gh project field-list <number> --owner <owner> --format json`.
+3. **Fill `labels.programType`** only if this project's Program-PRD type label should differ from the shipped literal default `type:program`.
+4. **Create two saved Views** in the GitHub Projects UI by hand (not API-creatable):
+   - **"Program"** — Group by: `Phase` · Sort by: `Wave` · Filter: `type:cluster OR wave-stub OR type:program`.
+   - **"Active Wave"** — Filter: `Wave=<n>` (the current wave number) · Group by: `Status`.

package/.claude/skills/setup-workflow/code-review.md

@@ -0,0 +1,26 @@
+# Code-review project layer
+
+The generic `code-review` skill ships the Two-Axis method (Standards × Spec),
+the Fowler-smell baseline, and the merge-base preflight — the *how*. This file
+is the **project layer**: it records exactly which docs count as this repo's
+Standards-axis sources, and how the method relates to any other review
+tooling already running in this environment. The skill reads it at runtime;
+with this file present it resolves the Standards sources directly instead of
+scanning the repo root itself.
+
+This is a structured-but-empty crust — `/setup-workflow` seeds the headings,
+it does not invent your project's answers. Fill the two sections below
+directly (or grow them over time) whenever you know the real values.
+
+## Standards sources in this repo
+<!-- List the docs the Standards axis should read: a root convention file
+     (CLAUDE.md/AGENTS.md/CONTRIBUTING.md), any per-package convention files
+     in a monorepo, a docs/conventions/ folder, a style guide. One per line. -->
+- _none recorded yet — add the paths this repo's standards actually live at_
+
+## Adjacent review tooling
+<!-- Name any other review-shaped tool/skill/command already running in this
+     environment (a plan-review loop, a security-specific audit, a
+     reuse/simplification pass, a reviewer subagent) and how code-review
+     relates to it (complements it / does not replace it). One per line. -->
+- _none recorded yet_

package/.claude/skills/setup-workflow/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/.claude/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/.claude/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.