@ikon85/agent-workflow-kit 0.33.0 → 0.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/.agents/skills/ask-matt/SKILL.md +4 -3
  2. package/.agents/skills/audit-skills/SKILL.md +6 -0
  3. package/.agents/skills/board-to-waves/SKILL.md +6 -2
  4. package/.agents/skills/code-review/SKILL.md +6 -0
  5. package/.agents/skills/codebase-design/DESIGN-IT-TWICE.md +11 -1
  6. package/.agents/skills/codex-adapter-sync/SKILL.md +23 -19
  7. package/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +6 -0
  8. package/.agents/skills/improve-codebase-architecture/SKILL.md +10 -1
  9. package/.agents/skills/kit-release/SKILL.md +29 -4
  10. package/.agents/skills/kit-update/SKILL.md +13 -0
  11. package/.agents/skills/orchestrate-wave/SKILL.md +1 -1
  12. package/.agents/skills/orchestrate-wave/references/dispatch-subagents.md +23 -11
  13. package/.agents/skills/orchestrate-wave/references/dispatch-workflow.md +8 -0
  14. package/.agents/skills/research/SKILL.md +6 -0
  15. package/.agents/skills/scale-check/SKILL.md +9 -7
  16. package/.agents/skills/setup-workflow/SKILL.md +47 -1
  17. package/.agents/skills/setup-workflow/board-sync.md +7 -2
  18. package/.agents/skills/setup-workflow/workflow-overview.md +1 -2
  19. package/.agents/skills/to-issues/SKILL.md +66 -8
  20. package/.agents/skills/to-waves/SKILL.md +24 -12
  21. package/.claude/skills/ask-matt/SKILL.md +4 -3
  22. package/.claude/skills/audit-skills/SKILL.md +6 -0
  23. package/.claude/skills/board-to-waves/SKILL.md +6 -2
  24. package/.claude/skills/code-review/SKILL.md +6 -0
  25. package/.claude/skills/codebase-design/DESIGN-IT-TWICE.md +8 -0
  26. package/.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +6 -0
  27. package/.claude/skills/improve-codebase-architecture/SKILL.md +6 -0
  28. package/.claude/skills/kit-release/SKILL.md +29 -4
  29. package/.claude/skills/kit-update/SKILL.md +13 -0
  30. package/.claude/skills/orchestrate-wave/SKILL.md +1 -1
  31. package/.claude/skills/orchestrate-wave/references/dispatch-subagents.md +23 -11
  32. package/.claude/skills/orchestrate-wave/references/dispatch-workflow.md +8 -0
  33. package/.claude/skills/research/SKILL.md +6 -0
  34. package/.claude/skills/scale-check/SKILL.md +9 -7
  35. package/.claude/skills/setup-workflow/SKILL.md +47 -1
  36. package/.claude/skills/setup-workflow/board-sync.md +7 -2
  37. package/.claude/skills/setup-workflow/workflow-overview.md +1 -2
  38. package/.claude/skills/to-issues/SKILL.md +66 -8
  39. package/.claude/skills/to-waves/SKILL.md +24 -12
  40. package/README.md +89 -13
  41. package/agent-workflow-kit.package.json +204 -44
  42. package/docs/adr/0004-release-intent-is-a-version-tag.md +42 -0
  43. package/docs/adr/0005-to-issues-is-the-planning-facade.md +42 -0
  44. package/docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md +91 -0
  45. package/docs/agents/skills/local-ci.md +89 -0
  46. package/docs/agents/wave-anchor-template.md +2 -2
  47. package/docs/methodology.html +1 -1
  48. package/docs/methodology.svg +1 -1
  49. package/docs/workflow.html +2 -2
  50. package/docs/workflow.png +0 -0
  51. package/package.json +1 -1
  52. package/scripts/codex-exec.sh +47 -8
  53. package/scripts/codex-exec.test.mjs +56 -0
  54. package/scripts/kit-release.test.mjs +178 -0
  55. package/scripts/release-state.mjs +35 -5
  56. package/scripts/release-state.test.mjs +122 -5
  57. package/scripts/test_codex_adapter_sync_contract.py +30 -15
  58. package/scripts/test_orchestrate_wave_contract.py +73 -0
  59. package/scripts/test_program_planning_contract.py +70 -0
  60. package/scripts/test_skill_portability_lint.py +54 -0
  61. package/src/cli.mjs +109 -2
  62. package/src/commands/init.mjs +17 -1
  63. package/src/commands/routing-policy-update.mjs +204 -0
  64. package/src/commands/update.mjs +22 -0
  65. package/src/lib/agentSurfaceRegistry.mjs +60 -0
  66. package/src/lib/bundle.mjs +24 -0
  67. package/src/lib/capabilityMatrix.mjs +85 -0
  68. package/src/lib/dispatchReceipt.mjs +162 -0
  69. package/src/lib/frontendWorkloads.mjs +170 -0
  70. package/src/lib/routeDispatcher.mjs +158 -0
  71. package/src/lib/routingAccessGraph.mjs +105 -0
  72. package/src/lib/routingAdapters/claude.mjs +62 -0
  73. package/src/lib/routingAdapters/codex.mjs +136 -0
  74. package/src/lib/routingCatalog.mjs +123 -0
  75. package/src/lib/routingEvidenceCache.mjs +222 -0
  76. package/src/lib/routingIntent.mjs +93 -0
  77. package/src/lib/routingPolicy.mjs +67 -0
  78. package/src/lib/routingProfile.mjs +334 -0
  79. package/src/lib/routingResolver.mjs +176 -0
  80. package/src/lib/routingSources/artificialAnalysis.mjs +129 -0
  81. package/src/lib/routingSources/benchlm.mjs +151 -0
  82. package/src/lib/routingSources/codeArena.mjs +162 -0
  83. package/src/lib/routingSources/deepswe.mjs +106 -0
  84. package/src/lib/routingSources/openhands.mjs +102 -0
  85. package/src/lib/routingSources/openhandsFrontend.mjs +135 -0
