From 440b15447533e465de2bda6978995763ac1038f0 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:57:59 -0400 Subject: [PATCH 1/2] fix(planning): align wayfind label taxonomy with colon-space axis grammar The typed decision-item labels become `wayfind: ` (colon-space), matching the axis grammar label-as-code owners enforce (github-iac's LabelsGrammarTests rejects bare-colon axis names), so the taxonomy can be declared verbatim with no grammar exception. Verified against the wild: colon-space is one of the two dominant OSS axis styles (React, Angular, Flutter); bare-colon is the rare one. `work-map` and `needs-human` stay flat and grammar-exempt. Frontier jq, bootstrap presence check, docs, and evals updated; existing maps charted under old names need a one-time label rename. Co-Authored-By: Claude Fable 5 --- plugins/planning/.claude-plugin/plugin.json | 2 +- plugins/planning/CHANGELOG.md | 11 +++++++++++ plugins/planning/skills/wayfind/SKILL.md | 12 ++++++------ .../planning/skills/wayfind/context/map-anatomy.md | 4 ++-- .../skills/wayfind/context/tracker-mechanics.md | 11 ++++++----- plugins/planning/skills/wayfind/evals/evals.json | 4 ++-- 6 files changed, 28 insertions(+), 16 deletions(-) diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index 8726c3137c..de614bad03 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.11.1", + "version": "0.11.2", "description": "Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, actively maintain resolved domain language, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate.", "author": { "name": "Melodic Software", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index eaaf2ca97d..4fed7b3445 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,17 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.11.2] + +### Changed + +- **`/planning:wayfind` label taxonomy follows the colon-space axis grammar**: the typed decision-item + labels are now `wayfind: research|interview|design|prototype|task` (previously `wayfind:research` + etc.), so label-as-code owners with a `prefix: value` naming grammar can declare the taxonomy + verbatim instead of carrying a grammar exception. `work-map` and `needs-human` stay flat + (grammar-exempt). Frontier queries and the bootstrap presence check match the new names. Maps + charted under the old names need a one-time label rename before `work` mode can route them. + ## [0.11.1] ### Fixed diff --git a/plugins/planning/skills/wayfind/SKILL.md b/plugins/planning/skills/wayfind/SKILL.md index 83a11fb090..747e4edecb 100644 --- a/plugins/planning/skills/wayfind/SKILL.md +++ b/plugins/planning/skills/wayfind/SKILL.md @@ -76,7 +76,7 @@ an interactive session — do not fabricate a map. commits, the topic). Sort every uncertainty through the fog test: sharp → candidate decision item; foggy → *Not-yet-specified* prose. 2. **Create or extend the map issue.** On first use in a repo, **verify** the wayfind label - taxonomy (`work-map`, `wayfind:*`, `needs-human`) is present — an unknown `--label` fails the + taxonomy (`work-map`, `wayfind: *`, `needs-human`) is present — an unknown `--label` fails the create. Honor the consuming repository's declared label ownership. If it names a label-as-code source of truth, STOP and report the exact missing set to that owner; otherwise report the set and ask the user how labels are provisioned. Never create labels ad hoc from this skill. Then create one issue labelled bare `work-map` @@ -111,11 +111,11 @@ an interactive session — do not fabricate a map. | Type label | Mode | Routes to | |---|---|---| - | `wayfind:research` | autonomous-capable | `/discovery:research` (falls back to inline research if not installed) | - | `wayfind:interview` | HITL | `/planning:interview` | - | `wayfind:design` | HITL | `/planning:design` — or `/event-storming:methodology` / `/event-storming:simulation` when the item is domain/event-model work | - | `wayfind:prototype` | HITL | `/prototype:logic` (behaviour/feasibility) or `/prototype:ui` (design/UX) — the item body says which | - | `wayfind:task` | per-item | Direct decision-unblocking work — no feature code, no PR tie | + | `wayfind: research` | autonomous-capable | `/discovery:research` (falls back to inline research if not installed) | + | `wayfind: interview` | HITL | `/planning:interview` | + | `wayfind: design` | HITL | `/planning:design` — or `/event-storming:methodology` / `/event-storming:simulation` when the item is domain/event-model work | + | `wayfind: prototype` | HITL | `/prototype:logic` (behaviour/feasibility) or `/prototype:ui` (design/UX) — the item body says which | + | `wayfind: task` | per-item | Direct decision-unblocking work — no feature code, no PR tie | 5. **Graduate on every resolution.** When the decision resolves: post the resolution as a comment on the item, add its one-line pointer to the map's *Decisions-so-far* index, then diff --git a/plugins/planning/skills/wayfind/context/map-anatomy.md b/plugins/planning/skills/wayfind/context/map-anatomy.md index 39de9b72df..9005821c42 100644 --- a/plugins/planning/skills/wayfind/context/map-anatomy.md +++ b/plugins/planning/skills/wayfind/context/map-anatomy.md @@ -39,7 +39,7 @@ an exclusion here is itself a decision; note why.> ## Typed decision items -Each sub-issue is one **sharp** question. The `wayfind:` label sets both the routing +Each sub-issue is one **sharp** question. The `wayfind: ` label sets both the routing target (which skill resolves it) and the default mode: | Type | Default mode | Meaning | @@ -51,7 +51,7 @@ target (which skill resolves it) and the default mode: | `task` | per-item | Decision-unblocking do-work — no feature code, no PR tie | Mode is materialized as the `needs-human` label (present = HITL). Extension policy: a new -`wayfind:` value requires an existing routing target — never a type with nowhere to go. +`wayfind: ` value requires an existing routing target — never a type with nowhere to go. ## Invariants (checked at every `work` session start) diff --git a/plugins/planning/skills/wayfind/context/tracker-mechanics.md b/plugins/planning/skills/wayfind/context/tracker-mechanics.md index 29f4fcba8a..f26e0f660a 100644 --- a/plugins/planning/skills/wayfind/context/tracker-mechanics.md +++ b/plugins/planning/skills/wayfind/context/tracker-mechanics.md @@ -19,8 +19,9 @@ or every item whose blocker ever closed is stranded off the frontier forever. ## Bootstrap labels (first use in a repo) -`/wayfind` uses its own taxonomy — `work-map`, `wayfind:research|interview|design|prototype|task`, -`needs-human`. At chart-mode entry, **verify** the taxonomy is present because an unknown `--label` +`/wayfind` uses its own taxonomy — `work-map`, `wayfind: research|interview|design|prototype|task` +(axis labels follow the colon-space grammar so label-as-code owners with a `prefix: value` convention +can declare them verbatim), `needs-human`. At chart-mode entry, **verify** the taxonomy is present because an unknown `--label` fails `gh issue create`. Read the consuming repository's instructions and configuration for label ownership. If they declare a label-as-code source of truth, treat that declared system as the writer, report the exact missing set to its owner, and stop. If no ownership policy is declared, report the @@ -30,7 +31,7 @@ provisioning repository and never creates labels ad hoc: ```shell # Presence check only — never create. Route missing labels to the repository-declared owner. have=$(gh label list --json name --jq '.[].name') -for L in work-map wayfind:research wayfind:interview wayfind:design wayfind:prototype wayfind:task needs-human; do +for L in work-map 'wayfind: research' 'wayfind: interview' 'wayfind: design' 'wayfind: prototype' 'wayfind: task' needs-human; do grep -qxF "$L" <<<"$have" || echo "MISSING (route to repository label owner): $L" done ``` @@ -50,7 +51,7 @@ A map is never assigned and never carries a claim label — it is a container, n # Type label routes + sets default mode. HITL types add `needs-human`; research omits it. gh issue create --parent \ --title "" \ - --label "wayfind:" \ + --label "wayfind: " \ --body "" # HITL item — materialize the mode: @@ -82,7 +83,7 @@ gh issue view "$MAP" --json subIssues --jq '.subIssues.nodes[].number' | tr -d ' select(.state == "OPEN") | select(([.blockedBy.nodes[] | select(.state == "OPEN")] | length) == 0) | select((.assignees | length) == 0) - | "#\(.number) \(.title) [\([.labels[].name] | map(select(startswith("wayfind:")))[])]"' | tr -d '\r' + | "#\(.number) \(.title) [\([.labels[].name] | map(select(startswith("wayfind: ")))[])]"' | tr -d '\r' done # Non-interactive: also drop needs-human items — add # | select((.labels | map(.name) | index("needs-human")) | not) diff --git a/plugins/planning/skills/wayfind/evals/evals.json b/plugins/planning/skills/wayfind/evals/evals.json index e8559238fb..5391e527c6 100644 --- a/plugins/planning/skills/wayfind/evals/evals.json +++ b/plugins/planning/skills/wayfind/evals/evals.json @@ -16,11 +16,11 @@ { "id": 2, "name": "work-mode-routes-decision-item-to-target-skill", - "prompt": "/planning:wayfind work — on our decision map (#142), the next open, unblocked, unassigned item is #145, labeled wayfind:design, asking us to choose the aggregate boundaries for the new billing domain. Resolve it.", + "prompt": "/planning:wayfind work — on our decision map (#142), the next open, unblocked, unassigned item is #145, labeled 'wayfind: design', asking us to choose the aggregate boundaries for the new billing domain. Resolve it.", "expected_output": "Work mode picks #145 as the frontier item, claims it (assignee plus a claim-comment lease), and routes the decision by invoking /planning:design directly — since design-typed items route there — rather than deciding the aggregate boundaries itself inline.", "files": [], "expectations": [ - "Output identifies #145 (wayfind:design) as the frontier item being resolved", + "Output identifies #145 ('wayfind: design') as the frontier item being resolved", "Output routes the decision to /planning:design, the routing target for design-typed items, rather than resolving the aggregate-boundary question itself inline", "Output claims the item (assignee plus claim comment) before starting resolution rather than working it unclaimed" ] From 1b47248317e7fb4cc84fc49f18f977e0802c7b5f Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Thu, 16 Jul 2026 23:06:09 -0400 Subject: [PATCH 2/2] =?UTF-8?q?fix(planning):=20bump=20to=200.12.0=20?= =?UTF-8?q?=E2=80=94=20label=20rename=20is=20a=20breaking=20change?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Repo precedent (hook-telemetry convention) treats rename of a contract field as breaking; the wayfind label taxonomy rename is the same shape, so at 0.x it signals as a minor bump, not a patch. Co-Authored-By: Claude Fable 5 --- plugins/planning/.claude-plugin/plugin.json | 2 +- plugins/planning/CHANGELOG.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index de614bad03..7c8ac8ac20 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.11.2", + "version": "0.12.0", "description": "Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, actively maintain resolved domain language, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate.", "author": { "name": "Melodic Software", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index 4fed7b3445..760cb09b66 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,7 +3,7 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. -## [0.11.2] +## [0.12.0] ### Changed