@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/scale-check/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: scale-check
+disable-model-invocation: true
+description: "Route an undertaking to the right altitude before any planning starts — a short plain-language dialog (3–6 questions) deciding between a Program, a Feature, a single Direct-Slice, or a Bug, then hand back a paste-ready start prompt for the chosen route. Use at the very start of a new build when the size is unclear (a new app, a big cross-cutting feature, or a where-do-I-start question). Owns the altitude criteria catalog; when in doubt it routes to Feature. NOT for slicing a chosen plan (to-issues) and NOT for clustering an existing backlog (board-to-waves)."
+---
+
+# scale-check — Route an undertaking to its altitude
+
+Answers one question in plain language: **"how big is this, and where do I start?"**
+The output is a **verdict** (Program / Feature / Direct-Slice / Bug), the **route**
+that fits it, and a **paste-ready start prompt** for that route. No requirements
+interview, no code, no board writes — this is a routing dialog, not a planning
+skill.
+
+This skill is the **single owner of the altitude criteria catalog** below. Other
+skills only *reference* it — a backlog-grooming pass escalates a candidate that
+trips the program criteria, and the skill router names it as the first step for a
+new build without a clear size. Keep the catalog here and cite it from there;
+never fork a second copy.
+
+## When to reach for it
+
+- A new undertaking whose size is genuinely unclear — greenfield app, "a bunch of
+  related work", a feature that might be bigger than one feature.
+- Someone asks "where do I start?" / "is this a program?" / "do I need a PRD?".
+- **Not** when the size is already obvious: a one-line fix goes straight to a
+  Direct-Slice, a known bug straight to a diagnosis — you can skip the dialog and
+  hand back that route directly.
+
+## The dialog — 3 to 6 plain-language questions
+
+Ask **one question at a time**, in plain language (no PM jargon), and recommend an
+answer where the person hesitates. Stop early once the verdict is unambiguous (two
+program criteria already tripped, or an obvious single-slice/bug). Each answer maps
+to the criteria catalog below.
+
+1. **Is this fixing something that used to work, or building something new?**
+   → "fixing" ends the dialog: **Bug** route.
+2. **In one sentence, what should exist at the end that doesn't today?**
+   (Frames the whole thing in outcome language — everything below hangs off this.)
+3. **Does it arrive in one go, or in several stages you'd ship and learn from
+   separately** (a first usable version, then expansions)?
+4. **Is it one clear area of the app, or several parts that each stand on their
+   own** (a whole new app counts as "several")?
+5. **Realistically, is this a handful of focused changes, or many separate work
+   sessions stretching over a longer horizon — and does its shape need big
+   structural calls locked before day one** (data model, phasing, cross-area
+   sequencing) **that would be expensive to revisit mid-build?**
+6. **Are there distinct acceptance stages** — e.g. a pilot that has to pass before
+   a wider rollout — **that gate what comes after them, and would progress only
+   make sense as a rollup across many waves rather than one issue's status?**
+
+Questions 3–6 are the four program-signal probes, each reaching two of the six
+altitude criteria (3→C1, 4→C2, 5→C3+C5, 6→C4+C6); question 1 catches bugs,
+question 2 anchors the outcome. You rarely need all six.
+
+## Altitude criteria (the single source of truth)
+
+Count how many of these the undertaking trips. **Two or more → Program route.**
+Fewer than two → it is a Feature (or smaller). **When it is borderline or you are
+unsure, route to Feature, never Program** — an emergent wave can always be promoted
+later, but program scaffolding you never needed is pure waste, and the Feature
+route can grow into a program the moment a second criterion clearly trips.
+
+- **C1 — Staged delivery.** It ships in several successive stages (a first usable
+  version, then expansions), not a single release.
+- **C2 — Multiple subsystems.** It spans several parts that each stand on their own,
+  or is a whole new app (greenfield), not one feature area.
+- **C3 — Long horizon.** It realistically needs many separate build sessions/waves,
+  not a handful of slices.
+- **C4 — Acceptance gates.** It has distinct acceptance stages (pilot → rollout,
+  phase gates) that gate later work.
+- **C5 — Upfront structure decisions.** Its shape needs structure-bearing decisions
+  locked before the first build day (data model, phasing, cross-area sequencing) —
+  decisions that would be expensive to revisit mid-build.
+- **C6 — Program-level overview.** Progress only makes sense as a rollup across many
+  waves, not as one issue's status.
+
+A single criterion is a strong Feature that may grow; **two or more is the program
+threshold**. The threshold is deliberately low and the tie always breaks to Feature.
+
+## Verdicts, routes, and start prompts
+
+Report the verdict, which criteria tripped (for a Program) or why it stayed below
+threshold, and the matching paste-ready start prompt. All four routes are existing
+skills — this skill only picks the entry point.
+
+### Program (≥2 criteria)
+
+A multi-wave undertaking: grill it once into a Program-PRD with a wave plan, then
+unfold that plan onto the board after a chat preview gate.
+
+```
+New program: <one-sentence outcome from Q2>.
+Tripped altitude criteria: <e.g. C1 staged delivery, C2 multiple subsystems, C4 gates>.
+1. Run a program grill with `grill-with-docs` — lock scope → phases → waves and any
+   structure-bearing decisions (escalate a single bounded choice to `decision-gate`).
+2. `to-prd` — it auto-detects the program mode from the Wellenplan chapter and writes
+   a Program-PRD (native anchor over the waves).
+3. `to-waves` — unfold the wave plan into named wave stubs + slice leaves after the
+   chat preview gate (nothing is written to the board until you approve it).
+```
+
+### Feature (0–1 criteria, or any doubt)
+
+One coherent feature — the standard single-wave line, unchanged.
+
+```
+New feature: <one-sentence outcome from Q2>.
+`grill-with-docs` (sharpen the terms + decisions) → `to-prd` (publish the Draft-PRD)
+→ `to-issues` (slice it into independently buildable tracer-bullet slices).
+```
+
+### Direct-Slice (a single, well-understood change)
+
+One behavior, already clear enough to build — no PRD, no slicing.
+
+```
+Small change: <one-sentence behavior>.
+`tdd` — one behavior at a time, red → green → refactor. No PRD, no decomposition.
+```
+
+### Bug (something that used to work)
+
+```
+Bug: <what's broken — expected vs. actual>.
+`diagnose` — reproduce, minimize, hypothesize, instrument, fix, regression-test.
+```
+
+## Output shape
+
+```
+scale-check: verdict=<Program | Feature | Direct-Slice | Bug>
+  criteria tripped=<C1,C2,… | none | n/a (bug/direct)>
+  route=<program grill → to-prd → to-waves | grill-with-docs → to-prd → to-issues | tdd | diagnose>
+  start-prompt: <the paste-ready block above, filled in>
+```
+
+Make the doubt-default visible: if it landed on Feature only because it was
+borderline, say so — "one criterion tripped (C2); routed to Feature by the
+tie-breaks-to-Feature rule — promote a wave later if a second one clearly appears."

