diff --git a/docs/upstream/aihero-shipping-course.md b/docs/upstream/aihero-shipping-course.md index edb76a408d..f33b277f21 100644 --- a/docs/upstream/aihero-shipping-course.md +++ b/docs/upstream/aihero-shipping-course.md @@ -57,7 +57,7 @@ Jira write (#2951), Gitea/Forgejo adapter (#2952), provenance/map fixes (#2947). ## Decided at interview (2026-08-17, not per-lane) - **Naming:** "work item" stays canonical; "ticket"/"issue" are documented first-class synonyms - (trigger coverage lands via #2947). Rename of plugin/seam REJECTED. + (trigger coverage landed via #2947). Rename of plugin/seam REJECTED. - **Setup-by-interview** (course "Set Up Your Issue Tracker" / `setup-matt-pocock-skills`): remains REJECTED per the skills-repo SSOT — this marketplace configures via the tracker-seam binding + setup skills. @@ -74,4 +74,4 @@ Jira write (#2951), Gitea/Forgejo adapter (#2952), provenance/map fixes (#2947). - Skills-repo SSOT: [`mattpocock-skills.md`](mattpocock-skills.md) (attribution table; tracked strands). The invocation-reach tracked strand's audit lands via lane X (#2940). - Full v1.2 map: [`mattpocock-skills-v12-map.md`](mattpocock-skills-v12-map.md). Staleness - fixes and absorbed-under-different-name traceability land via #2947. + fixes and absorbed-under-different-name traceability landed via #2947. diff --git a/docs/upstream/mattpocock-skills-v12-map.md b/docs/upstream/mattpocock-skills-v12-map.md index a80d057ca8..507fa44757 100644 --- a/docs/upstream/mattpocock-skills-v12-map.md +++ b/docs/upstream/mattpocock-skills-v12-map.md @@ -22,9 +22,9 @@ Legend — **Relation**: DERIVED (attributed port), PARTIAL (specific ideas take | 12 | `setup-matt-pocock-skills` | NONE | no analog — our plugins configure via `userConfig` + consumer CLAUDE.md instead of a setup interview | Omitted deliberately (different distribution model) | #502: friendlier (recommended-yes, monorepo signals, `.scratch//issues/-.md`, `spec.md`) | | 13 | `tdd` | CONVERGENT | `tdd:principles`, `testing:write` | Not ported. Deferred-ports ledger names "tdd top-up" (never shipped) | Seam discipline ("no test at an unconfirmed seam"), 3 anti-patterns (implementation-coupled, tautological, horizontal-slicing/tracer bullets), "refactoring is not part of the loop" | | 14 | `to-spec` | CONVERGENT | `planning:prd`/`planning:plan` + interview Brief | Not ported. His: no interview, pure synthesis; extensive user stories; no file paths in specs | `/to-prd`→`/to-spec` rename FINISHED (A9); spec file = `spec.md`; fewest-seams-possible doctrine | -| 15 | `to-tickets` | CONVERGENT | `work-items:decompose` (vertical-slice/tracer-bullet vocabulary near-identical) | No provenance recorded, but vocabulary overlap is striking — flag for honesty check | One-file-per-ticket local layout; **expand–contract** wide-refactor exception; "work the frontier" | -| 16 | `triage` | CONVERGENT | `work-items:triage` (state machine; our listing "a PR is an item with attached code" ≈ his "a PR is an issue with attached code" — flag) | No provenance recorded | **`.out-of-scope/` KB** (prior-rejection institutional memory, dedupe check) — candidate; mandatory AI-generated disclaimer on posted comments | -| 17 | `wayfinder` | DERIVED | `planning:wayfind` (fog-of-war + ticket-vs-fog attributed; tracker-native map ours) | Took: fog framing, ticket-vs-fog test. Rejected: file-based map, his tracker seam | **Decision-ticket term** (CONTEXT.md domain term); **research tickets burned down in parallel via /research subagents on `research/` branch** (exception to one-ticket-per-session); over-reach warning (well-scoped feature → grill, not wayfind); "when the map clears it hands off — merge at /to-spec" | +| 15 | `to-tickets` | PARTIAL | `work-items:decompose` (course "tickets" absorbed as canonical "work items"; ticket/issue are invocation synonyms, not a rename) | Vertical-slice / tracer-bullet vocabulary overlap recorded as influence. **expand–contract** wide-refactor exception already on our decompose (`SKILL.md` §2b) | One-file-per-ticket local layout; **expand–contract** wide-refactor exception; "work the frontier" | +| 16 | `triage` | DERIVED | `work-items:triage` (our surface; "a PR is an item with attached code" ≈ course/skills "a PR is an issue with attached code") | Structured `.out-of-scope/` KB port recorded on the skills-repo SSOT (already-adopted; v1.2 M15 rejected as duplicate) | **`.out-of-scope/` KB** already adopted (SSOT triage row); mandatory AI-generated disclaimer on posted comments | +| 17 | `wayfinder` | DERIVED | `planning:wayfind` (`wayfinder` → `wayfind`; fog-of-war + ticket-vs-fog attributed; tracker-native map ours) | Took: fog framing, ticket-vs-fog test. Rejected: file-based map, his tracker seam. Decision tickets → tracker-native decision items / work-map (work-items vocabulary) | **Decision-ticket term** maps to our "decision item" / work-map (not CONTEXT.md files); **research tickets burned down in parallel via /research subagents on `research/` branch** (exception to one-ticket-per-session; `research/` branch REJECTED on SSOT); over-reach warning (well-scoped feature → grill, not wayfind); "when the map clears it hands off — merge at /to-spec" | | 18 | `wizard` | DERIVED (lane 4) | `wizard:generate` — new single-capability plugin `wizard` 0.1.0 | PORTED (hardened): 4-step process, fixed library above STAGES marker, model-invoked + non-trigger fence, gh graceful degradation, ephemeral-by-default kept; hardened with human STAGES approval before `chmod +x`, https-only open_url, `/dev/tty` fail-closed prompts, quoted 0600 `.env` writes + gitignore assert, repo-confirmed `--repo`-explicit gh writes, key-name validation, readline non-secret asks (#741), names-only live-`.env` scoping + honest secrets-context prose. Codex sidecar not ported. SSOT row + `plugins/wizard/CHANGELOG.md` carry provenance | **NEW graduate**, model-invoked. Interactive bash wizard for human-only steps; fixed `template.sh` library above STAGES marker (never hand-edited); deterministic = secrets never reach agent; 4 trigger branches + explicit non-trigger; verify via `bash -n` + shellcheck; v1.2.3 dropped time estimates | ## Productivity bucket (7) @@ -35,7 +35,7 @@ Legend — **Relation**: DERIVED (attributed port), PARTIAL (specific ideas take | 20 | `grilling` | PARTIAL | `planning:interview` core loop | Domain-generalization (#532 reword) already mirrored by our domain-routing | — | | 21 | `handoff` | PARTIAL | `session-flow:handoff` (claim-provenance + constraint re-scan mined from his issues #186/#306/#617/#482) | Ours far larger (save-point files, find-handoff, reconcile) | ask-matt reframes: handoff is NARROW (only when something travels); ours already richer but framing worth comparing | | 22 | `teach` | DERIVED | `education:teach` (siblings: `education:explain`, `education:quiz-me`) | CORRECTED from CONVERGENT by the `teach-skill-comparison` topic audit: the original port took his workspace vocabulary (MISSION.md, learning records as "teaching ADRs"), near-verbatim FORMAT content, and K-S-W/ZPD pedagogy; storage-strength pedagogy, HTML-first lessons, and the `assets/` library re-adopted in education 0.7.0. Full taken/rejected/added record: mattpocock-skills.md attribution table | — | -| 23 | `to-questionnaire` | DERIVED | `planning:questionnaire` (#311) | Ours: interview-the-send invariant kept; output relocated cwd → memory slice (PII); tracker item; interview vocabulary | **Graduated in-progress → Productivity** (#593). Our provenance line still says "in-progress" — STALE, fix. ask-matt routes it as inverse of grill-me | +| 23 | `to-questionnaire` | DERIVED | `planning:questionnaire` (#311) | Ours: interview-the-send invariant kept; output relocated cwd → memory slice (PII); tracker item; interview vocabulary | **Graduated in-progress → Productivity** (#593). Our provenance line still says "in-progress" — STALE; skill-body fix is planning-owned (not this PR). ask-matt routes it as inverse of grill-me | | 24 | `wait-what` | DERIVED (lane 3) | `discipline:wait-what` (ported near-verbatim; declared non-corrector species). Lane-3 vetting corrected the adjacency: true nearest neighbors are `education:explain` (altitude) + `adhd:clarify` (structure) — this fills the third cell (precision-keeping re-pitch); `tighten-your-output`/`caveman` are output-shape (the failure register), `curate-language` owns glossary writes | — | **NEW** (#751). One-sentence user-invoked corrective (8-line file): re-pitch w/ context + ASD-STE100 + CONTEXT.md ubiquitous language. Name-as-mechanism doctrine (listener's state, not output shape). STE-100 verified real (Issue 9, 2025, 53 rules/900 words). Port record: SSOT row + PLAN.md `### Lane 3` | | 25 | `writing-for-agents` | CONVERGENT | `playbooks:skill-authoring`, `docs-hygiene:*` (audit-noise, audit-derivability, extract-ssot, compress), `skill-quality:check` | Not ported; strongly parallel doctrine | **Breaking rename** from writing-great-skills; scope = any agent-consumed doc; GLOSSARY merged in; SKILL-MECHANICS.md split out; model-invoked (v1.2.2: Codex sidecar policy line REMOVED so it stays model-invocable there); **"cache" pruning term** (environment is SSOT; doc restating it = cache, earns load only when lookup expensive) ≈ our audit-derivability; leading words, negation warning, two loads, information hierarchy | @@ -79,8 +79,8 @@ Legend — **Relation**: DERIVED (attributed port), PARTIAL (specific ideas take > "influence, recorded": the SSOT attribution table names both work-items skills. Finding 5 is > the standing audit baseline (SSOT records v1.2.3 @ `84fdeff`). -1. **STALE**: `plugins/planning/skills/questionnaire/SKILL.md:48-50` says upstream `to-questionnaire` is "in-progress" — it graduated to Productivity in v1.2.0 (#593). Fix provenance line. +1. **STALE**: `plugins/planning/skills/questionnaire/SKILL.md:48-50` says upstream `to-questionnaire` is "in-progress" — it graduated to Productivity in v1.2.0 (#593). The skill-body provenance-line fix is planning-owned (serialized with #2938/#2939), not this PR (#2947). 2. **WEAK TRIGGER**: "re-audit opportunistically" (questionnaire SKILL.md:50, planning CHANGELOG:562) fails `docs/conventions/upstream-drift/README.md` observability bar — no observable event. The guardrails attribution (`plugins/guardrails/CHANGELOG.md:~1783`) carries NO re-audit trigger at all. Candidate trigger: "a mattpocock/skills release whose changeset names ". [verifier-corrected] -3. **HONESTY FLAG**: `work-items:triage` ("a PR is an item with attached code") and `work-items:decompose` (vertical-slice/tracer-bullet) carry near-verbatim Pocock phrasings with no provenance record. Either coincidence-via-shared-sources or unrecorded influence — decide whether to add provenance lines. +3. **HONESTY FLAG** (resolved — influence, recorded): `work-items:triage` ("a PR is an item with attached code") and `work-items:decompose` (vertical-slice/tracer-bullet) carry near-verbatim Pocock phrasings. Decision landed in #2947: SSOT attribution table + map rows 15–16 (`to-tickets` PARTIAL, `triage` DERIVED) now carry the provenance record. 4. **ONE stale reference found** (fresh-context verifier overturned the initial all-clear): `docs/topics/ai-adoption-ladder/design/RESEARCH-sandcastle-pocock.md:35,37` (slice carried by PR #330) names `writing-great-skills` as a live upstream skill with no note of the v1.2.0 breaking rename to `writing-for-agents`. Fix or annotate. No other stale references (removed-skill names, `/to-prd`) exist in tracked files. [verifier-corrected] 5. His repo HEAD is v1.2.3, not v1.2.0 — any sync should target HEAD (Redact section, harness-neutral dispatch, wizard sans time-estimates, writing-for-agents Codex-sidecar fix). diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index 0c66138ce9..134007e868 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -98,3 +98,7 @@ Two `writing-for-agents` strands from v1.2 (lane 5) — tracked on events, never Full verified 35-skill upstream↔ours map (relations, v1.2 deltas, drift findings): [`docs/upstream/mattpocock-skills-v12-map.md`](mattpocock-skills-v12-map.md). + +Shipping-course SSOT (distinct source from this skills-repo record; course pages +are account-gated; recheck trigger lives there): +[`aihero-shipping-course.md`](aihero-shipping-course.md). diff --git a/plugins/work-items/.claude-plugin/plugin.json b/plugins/work-items/.claude-plugin/plugin.json index d7164a80ad..86e1b84219 100644 --- a/plugins/work-items/.claude-plugin/plugin.json +++ b/plugins/work-items/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "work-items", - "version": "0.35.26", + "version": "0.35.27", "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", diff --git a/plugins/work-items/CHANGELOG.md b/plugins/work-items/CHANGELOG.md index 1fe28c60d5..008bfb614f 100644 --- a/plugins/work-items/CHANGELOG.md +++ b/plugins/work-items/CHANGELOG.md @@ -3,6 +3,17 @@ 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.27] + +### Changed + +- **Naming:** "work item" stays canonical; `track` and `work` Use-when triggers + now include ticket/issue synonyms (`add a ticket`, `list tickets`, `close a + ticket`, `work the next ticket`/`issue`, `grab the next ticket`). Documented + once in this plugin's README. Course SSOT cross-linked from the skills-repo + SSOT; v1.2 map rows for `to-tickets` / `triage` / `wayfinder` record + absorption under those names (#2947). + ## [0.35.26] ### Added diff --git a/plugins/work-items/README.md b/plugins/work-items/README.md index c35a21c720..59983e0e08 100644 --- a/plugins/work-items/README.md +++ b/plugins/work-items/README.md @@ -8,7 +8,7 @@ bound adapter today. The tracker's capabilities are split across five focused skills (plus a setup skill). Invoke the one that matches the job (or let Claude invoke it when you ask -about work items, tracked work, or what to do next): +about work items, tickets, issues, tracked work, or what to do next): ```text /work-items:track # stats dashboard (default) @@ -30,6 +30,13 @@ about work items, tracked work, or what to do next): | `/work-items:scan-todos` | Sweep the codebase for TODO/FIXME/HACK markers; resolve or file each. | | `/work-items:setup` | `check` inspects the tracked `.github/recurring-schedule.json`, the jq/tracker-seam entry gates, and the recurring-maintenance role label read-only; `apply` binds the provider, writes the empty schedule skeleton, and offers the canonical-role → label remap in the tracker binding (re-runnable). Seeding actual rows — inferring candidate items from the repo and interviewing per item — is opt-in via `apply --seed-schedule` or an offer that recommends skipping; a schedule that already carries items is offered updates as before. | +## Naming + +**Work item** is the canonical term. **Ticket** and **issue** are first-class +synonyms for invocation — they appear in skill Use-when triggers so phrasing +like "add a ticket" or "work the next issue" routes here — not a rename of the +plugin, seam, or surface. + ## `/work-items:track` actions | Action | What it does | diff --git a/plugins/work-items/skills/track/SKILL.md b/plugins/work-items/skills/track/SKILL.md index 62785d5bca..e5e8ba32f0 100644 --- a/plugins/work-items/skills/track/SKILL.md +++ b/plugins/work-items/skills/track/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Track development work items through the bound tracker (work-item-tracker seam) — the backlog-CRUD multi-verb skill. Actions: stats, list, add, start, done, due, recheck, search, audit (default: stats dashboard). Use when: 'add a work item', 'add an issue', 'close a work item', 'start a work item', 'claim a work item', 'list work items', 'what work items are open', 'what's due', 'work-item stats', 'work items dashboard', 'search work items', 'check overdue recurring items', 'recheck a recurring item', 'audit work items', 'audit stale claims'. Not for new bug reports — use /bug-report:write first (read-only report), then chain to /work-items:track add via --context if filing is needed. Sibling skills own the other verbs: /work-items:work (auto-select + execute one), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO/FIXME sweep)." +description: "Track development work items through the bound tracker (work-item-tracker seam) — the backlog-CRUD multi-verb skill. Actions: stats, list, add, start, done, due, recheck, search, audit (default: stats dashboard). Use when: 'add a work item', 'add an issue', 'add a ticket', 'close a work item', 'close a ticket', 'close an issue', 'start a work item', 'start a ticket', 'start an issue', 'claim a work item', 'list work items', 'list tickets', 'list issues', 'what work items are open', 'what's due', 'work-item stats', 'work items dashboard', 'search work items', 'check overdue recurring items', 'recheck a recurring item', 'audit work items', 'audit stale claims'. Not for new bug reports — use /bug-report:write first (read-only report), then chain to /work-items:track add via --context if filing is needed. Sibling skills own the other verbs: /work-items:work (auto-select + execute one), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO/FIXME sweep)." argument-hint: " [args] — actions: stats, list, add, start, done, due, recheck, search, audit (default: stats)" user-invocable: true disable-model-invocation: false diff --git a/plugins/work-items/skills/work/SKILL.md b/plugins/work-items/skills/work/SKILL.md index 29c63def1f..d3618077fd 100644 --- a/plugins/work-items/skills/work/SKILL.md +++ b/plugins/work-items/skills/work/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Auto-select one development work item from the tracker frontier and execute it end-to-end through the project's development workflow. Use when: 'pick work', 'work the next item', 'what should I work on next', 'grab the next work item', 'auto-select a work item', 'work an item', 'do the next thing', 'start on the backlog'. Selects exactly ONE item by priority tiers (due recurring, guardrails, highest-impact, then not-yet-due recurring), claims it race-safe via the seam (assignee + lease), then runs the full workflow. Sibling skills: /work-items:track (backlog CRUD — add, start, done, list, stats, search, due, recheck, audit), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO sweep)." +description: "Auto-select one development work item from the tracker frontier and execute it end-to-end through the project's development workflow. Use when: 'pick work', 'work the next item', 'work the next ticket', 'work the next issue', 'what should I work on next', 'grab the next work item', 'grab the next ticket', 'auto-select a work item', 'work an item', 'do the next thing', 'start on the backlog'. Selects exactly ONE item by priority tiers (due recurring, guardrails, highest-impact, then not-yet-due recurring), claims it race-safe via the seam (assignee + lease), then runs the full workflow. Sibling skills: /work-items:track (backlog CRUD — add, start, done, list, stats, search, due, recheck, audit), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO sweep)." argument-hint: "(no arguments — auto-selects and claims one frontier item)" user-invocable: true disable-model-invocation: false diff --git a/plugins/work-items/tools/work-item-tracker/adapters/local-markdown/README.md b/plugins/work-items/tools/work-item-tracker/adapters/local-markdown/README.md index af3dfe8afc..ce281f997f 100644 --- a/plugins/work-items/tools/work-item-tracker/adapters/local-markdown/README.md +++ b/plugins/work-items/tools/work-item-tracker/adapters/local-markdown/README.md @@ -30,12 +30,9 @@ existing file number + 1 with no file lock. ## Claim / lease -Claim identity is `git config user.name`, then `$USER`, then `local`. The same -git user in two worktrees looks like the same holder. The lease handle is a -store-global `lease_comment_id` in the marker JSON (not a GitHub comment id); -`renew-lease` addresses that handle. The manifest declares `reclaim: false`; -invoking `reclaim` exits `6`. On expiry, `list-items` reports empty `assignees` -while `get-item` still shows the stored assignee. +Claim identity, the store-global `lease_comment_id` handle, `reclaim` exit `6`, +and the expiry-view split live in CONTRACT.md "Branch, worktree, and lease +confinement". `renew-lease` addresses that handle. ## Branch, worktree, and lease confinement @@ -54,8 +51,11 @@ open|closed|all`; `--repo` is accepted for interface parity and does not re-target the single-namespace store) and the core-derived `work-item-tracker.sh list-frontier`. Filter, search, and aggregation stay on those verbs; do not invent a query language against the markdown files. +`--label`, `--assignee`, `--search`, and `stats` projections that need item +bodies or timestamps are **unsupported** on this adapter — `list-items` +implements `--state` only. ## Auth None. The adapter touches no network and has no credential. Claim identity is -the git user name as under "Claim / lease" above. +the git user name (CONTRACT.md "Branch, worktree, and lease confinement").