@@ -16,7 +16,7 @@ How the board-managed workflow skills (`to-prd`, `to-issues`, `board-to-waves`,
16
16
  | Cluster | text | optional | thematic cluster tag |
17
17
  | Spec-Path | text | optional | link from an issue to its spec doc |
18
18
  | Plan-Path | text | optional | link from an issue to its plan doc |
19
- | Phase | single-select | optional | groups waves into phases for the Program route (`to-waves`/`validate-graph`) — only needed if this project uses it |
19
+ | Phase | single-select | optional | groups waves into phases for the Program route (`to-issues` Program mode / internal graph validation) — only needed if this project uses it |
20
20
 
21
21
  ## Machine profile (SSOT) — `scripts/board_config.py` reads this
22
22
 
@@ -112,7 +112,12 @@ their titles unchanged; set it once to match your board's language.
112
112
 
113
113
  ## Optional: the Program route (Phase field + saved Views)
114
114
 
115
- 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.
115
+ Skip this section entirely unless this project actually plans to use the Program
116
+ route (`scale-check` → `to-issues` with explicit Program identity → internal
117
+ graph validation) — `fields.phase` / `labels.programType` are never
118
+ auto-discovered or auto-created (a Phase field's option set is plan-specific,
119
+ not something `/setup-workflow` can guess), and a profile without them keeps
120
+ loading unchanged.
116
121
 
117
122
  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).