package/.agents/skills/security-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: security-audit
+description: "Run the whole application's security audit as an independent two-model pass — two AI models audit the same code separately — then harden the remediation plan before any fix lands. Use when the user wants a security audit / security review of the entire app ('audit the app for vulnerabilities', 'is the app secure', 'security check before release'), before a release, or after the attack surface changes (new endpoint, new input source, auth change, dependency bump). NOT for reviewing a single diff/PR (that is a code review) and NOT for infrastructure hardening (firewall/ports/TLS/SSH/backups — audited separately from the application layer)."
+---
+
+# security-audit — application-layer security audit (two-model run)
+
+Application-layer security audit of the whole repo. This skill is the **run
+procedure**; the checklist itself lives in a **runbook you own per project**. The
+generic runbook structure ships as a template you copy and fill:
+**`docs/agents/security-audit-runbook-template.md`** — copy it into your project
+(for example `docs/security/audit-runbook.md`), replace each `<placeholder>` with
+your actual stack, and keep it as the checklist single source of truth. Read your
+filled runbook first.
+
+**Scope guard:** code + config only. Infrastructure (firewall, exposed ports,
+TLS, SSH, backups) is audited **separately** — an exposed database port beats any
+code fix. Keep the two audits apart.
+
+## Workflow — two-model run
+
+Run in a **fresh session** (token hygiene). Anchor the campaign to a single
+tracking issue (an umbrella / cluster issue); open a new one per fresh audit.
+
+1. **Model-A pass (read-only).** Work the runbook's audit prompt → a findings
+   table with exact `file:line`, a severity, and a confirmed/suspected tag on
+   every finding. Cite real evidence — never claim a vulnerability you did not
+   locate in the code; prefer a flagged false positive over a silent omission.
+   Write it to a scratch file.
+2. **Model-B pass (read-only, independent).** Hand a *second* model the **same**
+   prompt in its own read-only sandbox. A second model refutes the first model's
+   false positives and catches what it missed — that independence is the whole
+   point. Generic operational gotchas when the second model is Codex:
+   - **Fresh session — never resume an existing one** during a parallel run:
+     context bleeds across sessions and you get hallucinated, off-topic verdicts.
+   - **Do not pipe the `--json` event stream through `grep`** (it can hang) —
+     write the raw json to a file and parse the thread id separately.
+   - The sandbox sees only tracked files; if you run it inside a git worktree,
+     copy any hook config into the worktree, or it fails closed to deny-all.
+3. **Consolidate.** Merge both passes into one report (the runbook's findings
+   template). Where the two models **disagree**, the finding goes onto a "needs
+   human verification" list — it is **never silently dropped**. Each finding keeps
+   its confirmed/suspected tag together with its evidence.
+4. **Harden the remediation plan.** Draft a remediation plan (which gaps, what
+   fix, what order, what blast radius), then grill **the plan** with a plan-review
+   pass: a relentless interview on scope and priority plus an adversarial
+   second-model review of the plan until it is approved. The audit produced the
+   *what*; the grill hardens the *how*. A human signs off before any code is
+   touched. (Your project layer names the concrete plan-review skill.)
+5. **Fix by slices.** Each confirmed gap → its own issue → a worktree → a
+   test-first fix → live-verify → a PR linked under the tracking anchor. Tick the
+   anchor's checklist on merge. Gaps discovered mid-fix → filed as their own
+   issue, linked under the same anchor.
+
+## Why two models + a grill
+
+Security findings are the textbook "plausible-but-wrong" case — one model's miss
+or false positive is expensive to catch later. An independent second model is
+cheap adversarial verification; grilling the plan stops over- or under-fixing
+before any code is touched.
+
+## Project layer
+
+Your project's runbook (copied from the template above) carries the stack-coupled
+checklist — the concrete framework, ORM, auth library, and deploy platform, and
+the exact commands to run. The standing tracking anchor and any category / board
+wiring live there too, not in this generic skeleton.

package/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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…_