@stylusnexus/work-plan 2026.6.9 → 2026.6.10

package/README.md

@@ -7,7 +7,23 @@
 
 Track-aware daily work planning for developers running parallel Claude Code / Codex sessions across many GitHub issues.
 
-`work-plan` is a CLI-backed agent skill (a pure-Python-stdlib CLI + `SKILL.md`). It treats your daily work as a set of *tracks* — each track is a markdown file with YAML frontmatter listing its priority, milestone, GitHub issue numbers, and current status. The skill derives state live from GitHub (`gh`), git, and the markdown body, so the markdown stays light (it references issues by ID rather than duplicating their state).
+## What this is
+
+A daily work-planning system for developers running parallel AI sessions across many GitHub issues. It's made of three things: a pure-Python stdlib CLI, a set of YAML-frontmattered markdown files ("tracks"), and a `SKILL.md` that tells your AI how to use the CLI. Together they give you and your agent a shared, live picture of what's in flight — without asking you to maintain it manually.
+
+**Installs as a plugin** for Claude Code and Codex (see [Quick install](#quick-install) for the exact commands), as an npm global for any editor or terminal (`npm install -g @stylusnexus/work-plan`), and as a VS Code extension (search "Work Plan", publisher `stylusnexus`).
+
+The system derives state *live* from GitHub (`gh`), `git`, and your track files on every run — nothing is mirrored or cached. AI sessions get a paste-ready context block; you stay oriented even when switching between a dozen parallel workstreams.
+
+**Why it exists:** born from the frustration of building detailed plans that die the moment you open a new agent session and start over. Inspired by [Andrej Karpathy's notes on vibe coding](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and the specific pain of doing enthusiastic work on the wrong thing.
+
+## What this is not
+
+- **Not a Jira / Linear / GitHub Projects replacement.** It doesn't manage sprints, roadmaps, or capacity planning — it helps *you and your AI agent* stay oriented on GitHub issues you already have.
+- **Not a standalone issue tracker.** GitHub is canonical; `work-plan` just reads and references it.
+- **Not zero-setup.** Requires Python 3.9+, the `gh` GitHub CLI (authenticated), and `yq` (the Go version, not the Python one).
+- **Not a background service.** No daemon, no cache, no sync loop — `git pull` is the sync mechanism for shared tracks.
+- **Not a replacement for reading your code.** It tells you *what* to work on and *where you left off* — not what the code does.
 
 ## Quick install
 
@@ -35,16 +51,24 @@ The five essentials you'll use 80% of the time are:
 | `/work-plan brief` | Morning. Multi-track snapshot — what's on your plate across every active track. Add `--repo=<key>` to scope to one project. |
 | `/work-plan handoff <track>` | End of a work block. Captures what you touched. Use `--auto-next` for an algorithmic priority-sorted `next_up` (no LLM), `--set-next 1,2,3` for explicit numbers, or pair with Claude in chat for a curated pick. |
 | `/work-plan orient <track>` | Switching context. ~15-line paste-block of priority / last session / next pick / git state — drop into a fresh Claude Code terminal. |
-| `/work-plan reconcile <track> \| --all \| --repo=<key> [--draft]` | Track frontmatter membership drifted from GitHub labels. Use on label-driven tracks only — for hand-curated tracks, use `refresh-md` instead. `--draft` previews proposed ADDs/FLAGs without prompting or writing. `--repo=<key>` scopes the sweep to one repo. |
-| `/work-plan hygiene [--repo=<key>]` | Weekly. Refresh status icons, reconcile labels, scan for duplicates. `--repo=<key>` scopes steps 1–2 to one repo (duplicates is global, so it's skipped in scoped mode). |
+| `/work-plan reconcile <track> \| --all \| --repo=<key> [--draft] [--yes]` | Track frontmatter membership drifted from GitHub labels. Use on label-driven tracks only — for hand-curated tracks, use `refresh-md` instead. In an `--all`/`--repo` sweep it also moves issues relabeled from one track to another in the same repo. `--draft` previews proposed ADDs/MOVEs/FLAGs; `--yes` applies without prompting. `--repo=<key>` scopes the sweep to one repo. |
+| `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Runs three steps: ① `refresh-md --all` (pull live GitHub state into every active track's status table), ② `reconcile --all` (sync frontmatter membership against GitHub labels), ③ `duplicates` (flag likely-duplicate issues). `--repo=<key>` scopes steps ① and ② to one repo; step ③ is skipped in scoped mode. |
+
+A dozen more subcommands cover slotting new issues into tracks, closing tracks (shipped/abandoned/parked), and one-time priority-label backfill. Three capabilities worth calling out explicitly:
+
+**Shared tracks** — track files can live *inside your repo clone* (`.work-plan/<slug>.md`) so teammates see the same planning state via `git pull`. The default is private (`notes_root/<repo>/`); register a local clone with `init-repo --local=<path>` to opt into shared mode. Pass `--private` to any write command to keep a specific track local. See [Shared tracks](#shared-tracks).
+
+**AI-powered clustering (`group`)** — hand a flat list of GitHub issues to your AI and get back thematic track files. Run `group --milestone=X` to fetch all issues in a milestone, get a clustering prompt, save the JSON answer, then `group --apply` creates the tracks. Pairs with `auto-triage` for ongoing maintenance: once tracks exist, `auto-triage` assigns newly-filed untracked issues back into them.
+
+**Coverage + auto-triage** — `coverage --repo=<key>` reports how many open issues fall outside the track model (42% on a real production repo). `auto-triage --repo=<key>` then produces an AI prompt to assign those orphans to existing tracks. Run both periodically to keep the backlog visible.
 
-A dozen more subcommands cover slotting new issues into tracks, closing tracks (shipped/abandoned/parked), AI-clustering raw GitHub issues into thematic tracks, and one-time priority-label backfill.
+**Cross-track dependencies** — set `depends_on: [<track-slug>]` in a track's frontmatter to declare explicit dependencies between tracks. The VS Code viewer renders these as thick amber `==>` edges in the dependency graph, and the detail panel shows clickable dependency chips that navigate directly to the dependent track. Set via `/work-plan set <track> depends_on=slug1,slug2` or the "Edit Track Fields" right-click menu in VS Code. Complementary to the issue-derived "owns" edges already inferred from blockers.
 
 Beyond issue tracking, **`plan-status`** answers a different question — *which of your accumulated plan/spec docs actually shipped, half-shipped, or died*. It correlates each plan's declared file-manifest (`Create:`/`Modify:`/`Test:` paths) against git and the filesystem rather than trusting checkboxes (which are routinely left unchecked even for shipped work). Read-only by default; optionally stamp the verdict into each doc (`--stamp`), get an AI verdict on prose/ambiguous docs (`--llm`), and act on the results behind confirmation gates (`--archive` dead plans, `--issues` for partial ones). See [Plan & doc liveness](#plan--doc-liveness-plan-status).
 
 ## How it works
 
-The toolkit treats GitHub as the canonical source of issue state and never tries to mirror it. Track markdown files are lightweight references — they list issue numbers and a few pieces of derived metadata (priority, milestone, `next_up`, last session timestamp). The CLI re-derives everything else live from `gh`, `git`, and the markdown body.
+The toolkit treats GitHub as the canonical source of issue state and never tries to mirror it. Track markdown files are lightweight references — they list issue numbers and a few pieces of derived metadata (priority, milestone, `next_up`, `depends_on`, last session timestamp). The CLI re-derives everything else live from `gh`, `git`, and the markdown body.
 
 ```mermaid
 flowchart TB
@@ -84,7 +108,49 @@ flowchart TB
   - Free-form via Claude in your agent session, which can review project memory and write a curated list back. The two `--*-next` flags are the no-LLM paths.
   - For tracks where you don't want to bother curating at all, set `next_up_auto: true` in the track's frontmatter — `brief` will then derive the list live each invocation, ignoring whatever's stored.
 - **Weekly** → `hygiene` runs `refresh-md --all` + `reconcile --all` + `duplicates` in sequence to keep status icons, GitHub labels, and dedup state honest.
-> **When does the body status table get refreshed?** `handoff` already rewrites the ✅/🔲 icons for its own track on every run (live `gh` fetch → `update_row_status`). `brief` reads GitHub state live and never relies on the body table, so it's always accurate. The only drift `refresh-md` exists to fix is *cross-track*: a track you haven't `handoff`'d recently whose icons fell behind because issues moved while you were heads-down on a sibling track. That's why `hygiene --all` sweeps it weekly.
+
+> **When should I run `refresh-md`?** Any time you close or merge issues and want the track body to reflect the new state. `handoff` rewrites the status table for one track on every run, but `brief` reads GitHub live without writing anything back — so a track you haven't `handoff`'d recently stays stale on disk. `refresh-md <track>` (or **Refresh Track Body** in VS Code) fixes that on-demand; `hygiene` sweeps all tracks weekly.
+
+> **GitHub access is read-only.** The toolkit never writes to GitHub. All issue data comes from read-only `gh` CLI calls (`gh issue list`, `gh issue view`). Every write (frontmatter, status table, session log) goes to your local markdown files only.
+
+## Shared tracks
+
+By default track files live under `notes_root/<repo>/` — local only, never committed. **Shared tracks** live inside the repo clone itself (`.work-plan/<slug>.md`) and travel with the repo via `git pull`/`git push`. Teammates see the same planning state without a separate notes sync.
+
+**Set up shared tracks for a repo:**
+
+```bash
+# Register the local clone path in your config
+/work-plan init-repo myproject --github=org/myproject --local=/path/to/clone
+```
+
+Once `local:` is set and points to a valid git repo, all new tracks for that repo go into `.work-plan/` automatically.
+
+**Syncing:**
+
+```bash
+git pull                          # pull teammates' track changes
+git add .work-plan/ && git commit && git push  # share your own
+```
+
+The CLI never auto-pushes. When you create or update a shared track, it prints a reminder:
+```
+↑ shared — commit + push to share with teammates.
+```
+
+**Opt out per-command:** pass `--private` to route a specific track to `notes_root` instead:
+
+```bash
+/work-plan group --milestone='v1.0' --private   # keep clusters local
+/work-plan new-track myproject exploration       # --private for one-off tracks
+```
+
+**Multi-repo disambiguation:** if the same track slug exists in two repos, qualify with `@<repo>` or `--repo=<key>`:
+
+```bash
+/work-plan slot 4234 auth-flow@critforge
+/work-plan close auth-flow --repo=critforge
+```
 
 ## Plan & doc liveness (`plan-status`)
 
@@ -215,7 +281,7 @@ To install for **both** Claude Code AND Codex, run the installer twice with diff
 
 ### VS Code extension
 
-The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph, the Untracked bucket, and full read/write (slot/close/edit/new-track/…) with a public-repo confirm modal.
+The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph (with focus toggle and repo-scoped full map), the Untracked bucket, cross-track dependency chips, per-issue move buttons, and full read/write (slot/close/edit/move/new-track/…) with a public-repo confirm modal.
 
 ![Work Plan VS Code extension — sidebar and dependency graph](https://raw.githubusercontent.com/stylusnexus/work-plan-toolkit/main/vscode/media/screenshots/dependency-graph.png)
 
@@ -226,6 +292,16 @@ Install it from either registry:
 
 The extension **shells out to the `work-plan` CLI**, so install the CLI too (npm or any method above). If `work-plan` isn't on your editor's `PATH` — common when VS Code is launched from the Dock/Finder rather than a terminal — set **`workPlan.cliPath`** in Settings to an absolute launcher path (e.g. `/path/to/work-plan-toolkit/bin/work-plan`, or the npm global bin), then reload the window. Extensions auto-update from the registry.
 
+Useful settings:
+
+| Setting | Default | What it does |
+|---|---|---|
+| `workPlan.cliPath` | `"work-plan"` | Absolute path to the CLI, if it's not on the editor's PATH |
+| `workPlan.autoRefreshInterval` | `0` (off) | Re-poll the CLI silently in the background (seconds). Set to 30, 60, 300, or 900 if teammates are pushing shared-track changes and you want the tree to stay current without manual refresh |
+| `workPlan.expandReposByDefault` | `false` | Expand all repo groups on load (single-repo workspaces always expand) |
+
+Shared tracks show a **`shared`** tag in the tree description so you can tell at a glance which tracks travel via `git push/pull` and which are local-only.
+
 ### Updating
 
 | Installed via | Update with |
@@ -304,9 +380,9 @@ work-plan-toolkit/
 │   ├── work-plan/
 │   │   ├── SKILL.md
 │   │   ├── work_plan.py                # CLI entry
-│   │   ├── commands/                   # 16 subcommand modules
+│   │   ├── commands/                   # 24 subcommand modules
 │   │   ├── lib/                        # config, frontmatter, gh, git, prompts, …
-│   │   └── tests/                      # 234 unittest cases
+│   │   └── tests/                      # 600+ unittest cases
 │   └── repo-activity-summary/
 │       └── SKILL.md                    # bundled companion skill
 ├── commands/
@@ -417,14 +493,16 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `close <track> [--state=shipped\|parked\|abandoned] [--note=<text>]` | Mark track shipped, parked, or abandoned. Moves to `archive/<state>/` for shipped/abandoned. Pass `--state=` (and an optional `--note=`) to run without prompts. |
 | `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Update issue STATE (open/closed, status labels) inside the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
 | `hygiene [--repo=<key>]` | Weekly all-in-one: `refresh-md` + `reconcile` + `duplicates`. With `--repo=<key>`, steps 1 and 2 scope to that repo and the global `duplicates` step is skipped. |
-| `list [--all]` | List active tracks (or all including parked/archived). |
+| `list [--all] [--sort=recent\|priority]` | List active tracks (or all including parked/archived). `--sort=recent` orders by `last_touched` (most recent first); `--sort=priority` orders by `launch_priority` (P0→P3) with recency as tiebreaker. Default keeps discovery order. |
 | `init <path> [--priority=P0..P3] [--milestone=<m>]` | Add frontmatter to a brand-new track .md file (the file must already exist). Pass `--priority=`/`--milestone=` to skip the prompts. |
 | `init-repo <key> --github=<slug> [--local=<path>]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. `--github` is required; `--local` is optional. |
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
-| `group [--milestone=X] [--label=Y]` | AI-cluster GitHub issues into thematic tracks (creates `<repo>/<slug>.md` per cluster). |
-| `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). `--draft` previews ADDs/FLAGs without prompting or writing. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
+| `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
+| `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
+| `coverage [--repo=<key>] [--list] [--limit=N]` | Report how many open issues are not in any track. `--list` prints titles. Read-only. |
+| `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft] [--yes]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). In an `--all`/`--repo` sweep it also detects **MOVEs** — an issue relabeled from one track to another in the same repo is moved (removed from the old track, added to the new); ambiguous targets stay as FLAGs. `--draft` previews ADDs/MOVEs/FLAGs without prompting or writing. `--yes` applies without prompting (non-interactive, e.g. the VS Code extension); PUBLIC-repo move destinations are skipped under `--yes`. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
 | `canonicalize <track>` | Add a canonical issue table to a track file (so `refresh-md` knows where to update). |
 | `plan-status [--repo=<key>] [--json] [--stamp [--draft]] [--llm [--apply]] [--archive \| --issues] [--draft]` | Reach a verdict on every plan/spec doc in a repo by correlating its declared file-manifest against git + the filesystem: ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less / 🧳 foreign. Read-only by default. `--stamp` writes an idempotent status header into each doc (`--draft` previews); `--llm` runs a two-step AI verdict on prose/ambiguous docs; `--archive` moves dead plans to `archive/abandoned/` and `--issues` opens issues for partial plans (both gated, both honor `--draft`); `--json` for machine output. |
@@ -467,7 +545,7 @@ cd skills/work-plan
 python3 -m unittest discover tests
 ```
 
-234 tests, no external dependencies (mocks `gh`/`git` calls).
+600+ tests, no external dependencies (mocks `gh`/`git` calls).
 
 ## License
 

package/VERSION

@@ -1 +1 @@
-2026.06.09+f3bc861
+2026.06.10+a6052bf

package/bin/work-plan

@@ -24,6 +24,29 @@ while [ -L "$src" ]; do
   esac
 done
 root="$(cd -P "$(dirname "$src")/.." && pwd)"
+
+# Runtime preflight: surface a clear, per-tool message if a required external
+# tool is missing, instead of a Python traceback from deep in config-load (the
+# classic "yq not found" confusion). yq/gh aren't needed for --version/--help,
+# so don't block those.
+_wp_have() { command -v "$1" >/dev/null 2>&1; }
+_wp_missing=""
+_wp_have python3 || _wp_missing="$_wp_missing python3"
+case "${1:-}" in
+  --version|-v|--help|-h|"") ;;
+  *)
+    _wp_have yq || _wp_missing="$_wp_missing yq"
+    _wp_have gh || _wp_missing="$_wp_missing gh"
+    ;;
+esac
+if [ -n "$_wp_missing" ]; then
+  echo "work-plan: missing required tool(s) on PATH:$_wp_missing" >&2
+  case "$_wp_missing" in *python3*) echo "  python3 — the CLI runtime            (brew install python · https://python.org)" >&2 ;; esac
+  case "$_wp_missing" in *yq*)      echo "  yq      — YAML config/frontmatter    (brew install yq — the Go mikefarah/yq, NOT the python yq)" >&2 ;; esac
+  case "$_wp_missing" in *gh*)      echo "  gh      — GitHub issue state         (brew install gh, then: gh auth login · https://cli.github.com)" >&2 ;; esac
+  exit 1
+fi
+
 for c in \
   "$root/skills/work-plan/work_plan.py" \
   "${CLAUDE_PLUGIN_ROOT:-}/skills/work-plan/work_plan.py" \

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.9",
-  "description": "Track-aware daily work planning over GitHub issues — the work-plan CLI. Pure Python stdlib; this package only ships + launches it.",
+  "version": "2026.6.10",
+  "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"
   },

package/skills/work-plan/SKILL.md

@@ -15,15 +15,17 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan brief` | Starting work or after a gap. Multi-track snapshot. |
 | `/work-plan handoff [track] [--auto-next \| --set-next 1,2,3]` | Wrapping up a work block. Captures touched + next + blockers; writes session log. Add `--auto-next` to suggest a priority-sorted next_up list from open issues (interactive: apply / edit / skip). Tracks with `next_up_auto: true` in frontmatter get the auto-derived list surfaced in `brief` automatically. |
 | `/work-plan orient [track]` (alias `where-was-i`) | Re-orienting. With a track: ~15-line track paste-block. Without: cwd snapshot (branch, recent commits, modified files) for non-track work. Add `--pick` for the interactive track picker. |
-| `/work-plan hygiene` | Weekly all-in-one cleanup: refresh-md --all + reconcile --all + duplicates. |
+| `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Three steps in sequence: ① `refresh-md --all` — pull live GitHub state into every active track's status table (same as "Refresh Track Body" but for all tracks); ② `reconcile --all` — sync track frontmatter membership against GitHub labels; ③ `duplicates` — flag likely-duplicate issues for consolidation. Run once a week to keep status icons, labels, and dedup state honest. `--repo=<key>` scopes steps ① and ② to one repo; step ③ is skipped in scoped mode (it needs a single explicit repo to be unambiguous). |
 | `/work-plan slot <issue-num> [track]` | A new GitHub issue should belong to a track. If the issue is already listed in another active track's frontmatter, you'll be prompted to move it (remove from source) instead of duplicating. |
 | `/work-plan close [track]` | Track is done (shipped) / paused (parked) / won't ship (abandoned). |
-| `/work-plan refresh-md <track> \| --all` | Status icons drifted from GitHub state. **You usually don't need to call this directly:** `handoff` already rewrites the body table for its own track on every run, and `brief` reads GitHub live. Reach for `refresh-md` (or `--all`) when a sibling track has drifted because you haven't `handoff`'d it lately. |
+| `/work-plan refresh-md <track> \| --all \| --repo=<key>` | **Pull live GitHub state into a track's status table.** Run this after closing or merging issues — it re-fetches each issue's open/closed state from GitHub and rewrites the status cells in the track body, which refreshes the dependency graph and `next_up` display. `--all` sweeps every active track; `--repo=<key>` scopes to one repo. In VS Code: right-click a track → **Refresh Track Body**. |
 | `/work-plan list [--all]` | List active tracks (or all including parked/archived). |
 | `/work-plan init <path>` | Add frontmatter to a new track .md file. |
 | `/work-plan init-repo <key> [--github=<slug>] [--local=<path>]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. |
 | `/work-plan suggest-priorities --repo=<key>` | Two-step AI label backfill (one-time migration). |
-| `/work-plan group [--milestone=X] [--label=Y] [--repo=Z]` | Two-step AI clustering: turn a flat list of issues into thematic track files. |
+| `/work-plan group [--milestone=X] [--label=Y] [--repo=Z]` | Two-step AI clustering: turn a flat list of issues into thematic track files. Powerful for a new milestone or repo re-org — fetches issues, prints a clustering prompt, you save the JSON answer, then `--apply` creates the track files. |
+| `/work-plan auto-triage [--repo=<key>]` | Two-step AI assignment: assign untracked open issues to *existing* tracks. Use after `coverage` shows a gap. Prints a prompt listing untracked issues + active tracks; save AI's JSON answer; re-run with `--apply`. |
+| `/work-plan coverage [--repo=<key>] [--list]` | Report how many open issues are not in any track (per repo). `--list` shows titles. Read-only. Run before `auto-triage` or `group` to measure the gap. |
 | `/work-plan reconcile <track> \| --all [--draft]` | Sync track frontmatter with GitHub labels (read-only on GitHub). Default label is `track/<slug>`; override per-track via `github.labels` in frontmatter. Add `--draft` to preview proposed ADDs/FLAGs without prompting or writing. |
 | `/work-plan duplicates [--min-similarity=0.7]` | Find likely-duplicate issues by title similarity (stdlib difflib). |
 | `/work-plan plan-status [--repo=<key>] [--stamp [--draft]] [--type=plan\|spec]` | **Doc/plan liveness.** "Which of my plan/spec docs actually shipped, half-shipped, or died?" Correlates each plan's declared file-manifest (Create/Modify/Test paths) against git + filesystem — not the unreliable checkboxes. Reports ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less. Read-only by default; `--stamp` writes an idempotent status header into each doc (`--draft` previews, writes nothing). Natural-language triggers: "what's done vs unfinished in `<repo>`", "stamp the plan statuses", "which plans are stale/dead". |
@@ -60,15 +62,46 @@ After running `handoff`:
 5. Persist via `python3 <skill-path>/work_plan.py handoff <track> --set-next <comma-list>` (e.g. `--set-next 4167,4148,4149`).
 6. Show the user what was set so they can override.
 
-## Two-step AI subcommands (`suggest-priorities`, `group`)
+## Two-step AI subcommands (`suggest-priorities`, `group`, `auto-triage`)
 
-Both are two-step:
+All three follow the same pattern:
 
-1. CLI fetches issues + writes prompt to terminal.
-2. **You** read the issues, output the requested JSON, save via Write tool to `~/.claude/work-plan/cache/priorities.answers.json` or `~/.claude/work-plan/cache/groups.answers.json`.
+1. CLI fetches issues + writes prompt to terminal (saved to `~/.claude/work-plan/cache/`).
+2. **You** read the issues, output the requested JSON, save via Write tool to the path the CLI printed.
 3. Re-run with `--apply` to commit changes.
 
-Show the proposed labels/clusters BEFORE applying. The user may want to override.
+Show the proposed labels/clusters/assignments BEFORE applying. The user may want to override.
+
+**Which one to use:**
+- `group` — issues need to be *clustered into new track files* (run once per milestone or after a re-org)
+- `auto-triage` — untracked issues need to be *assigned to existing tracks* (run after `coverage` shows a gap)
+- `suggest-priorities` — issues need `priority/PN` labels backfilled (one-time migration)
+
+## Two-tier track storage (shared vs private)
+
+Track files live in one of two places:
+
+| Tier | Path | Who sees it |
+|---|---|---|
+| **Shared** | `<local-clone>/.work-plan/<slug>.md` | Everyone with repo access (committed + pushed) |
+| **Private** | `<notes_root>/<folder>/<slug>.md` | Local only (never committed) |
+
+**Routing logic (automatic):** if a repo has a registered `local:` path that is a valid git repo, new tracks go into `.work-plan/` by default. Pass `--private` to any write command to route to `notes_root` instead.
+
+**Setup shared tracks for a repo:**
+```
+/work-plan init-repo myproject --github=org/myproject --local=/path/to/clone
+```
+
+**Syncing shared tracks:** `git pull` pulls teammates' track changes; `git add .work-plan/ && git commit && git push` shares your own. The CLI never auto-pushes.
+
+**Disambiguation when the same track slug exists in two repos:**
+```
+/work-plan slot 4234 auth-flow@critforge   # @repo qualifier
+/work-plan close auth-flow --repo=critforge  # --repo=<key> flag
+```
+
+Both forms work on: `slot`, `close`, `handoff`, `canonicalize`, `refresh-md`, `reconcile`, `set`.
 
 ## Track ↔ GitHub label mapping
 

package/skills/work-plan/commands/auto_triage.py

@@ -0,0 +1,243 @@
+"""auto-triage subcommand: AI-assign untracked issues to existing tracks.
+
+Two-step (same pattern as `group`):
+1. Run without --apply: fetches untracked open issues, writes a batch file,
+   prints a prompt for the AI to assign each issue to an existing track.
+2. Run with --apply: reads the AI's JSON answers and slots each assignment
+   into the relevant track's frontmatter.
+
+Use --repo=<key> to scope to one configured repo. When the config has a
+single repo, --repo is inferred automatically.
+
+Answers JSON format (written to cache/auto_triage.answers.json):
+  [
+    {"track": "auth-flow", "issues": [4501, 4502]},
+    {"track": "tabletop-sessions", "issues": [4503]}
+  ]
+Issues omitted from every list are left untracked (no error).
+"""
+import json
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.frontmatter import parse_file, write_file
+from lib.scratch import cache_dir
+from lib.tracks import discover_tracks
+from lib.github_state import fetch_open_issues
+
+
+def _batch_path() -> Path:
+    return cache_dir() / "auto_triage.json"
+
+
+def _answers_path() -> Path:
+    return cache_dir() / "auto_triage.answers.json"
+
+
+PROMPT_TEMPLATE = """\
+You have a list of EXISTING tracks and a list of UNTRACKED open issues.
+Assign each issue to the most appropriate existing track.
+
+Return JSON — an array of assignment objects:
+[
+  {"track": "<exact-track-slug>", "issues": [<issue-numbers>]},
+  ...
+]
+
+Rules:
+- Use ONLY the track slugs listed under "Existing tracks" below.
+- An issue can appear in AT MOST ONE track assignment.
+- Omit issues that genuinely don't fit any existing track (they stay untracked).
+- Do NOT invent new tracks — that's /work-plan group's job.
+- Do NOT include empty assignments (issues: []).
+
+"""
+
+
+def run(args: list[str]) -> int:
+    apply_mode = "--apply" in args
+    repo_arg = next((a for a in args if a.startswith("--repo=")), None)
+
+    limit = 100
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    if apply_mode:
+        return _apply(cfg)
+
+    # -----------------------------------------------------------------------
+    # Step 1: fetch untracked issues + print AI prompt
+    # -----------------------------------------------------------------------
+    repos_cfg = cfg.get("repos", {})
+    if repo_arg:
+        folder = repo_arg.split("=", 1)[1]
+        if folder not in repos_cfg:
+            print(f"ERROR: repo folder '{folder}' not in config.yml.")
+            return 1
+    elif len(repos_cfg) == 1:
+        folder = next(iter(repos_cfg))
+    else:
+        print("Multiple repos in config. Specify with --repo=<folder-name>.")
+        return 1
+
+    repo = repos_cfg[folder].get("github")
+    if not repo:
+        print(f"ERROR: repo entry '{folder}' has no 'github' key.")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    active_tracks = [
+        t for t in tracks
+        if t.has_frontmatter and t.repo == repo
+        and t.meta.get("status") in ("active", "in-progress", "blocked")
+    ]
+    if not active_tracks:
+        print(f"No active tracks found for {repo}. Run /work-plan group first.")
+        return 0
+
+    # Build per-repo set of already-tracked issue numbers
+    tracked_nums: set = set()
+    for t in tracks:
+        if t.repo == repo and t.has_frontmatter:
+            tracked_nums.update(t.meta.get("github", {}).get("issues") or [])
+
+    print(f"Fetching open issues from {repo}...")
+    open_issues = fetch_open_issues(repo, limit=500)
+    untracked = [i for i in open_issues if i.get("number") not in tracked_nums]
+
+    if not untracked:
+        print(f"No untracked issues found for {repo} — full coverage!")
+        return 0
+
+    batch_path = _batch_path()
+    batch_path.write_text(json.dumps({
+        "repo": repo,
+        "folder": folder,
+        "untracked": untracked,
+        "tracks": [{"slug": t.meta.get("track", t.name), "name": t.name,
+                    "milestone": t.meta.get("milestone_alignment"),
+                    "priority": t.meta.get("launch_priority")}
+                   for t in active_tracks],
+    }, indent=2))
+
+    print(f"Found {len(untracked)} untracked issues ({len(active_tracks)} active tracks).")
+    print()
+    print("=" * 60)
+    print(PROMPT_TEMPLATE)
+
+    print("Existing tracks:")
+    for t in active_tracks:
+        slug = t.meta.get("track", t.name)
+        milestone = t.meta.get("milestone_alignment", "—")
+        priority = t.meta.get("launch_priority", "—")
+        print(f"  {slug}  [{priority}, {milestone}]")
+
+    print()
+    print("Untracked issues to assign:")
+    shown = untracked[:limit]
+    for i in shown:
+        num = i.get("number", "?")
+        title = i.get("title", "")
+        milestone = i.get("milestone") or {}
+        m_title = milestone.get("title", "—") if isinstance(milestone, dict) else "—"
+        labels = [lb["name"] for lb in (i.get("labels") or [])]
+        print(f"  #{num} [{m_title}] [{','.join(labels) or 'no-labels'}] {title}")
+    remainder = len(untracked) - len(shown)
+    if remainder > 0:
+        print(f"  … and {remainder} more issues (use --limit=N to show more)")
+
+    print("=" * 60)
+    print()
+    print(f"After the agent returns assignment JSON, save it to:")
+    print(f"  {_answers_path()}")
+    print("Then run:")
+    print("  python3 ~/.claude/skills/work-plan/work_plan.py auto-triage --apply")
+    return 0
+
+
+def _apply(cfg: dict) -> int:
+    answers_path = _answers_path()
+    batch_path = _batch_path()
+    if not answers_path.exists():
+        print(f"ERROR: {answers_path} not found. Run without --apply first.")
+        return 1
+    if not batch_path.exists():
+        print(f"ERROR: {batch_path} not found.")
+        return 1
+
+    batch = json.loads(batch_path.read_text())
+    repo = batch["repo"]
+    folder = batch["folder"]
+    if folder not in cfg.get("repos", {}):
+        print(f"ERROR: batch folder '{folder}' not in config.yml repos.")
+        return 1
+
+    answers = json.loads(answers_path.read_text())
+
+    tracks = discover_tracks(cfg)
+    tracks_by_slug = {}
+    for t in tracks:
+        if t.repo == repo and t.has_frontmatter:
+            slug = t.meta.get("track", t.name)
+            tracks_by_slug[slug] = t
+            tracks_by_slug[t.name] = t  # also index by name for resilience
+
+    untracked_nums = {i["number"] for i in batch.get("untracked", [])}
+
+    slotted = 0
+    skipped = 0
+    for assignment in answers:
+        slug = assignment.get("track", "").strip()
+        issue_nums = assignment.get("issues") or []
+        if not slug or not issue_nums:
+            continue
+
+        track = tracks_by_slug.get(slug)
+        if not track:
+            print(f"  WARN: track '{slug}' not found — skipping {len(issue_nums)} issue(s).")
+            skipped += len(issue_nums)
+            continue
+
+        existing_meta, existing_body = parse_file(track.path)
+        if not existing_meta:
+            print(f"  SKIP {slug}: file exists but has no frontmatter.")
+            skipped += len(issue_nums)
+            continue
+
+        existing_issues = list(existing_meta.get("github", {}).get("issues") or [])
+        existing_set = set(existing_issues)
+        new_nums = [n for n in issue_nums if n in untracked_nums and n not in existing_set]
+        already_there = [n for n in issue_nums if n in existing_set]
+
+        if already_there:
+            print(f"  ℹ {slug}: #{','.join(str(n) for n in already_there)} already present.")
+        if not new_nums:
+            continue
+
+        merged = sorted(existing_set | set(new_nums))
+        existing_meta.setdefault("github", {})["issues"] = merged
+        existing_meta["last_touched"] = datetime.now().strftime("%Y-%m-%dT%H:%M")
+        write_file(track.path, existing_meta, existing_body)
+        print(f"  ✓ {slug}: added #{','.join(str(n) for n in new_nums)} "
+              f"({len(merged)} issues total)")
+        slotted += len(new_nums)
+
+    print()
+    print(f"Done: {slotted} issue(s) assigned, {skipped} skipped.")
+    if slotted:
+        print("Next: run /work-plan brief to see the updated tracks.")
+    return 0