118
123
  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`.
@@ -8,8 +8,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
8
8
  - **A new build whose size is unclear** (a new app, a big cross-cutting feature, an unclear where-to-start): run `scale-check` — a short plain-language dialog that routes it to a program, a feature, a single slice, or a bug, and hands back a paste-ready start prompt.
9
9
  - **New capability or unclear change:** start with `grill-with-docs` when the domain language or decisions need sharpening, then publish the agreed shape with `to-prd`.
10
10
  - **A slice hinges on an unresolved fact or trade-off before it can be built:** clear it first — a binary yes/no question against real code/runtime/platform with `verify-spike`, a bounded "which option" choice with `decision-gate`.
11
- - **Existing plan, PRD, or ready issue:** use `to-issues` to split it into independently buildable tracer-bullet slices.
12
- - **A Program-PRD with a wave plan:** use `to-waves` to unfold it into named wave stubs + slice leaves on the board, after a chat preview gate that shows the whole plan before any write.
11
+ - **Existing plan, PRD, or ready issue:** use `to-issues`, the single Planning facade. Explicit Feature identity selects tracer-bullet decomposition; explicit Program identity selects the internal graph path and its complete preview before any write.
13
12
  - **A backlog of open issues needs clustering into themed waves:** use `board-to-waves`.
14
13
  - **A whole wave anchor (file-disjoint slices, specs already locked) to build, verify and land end-to-end — often AFK:** use `orchestrate-wave` — it dispatches implementers per slice, integrates serially, verifies centrally, and lands. (A single slice just goes to `implement`.)
15
14
  - **Bugs or requests piling up that you didn't create:** use `triage` to move them into agent-ready issues.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: to-issues
3
- description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
3
+ description: Break a Feature or Program plan, spec, or PRD into independently-grabbable issues on the project issue tracker. This is the single public Planning facade: explicit Feature identity uses tracer-bullet decomposition; explicit Program identity delegates to the internal graph engine.
4
4
  ---
5
5
 
6
6
  # To Issues
@@ -23,6 +23,39 @@ node scripts/readiness.mjs check --skill to-issues --json
23
23
  - `managedBoard=not-applicable`: `STOP` and report that `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
24
24
  <!-- readiness:required-preflight:end -->
25
25
 
26
+ ## Planning facade — select by explicit identity only
27
+
28
+ `to-issues` is the **single public Planning facade**. After the readiness
29
+ preflight and before any remote write, classify the source from its explicit PRD
30
+ identity:
31
+
32
+ - **Feature identity → `planning-mode=feature`.** The body carries
33
+ `<!-- prd: awaiting-decomposition -->` and its one `type:*` label is not the
34
+ configured Program type. Run the existing Feature decomposition path below:
35
+ one slice stays ATOMIC; two or more slices PROMOTE to a wave anchor.
36
+ - **Program identity → `planning-mode=program`.** The body carries
37
+ `<!-- prd: program -->` and its one `type:*` label is the board profile's
38
+ `labels.programType` value. Preserve the source and delegate to the internal
39
+ `to-waves` graph engine. That engine still validates the graph, shows the
40
+ complete Program preview, waits for the single explicit approval, and performs
41
+ zero remote writes before approval.
42
+
43
+ **Missing or contradictory identity is a hard stop before a remote write.**
44
+ Missing means neither marker is present, including a raw issue, file bundle, or
45
+ external PRD without an explicit identity. Contradictory means both markers are
46
+ present, the marker disagrees with the `type:*` label, or the source carries
47
+ multiple type labels. Report the observed markers and type labels, then ask the
48
+ user to establish exactly one identity. A cold-entry source may receive a
49
+ Feature or Program identity only after that explicit choice; rerun this
50
+ classification before any normalization or publication.
51
+
52
+ **Size, prose, and model judgment never select the mode.** A `## Wellenplan`
53
+ heading, estimated file count, wording such as “large program”, or an agent's
54
+ inference may validate or contradict an already explicit identity, but none may
55
+ create or switch it. A Program identity without the graph grammar is a blocking
56
+ contract error, not a fallback to Feature. A Feature identity with Program-only
57
+ graph grammar is likewise contradictory and stops.
58
+
26
59
  ## Process
27
60
 
28
61
  ### 1. Gather context
@@ -110,7 +143,8 @@ Ask the user:
110
143
 
111
144
  Iterate until the user approves the breakdown.
112
145
 
113
- **Program batch handoff.** When `to-waves` invokes this skill for a Stufe-1p stub,
146
+ **Program batch handoff.** When the internal Program graph engine invokes this
147
+ skill for a Stufe-1p stub,
114
148
  the complete Program preview has already shown and approved every wave's slice
115
149
  contract. Reuse that approval when this pass preserves the approved cut: do not
116
150
  pause again merely because the internal pipeline crossed a skill boundary. Run
@@ -122,9 +156,21 @@ newly discovered gate invalidates the inherited approval and returns to §4.
122
156
 
123
157
  **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.
124
158
 
