master-plan

master-plan

AI-native task management for Claude Code. Track tasks in a MASTER_PLAN.md file, pick what to work on, save progress, and ship — all through agent skills.

/master-plan:task  →  create  →  /master-plan:next  →  pick  →  /master-plan:save  →  pause  →  /master-plan:done  →  ship

Quick Start

Step 1 — Install the plugin (run these two lines inside Claude Code):

/plugin marketplace add endlessblink/master-plan
/plugin install master-plan

Step 2 — Create your first task:

/master-plan:task

That's it. If your project doesn't have a MASTER_PLAN.md yet, the plugin creates one automatically in docs/MASTER_PLAN.md.

Step 3 — Work the loop:

/master-plan:next     Pick what to work on
                      ... write code ...
/master-plan:save     End of session? Save WIP + push
                      ... next day, different machine ...
/master-plan:next     Pick up where you left off
                      ... finish the task ...
/master-plan:done     Test + commit + push + mark complete

Already have tasks in a MASTER_PLAN.md? The plugin works with any existing file as long as tasks use ### TASK-123: Title (STATUS) headers. Run /master-plan:next to start picking from your existing backlog.

Why?

• Zero infrastructure — Just a markdown file + git. No Jira, no Linear, no database.
• AI-native — Claude reads the plan, scores priorities, picks tasks, updates status, runs tests, commits. You just approve.
• Session-resilient — /save your work, switch machines, come back tomorrow, /next picks up where you left off.
• Self-documenting — The MASTER_PLAN.md IS the project history. Nothing to keep in sync.
• Any language, any framework — Works with Node, Python, Rust, Go, or anything else. Auto-detects your test runner.
• Cross-platform — Built on the Agent Skills open standard. Core functionality works in Claude Code, Cursor, GitHub Copilot, Windsurf, and other compatible tools. Interactive task picking is best in Claude Code.

Skills

/master-plan:task — Create a Task

Creates a new task with an auto-generated sequential ID. If no MASTER_PLAN.md exists, creates one from a starter template.

> /master-plan:task

Using task number: 42

? Type: TASK / BUG / FEATURE / INQUIRY
? Priority: P0 (critical) → P3 (backlog)
? Title: Add user authentication

Task added to MASTER_PLAN.md:
- ID: TASK-42
- Title: Add user authentication
- Priority: P1
- Status: PLANNED

/master-plan:next — Pick What to Work On

Reads your MASTER_PLAN.md, scores tasks by priority and status, shows an interactive picker. Highlights in-progress tasks so you finish what you started.

> /master-plan:next

You have 1 task in progress.

? Which task would you like to work on?
  ● TASK-42: Add user authentication    P1 · PLANNED
    BUG-38: Fix login redirect          P0 · PLANNED
    TASK-40: Refactor API layer         P2 · IN PROGRESS
    Show more tasks...

> [Selects TASK-42, shows full details, offers to start working]

Filters: /master-plan:next bugs · /master-plan:next planned · /master-plan:next active · /master-plan:next review

/master-plan:save — Save Work-in-Progress

Commits and pushes without marking the task done. No tests, no ceremony — just save and go. Perfect for switching machines or ending a session.

> /master-plan:save

## Progress Saved
- Task: TASK-42
- Summary: Added login form and validation
- Commit: a1b2c3d — wip(TASK-42): Added login form and validation
- Status: Still IN PROGRESS

Ready to continue on another machine:
  git pull → /master-plan:next

/master-plan:done — Ship It

The full completion workflow: run tests, commit, push, and mark the task done in all locations within MASTER_PLAN.md.

> /master-plan:done

## Task Complete
- Task: TASK-42
- Tests: ✅ Passed
- Commit: d4e5f6g — feat(TASK-42): Add user authentication
- Push: ✅ Pushed to origin
- MASTER_PLAN.md: ✅ Updated (table + header + bullets)

Test auto-detection: npm test · pytest · cargo test · go test ./... · make test

Commit format: feat(TASK-XXX): for features, fix(BUG-XXX): for bugs, wip(TASK-XXX): for saves.

The Workflow

Start session
    │
    ▼
/master-plan:next          ← Pick a task (scored by priority)
    │
    ▼
  Work on it               ← Write code, debug, iterate
    │
    ├──► Need to stop?     → /master-plan:save (WIP commit + push)
    │                         Come back later, git pull, /next
    │
    ├──► Found a bug?      → /master-plan:task (log it, keep working)
    │
    └──► Done!             → /master-plan:done (test + commit + push + mark complete)
         │
         ▼
    /master-plan:next      ← Pick the next task

MASTER_PLAN.md Format

The plugin reads and writes tasks in this format:

### TASK-42: Add user authentication (IN PROGRESS)
**Priority**: P1
**Status**: IN PROGRESS (2026-02-23)

Description of the task...

**Tasks**:
- [ ] Create login form
- [x] Set up auth provider

Statuses: PLANNED · IN PROGRESS · REVIEW · PAUSED · ✅ DONE

When a task is marked done, it gets strikethrough on the ID and a status update:

### ~~TASK-42~~: Add user authentication (✅ DONE)

Tasks can also appear in a roadmap table — the plugin updates both locations automatically.

Starting fresh? Run /master-plan:task and the plugin creates the file for you. A starter template is also available at templates/MASTER_PLAN.md.

Task ID Format

IDs are globally sequential across all types. If TASK-42 and BUG-43 exist, the next ID is 44.

Team Install

Commit this to your project's .claude/settings.json and teammates are prompted to install automatically:

{
  "extraKnownMarketplaces": {
    "endlessblink-tools": {
      "source": { "source": "github", "repo": "endlessblink/master-plan" }
    }
  },
  "enabledPlugins": {
    "master-plan@endlessblink-tools": true
  }
}

Requirements

• Claude Code (or any Agent Skills-compatible tool)
• Git

No npm install, no build step, no external dependencies. The skills are pure markdown — Claude does the parsing.

Contributing

Issues and PRs welcome at github.com/endlessblink/master-plan.

License

MIT