@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/to-prd/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: to-prd
+disable-model-invocation: true
+description: "Turn a locked plan (PLAN.md in the worktree, conversation context, or an externally-authored spec) into a Draft-PRD issue on the project board, then run spec-self-critique. Use after a grill (grill-me / grill-with-docs / their -codex variants) when you want to publish the PRD. Three modes — create fresh, reuse an existing cluster/Wave-less issue, or auto-detect a Program-PRD from a plan's Wellenplan chapter. Does NOT decompose into slices (that is to-issues) and does NOT set type:cluster / Wave (that is to-issues promotion)."
+---
+
+# to-prd — Draft PRD to the Board
+
+> **Skill identity (don't get confused):** the folder `to-prd` + invocation `/to-prd` map to Matt Pocock's upstream skill **`to-spec`**. Upstream renamed `to-prd` → `to-spec` (v1.1.0); we deliberately keep the folder name `to-prd` (invocation stability, and PRD is this workflow's vocabulary). Content remains our fork, compared against upstream `to-spec` @ `d574778`. Provenance/rename ledger: `docs/agents/provenance.md` (§Re-Sync-Log), at the project root.
+
+Takes an **already-locked plan** and publishes it as a **Draft-PRD issue**. **Never invents requirements** — only synthesizes what's already decided. Pipeline: `board-to-waves → grill(-with-docs) → to-prd → to-issues`. The **grill sits upstream**; to-prd writes the PRD after the grill. **Slicing + promotion to an anchor (cluster/Wave, child link) = `to-issues`** (future), not here.
+
+Board constants (project node, field/status IDs) + helpers live **consumer-side**: read `docs/agents/board-sync.md` from the project root + use the helper `scripts/board-sync.py` (missing → `/setup-workflow` scaffolds the project layer). Issue body **always** via `--body-file` (inline `--body` with backticks/parens crashes bash).
+
+## 1. Input — source-agnostic
+
+to-prd reads the locked plan regardless of source:
+<!-- mirror-xform:start codex-escalation -->
+- **Default: `PLAN.md` in the current worktree** — `grill-me` / `grill-with-docs` only write `PLAN.md` conditionally (on a worktree/session cut).
+<!-- mirror-xform:end -->
+- **Fallback: conversation context** (same-session, no PLAN.md).
+- **Externally supplied:** a spec authored elsewhere (e.g. Claude Web/Codex), handed into context.
+
+If a `PLAN.md` exists in the worktree, it's the source; otherwise conversation/external.
+
+**Cold start = extract-or-synthesize, not assume-or-fail (anchor).** `to-prd` is the **universal normalizer** for loose artifacts (plan/doc/external PRD without a board issue): the PRD template sections are **extracted from what exists**, instead of assuming a prior grill. `to-prd` **mandates no** grill and **no** Codex — depth is the entry person's choice.
+- **A non-derivable required section ≠ a silent "complete" placeholder (anchor):** if a required section (e.g. "Testing Decisions") can't be derived from the input, the open content moves into a **`## Open Questions (not derivable from input)`** section — the PRD is then honestly *open* instead of falsely *complete*. `spec-self-critique` (step 5) remains mandatory.
+- **Downstream contract:** a non-empty `## Open Questions` forces `to-issues` to publish the affected slices as **HITL** (`headings.vorBau` heading, board profile `docs/agents/board-sync.md`; <project> currently `## Vor Bau zu klären`) or ask first — open questions never disappear silently (see `to-issues` §3b). Each open question is classified by **gate type** (🧭 design grill / 🔬 verify-spike / 📐 trade-off research / 📝 review note) so `to-issues` sequences it as a gate slice **before** the dependent build slice (gate-before-build) — a 📝 review note is **not** cut into a slice (see template section "Review Notes" + `to-issues` §3b). (Retro anchor)
+
+## 2. Detect mode — new vs existing issue
+
+No user flag — auto:
+- **Mode A (fresh):** no target issue → to-prd creates a new Draft-PRD.
+- **Mode B (reuse):** a **cluster/Wave-less** issue already exists (an earlier Draft-PRD on re-run, or a de-cored `board-to-waves` candidate stub) → to-prd writes the PRD **into that issue** (no duplicate).
+- **Mode program (auto-detected, no flag, same as A/B):** the plan/source carries a `## Wellenplan` chapter (the machine-parsable table `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` defines) → to-prd writes a **Program-PRD** per that format instead of the regular `<prd-template>` below (§4b), stamps `<!-- prd: program -->` instead of `<!-- prd: awaiting-decomposition -->` (§4), and the §8 audit line names the mode loudly (`mode=program`). Detection is purely content-based — a program-mode write can still be a fresh create (Mode A) or a reuse (Mode B); the Wellenplan chapter flips the format/marker/label, not the target-selection logic.
+
+**Cluster/Wave discriminator (identical wording — `to-prd` §2 / `to-issues` §5):** `type:cluster` (label) always stops. A Wave number also stops, **unless** the target carries the `wave-stub` label — a Wave-stamped `wave-stub` issue is a **Stufe-1p Program-stub** (`to-waves`-published, native parent = a Program-PRD) and remains a **valid target**. A Wave-stamped issue **without** `wave-stub` (an already-assigned leaf, or a drifted item) is still a hard stop.
+
+**Hard stop before any write:** per the discriminator above → **abort** and report: "cluster/Wave anchor is not a to-prd target — belongs on the Wave-model/`to-issues` path". to-prd **never sets** cluster/Wave and **never strips** them — it only ever operates on cluster/Wave-less issues, or on a `wave-stub`-labeled Stufe-1p stub (the exception above — this is how `to-waves`'s per-wave-start content pass writes into a wave stub, `to-waves` SKILL.md §7). Wave lives in the Projects-v2 **field**, not as a label → read the board item + its labels before writing:
+```bash
+gh project item-list 1 --owner <owner> --limit 500 --format json   # check target's Wave/cluster/wave-stub membership
+```
+
+**Programm-Verdacht net (a plan without a Wellenplan chapter, but oversized).** When the source carries **no** `## Wellenplan` chapter but its scope trips the `scale-check` altitude criteria (owned at `.claude/skills/scale-check/SKILL.md` § "Altitude criteria (the single source of truth)" — referenced here, **never** re-forked) — e.g. **staged delivery across >~7 slices** or **several subsystems that each stand on their own** — to-prd does **not** silently write a plain Feature-PRD. It surfaces a loud hint first: "Programm-Verdacht — scale-check-Kriterien prüfen", catching a mis-entry below the program altitude before the Feature-PRD write proceeds. Only after that hint is seen (confirmed as a Feature by the doubt-default, or re-routed through `scale-check`/a program grill) does the write continue.
+
+## 3. Target identity — identity ≠ content
+
+- **Mode B:** target issue number **explicit** (passed in/from context). Branch derivation `feat/<#>-…` **only** when the operation explicitly says "update this issue" — the slice branch is **not** automatically the PRD.
+- **Mode A — idempotency via two separate markers in the body:**
+  - **Stable source identity** `<!-- prd-source-id: <id> -->` — **never** changes across plan content edits (otherwise search-before-create misses the changed re-run → duplicate). **Default rule** for `<id>` (identity ≠ content; set on the **first** to-prd run, **never** changed after — the slug then lives in the issue body and is discoverable via search-before-create): kebab-case slug of the plan topic. Priority: **(1)** explicitly passed ID / durable issue number → **(2)** existing slug from a prior run (found via search-before-create) → **(3)** new kebab-case slug from the plan/title topic. The `PLAN.md` path is only a **secondary hint** (not stable across worktrees; external specs have none), **never** the identity itself.
+  - **Separate content fingerprint** `<!-- prd-content-fp: <hash> -->` — only for diff/audit/bump decisions, **not** for identity.
+- **search-before-create:** **no** reliance on GitHub Search (doesn't index HTML comments). Bounded, local:
+  ```bash
+  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
+  # filter locally on `prd-source-id: <id>` → 1 match ⇒ update; >1 ⇒ STOP+report; 0 ⇒ create
+  ```
+
+## 4. Write the Draft PRD (deliverable)
+
+1. Understand repo/code (if not already), respect the domain glossary + ADRs. Sketch deep modules, align with the user (which get tested).
+2. Write the PRD per the template below.
+3. **Board sync (mandatory):**
+   - **Status `Spec`**, exactly **one** `type:*` (default `type:feature`; pure process/workflow scope → `type:followup`/`type:research` per intent) **plus** one `priority:*` (mandatory vocabulary "type+priority"). **No** `type:cluster`, **no** Wave, **no** `ready-for-agent` — a Draft PRD isn't buildable yet, it's waiting on `to-issues` decomposition.
+   - Board sync via helper:
+     ```bash
+     python3 scripts/board-sync.py create --title "<PRD title>" --body-file <prd.md> \
+       --label type:feature --label priority:medium --status-role spec   # Mode A
+     # Mode B: gh issue edit <target> --body-file <prd.md>  +  board-sync.py add --issue <target> --status-role spec
+     ```
+   - **Mode B — explicit status flip:** writing the PRD into a `board-to-waves` stub, `board-sync.py add --issue <target> --status-role spec` flips the board status **triaged → spec** (role names; the stub sat at the triaged-role status, a Draft PRD sits at the spec-role status).
+   - **mode=program's `type:*`:** the Program-PRD's one `type:*` label is the profile's `labels.programType` value (`board_config.program_type_label()`, literal default `type:program` when unset) — never `type:feature` **and** `type:program` together (the "exactly one `type:*`" invariant is unchanged, program mode just uses a different vocabulary member). `type_labels_to_strip` protects this label from ever being stripped at promote (a Program-PRD is never itself a promote target).
+4. **Body markers (top of the PRD body):**
+   - `**plan_revision:** r1`
+   - `<!-- prd: awaiting-decomposition -->` — durable distinguishability marker: makes "PRD awaiting `to-issues`" board-discoverable **without** a new label (status `Spec` alone also covers planned anchors/other specs).
+   - **mode=program:** `<!-- prd: program -->` **instead of** `awaiting-decomposition` — the program-altitude counterpart marker (never both on the same issue).
+   - `<!-- prd-source-id: <id> -->` + `<!-- prd-content-fp: <hash> -->` (see step 3).
+5. **Mode B label normalization:** if the reused issue carries wrong/multiple `type:*`, missing `priority:*`, `ready-for-agent`, or `needs-info` → **normalize onto the PRD contract** (exactly one `type:*`, one `priority:*`, no `ready-for-agent`/`needs-info`). Exception per the discriminator (§2): `type:cluster` always, or Wave **without** `wave-stub` → **no** normalization, **hard stop** (step 2); a `wave-stub`-labeled Stufe-1p target normalizes normally — it is a valid Mode B target.
+
+## 4b. Program-PRD body (mode=program)
+
+mode=program writes the Program-PRD per `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` instead of the `<prd-template>` below — a **parallel** grammar for the program altitude, not a replacement (a Feature-PRD keeps using `<prd-template>` unchanged). It carries: the `## Scope` chapter with stable Scope-Item IDs (`S1`, `S2`, …), the machine-parsable `## Wellenplan` table (`Welle | Status | Name | Phase | Slices | Gate | covers`), the `## Phasen-Gates` checklist (only when the program uses phases), the `## Slices` per-slice detail chapter (one `####` section per planned slice, per `SLICE-METADATA-FORMAT.md`'s grammar), and the Abbruch-Konvention. `scripts/program_graph.py` (`board-sync.py validate-graph`) is the parser — to-prd writes the shape, it does not itself validate the graph (that is `to-waves`'s job, run once the Program-PRD exists).
+
+## 5. `spec-self-critique` — mandatory next step
+
+to-prd has `disable-model-invocation: true` and can't literally invoke a skill. **After** the PRD write, the agent **must** run `spec-self-critique` on the Draft PRD; its visible two-liner (`Self-critique complete — N corrections: …` or `…no corrections needed`) is required output **before** the user review question.
+
+## 6. Idempotent reconcile (re-run)
+
+- **`plan_revision` parse:** counter `r<N>`; missing/malformed → treat as `r1` + warn. **Body-changing** = a non-empty diff over the **canonical PRD sections** (Problem/Solution/User-Stories/Implementation-Decisions/Testing), **excluding** metadata markers, the child-drift section, and critique output. An identical plan re-run does **not** bump.
+- **R1 — no children:** update body instead of duplicating; bump `plan_revision` only on a body-changing run; critique re-runs.
+- **R2 — children/cluster exist:** update body + bump + **flag durably** — a **`## Child Drift (as of r<N>)`** section in the body (not ephemeral chat output) lists children + their revision. **No** child mutation (= `to-issues`/1d), **no** blocking guard (= 1g).
+- **Program-stub exception to R2 (Stufe-1p pre-created skeleton):** if the Mode B target is a `wave-stub`-labeled Stufe-1p Program-stub (native parent = a Program-PRD), its existing native children are the **slice leaves `to-waves` pre-created** for this wave — that is the program's **expected skeleton**, not R2's `## Child Drift` finding, as long as they match the Program-Graph's `Wellenplan` row for this wave. A mismatch (a missing or a foreign child) is `validate-graph`'s finding to raise, not this reconcile heuristic's — to-prd Mode B does not re-derive graph conformance itself. An ordinary Mode B target (a plain cluster/Wave-less reuse, or a `board-to-waves` candidate stub) keeps the unmodified R2 behavior.
+- **Child discovery:** native sub-issues (via `python3 scripts/board-sync.py parent-of <#>` / rollup) are the authoritative set; report native-vs-body-listed mismatches in the drift section.
+
+## 7. Execute-ready assertion (exit)
+
+- **Before the write (gate):** target carries cluster/Wave → **fail before write** (hard stop, step 2) — never "reconcile after the write".
+- **After the write:** assert that the Draft PRD **exists as a board item** (status write = `Spec`), exactly **one** `type:*` + **one** `priority:*`, **no** `ready-for-agent`, **no** `type:cluster` + **no** Wave (defensive against accidental mutation), carries `plan_revision` + `awaiting-decomposition` + `prd-source-id`, body complete (critique ran). = an unambiguous "PRD-awaiting-decomposition" state (neither AFK leaf nor HITL child — that's `to-issues`'s call). mode=program asserts the same shape with its own markers: `plan_revision` + `<!-- prd: program -->` + `prd-source-id`, the profile's `programType` label (default `type:program`) as the one `type:*`, still no `ready-for-agent`, still no `type:cluster`/Wave — a Program-PRD is exactly as "awaiting further work" as a Feature-PRD, just at a higher altitude (its own lifecycle, §9).
+
+## 8. Audit block (visible output)
+
+```
+to-prd: mode=<A|B|program> target=#<n> <created|updated> rev <old>→<new>
+  status=Spec  labels=<type:*, priority:*>  cluster/Wave=none
+  source=<plan|conversation|external>  synthesized=<marker-list | none>  readiness=<ok | open-questions>
+  child-drift=<none | #a(r1) #b(r1) …>
+```
+`source` = where the input came from (make cold start visible anchor). `synthesized` = which markers `to-prd` freshly set (e.g. `prd-source-id`). `readiness=open-questions` ⇔ the PRD carries a non-empty `## Open Questions` section. For `mode=program`, `labels` shows the profile's `programType` value (default `type:program`) as the one `type:*`, and `cluster/Wave=none` still holds for the Program-PRD itself.
+
+## 9. Program-PRD lifecycle (mode=program only)
+
+A Program-PRD's board Status travels a longer arc than a Feature-PRD's:
+
+- **spec role** — set here, at the mode=program write (§4's board sync, same as any Draft-PRD).
+- **in-progress role** — flipped by `to-issues`, at the **first** wave-stub promotion under this PRD (not by to-prd itself; a re-run of to-prd on an already-in-progress Program-PRD leaves the status untouched).
+- **done role** — set **manually**, by the maintainer, at the program's last Phasen-Gate. `closes` **never** targets a Program-PRD (same close-protection contract as any Welle-Anchor, `to-waves` §8) — it is closed last, by hand, once every wave/stub/leaf under it is done (or, on an abort, closed per the Abbruch-Konvention in `PROGRAM-PRD-FORMAT.md`).
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. **Write each story in the same language as the rest of the PRD** (this project is German-first → German stories; never mix an English scaffold onto German content). Each user story follows the actor/feature/benefit shape:
+
+- Deutsch: `Als <Akteur> möchte ich <Funktion>, damit <Nutzen>.`
+- English: `As a(n) <actor>, I want <feature>, so that <benefit>.`
+
+<user-story-example lang="de">
+1. Als QA-Lead möchte ich den Testfortschritt je Phase auf einen Blick sehen, damit ich Engpässe früh erkenne.
+</user-story-example>
+<user-story-example lang="en">
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending.
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Review Notes (findings that do NOT become slices)
+
+Findings that are real but **not a buildable item** — e.g. a review-only smell no linter/gate catches (SoC drift in a handler, a style question). Per entry: what + why it's not a slice. These carry the gate tag 📝; `to-issues` does **not** cut them into a slice. Fixed opportunistically at the next touch, not tracked. (Boundary: a buildable finding belongs in Implementation Decisions; an open decision/research question belongs in `## Open Questions`.)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>

package/.agents/skills/to-prd/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/to-spec` @ 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/to-waves/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: to-waves
+disable-model-invocation: true
+description: "Unfold a Program-PRD's wave plan onto the board — parse + graph-validate it, show the complete Wellenplan as a chat preview before ANY board write, then after approval publish named wave stubs (native parent = the PRD) + slice leaves (native parent = their stub) with Wave and Phase stamped in one batch, and report a counted completion. Idempotent + crash-recoverable on re-run; adopts referenced existing issues instead of duplicating them. Use on a Program-PRD, the native anchor over several waves. NOT for a single-wave feature (to-issues) and NOT for clustering a backlog (board-to-waves)."
+---
+
+# to-waves — Unfold a Program-PRD's wave plan onto the board
+
+Takes a **Program-PRD** — the native Sub-Issue anchor over a multi-wave program
+(Programm → Phase → Welle → Slice) — and turns its `## Wellenplan` chapter into
+**named wave stubs + slice leaves** on the board. Pipeline position:
+`scale-check → grill → to-prd (program mode) → to-waves → …per wave: to-issues`.
+The **grill and to-prd sit upstream**; to-waves runs once the Program-PRD exists.
+It **never invents structure** — it only unfolds what the plan already decided.
+
+Board constants (project node, field/status IDs) + helpers live **consumer-side**:
+read `docs/agents/board-sync.md` from the project root + use the helper
+`scripts/board-sync.py` (missing → `/setup-workflow` scaffolds the project layer).
+Issue bodies **always** via `--body-file` (inline `--body` with backticks/parens
+crashes bash).
+
+The two grammars to-waves consumes: the Program-PRD body grammar
+(`.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` — the 8-column
+`Welle | Status | Issue | Name | Phase | Slices | Gate | covers` Wellenplan table) and the
+per-slice metadata block (`SLICE-METADATA-FORMAT.md`, next to this file). Read both;
+to-waves does not re-parse them by hand — `scripts/program_graph.py` (via the helper)
+is the parser.
+
+## 1. Input — a Program-PRD
+
+The target is a Program-PRD issue: it carries the `<!-- prd: program -->` marker (or
+the program-type label) and a `## Wellenplan` table. Passed in / from context. If the
+issue is a plain feature-PRD or a Welle-Anchor, stop — a feature-PRD is `to-issues`'
+target, an anchor is already a single wave.
+
+## 2. Parse + validate — the graph preflight
+
+Run the graph preflight first — it is **read-only** (a single board read, zero
+mutations):
+
+```bash
+python3 scripts/board-sync.py validate-graph --issue <prd#>
+```
+
+It parses the Wellenplan table + the per-slice metadata blocks and reports the
+counted Programm-Graph findings: cycles and backward refs across wave boundaries
+(blocking), a Gate-Slice with dependents outside its own wave (a non-blocking
+"Struktur-Verdacht" warning), capacity preflight (the 100-children-per-parent
+GitHub limit), the phase-option preflight, revision coherence, and **both
+completeness axes counted** — vertical Rollup-Kette (every leaf → one wave, every
+wave → ≥1 slice + outcome gate + phase where used) and horizontal Scope-Abdeckung
+(every Scope-Item covered by ≥1 wave; every wave covers ≥1 Scope-Item or is an
+explicit `enabler`). The command exits non-zero when a **blocking** finding exists.
+
+**A blocking finding stops the run — do not publish a broken graph.** Report it and
+send the fix back to the PRD (a structural fix is an escalation, see §8).
+
+## 3. Preview gate — before ANY board write
+
+This is a **hard stop**. Show the whole plan in chat and get explicit approval
+**before the first write**. Because nothing has been written yet, **a rejection
+costs nothing** — the board is never left half-built.
+
+Show:
+
+- The **complete Wellenplan table**, one row per wave: number, name, phase, the
+  slices with their bucket (AFK/HITL) + Gate tag, and each wave's dependencies.
+- The **counted graph result** from `validate-graph` verbatim (Scope-Abdeckung
+  `X von Y`, Rollup-Kette ✓/gaps, any warnings).
+- The **publish plan**: how many stubs + leaves will be created, which referenced
+  existing issues will be **adopted** (§4) rather than created, and which
+  Wave/Phase stamps will be applied.
+
+Then ask for approval. Only on an explicit "yes" proceed to §4/§5. On "no", stop —
+no writes happened.
+
+## 4. Publish — the fixed order
+
+After approval, publish in **exactly this order** (issue CREATES stay sequential so
+the numbering is deterministic; only the field stamps are batched):
+
+1. **Wave stubs — Stufe 1p.** One per Wellenplan row, native parent = the PRD.
+   Title `Welle <N> — <Name>`; created with the `wave-stub` label and Status Spec.
+   Body = the Stufe-1p stub template (named header, the program idempotency marker,
+   the revision marker — see §6). Not yet Wave/Phase-stamped (that is step 4).
+   ```bash
+   python3 scripts/board-sync.py create --title "Welle <N> — <Name>" \
+     --body-file <stub.md> --wave-stub --status-role spec
+   ```
+2. **Slice leaves.** One per slice under each wave, native parent = its stub. Created
+   with the spec-role status and **no** `ready-for-agent` (a leaf is not buildable until its
+   wave is promoted — the ordering guard stays unambiguous). Body = the slice's
+   `## Slices` section carried forward per `SLICE-METADATA-FORMAT.md` (metadata block +
+   the outcome/placeholder skeleton, sharpened only at promotion). **Title carries the
+   navigation prefix** `Welle <N> / Slice <local-id> — <title>` — the local-id
+   (`1a`, `1b`, …) encodes the build order, so the sub-issue LIST is navigable by title
+   alone (same convention as `to-issues`' promoted children, `Welle N / Slice X — <outcome>`).
+   ```bash
+   python3 scripts/board-sync.py create --title "Welle <N> / Slice <local-id> — <slice title>" --body-file <leaf.md> --status-role spec
+   ```
+3. **Sub-issue links.** Link each stub under the PRD and each leaf under its stub.
+   `link` is one-parent-checked + idempotent (a foreign parent is reported, never
+   silently re-parented) — which is exactly what makes the re-run in §5 safe.
+   ```bash
+   python3 scripts/board-sync.py link --parent <prd#> --child <stub#>
+   python3 scripts/board-sync.py link --parent <stub#> --child <leaf#>
+   ```
+   **Blocking edges — native.** For every leaf whose metadata `blocked_by` names
+   sibling slices (local-ids now resolved to issue numbers), set the edge natively —
+   native issue dependencies are the blocking SSOT; the helper also writes the
+   `## Blocked by` body mirror (idempotent, safe under the §5 re-run):
+   ```bash
+   python3 scripts/board-sync.py dep-add --issue <blocked-leaf#> --blocked-by <blocker-leaf#>
+   ```
+4. **Batch-stamp Wave + Phase.** One `stamp-batch` over every stub and leaf. It
+   consumes a JSON list of `{issue, item_id, wave, phase}`; assemble it by resolving
+   each freshly-created issue's board **item id** from the project item list (the
+   same read the helper's `next-wave` performs — `gh project item-list <n> --owner
+   <owner> --limit 2000 --format json` (no `--limit` defaults to 30 — a silent
+   truncation dead-end on a real board), matching `content.number` → item `id`).
+   Missing `phase` in the profile is **skipped visibly**, never dropped silently.
+   ```bash
+   python3 scripts/board-sync.py stamp-batch --items-file <stamps.json>
+   ```
+   The counted line `N von M Feld-Stempel gesetzt` is the verification — there is no
+   extra read-back pass. Any failed alias prints an idempotent single-item repair
+   (`stamp-batch --issue … --item-id … --wave …`); re-run it, a field-set is idempotent.
+5. **Wellenplan back-link sync.** Run `program-sync` once so the PRD's Wellenplan
+   `Issue` column links each freshly created stub (`#<stub#>`, matched via the
+   `Welle <N> —` title —; idempotent, fills-never-overwrites):
+   ```bash
+   python3 scripts/board-sync.py program-sync <prd#>
+   ```
+6. **Counted completion report + program view link.** Report `X von Y` for each part
+   (stubs created, leaves created, issues adopted, field stamps set) and link the
+   program board view. Completeness is **counted, never claimed** — the numbers come
+   from the create outputs + the `stamp-batch` response, not from memory.
+
+## 5. Adopt path — referenced existing issues
+
+If a Wellenplan row references an **existing** issue (`#n`, e.g. one produced by
+bottom-up backlog grooming), that issue is **ADOPTED**, not re-created — otherwise a
+bottom-up → program transition rains duplicates. Adoption:
+
+- **Board-sync + strip the buildable labels** in one call. `--bucket hitl` strips
+  `ready-for-agent` and `wave-stub` (a leaf is not buildable until its wave is
+  promoted) while the **body is kept** as the source content:
+  ```bash
+  python3 scripts/board-sync.py add --issue <n> --status-role spec --bucket hitl
+  ```
+- **Re-parent under the stub** with `link` (one-parent-checked — a foreign parent is
+  reported, not overwritten). Resolve a reported conflict by hand: unlink the old
+  parent first — `python3 scripts/board-sync.py unlink --parent <old#> --child <n>`
+  — then re-run `link` under the intended stub.
+- **Include it in the §4 batch-stamp** so it gets the same Wave/Phase as a fresh leaf.
+
+Adoption normalizes workflow labels **immediately** (the strip above) so the
+ordering guard stays clean; it never touches the issue's body.
+
+## 6. Idempotent re-run + revision coherence
+
+A re-run of to-waves on the same program is **delta-apply** and doubles as
+**crash-recovery** for a publish that was interrupted mid-way.
+
+- **Idempotency markers.** Every stub carries a stable
+  `<!-- program-stub-source: <prd-source-id>/w<N> -->` and every leaf a
+  `<!-- program-leaf-source: <prd-source-id>/<local-id> -->` (same spirit as the
+  bottom-up `wave-stub-source` marker; `<prd-source-id>` is the PRD's own source
+  slug). These never change across revisions — they are the identity for
+  search-before-create.
+- **Delta apply.** Filter existing issues locally by their source marker
+  (`gh issue list --json number,body` + a local filter, no reliance on GitHub search —
+  it does not index HTML comments). For each planned stub/leaf: **match** → update in
+  place (never duplicate); **missing** → create; a live issue carrying a
+  `program-*-source` for this program that the current plan no longer references →
+  report as **orphaned** (do not auto-close — closing is the abort convention, §8).
+  Cross-check the native children (`children-of <prd#>` and each stub) against the
+  plan so both origins are covered.
+- **Crash recovery.** Because create is search-before-create, `link` is idempotent,
+  and `stamp-batch` field-sets are idempotent, re-running the whole publish after an
+  abort resumes cleanly — already-created issues match, missing ones are created,
+  links/stamps re-apply harmlessly.
+- **Revision coherence.** to-waves stamps `<!-- program-revision: rN -->` on every
+  stub. `validate-graph` checks this marker against the PRD's
+  current `plan_revision` — a **stale** stub (the wave plan was revised since) blocks
+  **loudly** instead of silently building from an old shape. On a plan-revision bump
+  (the escalation path, §8), the delta re-run **renews the `program-revision` marker
+  of every still-living stub that would otherwise fail the current PRD check** — read
+  this broadly: every stub whose marker is behind, not only the textually changed
+  rows. The renewal is a body edit via `gh issue edit <stub#> --body-file <updated>`
+  (the same sanctioned body-write `to-prd` Mode B uses). The mechanism that renews
+  coherence is the same one the revision broke — it self-repairs.
+
+## 7. Program-grill agenda + the per-wave-start content pass
+
+to-waves also carries the **program-grill agenda** as a reference chapter — the
+checklist a program grill (upstream) should cover so the wave plan does not rest on
+open switches:
+
+- **Scope → Phases.** Break the outcome into phases (optional) and the Scope-Items
+  (stable IDs) each phase serves.
+- **Gates from DoDs, in outcome language.** Every phase/wave gate is an
+  acceptance criterion phrased as a user-visible outcome, not a task.
+- **Wave cut.** Each wave is an outcome slice (a tracer), never a layer slice — a
+  "backend wave" is an anti-pattern; an enabler wave names the half it cuts off and
+  the outcome wave that closes it.
+- **Metadata.** Wave numbers, phases, covers-IDs, gate tags filled per the two
+  grammars.
+- **Structure-bearing decisions are grill work, never a plan work-item.** A decision
+  that changes where a boundary falls is resolved **at the grill** — escalate a
+  single bounded choice to `decision-gate` — not deferred into the plan as an open
+  task.
+
+**The per-wave-start content pass** is where slice content is sharpened — deliberately
+**just-in-time (Late Binding)**, never ex ante on spec. When a wave is promoted:
+`to-prd` (Mode B, into the wave stub) + `spec-self-critique` are **mandatory**, and
+the depth ladder is **raised for a high-stakes wave** (a design-grill or a
+`decision-gate` before slicing). This is what folds in any drift propagated since the
+plan was first written.
+
+## 8. Close protection, abort convention, escalation path
+
+- **Never `closes` the Program-PRD or a wave anchor.** A slice PR uses `Part of
+  #<anchor>`; `closes` only ever targets a leaf. The PRD is closed **last, manually**,
+  when the program is done — never auto-closed by a PR.
+- **Abort convention.** To abandon a program cleanly (no board zombies): close
+  **leaves first** (`superseded by program abort`), then their **stubs**, then the
+  **Program-PRD** last, manually — the order documented in the PROGRAM-PRD-FORMAT
+  Abbruch-Konvention.
+- **Escalation path.** When a gate result flips the structure (a wave needs to
+  split/merge/reorder), **STOP** — do not patch it in a build slice. Revise the
+  Wellenplan **at the PRD** with the maintainer, **bump `plan_revision`**, and re-run
+  to-waves as a **delta** (which renews the `program-revision` markers per §6).
+  Append-only drift notes (to future stubs/leaves + the PRD) do **not** bump
+  `plan_revision`; only a structural wave-plan change does.
+
+## 9. Live dashboard — program-sync
+
+Between wave events the PRD's Wellenplan **Status** + **Issue** columns are
+regenerated from the board (monotone, idempotent — Status never regresses, Issue
+fills but never overwrites; hand-owned Name/Plan cells survive verbatim), and
+mechanically completed **Phasen-Gates** are checked off (all waves of a phase ✅ →
+`[x]` with an `— alle Wellen ✅ (<date>)` stamp). `wrapup` triggers the same
+sync automatically on every slice merge whose wave anchor has a program parent
+(upward propagation — the program table shows the event, not only the wave):
+
+```bash
+python3 scripts/board-sync.py program-sync <prd#> --dry-run   # preview the diff first
+python3 scripts/board-sync.py program-sync <prd#>
+```
+
+## Audit block (visible output)
+
+```
+to-waves: prd=#<n> preview=<approved|rejected>
+  created=<stubs X von Y, leaves X von Y>  adopted=<#a #b … | none>
+  stamped=<N von M Wave/Phase>  phase=<stamped | skipped (profile lacks fields.phase)>
+  revision=r<N>  renewed-markers=<count | none>  orphaned=<#… | none>
+  graph=<ok | blocking: …>  program-view=<url>
+```

package/.agents/skills/to-waves/SLICE-METADATA-FORMAT.md

@@ -0,0 +1,74 @@
+# SLICE-METADATA-FORMAT — per-slice metadata block
+
+The metadata block a **planned slice** carries inside a Program-PRD's
+`## Slices` chapter (see `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md`), and the
+same fields carried forward onto the real Slice **leaf issue** once `to-waves`
+publishes it. Parsed pre-publish by `scripts/program_graph.py`
+for `validate-graph`; the same grammar is what a published leaf keeps so drift
+tooling (adopt-path, program-sync) reads one consistent shape whether the slice
+is still a PRD sub-section or already a real GitHub issue.
+
+## The five fields — grep-bare HTML comments
+
+One fact per line, consistent with the existing `final-cut-depends-on`
+convention (`scripts/execute-ready-check.py`'s marker table) — plain HTML
+comments, never folded into prose, so a script can `grep`/regex them without
+parsing Markdown semantics:
+
+```
+<!-- wave: 1 -->
+<!-- phase: P1 -->
+<!-- area: scripts -->
+<!-- gate: — -->
+<!-- blocked_by: none -->
+```
+
+| Field | Value | Meaning |
+|---|---|---|
+| `wave` | integer | The Welle number (from the Wellenplan's `Welle` column) this slice belongs to. |
+| `phase` | a Phase id (`P1`, …) or `—` | Omit/`—` when the program doesn't use phases. |
+| `area` | free text (e.g. `scripts`, `frontend`, `backend`) | A short human hint about where the slice lands — not machine-checked, purely orientation. |
+| `gate` | `—` \| `🧭` \| `🔬` \| `📐` \| `📝` | Same Gate-Legende as `wave-anchor-template.md`. `—` = AFK-buildable; the other four mark a Gate-Slice (read-only, blocks its dependent build-slice). |
+| `blocked_by` | `none` or comma-separated **local-ids** | Other slices (by local-id, e.g. `1a`, `2c`) that must land first. `none` (not an empty string) when there is no dependency. |
+
+**Never add a sixth field without updating this file first** — `program_graph.py`'s
+parser only recognizes exactly these five keys; an unrecognized field is silently
+ignored (forward-compatible for prose additions), but a mistyped one of these
+five (e.g. `blocks_by`) breaks that slice's graph edges invisibly.
+
+## Local-id convention
+
+The local-id (`1a`, `1b`, `2a`, …) is the slice's identity **before** it becomes
+a real GitHub issue — `<wave-number><letter>`, letters assigned in the order the
+slice appears under its wave. It is how the Wellenplan table's `Slices` column,
+other slices' `blocked_by`, and this slice's own heading
+(`#### 1a — <Title>`) all refer to the same slice unambiguously pre-publish.
+Once `to-waves` publishes the slice as a real issue, the local-id is superseded
+by the issue number everywhere `final-cut-depends-on`-style cross-references are
+used — but the metadata block's five fields keep the same shape (only `wave` and
+`phase` typically survive verbatim; `blocked_by` gets rewritten to `#<n>`
+references by the publish step **and set as native issue-dependency edges**
+(`dep-add`) — the blocking SSOT; the leaf's `## Blocked by` body section is
+their machine-written mirror).
+
+## Body skeleton
+
+Below the metadata block, every slice section carries the same three-part
+skeleton — filled in loosely during `to-waves`' planning pass, **finalized**
+(sharpened into a full What-to-build + AC, matching a leaf issue's usual shape)
+only at promotion time, same "Late Binding" principle as the rest of the
+program-route mechanics (content quality is deliberately just-in-time, not
+ex ante):
+
+```
+Outcome: <one sentence — the user-visible or structural result this slice delivers>
+
+What to build: <placeholder — sharpened at promotion>
+
+AC: <placeholder — sharpened at promotion>
+```
+
+A slice section that still carries bare placeholders is normal *before*
+promotion — `validate-graph`'s structural axes don't require sharpened prose,
+only the five metadata fields and a resolvable heading. Content sharpening is a
+`to-waves` promotion-time concern, not a `validate-graph` concern.