125
- The canonical source is a **Draft-PRD** issue from `to-prd` (carries `plan_revision`, `<!-- prd: awaiting-decomposition -->`, exactly one `type:*` + one `priority:*`, **no** `type:cluster`, and no Wave **unless** the discriminator's `wave-stub` exception applies — a Program-stub's per-wave-start content pass writes this same shape into an already Wave-stamped stub, `to-prd` §2). But `to-issues` is **provenance-independent**: it re-derives readiness from the **artefact** (§3b), never from which tool produced it.
126
-
127
- **Cold entry on an already-existing issue.** The source can also be a **raw issue**, an **external PRD embedded in an issue**, or a **mechanical file bundle** — without the `to-prd` markers. Then a **cold-entry preflight applies before anything is mutated:**
159
+ The canonical Feature source is a **Draft-PRD** issue from `to-prd` (carries
160
+ `plan_revision`, `<!-- prd: awaiting-decomposition -->`, exactly one `type:*` +
161
+ one `priority:*`, **no** `type:cluster`, and no Wave **unless** the
162
+ discriminator's `wave-stub` exception applies — a Program-stub's per-wave-start
163
+ content pass writes this same shape into an already Wave-stamped stub, `to-prd`
164
+ §2). The facade is provenance-independent but not identity-optional: it
165
+ re-derives readiness from the **artefact** (§3b), never from which tool produced
166
+ it, only after the explicit identity classification above selected the mode.
167
+
168
+ **Cold entry on an already-existing issue.** The source can also be a **raw
169
+ issue**, an **external PRD embedded in an issue**, or a **mechanical file
170
+ bundle** — without the `to-prd` markers. That absence first triggers the
171
+ facade's identity hard stop above. Only after the user explicitly establishes
172
+ Feature identity may this **cold-entry preflight apply before anything is
173
+ mutated:**
128
174
  - **Hard-stop per the discriminator above** — `type:cluster` always; Wave only when the issue is **not** a `wave-stub` (the exception is already an intended promote target — `promote` reuses its pre-stamped Wave number, §5a below).
