Skip to content
31 changes: 30 additions & 1 deletion docs/upstream/aihero-shipping-course.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ PARTIAL / REJECTED / OPEN.

| Lane | Course concept | Candidates | Our surface | Verdict | Item |
|---|---|---|---|---|---|
| A | Spec lifecycle: /to-spec, spec-on-tracker, archive-your-specs | C1–C4 | planning:prd/plan + work-items:decompose | OPEN | #2934 |
| A | Spec lifecycle: /to-spec, spec-on-tracker, archive-your-specs | C1–C4 | planning:prd/plan + work-items:decompose | PARTIAL (C4 adopted gate-added; C3 partial; C1 already-present; C2 routed to #2936) | #2934 |
| B | /to-tickets deltas | C5–C8, C17 | work-items:decompose | ADOPTED | #2935 |
| C | /implement + /tdd wiring, zero-assembly chain | C9–C11 | implementation:implement, tdd:principles, testing:write | OPEN | #2936 |
| D | Two-axis review, spec lens, close-out review | C12–C16 | review:quality-gate/fanout | OPEN | #2937 |
Expand All @@ -54,6 +54,35 @@ Seam-scrutiny follow-ons (not course-derived, surfaced by the same audit): bindi
multi-provider topology (#2945), Linear adapter (#2946), adapter-onboarding skill (#2950),
Jira write (#2951), Gitea/Forgejo adapter (#2952), provenance/map fixes (#2947).

## Lane A (#2934)

Interview rounds 1–4 locked the shape (2026-08-17): extend `work-items:decompose` +
`planning:plan close-out` — NOT a new to-spec skill; mandatory approval gate; opt-in and
consumer-configurable throughout.

- **C1 ALREADY-PRESENT**: no-interview pure-synthesis spec mode. `planning:interview`
synthesizes directly when intent is clear (anti-re-interrogation is its documented smart
default), and `planning:plan`'s empty-argument smart default finalizes an existing
conversation plan without re-interviewing. No new entry path added.
- **C2 PARTIAL**: seam-sketch-before-spec accepted as doctrine direction but ROUTED to lane C
(#2936), where it lands alongside C9 (the pre-agreed-seam gate — same doctrine family, one
landing surface across planning:design / tdd:principles / testing:plan). The "ideal number
of seams is one" numeric absolutism is REJECTED (folklore-figure posture).
- **C3 PARTIAL**: container body = the Brief **verbatim** (our spec template), plus an optional
`## Testing decisions` section with prior-art test pointers — that section is the adopted
delta. The "LONG, numbered, extremely extensive" directive stays excluded (worse-than-us
list).
- **C4 ADOPTED (gate-added variant only)**: the spec publishes to the tracker as a `work-map`
container with slices as native sub-items (`work-items:decompose` "Container lifecycle") —
opt-in at approval, `decompose_container_publish` userConfig pre-select, container label
remappable via binding `config.container_label`. Upstream's gate-free publish remains
excluded.
- **Archive-your-specs** (course "Should You Keep Your Specs?"): ADOPTED as archival by
closure — the container closes at ship after a close-out review against its body; a closed
container stays findable but no spec sits in repo or open tracker for agents to trust over
code. Pass-by-reference ADOPTED: `/work-items:work` reads the parent container body as
quoted briefing data before executing a sub-item.

## Lane B (#2935)

- **C5 ADOPTED**: prefactor look-ahead at decompose time ("make the change easy, then make the easy change"); prefactor slices are blockers of the slices they unblock. Qualitative — no token folklore.
Expand Down
2 changes: 1 addition & 1 deletion plugins/planning/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "planning",
"version": "0.30.6",
"version": "0.30.7",
"userConfig": {
"use_ask_user_question": {
"type": "boolean",
Expand Down
27 changes: 27 additions & 0 deletions plugins/planning/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,33 @@
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.30.7]

### Added

- **`plan` close-out: spec-container ship ritual (#2934).** Close-out gains a
presence-gated step 4: when the `work-items` plugin is installed and the
topic's decomposition published a spec container, route the container's
close-at-ship ritual through `/work-items:decompose` "Container lifecycle"
(that path owns the mechanics; close-out only sequences it). Partial ships
leave the container open; no container or no plugin skips silently.

### Changed

- **`wayfind`: container label resolved from the seam's binding key, not hardcoded
(#2934 review).** The map marker previously appeared as a literal `work-map` in the
bootstrap check, the create command, the open-maps pre-compute, and prose. Now that
`config.container_label` is a live per-repo remap in the work-item tracker seam, a
hardcoded literal would strand wayfind maps on the old string after a remap — no longer
matching the seam's frontier exclusion, so `/work-items:work-loop` would surface a map
as a claimable item. `tracker-mechanics.md` gains a resolve-once snippet (same key,
shipped default `work-map` when no binding/key/jq) that also repeats the seam's type rule
on wayfind's own read path — a present non-string value is a configuration error that
stops the create, never a silent fallback (wayfind never routes through the seam's
loader, so it cannot assume that validation ran); the create/bootstrap snippets use
`"$CONTAINER_LABEL"`; the `SKILL.md` pre-compute resolves the label inline with a
string-typed read (non-string or empty → default; display-only, fail-soft).

## [0.30.6]

### Changed
Expand Down
15 changes: 15 additions & 0 deletions plugins/planning/skills/plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,21 @@ Write the plan even for small changes — future you or a fresh-session agent wi

**ADR admission test** — a decision earns an ADR only when ALL three hold: **hard to reverse** (changing course later carries real cost), **surprising without context** (a future reader of the code would wonder why it was done this way), and **the result of a real trade-off** (genuine alternatives existed and one was picked for specific reasons). Any one missing → no ADR: an easily reversed decision just gets reversed, an unsurprising one raises no questions, and a no-alternative decision has nothing worth recording. Keep each ADR minimal — a title plus a few sentences covering context, decision, and why; optional sections (status, considered options, consequences) only when they earn their place. Prefer writing the ADR the moment the decision crystallizes during planning over batching candidates at graduation — this step then just moves the already-written file.
3. Prune with pointer: a final commit before merge deletes the contract slice `<contract_dir>/<topic-slug>/` (default `docs/topics/`), leaving context pointers (the PR body, the promoted-doc and tracker locations) in its place.
4. Spec-container ship ritual (presence-gated — only when the `work-items` plugin is installed
AND the topic's decomposition published a spec container). **Detect the container
mechanically, never from in-session memory** (close-out often runs in a fresh session):
first read the topic's PLAN.md for the `**Spec container:** <qualified-id>` line
`/work-items:decompose` records under `## Brief` at publish time; absent that line, query
the tracker for an open item carrying the binding-resolved container label (default
`work-map`) whose body cites the topic slug. Found → run the container's close-at-ship
ritual through the path that owns it — `/work-items:decompose` "Container lifecycle
(spec-on-tracker)". That section owns the mechanics (verify every sub-item closed, close-out
review against the container body, close with a comment linking the shipping PRs — archival
by closure); this step only sequences it into close-out and never redefines it. When the
shipped work covers only part of the container's sub-items, the container stays open — close
it only when the whole spec has shipped. Neither detection path yields a container, or no
`work-items` plugin: skip silently. Publishing a container is `/work-items:decompose`'s
approval-time offer, never a close-out side effect.

Lifecycle detail and the redaction bar for committed evidence: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md).

Expand Down
10 changes: 6 additions & 4 deletions plugins/planning/skills/wayfind/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ metadata:
## Pre-computed context

Current user: !`gh api user --jq '.login' 2>/dev/null || echo "unknown"`
Open maps: !`gh issue list --label work-map --state open --json number,title --jq '.[] | "#\(.number) \(.title)"' 2>/dev/null || echo "none"`
Open maps: !`gh issue list --label "$(l=$(jq -r '.config.container_label | if type=="string" then . else "" end' .work-item-tracker.json 2>/dev/null); echo "${l:-work-map}")" --state open --json number,title --jq '.[] | "#\(.number) \(.title)"' 2>/dev/null || echo "none"`

## Variables

Expand Down Expand Up @@ -88,11 +88,13 @@ an interactive session — do not fabricate a map.
instead of fabricating one: a single contract to lock → `/planning:interview`; a set of
sharp tickets → `/work-items`; small enough to just do → say so. (The trigger is too-big
AND foggy — both, never either alone.)
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
2. **Create or extend the map issue.** On first use in a repo, resolve the container label
(the seam's `config.container_label` key, default `work-map` — snippet in
`context/tracker-mechanics.md`), then **verify** the wayfind label
taxonomy (the container label, `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`
ask the user how labels are provisioned. Never create labels ad hoc from this skill. Then create one issue labelled with the bare container label
(+ any repo program labels). Body carries the five sections — **Destination** (where this is going once the
fog clears) / **Notes** (durable pointers only — PRs, committed docs, prior items, external links;
memory-tier `<memory_dir>/` artifacts are checkout-local, so distill their relevant content inline
Expand Down
3 changes: 2 additions & 1 deletion plugins/planning/skills/wayfind/context/map-anatomy.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Map anatomy — the five sections + invariants

A decision map is one tracker issue (bare `work-map` marker) whose sub-issues are typed
A decision map is one tracker issue (bare container-label marker — default `work-map`,
resolved per `tracker-mechanics.md`) whose sub-issues are typed
decision items. The issue **body** carries five sections. Everything volatile (each decision's
actual resolution, current frontier, claim state) lives on the items, not recopied into the
body — the body is a stable index, not a mirror.
Expand Down
38 changes: 34 additions & 4 deletions plugins/planning/skills/wayfind/context/tracker-mechanics.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,39 @@ blocker count. (`assignees` and `labels` ARE flat arrays — `| length` is corre
closes. Frontier must count only **OPEN** blockers (`.blockedBy.nodes[] | select(.state=="OPEN")`),
or every item whose blocker ever closed is stranded off the frontier forever.

## Resolve the container label (once per session, before any map read or write)

The map marker is the **container label** the work-item tracker seam defines — the same
`config.container_label` binding key, same shipped default (`work-items` CONTRACT.md,
"Containers and state"). Resolving it here instead of hardcoding `work-map` keeps wayfind
maps and decompose containers on ONE marker: a repo that remaps the label would otherwise
strand wayfind maps on the old string, where the seam's frontier exclusion no longer
matches them and `/work-items:work-loop` would surface a map as a claimable item.

```shell
# Same key + same type rule as the seam's lib/binding.sh: absent/empty → shipped default;
# a PRESENT non-string value is a configuration error, never a silent fallback.
ROOT=$(git rev-parse --show-toplevel)
t=$(jq -r '.config.container_label | type' "$ROOT/.work-item-tracker.json" 2>/dev/null || echo null)
case "$t" in
string) CONTAINER_LABEL=$(jq -r '.config.container_label' "$ROOT/.work-item-tracker.json" 2>/dev/null) ;;
null) CONTAINER_LABEL= ;; # no binding, no key, or jq missing
*) echo "ERROR: config.container_label must be a string (got $t) — fix .work-item-tracker.json" >&2
# Real stop — works sourced or standalone; never proceed with a coerced label.
return 1 2>/dev/null || exit 1
;;
esac
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
CONTAINER_LABEL=${CONTAINER_LABEL:-work-map}
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
```

The snippets below use `"$CONTAINER_LABEL"`; prose that says `work-map` means the shipped
default. Wayfind reads the binding file directly (it never routes through the seam's
loader), so the type check above repeats the seam's rule on this path rather than assuming
the seam already ran — on the ERROR branch, stop and report instead of creating anything.

## Bootstrap labels (first use in a repo)

`/planning:wayfind` uses its own taxonomy — `work-map`, `wayfind: research|interview|design|prototype|task`
`/planning:wayfind` uses its own taxonomy — the container label (default `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
Expand All @@ -31,16 +61,16 @@ 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 "$CONTAINER_LABEL" '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
```

## Create / extend the map

```shell
# Map issue: bare `work-map` marker + any repo program labels. Body per context/map-anatomy.md.
gh issue create --title "Map: <effort>" --label work-map --body-file <map-body.md>
# Map issue: bare container-label marker + any repo program labels. Body per context/map-anatomy.md.
gh issue create --title "Map: <effort>" --label "$CONTAINER_LABEL" --body-file <map-body.md>
```

A map is never assigned and never carries a claim label — it is a container, not a work item.
Expand Down
7 changes: 6 additions & 1 deletion plugins/work-items/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "work-items",
"version": "0.35.29",
"version": "0.35.30",
"description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github and local-markdown adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.",
"author": {
"name": "Melodic Software",
Expand All @@ -24,6 +24,11 @@
"title": "Lane instance id",
"description": "Writer identity for this machine's loop-lane telemetry, per the loop-lane convention's lane-instance identity rule. It becomes the suffix of the lane's telemetry sentinel marker (`work-items:work-loop@<id>`), so each concurrently running lane instance owns its own comment and none can overwrite another's durable state \u2014 including first_drain_complete, whose loss would end one machine's earn-trust ratification gate because a different machine finished a drain. Must match ^[a-z0-9][a-z0-9-]{0,31}$, be stable across restarts, and be distinct across concurrent instances; two lanes on one machine each need an explicit value. Absent: the sanitized lowercased hostname. The value appears verbatim in tracker comments \u2014 set an opaque id if a machine name should not be published in a public tracker."
},
"decompose_container_publish": {
"type": "boolean",
"title": "Pre-select spec-container publish at decompose approval",
"description": "When true, /work-items:decompose pre-selects the spec-container offer in its approval round for multi-session breakdowns (the Brief published as a container item carrying the binding-resolved container label, default work-map, with slices as native sub-items). The approval gate itself is unchanged and mandatory — this key changes the offered default answer, never bypasses approval. Leave unset (or false) for the default plain ask with a default answer of no; this key declares no default so an unset value stays distinguishable from a configured one."
},
"work_dispatch_concurrency_cap": {
"type": "number",
"title": "Autonomous dispatch concurrency cap",
Expand Down
19 changes: 19 additions & 0 deletions plugins/work-items/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,25 @@
All notable changes to the `work-items` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.35.30]

### Added

- **Spec-on-tracker container lifecycle (#2934):** `decompose` gains an opt-in
"Container lifecycle" — at approval (multi-session sources only, default no,
`decompose_container_publish` userConfig pre-select) it can publish the Brief
verbatim as a container item (binding-resolved container label + human-gated
label, never claimable) with slices as native `--parent` sub-items, and owns
the close-at-ship ritual (close-out review against the container body, then
archival by closure). `work` reads the parent container body first
(pass-by-reference, quoted data under item-content-trust). The seam's
container label is now remappable: binding `config.container_label` (sibling
of `config.role_labels`, default `work-map`), resolved
configured-over-default by `lib/binding.sh` and exported as
`WIT_CONTAINER_LABEL`; the F3.7 recorded deferral is converted to a live
remap seam (CONTRACT.md, label-taxonomy.md). Upstream's gate-free publish
stays excluded — the approval gate is mandatory.

## [0.35.29]

### Changed
Expand Down
Loading