spectra-propose

name	spectra-propose
description	Create a change proposal with all required artifacts
effort	xhigh
license	MIT
compatibility	Requires spectra CLI.
metadata	{"author":"spectra","version":"1.0","generatedBy":"Spectra"}

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 ~/.claude/plans/<name>.md)
   • If found, check if the file exists at ~/.claude/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

---

Rationalization Table

What You're Thinking	What You Should Do
"The requirements are clear enough, no need for discuss"	Fine if true — but check you're not skipping because you're lazy
"This artifact isn't needed for this change"	Check applyRequires — if it's in the dependency chain, create it
"The spec doesn't need scenarios, the requirement is obvious"	Obvious to you now. Write scenarios for the implementer who doesn't have your context
"I'll keep the design brief, code will be self-explanatory"	Design exists so implementers don't reverse-engineer intent. Be specific
"This is a small change, skip the scope check"	Small changes touching 5 subsystems aren't small. Check
"The placeholder is fine for now, I'll fill it in later"	There is no "later" — implementation is next. Fill it in now

---

9. Analyze-Fix Loop (max 2 iterations)

   1. Run spectra analyze <change-name> --json
   2. Filter findings to Critical and Warning only (ignore Suggestion)
   3. If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
   4. If Critical/Warning findings exist: a. Show: "Found N issue(s), fixing... (attempt M/2)" b. Fix each finding in the affected artifact c. Re-run spectra analyze <change-name> --json d. Repeat up to 2 total iterations
   5. After 2 attempts, if findings remain:
      • Show remaining findings as a summary
      • Proceed normally (do NOT block)

10. Validation

    spectra validate "<name>"
    

    If validation fails, fix errors and re-validate.

11. Park the change and end the workflow

    Show summary:

    • Change name and location
    • List of artifacts created
    • Validation result

    Then unconditionally execute:

    spectra park "<name>"
    

    Inform the user that the change is parked and that running /spectra-apply <change-name> when ready will auto-unpark the change and start implementation.

    If you are currently in Codex Plan Mode, also remind the user to switch the session to normal mode before running /spectra-apply <change-name>. This is only a reminder: do NOT try to use ExitPlanMode or EnterPlanMode, do NOT ask whether to switch modes, and do NOT invoke apply.

    The propose workflow ENDS here. Do NOT invoke /spectra-apply. Do NOT call AskUserQuestion to ask whether to park or apply. This behavior is identical across Auto Mode, interactive mode, and any other agent mode — parking is unconditional and does not depend on AskUserQuestion availability or UI auto-accept settings.

Artifact Creation Guidelines

• Follow the instruction field from spectra instructions for each artifact type
• Read dependency artifacts for context before creating new ones
• Use template as the structure for your output file - fill in its sections
• IMPORTANT: context and rules are constraints for YOU, not content for the file
  • Do NOT copy <context>, <rules>, <project_context> blocks into the artifact
  • These guide what you write, but should never appear in the output
• Parallel task markers ([P]): When creating the tasks artifact, first read .spectra.yaml. If parallel_tasks: true is set, add [P] markers to tasks that can be executed in parallel. Format: - [ ] [P] Task description. A task qualifies for [P] if it targets different files from other pending tasks AND has no dependency on incomplete tasks in the same group. When parallel_tasks is not enabled, do NOT add [P] markers.

Guardrails

• Create all artifacts needed for implementation. Optional artifacts (those not in the applyRequires dependency chain) may be skipped if their inclusion criteria don't apply.
• Always read dependency artifacts before creating a new one
• If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
• If a change with that name already exists, suggest continuing that change instead
• Verify each artifact file exists after writing before proceeding to next
• NEVER write application code or implement features during this workflow
• NEVER skip the artifact workflow to write code directly
• NEVER reinterpret requirements by ignoring the proposal file
• NEVER invoke /spectra-apply — this workflow ends after artifact creation. The user decides when to start implementation
• If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response