@ikon85/agent-workflow-kit 0.10.0

package/docs/agents/board-sync.md

@@ -0,0 +1,71 @@
+<!-- setup-workflow: state=filled; mode=github-projects-v2 -->
+# Board sync — GitHub Projects field IDs
+
+The workflow board is [Agent Workflow Kit](https://github.com/users/iKon85/projects/3). Board-managed skills address it through the profile below and `scripts/board-sync.py`.
+
+<!-- board-sync:profile -->
+```json
+{
+  "repo": "iKon85/agent-workflow-kit",
+  "project": {
+    "number": 3,
+    "owner": "iKon85",
+    "nodeId": "PVT_kwHOAuH31M4BdM5V"
+  },
+  "fields": {
+    "status": {
+      "id": "PVTSSF_lAHOAuH31M4BdM5VzhXwFOk",
+      "options": {
+        "Idea": "357a9b54",
+        "Triaged": "463d3f21",
+        "Spec": "1cd0343b",
+        "In Progress": "35e6c509",
+        "Review": "51f16b28",
+        "Done": "491150b6"
+      },
+      "roles": {
+        "idea": "Idea",
+        "triaged": "Triaged",
+        "spec": "Spec",
+        "inProgress": "In Progress",
+        "review": "Review",
+        "done": "Done"
+      }
+    },
+    "wave": "PVTF_lAHOAuH31M4BdM5VzhXwFWg",
+    "cluster": "PVTF_lAHOAuH31M4BdM5VzhXwFWk",
+    "specPath": "PVTF_lAHOAuH31M4BdM5VzhXwFWo",
+    "planPath": "PVTF_lAHOAuH31M4BdM5VzhXwFWs",
+    "phase": {
+      "id": "PVTSSF_lAHOAuH31M4BdM5VzhXwFWw",
+      "options": {
+        "P1": "9c8c93e0",
+        "P2": "cf741bec",
+        "P3": "8a69a61e"
+      }
+    }
+  },
+  "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
+  }
+}
+```
+
+The Program route uses phases `P1`, `P2`, and `P3`. Saved board views remain a GitHub UI concern; the machine profile above is the workflow SSOT.
+

package/docs/agents/code-review.md

@@ -0,0 +1,14 @@
+<!-- setup-workflow: state=filled -->
+# Code-review project layer
+
+## Standards sources in this repo
+
+- `CLAUDE.md` and `AGENTS.md`
+- `docs/conventions/`
+- The originating issue or PRD for the Spec axis
+
+## Adjacent review tooling
+
+- `spec-self-critique` reviews plans before code exists; it does not replace diff review.
+- Security audits and simplification passes remain narrower complementary checks.
+

package/docs/agents/domain.md

@@ -0,0 +1,7 @@
+<!-- setup-workflow: state=filled -->
+# Domain docs
+
+This is a single-context repository. Before design work, read root `CONTEXT.md` when present and the relevant decisions under `docs/adr/`. Their absence is non-blocking: `grill-with-docs` creates them when the product language or a durable decision first needs recording.
+
+Use glossary terms consistently in issues, tests, and skill text. Surface conflicts with an existing ADR instead of silently replacing its decision.
+

package/docs/agents/issue-tracker.md

@@ -0,0 +1,12 @@
+<!-- setup-workflow: state=filled -->
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live in `iKon85/agent-workflow-kit` as GitHub issues.
+
+## Conventions
+
+- Use `gh` for issue reads and comments; infer the repository from the remote.
+- Write multi-line issue and PR bodies through a temporary file and `--body-file`.
+- Route board writes, status/wave/cluster field edits, dependencies, and sub-issue links through `scripts/board-sync.py`, not bare `gh project` commands.
+- Board state is authoritative for workflow status; GitHub issues remain the durable content source.
+

package/docs/agents/security-audit-runbook-template.md

@@ -0,0 +1,205 @@
+# Security-Audit Runbook — TEMPLATE
+
+> **Copy this file into your project** (for example `docs/security/audit-runbook.md`),
+> then replace every `<placeholder>` with your actual stack and delete the guidance
+> lines. The `security-audit` skill is the *run procedure*; this runbook is the
+> *checklist* it works through. The STRUCTURE below carries the value — keep all six
+> Parts, fill them for your stack.
+>
+> **Scope: source code + config = the application layer only.** Infrastructure
+> (firewall, exposed ports, TLS, SSH, backups) is audited **separately** — an exposed
+> database port beats any code fix. Track the standing audit anchor issue in Part 0.
+
+---
+
+## Part 0 — Scope
+
+Fill this once per project; re-confirm it each run (the attack surface moves).
+
+| Question | Answer |
+|---|---|
+| **Public surface** | `<public URLs>` — which routes are reachable **unauthenticated** vs auth-gated. |
+| **Trust boundary** (untrusted input) | `<HTTP body/query/params · file uploads · outbound fetch of user/admin-configured URLs · webhook payloads · SSE/websocket streams>` |
+| **Crown jewels** | `<secrets/keys · third-party credentials · per-tenant data · the database · admin accounts>` |
+| **Auth model** | `<session/token mechanism → authn gate → per-resource authorization → tenant/row scoping>` |
+| **Deployment** | `<where it runs, which images/artifacts, what is internal-only, deploy trigger>` |
+| **Tracking anchor** | `#<issue>` — the umbrella issue this audit's findings link under. |
+
+---
+
+## Part 1 — AI-runnable audit prompt
+
+Open your AI code assistant (and a second, independent model — see Part 5) in the
+repo root and paste a prompt shaped like this, tailored to your stack:
+
+````text
+You are performing a READ-ONLY security audit of THIS repository
+(<framework> backend, <ORM> on <database>, <auth lib>, <frontend stack>,
+<deploy platform>). Do NOT modify files.
+
+For EACH checklist item: search the code (prefer ripgrep), report findings with an
+exact `file:line`, classify severity (Critical/High/Medium/Low/Info), and give a
+concrete fix. If an item does not apply, say "N/A" and why. End with a findings
+table sorted by severity plus a "needs human verification" list.
+
+Rules:
+- Cite a real file:line for every finding. No finding without evidence
+  (tag each: suspected / verified-with-evidence).
+- Distinguish confirmed from suspected. Never claim a vuln you did not locate.
+- Prefer a flagged false positive over a silent omission.
+
+CHECKLIST: <paste the 12 headings from Part 2>
+````
+
+> The agent pass is a **lead generator, not a verdict**. Every finding is
+> "suspected" until confirmed against the real code in Part 2.
+
+---
+
+## Part 2 — Manual checklist
+
+Each section: **what & why**, **example commands** (swap in your paths/tools), a
+**baseline** you record on the first run and re-verify every run (code moves), and a
+**severity**. Read the surrounding code; never trust a grep hit alone. Anchor every
+path from the repo root.
+
+### 1. Secrets & credentials · **Critical**
+- [ ] No secrets in tracked files **or git history** (treat any hit as compromised → **rotate**).
+- [ ] Ignore files exclude `.env*`, key/credential files (from both VCS and the build image).
+- [ ] Secrets read from the environment at runtime; no defaults baked into code.
+- **Baseline:** `<record: committed secrets? history scanned? gaps + tracking issue>`
+
+### 2. Authentication & authorization (IDOR + tenant scope) · **Critical**
+- [ ] Every non-public route requires the authn guard, applied **before** the handler.
+- [ ] Reads/writes verify the caller **owns / belongs to** the resource, not just "logged in".
+- [ ] **Every** tenant-scoped query filters by `<tenant-scope column>` — no query forgets it.
+- [ ] Admin routes check an admin role, not merely authentication.
+- **Baseline:** `<record>`
+
+### 3. Injection · **Critical**
+- [ ] All DB access parameterized (query builder or bound params) — no user input concatenated.
+- [ ] Any credential-decrypting / privileged DB function only ever receives bound params.
+- [ ] No `child_process` / `exec` / `eval` / dynamic-code on untrusted data.
+- **Baseline:** `<record — mark stack-irrelevant classes (NoSQL, templating, deserialization) N/A>`
+
+### 4. XSS & output encoding · **High**
+- [ ] User input rendered to HTML is escaped (most frameworks auto-escape by default).
+- [ ] Any raw-HTML sink (`<raw-html API>`) is justified and sanitized if input is user-controlled.
+- **Baseline:** `<record>`
+
+### 5. Attack-surface & error exposure · **High**
+- [ ] Generic 500s — no stack traces / internals returned to clients.
+- [ ] CORS is an explicit allowlist; never `*` with credentials.
+- [ ] Debug/test routes gated behind an env flag, off in production. No open redirects.
+- [ ] Security headers present (`<header middleware / proxy config>`).
+- **Baseline:** `<record>`
+
+### 6. Input validation, uploads, path traversal, SSRF · **High**
+- [ ] Request bodies validated against a schema, not trusted raw.
+- [ ] Uploads enforce **type (real MIME, not just extension), size, safe path**; content scrubbed
+      (for example spreadsheet formula injection on leading `=` `+` `-` `@` cells).
+- [ ] No path traversal: user input never joined into a filesystem path without normalize + base-dir check.
+- [ ] **SSRF:** any server-side fetch of a user/admin-supplied URL is allowlisted / blocks internal
+      ranges (`169.254.169.254`, `localhost`, RFC1918).
+- **Baseline:** `<record — SSRF and upload scrubbing are common blind spots; confirm this run>`
+
+### 7. Auth tokens, sessions, cookies · **High**
+- [ ] Session/token secret is strong and **from env**, never a hardcoded default.
+- [ ] Cookies `HttpOnly` + `Secure` (prod) + `SameSite`; session invalidated on logout/deactivation.
+- **Baseline:** `<record>`
+
+### 8. Client-side / frontend leaks · **High**
+- [ ] No secret/private key in any client-exposed env var or the shipped bundle (only public values).
+- [ ] Source maps not deployed to prod (or access-restricted).
+- [ ] Security enforced **server-side**; client checks are UX only.
+- **Baseline:** `<record>`
+
+### 9. Dependencies & supply chain · **High**
+- [ ] No known-vulnerable deps; critical CVEs triaged.
+- [ ] Dependencies pinned / lockfile committed.
+- [ ] Automated alerts (Dependabot / Renovate / equivalent) enabled.
+- **Baseline:** `<record + tracking issue for any automation gap>`
+
+### 10. Config, logging & headers · **Medium**
+- [ ] No default credentials anywhere (`user:user`, `admin:admin`, `changeme`, …).
+- [ ] Secrets / tokens / PII never written to logs / error tracker / audit tables (sanitizer-covered).
+- [ ] DB connects as a least-privilege user.
+- **Baseline:** `<record>`
+
+### 11. Repo & CI/CD hygiene · **Medium**
+- [ ] Branch protection on the default branch; force-push disabled (or the local gate that stands in for it).
+- [ ] 2FA on the org; write access + installed Apps/OAuth grants reviewed.
+- [ ] Secret scanning in the commit/push gate.
+- **Baseline:** `<record — name where the gate lives if you have no hosted required check>`
+
+### 12. Container & image security · **High**
+- [ ] **Non-root USER** in every Dockerfile.
+- [ ] **Base image digest-pinned** (`@sha256:…`), not tag-only.
+- [ ] No secrets in `ARG` / `ENV` / `RUN` (use build-time secret mounts or runtime env).
+- [ ] Ignore file excludes `.git/`, `.env*`, keys (verify by listing the image, not trusting the file).
+- [ ] Internal services **not published** to the host; only the proxy faces `0.0.0.0`; no docker socket mount.
+- **Baseline:** `<record — mark N/A if you do not ship containers>`
+
+---
+
+## Part 3 — Tooling
+
+Wire the fast scanners into your commit/push gate so the audit is continuous, not a
+one-off. Swap in the tools your stack needs.
+
+| Tool | Purpose | Quick start |
+|------|---------|-------------|
+| **gitleaks** | Secrets in tree **and git history** | `gitleaks detect --source . --redact` |
+| **detect-secrets** | Pre-commit secret baseline | `detect-secrets scan > .secrets.baseline` |
+| **semgrep** | Static analysis (injection / authz / XSS) | `semgrep --config auto .` |
+| **trivy** | Vulns + secrets + IaC misconfig (also images) | `trivy fs --scanners vuln,secret,misconfig .` |
+| **`<dep auditor>`** | Dependency CVEs | `<npm/pnpm/pip/... audit>` |
+
+---
+
+## Part 4 — Findings report template
+
+Copy per run → `<docs/audits/YYYY-MM-security-audit/findings.md>` (date the folder per
+run). **Severity:** Critical = fix today · High = this week · Medium = schedule ·
+Low/Info = hygiene.
+
+```markdown
+# Security Audit — <project> — <YYYY-MM-DD> — auditor: <model A> + <model B>
+
+Scope: <repo @ commit/branch>   Public surface: <…>   Crown jewels: <…>
+
+## Summary
+Critical: N   High: N   Medium: N   Low: N
+
+## Findings
+| # | Severity | Category | Location (file:line) | Issue | Fix | Verified-by | Status |
+|---|----------|----------|----------------------|-------|-----|-------------|--------|
+| 1 | High | Container | <Dockerfile> | runs as root | add USER | both | Open |
+
+## Needs human verification
+- <agent-flagged item, why unconfirmed, which model disagreed>
+
+## Top 5 actions (by priority)
+1. …
+```
+
+---
+
+## Part 5 — Triage & the two-model run
+
+Fix by **exploitability × impact**, not top-to-bottom:
+
+1. **Secrets exposed** (§1, §8) → rotate immediately, then remove from code/history. Beats everything.
+2. **Auth/authz holes** (§2) → IDOR / missing tenant scope leaks other tenants' data with no tooling.
+3. **Injection** (§3) → SQL/command injection ≈ full data/host compromise.
+4. **Exposed surface & XSS** (§5, §4) → debug routes, `*` CORS, reflected XSS.
+5. **Everything else** (§6–§12) → validation, headers, deps, container, hygiene — defense-in-depth.
+
+**One confirmed Critical outweighs ten Lows.** And remember: this is the *application*
+layer — infrastructure is checked separately.
+
+**The two-model run** is the `security-audit` skill's job: model A and model B work
+this runbook independently and read-only, their findings are consolidated (disagreements
+→ "needs human verification", never dropped), then the *remediation plan* is hardened
+with a plan-review grill before any fix lands. This runbook is the *what*; the skill
+drives the *how*.

package/docs/agents/skills/orchestrate-wave.md

@@ -0,0 +1,13 @@
+<!-- setup-workflow: state=filled -->
+# Project layer — orchestrate-wave
+
+These stable sections are intentionally empty until the kit has proven its own landing recipe. The skill uses its generic fallback meanwhile.
+
+## §Setup
+## §Builder Commands
+## §Builder Hard Rules
+## §Integration Suites
+## §Verify Recipe
+## §Headless Login
+## §Landing
+

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

@@ -0,0 +1,18 @@
+<!-- setup-workflow: state=filled -->
+# Project layer — spec-self-critique
+
+The generic checklist owns the checks; `/retro` appends project-specific incidents below these stable anchors.
+
+## Point 1
+## Point 2
+## Point 3
+## Point 4
+## Point 5
+## Point 6
+## Point 7
+## Point 8
+## Point 9
+## Point 10
+## Point 11
+## Point 12
+

package/docs/agents/triage-labels.md

@@ -0,0 +1,10 @@
+<!-- setup-workflow: state=filled -->
+# Triage labels
+
+| Canonical role | Label in this repository | Meaning |
+|---|---|---|
+| `needs-info` | `needs-info` | Waiting for information from the reporter |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and safe for an AFK agent |
+
+The board Status field owns `Idea`, `Triaged`, `Spec`, `In Progress`, `Review`, and `Done`. Close rejected work instead of adding a separate `wontfix` workflow label.
+

package/docs/agents/wave-anchor-template.md

@@ -0,0 +1,88 @@
+# Wave Anchor Template
+
+The body of a wave-anchor issue. Model: this is the tracker that worked — **slimmed in**: the body is read by the agent in every slice session (`--json body` loads ALL of it, a `<details>` block collapses only in the browser), so it carries **navigation + decisions only**. The full PRD is posted as **issue comment #1** on the anchor (one click away for a human, loaded only on demand by an agent); the paste-ready handoff lives **in each slice leaf** (self-contained — no anchor↔leaf circular reference).
+**Maturity stages** — replace `<…>` placeholders, delete lines that don't apply:
+
+- **Stage 1 (candidate stub, bottom-up)** — filled by `board-to-waves`: header through the To-Do checklist. **No cluster/Wave** yet, Slice table stays empty (`⬜ via to-issues`).
+- **Stage 1p (program pre-state, top-down)** — filled by `to-waves` from a Program PRD: a named stub `Welle <N> — <Topic>` **from creation**, `wave-stub` label, **Wave + Phase stamped immediately**, native parent = the Program PRD, pre-generated Slice leaves as native children. Difference from Stage 1: named + stamped + PRD-parent instead of no cluster/Wave. Details below (§ Stage 1p).
+- **Stage 2 (matured + promoted)** — filled by `to-prd` (Decisions body) + `to-issues` (Slice table, links sub-issues, promotion sets `type:cluster` + Wave; the full PRD moves to **issue comment #1**, the To-Do checklist **collapses to its one-line summary**, per-slice handoffs land in the **leaf bodies**). A Stage-1p stub matures the same way here (the first program-stub promotion flips the PRD to the in-progress status, `roles.inProgress`).
+
+The **candidate stub** (Stage 1) has no cluster/Wave. On **`to-issues` promotion** (Stage 2) the anchor gets `type:cluster` + **Wave field = `<N>`** (monotone number, no `wave:*` label); `type:cluster` **replaces** the stub's previous `type:*` (e.g. `type:followup`) — exactly one `type:*` per issue, `board-sync.py promote` strips the old one; the **issue title becomes `Welle <N> — <Topic>`** (this is `board-sync.py promote`'s default behavior — `wave_title()` idempotently replaces any existing `Welle X —` prefix and strips a leading conventional-commit prefix; opt out with `--no-rename` — **the `promote` code is authoritative**), and the `Welle <N> — <Topic>` string also appears in the **body's top line**. Body **always** via `--body-file` (`gotchas_gh_body_file`). Numbering → [the `board-to-waves` SKILL.md](.claude/skills/board-to-waves/SKILL.md) "Wave numbering".
+
+---
+--- TEMPLATE STARTS HERE (everything above is guidance, don't copy it into the issue) ---
+
+<!-- wave-stub-source: <topic-slug> -->   <!-- Stage 1: stable idempotency marker, board-to-waves search-before-create; kebab-case slug of the gate outcome, never changed -->
+<!-- prd-source-id: <#> -->
+**plan_revision:** r<N>        <!-- Stage 2: stamped at promotion (before the first heading — the execute-ready checker requires it there, otherwise the post-promote audit denies the anchor) -->
+
+**Welle <N> — <Short description>.** Common thread: <Gate — the shared outcome that makes these issues a wave>.
+
+> 📍 **Execution tracker (as of <Date>).** This issue is the single source of truth for "where do we stand, what's next". Every sub-session anchors here.
+
+## Origin
+
+- **Source:** <board-to-waves | external-prd | raw-issue | plan | grill> *(provenance-neutral — the shape is the same regardless of origin; fill the following lines where they apply, delete where they don't)*
+- **Member issues:** #<a> #<b> #<c> … *(listed; linked via `to-issues` promotion, To-Do below)*
+- **Why together (firing criteria):** Gate=<Outcome> · <B1 code proximity / B2 type homogeneity / B3 dependency / B4 verify surface, where applicable>
+- **Size + risk:** ~<N> slices · Backend: <yes/no> · Model mix: <Model [Effort], e.g. Sonnet [medium] / Opus [high] / gpt-5.5 [medium]> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
+- **`grill-needed`:** <no> | <yes — this session> | <yes — own session (too big/fuzzy)>
+
+### To-Do (maturation: grill → to-prd → to-issues) — *(Stage 1/1p only; at promotion this whole checklist collapses to ONE line: `Maturation: grill <✓/–> · to-prd ✓ · to-issues ✓ (<Date>) — Wave gate + tracking open`)*
+- [ ] *(only if grill-needed=yes, own session)* dedicated `grill-with-docs` session — domain discovery
+- [ ] **`to-prd`** → write decisions/PRD body into this stub (Mode B); `spec-self-critique` runs automatically
+- [ ] **`to-issues`** → cut slices, **one sub-issue per slice** (reuse member issue / create new), fill the slice table + a **self-contained `## Handoff Start Command` in each slice leaf** (§5d); at ≥2 slices **promote** (sets `type:cluster` + Wave, moves the PRD to comment #1) + link **all** slice sub-issues natively (complete — slice set == sub-issue set)
+- [ ] **Wave gate** → before closing: reconcile any open `annahme-drift` propagation toward future waves/stubs (and, if part of a program, the Program PRD) — no unnoticed drift across the wave boundary (drift checkpoint, `wrapup` Step 5e.2)
+- [ ] **Track** → rollup is the status; anchor closes at 100%
+
+## Decisions — *(`to-prd` fills; for source `grill`: "Grill <Date>, locked")*
+
+| Item | Decision |
+|---|---|
+| <Issue/Topic> | <What exactly, in outcome language> |
+
+**Artifacts:** <CONTEXT.md terms / docs/adr/<nnnn>-…md, if produced during the grill>
+
+## Slices (vertical, 1 PR/session each) — *(`to-issues` fills)*
+
+Order (WSJF-lite): visible + low-risk first → logic/backend → cleanup. Dependencies force ordering.
+
+<!-- slice-table:start -->
+| # | Status | Slice | Sub-Issue | Gate | closes/refs |
+|---|---|---|---|---|---|
+| 1 | ⬜ | <Slice title> | #<sub> | <—/🧭/🔬/📐/📝> | <closes #x / refs #y> |
+<!-- slice-table:end -->
+
+Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, the model recommendation lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
+
+**Gate legend (retro):** `—` AFK build (`/tdd`) · 🧭 design grill (`grill-with-docs-codex`, ADR) · 🔬 verify spike (read-only fact question) · 📐 trade-off/research (read-only, below grill threshold) · 📝 review note (not a build slice). A gate slice (🧭/🔬/📐) sits **before** its dependent build slice (gate-before-build) and blocks it.
+
+**Closing conditions:** <Issue #x → after which slices> · <…> · Anchor #<self> → all slices merged + native sub-issues 100%.
+
+**Mid-wave discovered follow-ups** → schedule as a **slice row in this table** (an intermediate slice at the right sequence position, or at the end) + its own sub-issue (natively linked, counts in the rollup). **No** separate follow-ups table — that would be invisible in the slice view.
+
+**Parallel note:** true parallelism only with a worktree per strand. Slices that share files → serial.
+
+**Handoff + PRD live elsewhere:** the paste-ready start command sits **self-contained in each slice leaf** (`to-issues` §5d — scope + live-verify inline, no "see anchor" indirection), and the full grilled PRD is **issue comment #1** on this anchor (posted at promotion; rationale archive, not per-session reading). The anchor body itself ends here.
+
+## Stage 1p — Program pre-state (top-down, `to-waves`)
+
+`to-waves` creates a **Program PRD**'s wave stubs in exactly this shape — the defined pre-state above the feature route (instead of no cluster/Wave like Stage 1):
+
+- **Title** `Welle <N> — <Topic>` **from creation** (not only at promotion).
+- **Label** `wave-stub`; **Wave + Phase** stamped immediately (batched via `stamp-batch`).
+- **Native parent = the Program PRD** (3 levels: PRD → Stub → Slice leaves). The pre-generated Slice leaves hang as native children under the stub — for `to-prd` Mode B the **expected skeleton**, no child drift.
+- **Idempotency marker in the body** (top line, grep-able, never changed):
+
+```
+<!-- program-stub-source: <prd-source-id>/w<N> -->   <!-- stable identity: to-waves search-before-create + delta re-run/crash recovery -->
+<!-- program-revision: rN -->                          <!-- checked against the PRD's plan_revision; a stale stub blocks loudly; the delta re-run refreshes it -->
+```
+
+- **Handoff worktree line stays consumer-neutral** — the program pre-state is part of the published `to-waves` route, so **no** project-specific script path, but instead:
+
+```
+Worktree: your project's worktree helper, or `git worktree add`
+```
+
+Maturation: the stub matures at **wave promotion** like Stage 2 (`to-prd` Mode B into the stub + `to-issues`); unbuilt leaves/stubs of an abandoned program close in the order leaves → stubs → PRD (abandonment convention in the PROGRAM-PRD-FORMAT).

package/docs/conventions/spec-completeness.md

@@ -0,0 +1,23 @@
+<!-- setup-workflow: state=filled -->
+# Convention — Spec completeness before implementation
+
+## Self-Critique-Check
+
+**Trigger:** A spec states a concrete count, quantity, or `N of M` claim.
+
+**Check:** Is each number freshly derived from the source rather than estimated or recalled?
+
+**Korrektur:** Recount from code and replace the claim, or mark it explicitly as an implementation-time assumption.
+
+## Vertical-slice completeness
+
+Every user-facing slice is an outcome tracer, carries at least one acceptance criterion, names its estimated blast radius, and identifies seam ownership. Every prep slice names the omitted half and the later slice that closes it. `to-issues` must re-derive this readiness rather than trusting a pre-cut table.
+
+## Self-Critique-Check
+
+**Trigger:** A spec contains a wave/slice table or decomposes into multiple issues.
+
+**Check:** Are rows outcomes rather than layer names, and do enablers name the outcome wave that closes them?
+
+**Korrektur:** Reword or split layer-only rows and make every deferred half explicit.
+

package/docs/index.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>agent-workflow-kit</title>
+<link rel="canonical" href="methodology.html">
+<meta http-equiv="refresh" content="0; url=methodology.html">
+<style>
+  :root {
+    --page-bg: #F5F1E8;
+    --surface: #FAFAF7;
+    --ink: #1F2532;
+    --muted: #5B6579;
+    --accent: #B5533A;
+  }
+  html, body { height: 100%; margin: 0; }
+  body {
+    background: var(--page-bg);
+    color: var(--ink);
+    font: 16px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif;
+    display: grid;
+    place-items: center;
+    text-align: center;
+    padding: 2rem;
+  }
+  .card {
+    background: var(--surface);
+    border: 1px solid rgba(31, 37, 50, 0.08);
+    border-radius: 14px;
+    padding: 2.5rem 2.75rem;
+    max-width: 30rem;
+    box-shadow: 0 1px 3px rgba(31, 37, 50, 0.06);
+  }
+  h1 { font-size: 1.4rem; margin: 0 0 0.5rem; }
+  p { color: var(--muted); margin: 0 0 1.5rem; }
+  a.go {
+    display: inline-block;
+    background: var(--accent);
+    color: #fff;
+    text-decoration: none;
+    font-weight: 600;
+    padding: 0.7rem 1.4rem;
+    border-radius: 9px;
+  }
+  a.go:hover { filter: brightness(1.05); }
+</style>
+</head>
+<body>
+  <main class="card">
+    <h1>agent-workflow-kit</h1>
+    <p>Redirecting to the methodology&hellip;</p>
+    <a class="go" href="methodology.html">Read the methodology &rarr;</a>
+  </main>
+</body>
+</html>