129
175
  - **Normalize labels** (mirroring `to-prd`'s normalization): exactly **one `type:*` + one `priority:*`**; `needs-info`/`ready-for-agent` **stripped** until the final bucket assignment (§5c).
130
176
  - **Synthesize missing `to-prd` markers in place** (never assume them): `plan_revision r1` at the body head, render the Tier-2 anchor body from the template. Surface `source`/`synthesized` in the §7 audit.
@@ -389,7 +435,8 @@ Reference the blocking ticket(s), or "None - can start immediately".
389
435
  <!-- mirror-xform:start codex-escalation -->
390
436
  ```
391
437
  Welle <N> · Slice <X> (<closes #x | refs #<prd#>, Parent #<prd#>>). Read #<prd#> for decisions.
392
- Start skill: 🧭 Design Grill → /grill-with-docs-codex · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /implement · HITL → /grill-me → /implement. Recommended model: <Model [Effort]>.
438
+ Start skill: 🧭 Design Grill → /grill-with-docs-codex · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /implement · HITL → /grill-me → /implement.
439
+ Routing intent: `routing-intent: <judgment | development | mechanical>` · `reasoning-intent: <deep | balanced | light>`. The dispatching surface resolves the current executable route; never persist that provider route here.
393
440
  Worktree: your project's worktree helper, or `git worktree add`
394
441
  Scope (<N> files) — REQUIRED FIELD, blast-radius estimate at cut time; the build session checks it against its own recon findings, >2x deviation → STOP:
395
442
  - <concrete file + change>
@@ -397,6 +444,12 @@ Live-verify: <user outcome, DB/UI value with comparison>
397
444
  PR: <closes #x | Part of #<prd#> — NEVER closes on the anchor>.
398
445
  ```
399
446
  <!-- mirror-xform:end -->
447
+
448
+ At execution time, consume that provider-neutral intent only through
449
+ `src/lib/routeDispatcher.mjs` and its shared spawn guard. The active Claude or
450
+ Codex adapter must produce Dispatch receipt v2 with requested/applied route,
451
+ model/effort enforcement, precedence, and catalog/access/policy revisions
452
+ before an AFK subagent starts; the durable issue never claims that proof.
400
453
  </issue-template>
401
454
 
402
455
  **Blast-radius reconciliation (build session):** the stamped `**Blast-Radius:**` is the estimate *at the cut* — the build session compares it against its own recon finding. A real finding **> 2× the estimate → STOP + report** (re-cut at the anchor), do NOT keep building silently.
@@ -430,12 +483,17 @@ It asserts, for the rooted local graph:
430
483
 
431
484
  If the source was a `wave-stub` stub, briefly confirm the label is gone (the publish mechanic strips it automatically — see §5): `gh issue view <anchor-or-leaf#> --json labels -q '.labels[].name'` shows **no** `wave-stub`. (Not part of `execute-ready-check.py` — its own quick check.)
432
485
 
433
- `--mode audit` is **non-blocking** — a mismatch is a **loud warning** here; the **hard block** is `.claude/hooks/drift-guard.py` at handoff-creation. Emit a visible audit two-liner:
486
+ `--mode audit` is **non-blocking** — a mismatch is a **loud warning** here; the
487
+ **hard block** is `.claude/hooks/drift-guard.py` at handoff-creation. Emit a
488
+ visible audit that names the selected facade mode:
434
489
 
435
490
  ```
436
- to-issues: anchor=#<X> mode=<promote|atomic> slices=<n> rev <old>→<new>
491
+ to-issues: planning-mode=feature anchor=#<X> mode=<promote|atomic> slices=<n> rev <old>→<new>
437
492
  source=<draft-prd|raw-issue|external-prd|bundle> synthesized=<marker-list | none>
438
493
  AFK=[#a #b] HITL=[#c] · drift=<none | …> shape=<ok | warn:…>
439
494
  ```
440
495
 
496
+ The Program graph engine emits `planning-mode=program` in its own counted audit
497
+ after the complete preview gate; the facade relays that audit unchanged.
498
+
441
499
  Do NOT close or modify any parent issue beyond the promote stamp.
@@ -1,17 +1,25 @@
1
1
  ---
2
2
  name: to-waves
3
3
  disable-model-invocation: true
4
- description: "Turn a Program-PRD's wave plan into fully planned, execute-ready wave anchors and slice leaves after one complete chat preview. Validates the graph, publishes every wave, runs the to-prd/spec-self-critique/to-issues maturity contract for each wave, models unresolved work as explicit gates, and audits counted readiness. Idempotent and crash-recoverable. Use on a Program-PRD over several waves. NOT for a single-wave feature (to-issues) or backlog clustering (board-to-waves)."
4
+ description: "Internal Program graph engine behind the public to-issues Planning facade. Turns an explicitly identified Program-PRD into execute-ready wave anchors and slice leaves after one complete chat preview. Kept as a disabled compatibility entrypoint for existing explicit invocations; normal routing always selects to-issues."
5
5
  ---
6
6
 
7
- # to-waves — Unfold a Program-PRD's wave plan onto the board
7
+ # to-waves — Internal Program graph engine
8
+
9
+ This skill is an **Internal Program graph engine**, selected by `to-issues` only
10
+ when the source carries explicit, coherent Program identity. It is not a second
11
+ public Planning route. The disabled `/to-waves` invocation remains only as a
12
+ compatibility entrypoint for existing callers and tests; it applies this same
13
+ contract and should direct future normal use to `/to-issues`.
8
14
 
9
15
  Takes a **Program-PRD** — the native Sub-Issue anchor over a multi-wave program
10
16
  (Programm → Phase → Welle → Slice) — and turns its `## Wellenplan` chapter into
11
17
  **fully planned wave anchors + slice leaves** on the board. Pipeline position:
12
- `scale-check → grill → to-prd (program mode) → to-waves`, with the per-wave
13
- `to-prd → spec-self-critique → to-issues` maturity pass owned inside this run.
14
- The **grill and to-prd sit upstream**; to-waves runs once the Program-PRD exists.
18
+ `scale-check → grill → to-prd (program mode) → to-issues`, with this internal
19
+ engine owning the per-wave `to-prd → spec-self-critique → to-issues` maturity
20
+ pass inside this run.
21
+ The **grill and to-prd sit upstream**; the facade dispatches here once the
22
+ Program-PRD exists and its identity is coherent.
15
23
  It **never invents structure** — it only unfolds what the plan already decided.
16
24
 
17
25
  <!-- readiness:required-preflight:start -->
@@ -24,8 +32,8 @@ node scripts/readiness.mjs check --skill to-waves --json
24
32
  ```
25
33
 
26
34
  - `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
27
- - `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-waves`.** Do not fall back to bare tracker or board commands.
28
- - `managedBoard=not-applicable`: `STOP` and report that `/to-waves` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
35
+ - `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-issues`.** Do not fall back to bare tracker or board commands.
36
+ - `managedBoard=not-applicable`: `STOP` and report that Program planning through `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
29
37
  <!-- readiness:required-preflight:end -->
30
38
 
31
39
  Board constants (project node, field/status IDs) + helpers live **consumer-side**:
@@ -43,10 +51,14 @@ is the parser.
43
51
 
44
52
  ## 1. Input — a Program-PRD
45
53
 
46
- The target is a Program-PRD issue: it carries the `<!-- prd: program -->` marker (or
47
- the program-type label) and a `## Wellenplan` table. Passed in / from context. If the
48
- issue is a plain feature-PRD or a Welle-Anchor, stop a feature-PRD is `to-issues`'
49
- target, an anchor is already a single wave.
54
+ The target is a Program-PRD issue: it carries both the
55
+ `<!-- prd: program -->` marker and the configured Program-type label, plus a
56
+ `## Wellenplan` table. Passed in from the facade or explicit compatibility
57
+ invocation. If either identity half is missing, they disagree, or Feature
58
+ identity is also present, stop before preview or write and return to
59
+ `to-issues`; never infer Program mode from the table, prose, size, or model
60
+ judgment. A plain Feature-PRD remains on the facade's Feature path; a
61
+ Wave-Anchor is already a single wave.
50
62
 
51
63
  ## 2. Parse + validate — the graph preflight
52
64
 
@@ -316,7 +328,7 @@ python3 scripts/board-sync.py program-sync <prd#>
316
328
  ## Audit block (visible output)
317
329
 
318
330
  ```
319
- to-waves: prd=#<n> preview=<approved|rejected>
331
+ to-issues: planning-mode=program engine=to-waves prd=#<n> preview=<approved|rejected>
320
332
  created=<stubs X von Y, leaves X von Y> adopted=<#a #b … | none>
321
333
  stamped=<N von M Wave/Phase> phase=<stamped | skipped (profile lacks fields.phase)>
322
334
  matured=<X von Y> execute-ready=<X von Y Wellen ausführungsreif>
package/README.md CHANGED
@@ -24,8 +24,10 @@ changes.
24
24
  Maintainers prepare releases with `/kit-release`. It derives the shipped delta
25
25
  from a fresh manifest, recommends Semver, applies only the confirmed target,
26
26
  regenerates the checked-in manifest, and runs the full test and pack gates.
27
- Landing remains owned by `/wrapup`; publishing the matching npm package and
28
- GitHub release happens only through the configured post-merge release flow.
27
+ Landing remains owned by `/wrapup` and only integrates the prepared version.
28
+ After a separate publication confirmation, a matching annotated `v<version>`
29
+ tag on canonical `main` starts the trusted publish flow. Manual dispatch
30
+ requires an explicit existing tag and only reconciles an incomplete release.
29
31
 
30
32
  These are the skills, helper scripts, and conventions one team actually uses to
31
33
  take work from a vague idea to a merged, verified PR with [Claude Code] and
@@ -85,9 +87,11 @@ into the *same shaped artefact*: a Draft-PRD that, once sliced, becomes either o
85
87
  atomic issue or a wave anchor with child slices. What counts downstream is the
86
88
  **shape of the artefact, never where it came from** — so each step can be entered
87
89
  cold and *extracts or synthesizes* what's missing instead of assuming an earlier
88
- step ran. The routing key is just *"is there an issue yet?"*: a loose artefact
90
+ step ran. The entry key is just *"is there an issue yet?"*: a loose artefact
89
91
  (no issue) enters at `to-prd`; an existing issue or file-bundle enters at
90
- `to-issues` directly.
92
+ `to-issues` directly. Inside that facade, the explicit PRD identity — Feature or
93
+ Program — is the only mode selector; a cold source must establish one before a
94
+ remote write.
91
95
 
92
96
  - **Grill as deep as the work deserves — it's optional.** `grill-me` /
93
97
  `grill-with-docs` interrogate the intent (and your domain docs) until the real
@@ -98,13 +102,15 @@ step ran. The routing key is just *"is there an issue yet?"*: a loose artefact
98
102
  Draft-PRD issue, *extracting* the template sections from what already exists. A
99
103
  required section it genuinely can't derive becomes an honest **Open points**
100
104
  block, never a silent "looks complete" placeholder.
101
- - **`to-issues`** slices the PRD into tracer-bullet verticals and picks the shape:
102
- **1 slice one atomic issue** the PR closes; **≥2 slices a wave anchor** with
103
- linked child slices. It re-derives readiness from the artefact itself, so it works
104
- just as well started straight on a raw issue or file-bundle — any unresolved
105
- *Open points* travel through as a build-blocking gate (the profile's
106
- configurable `vorBau` heading, see [Configuration](#configuration)) that never
107
- vanishes silently.
105
+ - **`to-issues`** is the single public Planning facade. Explicit Feature
106
+ identity selects tracer-bullet decomposition and picks the shape: **1 slice
107
+ one atomic issue** the PR closes; **≥2 slices a wave anchor** with linked
108
+ child slices. Explicit Program identity selects the existing internal graph
109
+ engine and preserves its complete chat preview before any board write.
110
+ Missing or contradictory identity stops before a write; size, prose, and model
111
+ judgment never select the mode. Any unresolved *Open points* travel through as
112
+ a build-blocking gate (the profile's configurable `vorBau` heading, see
113
+ [Configuration](#configuration)) that never vanishes silently.
108
114
  - **`board-to-waves`** clusters an existing backlog into themed campaigns when you
109
115
  need to *find* the next wave rather than start fresh.
110
116
  - **`triage`** keeps the inbox sane with a consistent label vocabulary.
@@ -211,7 +217,8 @@ hands a well-defined object to the level below:
211
217
 
212
218
  Two roads lead to the same wave. **Top-down:** `scale-check` names the size in
213
219
  a few plain questions; a big undertaking gets grilled once into a Program PRD
214
- with a wave plan, and `to-waves` unfolds it into named waves after you approve
220
+ with a wave plan, and `to-issues` selects its internal Program graph path from
221
+ that explicit identity. It unfolds the plan into named waves after you approve
215
222
  a full preview in chat — zero board writes until you say yes. **Bottom-up:**
216
223
  `board-to-waves` clusters loose issues into a wave candidate, which earns a
217
224
  real number only when you promote it. Either road lands in the *identical*
@@ -222,7 +229,7 @@ When the slices are file-disjoint and their specs are locked, **`orchestrate-wav
222
229
  lands the whole anchor end-to-end — often AFK: it dispatches an implementer per
223
230
  slice into its own worktree, integrates serially, verifies centrally, and lands
224
231
  the wave. It's the execute-and-land node of the wave ladder (`scale-check` →
225
- `to-waves` / `board-to-waves` → `orchestrate-wave`); a single slice still just
232
+ `to-issues` / `board-to-waves` → `orchestrate-wave`); a single slice still just
226
233
  goes to `implement`.
