joplin-llm-wiki: Command for Claude Code

Create a complete Spectra change proposal — from requirement to validated artifacts — in a single workflow.

Input: The argument after /spectra:propose is the requirement description. Examples:

• /spectra:propose add dark mode
• /spectra:propose fix the login page crash
• /spectra:propose improve search performance

If no argument is provided, the workflow will extract requirements from conversation context or ask.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

Steps

1. Determine the requirement source

   a. Argument provided (e.g., "add dark mode") → use it as the requirement description, skip to deriving the change name below.

   b. Plan file available:

   • Check if the conversation context mentions a plan file path (plan mode system messages include the path like .cursor/plans/<name>.md)
   • If found, check if the file exists at .cursor/plans/
   • If a plan file is found, use the AskUserQuestion tool to ask:
     • Option 1: Use the plan file
     • Option 2: Use conversation context
   • If conversation context has no relevant discussion, mention this when presenting the choice
   • If the user picks the plan file → read it and extract:
     • plan_title (H1 heading) → use as requirement description
     • plan_context (Context section) → use as proposal Why/Motivation content
     • plan_stages (numbered implementation stages) → use for artifact creation
     • plan_files (all file paths mentioned) → use for Impact section
   • If the user picks conversation context → fall through to (c)

   c. Conversation context → attempt to extract requirements from conversation history

   • If context is insufficient, use the AskUserQuestion tool to ask what they want to build

   From the resolved description, derive a kebab-case change name (e.g., "add dark mode" → add-dark-mode). Do not keep archive-style date prefixes in active change names. If the source name starts with YYYY-MM-DD-, strip that date prefix before running spectra new change; archived change names and directories are historical references, not active names to reuse.

   IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Classify the change type

   Based on the requirement, classify the change into one of three types:

   Type	When to use
   Feature	New functionality, new capabilities
   Bug Fix	Fixing existing behavior, resolving errors
   Refactor	Architecture improvements, performance optimization, UI adjustments

   This determines the proposal template format in step 5.

3. Scan existing specs for relevance

   Before creating the change, check if any existing specs overlap:

   1. Use the Glob tool to list all files matching openspec/specs/*/spec.md
   2. Extract directory names as the spec identifier list
   3. Compare against the user's description to identify related specs (max 5 candidates)
   4. For each candidate (max 3), read the first 10 lines to retrieve the Purpose section
   5. If related specs are found, display them as an informational summary

   IMPORTANT:

   • If related specs are found, display them but do NOT stop or ask for confirmation — continue to the next step
   • If no related specs are found, silently proceed without mentioning the scan

4. Create the change directory

   spectra new change "<name>" --agent cursor
   

   If a change with that name already exists, suggest continuing the existing change instead of creating a new one.

5. Write the proposal

   IMPORTANT — file path rules for the ## Impact section:

   • All file paths SHALL be written relative to the project root (e.g., src/lib/foo.ts, src-tauri/crates/core/src/bar.rs, docs/specs/specs/auth/spec.md).
   • Do NOT use relative fragments (e.g., parser/mod.rs, core/mod.rs) — preflight rejects them as non-anchored paths.
   • Do NOT wrap shell commands in backticks inside artifact text (e.g., `git mv a.rs b.rs`) — preflight's backtick extractor will otherwise mis-parse the command as a file reference.
   • When referring to a file without naming its concrete path, use descriptive prose (e.g., "Parser 入口檔") rather than a backticked path fragment.