mk-plan-master

Idea triage + RICE scoring + quarterly roadmap + spec-draft bridge — over MCP. Reads from Linear / JIRA / Notion / Markdown, hands the generated spec draft directly to mk-spec-master.parse_spec, and remembers every decision so the same idea never bounces back unexplained.

🟢 Alpha — v0.1. 15 tools + 4 adapters + 77 tests passing. Full design in docs/prd.md. Walkthrough using a real dogfood case in docs/walkthrough.md.

Why this exists

With mk-plan-master shipped, the AI-driven dev pipeline now looks like this:

Idea  →  Plan       →  Spec        →  Code     →  Test      →  Coverage    →  Coach
         mk-plan       mk-spec        your IDE     mk-qa       mk-spec        both

Until v0.1 the upstream slot was a ??? — mk-spec-master could parse a spec, mk-qa-master could run tests, but nobody had built the piece that turns a pile of 30–200 raw ideas (chat snippets, customer calls, URLs, gut hunches) into a prioritized, RICE-scored backlog and emits a spec draft that drops straight into mk-spec-master.parse_spec(raw_text=...) — no manual reformatting, no copy-paste fragility.

mk-plan-master is that piece. The mk-* family is now whole:

• mk-plan-master — ideas in, prioritized plans + spec drafts out (this repo)

• mk-spec-master — specs in, scenarios out, coverage matrix

• mk-qa-master — scenarios in, runnable tests out (pytest / Jest / Cypress / Go test / Maestro)

It's also the planning MCP that measures its own decision quality over time — history snapshots, decision signatures (ghost initiatives / score whiplash / orphan OKRs), and tool-usage telemetry. The mk-spec-master v0.4 self-reinforcement layer, applied one step upstream.

Related MCP server: mk-spec-master

The family loop

   ┌─────────┐      ┌──────────┐      ┌─────────┐      ┌─────────┐      ┌──────────┐      ┌─────────┐
   │  Idea   │ ───> │   Plan   │ ───> │  Spec   │ ───> │  Code   │ ───> │   Test   │ ───> │ Coverage│
   │ (chat,  │      │ mk-plan- │      │ mk-spec-│      │ your IDE│      │ mk-qa-   │      │ mk-spec-│
   │ URL,    │      │ master   │      │ master  │      │ (Claude │      │ master   │      │ master  │
   │ call)   │      │          │      │         │      │ Code /  │      │          │      │         │
   │         │      │ RICE +   │      │ AC +    │      │ Cursor /│      │ runnable │      │ matrix  │
   │ AI      │      │ roadmap +│      │ scenarios│     │ Copilot)│      │ tests in │      │ + drift │
   │ summary │      │ spec     │      │ + drift │      │ writes  │      │ pytest / │      │ + coach │
   │         │      │ draft    │      │         │      │ impl    │      │ Jest / …│      │         │
   └─────────┘      └──────────┘      └─────────┘      └─────────┘      └──────────┘      └─────────┘
       ▲                  │                  │                  ▲                  ▲                  │
       │                  │                  │                  │                  │                  │
       │                  └──── spec_draft ──┘                  │                  │                  │
       │                                                        │                  │                  │
       │                                            red tests ──┘                  │                  │
       │                                                                           │                  │
       └─────────────────── decision history / chronic patterns ───────────────────┴──────────────────┘

Important. Code lives in your IDE, not in the family. Between spec and green tests, Claude Code / Cursor / Copilot writes the actual implementation. The MCP family wraps the rails — planning, spec, test, coverage, coach — and deliberately leaves the code-writing layer to whatever AI-pair-programming tool you already use. Tests generated by mk-qa-master are a runnable TODO list; the IDE loop flips them red → green.

Install

uvx mk-plan-master    # or: pip install mk-plan-master

Add to your MCP client config:

{
  "mcpServers": {
    "mk-plan-master": {
      "command": "uvx",
      "args": ["mk-plan-master"],
      "env": {
        "PLAN_SOURCE": "markdown_local",
        "PLAN_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Works in Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI — any MCP client.

Claude Desktop config lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Then in your AI session:

"Use mk-plan-master to score every triage idea, pick the top one, run analyze_initiative on it, then generate a spec draft and hand it to mk-spec-master."

Tool surface (15 tools)

Grouped by role in the idea → plan → spec → memory loop.

Meta — orientation (1)

Discovery — find and load ideas (2)

Capture — chat / WebFetch handoff (1)

Analysis — the senior-PM SOP (1)

Scoring — prioritize the backlog (2)

Bridge — the family lock-in (1)

Roadmap — quarterly planning (2)

Knowledge — methodology layer (2)

Self-reinforcement — long-running view (3)

Adapter status

Why analyze_initiative exists — a real case study

This is the differentiator. AI clients, by default, shortcut into a shallow read of any idea handed to them. They infer Reach / Impact / Confidence / Effort from a 2-paragraph blurb and produce a confident-looking RICE score that's mostly noise. The numbers below are from the actual dogfood corpus in mk-plan-test/ — same URL, same idea, two passes.

Pass 1 — without analyze_initiative (the AI just reads the URL and guesses):

IDEA-001  ·  一鍵式 IP 授權平台（AI + 區塊鏈）
  reach        500
  impact         2
  confidence   0.5
  effort        12  person-weeks
  out_of_scope  []  (none)
  RICE         (500 × 2 × 0.5) / 12  =  41.7   →   P0

A confident P0. Looks like a no-brainer "ship it next quarter."

Pass 2 — with analyze_initiative (the AI is forced through the senior-PM SOP first):

IDEA-002  ·  RightClick — 一鍵式 IP 授權平台（AI + 區塊鏈）
  reach        250                    ←  scoped to "active users per quarter
                                          in initial regions (Singapore + US-west
                                          social), not raw addressable market"
  impact         2                    ←  same
  confidence   0.4                    ←  dropped: logo wall is unverifiable,
                                          AI-contract legal status untested,
                                          two-sided cold-start unproven, no GMV
  effort        18  person-weeks      ←  raised: wallet 3w + AI templates 4w
                                          + contracts/NFT 3w + marketplace 3w
                                          + lawyer review + security 3w
                                          + backoffice/observability 2w
  out_of_scope  8 explicit items      ←  fiat rails, cross-chain bridging,
                                          derivative auto-royalties (v2),
                                          multi-jurisdiction custom legal,
                                          DRM, PRO-style collective rights,
                                          video/animation, enterprise SSO
  RICE         (250 × 2 × 0.4) / 18  =  11.1   →   P1

The delta — same URL, same idea, an order of magnitude more honest:

P0 → P1 is the difference between "ship next quarter" and "validate first." analyze_initiative is the SOP that gets you there without needing a senior PM in the room. Same idea, same source URL — different rigor.

Both initiatives are in mk-plan-test/initiatives/ verbatim. Both spec drafts are in mk-plan-test/specs/. The full decision trail is in .mk-plan-master/index.json — every scored and spec_generated event with timestamps. Walkthrough with prompts + tool chains in docs/walkthrough.md.

4 prompting workflows

Four natural-language prompts cover ~90% of real use. Each is one sentence to your AI client; the tools chain automatically.

1. Lock one idea — URL → spec_draft

"I read https://rightclickip.xyz/ — capture it as an initiative, run analyze_initiative on it, score it, and produce a detailed spec draft I can hand to mk-spec-master."

Chains: add_initiative (from your chat summary, family does NOT crawl) → analyze_initiative → add_initiative(overwrite=true) (with the enriched body) → score_initiative → generate_spec_draft(template="detailed") → mk-spec-master.parse_spec(raw_text=...).

2. Weekly backlog re-rank — trend over time

"Every Monday, rank my Linear triage backlog with RICE and show me the trend vs last week and last month."

Chains: rank_backlog(method="rice", limit=10) → get_planning_history(window_days=30). The first call auto-archives the snapshot; the second reads them all and computes deltas.

3. Senior-PM SOP on demand

"Apply the senior-PM analysis SOP to IDEA-014 — I want target users, competition, market signal, risks, MVP scope, out-of-scope, and RICE rationale before I score it."

Chains: get_plan_context (loads methodology + glossary) → fetch_initiative("IDEA-014") → analyze_initiative("IDEA-014", framework="default") → AI fills checklist in response → add_initiative(overwrite=true) → score_initiative.

4. Quarterly roadmap from Notion triage

"Pull every Notion idea in the Triage view, rank them with RICE, then pack a Q3 2026 roadmap assuming 4 engineers and 20% buffer. Tell me if the feature/tech-debt/strategic mix looks healthy."

Chains: list_initiatives(status="triage") → rank_backlog → generate_roadmap(capacity_engineer_months=12, period="Q3 2026", buffer_pct=20) → analyze_roadmap_balance.

Self-reinforcement layer

get_planning_history + get_decision_signature + get_telemetry are the trio that makes mk-plan-master measure its own decision quality over time. The mk-spec-master v0.4 pattern, applied one step upstream.

Same shape as mk-spec-master's get_spec_history / get_drift_signature / get_telemetry, so if you already trust that pattern you know the layout.

The decisions[] audit trail on every initiative ("why did we deprioritize this last quarter?") is what kills the bouncing back problem. No more "didn't we discuss this in March?" — March's RICE breakdown is in the index with its confidence and effort values.

Why this is missing from the ecosystem

See docs/prd.md §4 for the full positioning.

Status

77 tests passing on Python 3.10 / 3.11 / 3.12 / 3.13.

Family

• mk-spec-master — AI 規格大師. Spec → scenarios → coverage matrix. generate_spec_draft output is shaped to drop into its parse_spec(raw_text=...) verbatim.

• mk-qa-master — AI 測試大師. Scenarios → runnable tests in pytest / Jest / Cypress / Go test / Maestro.

The family loop: mk-plan-master → mk-spec-master → your IDE → mk-qa-master → back into mk-spec-master coverage.

License

MIT © 2026 Jack Kao — see LICENSE.

Plain-English version: personal use, commercial use, modification, redistribution — all allowed. The only requirement is that you keep the copyright and license notice in your copy. No warranty: if it breaks in production, you can't come after the author.

Built by Jack Kao . Part of the mk-* family: mk-qa-master + mk-spec-master + mk-plan-master.

If this saved you time, a coffee goes a long way.