227
234
 
228
235
  ![The Program-to-Phase-to-Wave-to-Slice altitude ladder, and the two routes — a planned top-down Program route and a grown bottom-up board route — that both fund the same Wave-and-Slices build spine.](docs/methodology.svg)
@@ -380,6 +387,75 @@ the old way. Decision record:
380
387
 
381
388
  ## Release notes
382
389
 
390
+ ### 0.34.1
391
+
392
+ - changed: `.agents/skills/kit-release/SKILL.md`
393
+ - changed: `.claude/skills/kit-release/SKILL.md`
394
+ - changed: `scripts/release-state.mjs`
395
+
396
+ ### 0.34.0
397
+
398
+ - added: `src/commands/routing-policy-update.mjs`
399
+ - added: `src/lib/agentSurfaceRegistry.mjs`
400
+ - added: `src/lib/dispatchReceipt.mjs`
401
+ - added: `src/lib/frontendWorkloads.mjs`
402
+ - added: `src/lib/routeDispatcher.mjs`
403
+ - added: `src/lib/routingAccessGraph.mjs`
404
+ - added: `src/lib/routingAdapters/claude.mjs`
405
+ - added: `src/lib/routingAdapters/codex.mjs`
406
+ - added: `src/lib/routingCatalog.mjs`
407
+ - added: `src/lib/routingEvidenceCache.mjs`
408
+ - added: `src/lib/routingIntent.mjs`
409
+ - added: `src/lib/routingPolicy.mjs`
410
+ - added: `src/lib/routingProfile.mjs`
411
+ - added: `src/lib/routingResolver.mjs`
412
+ - added: `src/lib/routingSources/artificialAnalysis.mjs`
413
+ - added: `src/lib/routingSources/benchlm.mjs`
414
+ - added: `src/lib/routingSources/codeArena.mjs`
415
+ - added: `src/lib/routingSources/deepswe.mjs`
416
+ - added: `src/lib/routingSources/openhands.mjs`
417
+ - added: `src/lib/routingSources/openhandsFrontend.mjs`
418
+ - changed: `.agents/skills/ask-matt/SKILL.md`
419
+ - changed: `.agents/skills/audit-skills/SKILL.md`
420
+ - changed: `.agents/skills/board-to-waves/SKILL.md`
421
+ - changed: `.agents/skills/code-review/SKILL.md`
422
+ - changed: `.agents/skills/codebase-design/DESIGN-IT-TWICE.md`
423
+ - changed: `.agents/skills/codex-adapter-sync/SKILL.md`
424
+ - changed: `.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md`
425
+ - changed: `.agents/skills/improve-codebase-architecture/SKILL.md`
426
+ - changed: `.agents/skills/kit-update/SKILL.md`
427
+ - changed: `.agents/skills/orchestrate-wave/SKILL.md`
428
+ - changed: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`
429
+ - changed: `.agents/skills/orchestrate-wave/references/dispatch-workflow.md`
430
+ - changed: `.agents/skills/research/SKILL.md`
431
+ - changed: `.agents/skills/scale-check/SKILL.md`
432
+ - changed: `.agents/skills/setup-workflow/SKILL.md`
433
+ - changed: `.agents/skills/setup-workflow/board-sync.md`
434
+ - changed: `.agents/skills/setup-workflow/workflow-overview.md`
435
+ - changed: `.agents/skills/to-issues/SKILL.md`
436
+ - changed: `.agents/skills/to-waves/SKILL.md`
437
+ - changed: `.claude/skills/ask-matt/SKILL.md`
438
+ - changed: `.claude/skills/audit-skills/SKILL.md`
439
+ - changed: `.claude/skills/board-to-waves/SKILL.md`
440
+ - changed: `.claude/skills/code-review/SKILL.md`
441
+ - changed: `.claude/skills/codebase-design/DESIGN-IT-TWICE.md`
442
+ - changed: `.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md`
443
+ - changed: `.claude/skills/improve-codebase-architecture/SKILL.md`
444
+ - changed: `.claude/skills/kit-update/SKILL.md`
445
+ - changed: `.claude/skills/orchestrate-wave/SKILL.md`
446
+ - changed: `.claude/skills/orchestrate-wave/references/dispatch-subagents.md`
447
+ - changed: `.claude/skills/orchestrate-wave/references/dispatch-workflow.md`
448
+ - changed: `.claude/skills/research/SKILL.md`
449
+ - changed: `.claude/skills/scale-check/SKILL.md`
450
+ - changed: `.claude/skills/setup-workflow/SKILL.md`
451
+ - changed: `.claude/skills/setup-workflow/board-sync.md`
452
+ - changed: `.claude/skills/setup-workflow/workflow-overview.md`
453
+ - changed: `.claude/skills/to-issues/SKILL.md`
454
+ - changed: `.claude/skills/to-waves/SKILL.md`
455
+ - changed: `docs/agents/wave-anchor-template.md`
456
+ - changed: `scripts/codex-exec.sh`
457
+ - changed: `src/lib/capabilityMatrix.mjs`
458
+
383
459
  ### 0.33.0
384
460
 
385
461
  - added: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`