/plan — Create, Update, or List Plans

Usage

/plan create <file_path> [--prefix=X] [--priority=P1-P5] [--type=X] [--feature-dir=X] /plan update <plan_slug> [--priority=X] [--status=X] [--prefix=X] [--type=X] [--tags=a,b,c] /plan list [args]

Subcommands

/plan create — Create a New Plan

Reads a plan from a text/markdown file, extracts the title, generates metadata, writes the canonical file to ~/.claude/plans/ , and upserts to the KB in one step.

Step 1 — Parse Arguments

Argument Required Description

file_path yes Path to a text or markdown file containing the plan

--prefix=X

no Story prefix (e.g., APIP , DASH )

--priority=P1-P5

no Priority level (default: P3 )

--type=X

no Plan type override (feature, refactor, migration, infra, tooling, workflow, audit, spike)

--feature-dir=X

no Target feature directory

Read the file using the Read tool. The file must exist.

Step 2 — Extract Title

Extract the title from the first # Heading line in the file. If no # heading exists, use the filename (without extension) as the title.

Step 3 — Generate Slug

• Take the title

• Lowercase it

• Replace non-alphanumeric characters with hyphens

• Collapse multiple consecutive hyphens into one

• Trim leading/trailing hyphens

• Truncate to 60 characters

• Check uniqueness: call kb_list_plans with limit: 100 , scan returned slugs

• If collision: append -2 , -3 , etc. until unique

Step 4 — Infer Plan Type

If --type was not provided, infer from plan text using keyword matching (first match wins):

Type Keywords

feature new feature , product feature , user-facing , ui component , gallery , dashboard

refactor refactor , restructur , clean up , rename , consolidat

migration migrat , import , move to , port to , convert

infra infrastructure , deployment , docker , aws , lambda , terraform , ci/cd

tooling tooling , developer experience , dx , cli , script , automation

workflow workflow , agent , orchestrat , pipeline , scrum , story generation

audit audit , coverage , gap analysis , review all , assess

spike spike , investigation , experiment , explore , poc , proof of concept

Default to feature if no keywords match.

Step 5 — Infer Tags

Scan the plan text (case-insensitive) for keyword groups. If any keyword in a group matches, include that tag. Deduplicate and take the first 10.

Tag Keywords

database migration , schema , postgres , drizzle , sql

frontend react , component , ui , tailwind , shadcn , page

backend lambda , api , endpoint , handler , server

testing playwright , vitest , e2e , test coverage , cucumber

knowledge-base knowledge base , kb_ , mcp , embedding

story-generation story generation , pm-story , pm-generate , elab

performance token usage , performance , bottleneck , caching , optimiz

worktree worktree , branch , git

Step 6 — Extract Summary

Find the first non-heading, non-empty paragraph in the plan text (skip lines starting with # and blank lines). Join consecutive non-blank, non-heading lines into one string. Truncate to 500 characters.

Step 7 — Extract Additional Metadata

• story_prefix: If --prefix not provided, scan for the first UPPER-NNN pattern (e.g., WKFL-001 ) and extract the prefix

• estimated_stories: Scan for patterns like N stories , ~N stories and extract the number

• feature_dir: If --feature-dir not provided, scan for plans/future/platform/<dir> or plans/future/<dir> patterns

Step 8 — Write Markdown File

Copy the plan content to ~/.claude/plans/{slug}.md using the Write tool.

If the file content did NOT start with a # Title heading, prepend one:

{title}

{file content}

Step 9 — Upsert to KB

Load the kb_upsert_plan MCP tool via ToolSearch, then call it with:

{ "plan_slug": "{slug}", "title": "{title}", "raw_content": "{full markdown content}", "summary": "{extracted summary}", "plan_type": "{inferred or specified type}", "status": "draft", "priority": "{specified or P3}", "tags": ["{inferred tags}"], "source_file": "~/.claude/plans/{slug}.md", "story_prefix": "{if found}", "feature_dir": "{if found}", "estimated_stories": "{if found}" }

Step 10 — Display Confirmation

Output a summary:

Plan created successfully.

Slug: {slug} Title: {title} Type: {plan_type} Priority: {priority} Status: draft Tags: {tags, comma-separated} Source: {original file_path} File: ~/.claude/plans/{slug}.md

Next steps: /plans — verify it appears in the list /pm-bootstrap-workflow {slug} — generate stories from this plan /plan update {slug} --priority=P1 — adjust metadata

/plan update — Update Plan Metadata

Lightweight update of an existing plan's metadata fields.

Step 1 — Parse Arguments

Argument Required Description

plan_slug yes The slug of the plan to update

--priority=X

no New priority (P1-P5)

--status=X

no New status (draft, active, accepted, stories-created, in-progress, implemented, superseded, archived, blocked)

--prefix=X

no New story prefix

--type=X

no New plan type

--tags=a,b,c

no New tags (comma-separated, replaces existing)

--title=X

no New title

--feature-dir=X

no New feature directory (use none to clear)

--estimated-stories=N

no New estimated stories count (use none to clear)

At least one optional argument must be provided.

Step 2 — Call kb_update_plan

Load the kb_update_plan MCP tool via ToolSearch, then call it with the plan_slug and only the provided fields.

For --tags , split on commas and pass as an array. For fields set to none , pass null to clear them.

Step 3 — Display Confirmation

Plan "{plan_slug}" updated.

Changed: {list of changed fields with new values}

/plan list — List Plans

Delegates to the /plans skill. Pass through any arguments.

Run: /plans {args}

MCP Tools Used

• kb_upsert_plan — Insert or update a plan record (load via ToolSearch first)

• kb_update_plan — Lightweight metadata update (load via ToolSearch first)

• kb_list_plans — List plans for slug uniqueness check and listing (load via ToolSearch first)

Important: These tools must be loaded via ToolSearch before calling. Use:

• ToolSearch({ query: "select:mcp__knowledge-base__kb_upsert_plan" }) for create

• ToolSearch({ query: "select:mcp__knowledge-base__kb_update_plan" }) for update

• ToolSearch({ query: "select:mcp__knowledge-base__kb_list_plans" }) for list/uniqueness check

Fallback: If kb_upsert_plan or kb_update_plan are not available in the deferred tools list (MCP server may need restart), inform the user:

The kb_upsert_plan / kb_update_plan MCP tools are not currently available in the deferred tools registry. The MCP server likely needs a restart to pick them up.

To fix: restart the knowledge-base MCP server, then retry this command.

The plan markdown file has been written to ~/.claude/plans/{slug}.md. You can sync it to the DB later with: pnpm tsx apps/api/knowledge-base/src/scripts/migrate-plans-to-kb.ts