plan（计划）

/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

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

1. Take the title
2. Lowercase it
3. Replace non-alphanumeric characters with hyphens
4. Collapse multiple consecutive hyphens into one
5. Trim leading/trailing hyphens
6. Truncate to 60 characters
7. Check uniqueness: call kb_list_plans with limit: 100, scan returned slugs
8. 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):

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.

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

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