work-plan toolkit

Track-aware daily work planning for developers running parallel Claude Code / Codex sessions across many GitHub issues.

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 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 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

Claude Code (recommended):

/plugin marketplace add stylusnexus/agent-plugins
/plugin install work-plan@stylus-nexus

Codex: codex plugin marketplace add stylusnexus/agent-plugins → codex plugin add work-plan@stylus-nexus npm (any editor / standalone CLI):

npm install -g @stylusnexus/work-plan

VS Code extension (the visual viewer): search "Work Plan" (publisher stylusnexus) in the Extensions view, or code --install-extension stylusnexus.work-plan-viewer. It drives the CLI above — see VS Code extension. Cursor / Copilot / direct: clone + ./install.sh (see Install).

Full multi-agent guide: the agent-plugins marketplace README. See Install below for details, the npm path, and updating.

Command names: examples below use the standalone form /work-plan <subcommand> (what install.sh gives you). Installed as a plugin, commands are namespaced — /work-plan brief → /work-plan:brief, /work-plan handoff → /work-plan:handoff, and the long tail is /work-plan:run <subcommand>. On Codex, invoke via @work-plan / /skills.

The seven essentials you'll use 80% of the time are:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