Work Plan

Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file that references GitHub issues by ID; the CLI derives state live from gh/git. Composes with /repo-activity-summary for the global multi-repo view.

Subcommand reference

How to invoke

All subcommands route through the Python CLI. Prefer the work-plan launcher (on PATH as a plugin, and installed by install.sh): work-plan <subcommand>. It resolves work_plan.py relative to itself, then via ${CLAUDE_PLUGIN_ROOT} / ${PLUGIN_ROOT} / ~/.claude / ~/.agents. If the launcher isn't on PATH, call the CLI directly, first match wins:

1. ${CLAUDE_PLUGIN_ROOT}/skills/work-plan/work_plan.py (Claude plugin; Codex sets this too)
2. ${PLUGIN_ROOT}/skills/work-plan/work_plan.py (Codex plugin)
3. ~/.claude/skills/work-plan/work_plan.py (install.sh → Claude Code)
4. ~/.agents/skills/work-plan/work_plan.py (install.sh → Codex)

Run via Bash. Don't reimplement the logic in chat.

Verbatim relay (orientation subcommands)

For brief, handoff, orient (where-was-i), and hygiene, the Python output IS the deliverable. After running the Bash command, reproduce the full Python output verbatim in a fenced code block in your chat reply. Don't summarize, paraphrase, or truncate — users copy-paste from chat into other terminals/sessions, so any rewording loses information.

plan-status is also verbatim-relay, with one exception: its report can run to hundreds of docs. If the output is large, relay the headline line (counts + lie-gap) and the actionable 🟡 partial bucket verbatim, then offer the full report rather than flooding the chat. The --stamp/--draft summary line (stamped N doc(s) / would stamp N doc(s)) is always relayed verbatim.

Handoff: Claude-driven next_up

After running handoff:

1. Read the output (open issues, last session log, priority, milestone).
2. Survey the user's project memory (e.g., a MEMORY.md index in their working directory or ~/.claude/projects/.../memory/) for related signals — deploy gates, blocked items, in-flight clusters.
3. Pick a "next" — single ticket OR tight cluster (2-4 issues) — based on track priority, milestone, what's gating other work, what cluster naturally goes together.
4. Justify the pick in chat (1-2 sentences).
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, auto-triage)

All three follow the same pattern:

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/assignments BEFORE applying. The user may want to override.

auto-triage answers — write atomically and copy the batch_id. The VS Code viewer watches the answers file and reads suggestions live (#241), so a half-written file would be read mid-write. Write to a .tmp sibling and then rename it onto the final auto_triage.<repo>.answers.json path the CLI printed (the Write tool's create-then-replace is fine; never append). Use the v2 answers shape — {"version": 2, "batch_id": "<copy from the scan output>", "suggestions": [...]} — and copy the batch_id the scan printed so the viewer can tell fresh suggestions from a stale older scan. Prefer "verdict": "abstain" for issues with no clear home: most untracked issues genuinely have none, and a wrong suggestion a human rubber-stamps is worse than silence.

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:

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 group or new-track to route to notes_root instead; every other command rejects the flag with exit 2.

Local history for the private tier (opt-in): the shared tier already gets version control from its repo. For the private tier, /work-plan notes-vcs init git-inits notes_root as a personal, never-pushed repo and turns on auto-commit — every track-mutating command then writes an undoable commit to notes_root. notes-vcs status reports the state; enable/disable toggle it. Off until you run it.

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@myproject   # @repo qualifier
/work-plan close auth-flow --repo=myproject  # --repo=<key> flag

Both forms work on: slot, close, handoff, canonicalize, refresh-md, reconcile, set.

Track ↔ GitHub label mapping

By default, reconcile and the brief new-issue suggester look for the label track/<slug> on GitHub issues. If your repo uses a different scheme (flat labels like storytelling, namespaced labels like area/maps, or no track/* namespace at all), declare the labels per-track in the markdown frontmatter:

---
track: storytelling-enhancements
status: active
github:
  repo: your-org/your-repo
  labels: [storytelling, campaigns]   # OR semantics — issue matches if ANY label is present;
                                       # `track/storytelling-enhancements` always matches too
  issues: [4296, 4290, ...]
---

This is read-only on GitHub: the skill never adds, removes, or rewrites labels on the remote — it only reads them to know which issues belong to a track. The only writes are to your local markdown frontmatter, gated behind interactive confirmation. If github.labels is omitted, the default track/<slug> pattern is used (existing setups keep working unchanged).

Track ↔ commit attribution

handoff shows commits attributed to a track since the last handoff. Attribution rules (in order):

1. Explicit branches — if frontmatter has github.branches: [feature/x, ...], only commits on those branches count. Path globs do not apply.
2. Issue mention OR path glob — otherwise, scan all branches and keep commits whose message (subject OR body) mentions an issue in github.issues, OR whose changed paths match any glob in github.paths (fnmatch syntax — *, ?, **, [seq]). Scanning the body matters for squash-merged PRs whose subjects follow Conventional Commits (e.g. feat(scope): description) and carry the issue ref in the body (Closes #1234).

github:
  repo: your-org/your-repo
  issues: [4148, 4149, ...]
  paths:
    - "apps/web/src/components/ux/**"
    - "**/useToast*"

When zero commits attribute to the track but the repo has activity in the same window, the handoff renders a soft signal (0 attributed / N repo-wide since last handoff) so the silence isn't mistaken for "nothing happened."

Setup

Run ./install.sh (macOS / Linux / WSL) or .\install.ps1 (Windows) from the toolkit root. Then /work-plan init-repo <key> --github=<org/repo> to bootstrap your first repo. See the toolkit README for full setup, requirements, and platform-specific install commands.

Common mistakes