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
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).
IMPORTANT: Do NOT proceed without understanding what the user wants to build.
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.
Scan existing specs for relevance
Before creating the change, check if any existing specs overlap:
- Use the Glob tool to list all files matching
openspec/specs/*/spec.md
- Extract directory names as the spec identifier list
- Compare against the user's description to identify related specs (max 5 candidates)
- For each candidate (max 3), read the first 10 lines to retrieve the Purpose section
- 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
Create the change directory
spectra new change "<name>" --agent claude
If a change with that name already exists, suggest continuing the existing change instead of creating a new one.
Write the proposal
Get instructions:
spectra instructions proposal --change "<name>" --json
Write the proposal file using the template from instructions, with the following format based on change type:
Feature
## Why
<!-- Why this functionality is needed -->
## What Changes
<!-- What will be different -->
## Capabilities
### New Capabilities
- `<capability-name>`: <brief description>
### Modified Capabilities
(none)
## Impact
- Affected specs: <new or modified capabilities>
- Affected code: <list of affected files>
Bug Fix
## Problem
<!-- Current broken behavior -->
## Root Cause
<!-- Why it happens -->
## Proposed Solution
<!-- How to fix -->
## Success Criteria
<!-- Expected behavior after fix, verifiable conditions -->
## Impact
- Affected code: <list of affected files>
Refactor / Enhancement
## Summary
<!-- One sentence description -->
## Motivation
<!-- Why this is needed -->
## Proposed Solution
<!-- How to do it -->
## Alternatives Considered (optional)
<!-- Other approaches considered and why not -->
## Impact
- Affected specs: <affected capabilities>
- Affected code: <list of affected files>
Get the artifact build order
spectra status --change "<name>" --json
Parse the JSON to get:
applyRequires: array of artifact IDs needed before implementation
artifacts: list of all artifacts with their status and dependencies
Create remaining artifacts in sequence
Loop through artifacts in dependency order (skip proposal since it's already done):
a. For each artifact that is ready (dependencies satisfied):
b. Continue until all applyRequires artifacts are complete
- After creating each artifact, re-run
spectra status --change "<name>" --json
- Check if every artifact ID in
applyRequires has status: "done"
- Stop when all
applyRequires artifacts are done
c. If an artifact requires user input (unclear context):
- Use AskUserQuestion tool to clarify
- Then continue with creation
Analyze-Fix Loop (max 2 iterations)
- Run
spectra analyze <change-name> --json
- Filter findings to Critical and Warning only (ignore Suggestion)
- If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
- 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
- After 2 attempts, if findings remain:
- Show remaining findings as a summary
- Proceed normally (do NOT block)
Validation
spectra validate "<name>"
If validation fails, fix errors and re-validate.
Show final status and end workflow
Show summary:
- Change name and location
- List of artifacts created
- Validation result
Use AskUserQuestion tool to ask what to do next. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:
- First option (will be auto-selected): "Park" — Execute
spectra park "<name>" to park the change, then inform the user they can run /spectra-apply <change-name> when ready (which will auto-unpark).
- Second option: "Apply" — Invoke
/spectra-apply <change-name> to start implementation.
If AskUserQuestion tool is not available, execute spectra park "<name>" and inform the user to run /spectra-apply <change-name> when ready. Then STOP — do not continue.
After the user responds, if they chose "Park", execute spectra park "<name>" and the workflow is OVER. If they chose "Apply", invoke /spectra-apply <change-name> to begin implementation.
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 openspec/config.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
- 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
1---2name: spectra-propose-33description: "Create a change proposal with all required artifacts"4license: MIT5compatibility: Requires spectra CLI.6metadata:7 source: https://skillmd.com/skills/dansnow/spectra-propose-38 author: spectra9 version: "1.0"10 generatedBy: "Spectra"11---1213Create a complete Spectra change proposal — from requirement to validated artifacts — in a single workflow.1415**Input**: The argument after `/spectra-propose` is the requirement description. Examples:1617- `/spectra-propose add dark mode`18- `/spectra-propose fix the login page crash`19- `/spectra-propose improve search performance`2021If no argument is provided, the workflow will extract requirements from conversation context or ask.2223**Prerequisites**: This skill requires the `spectra` CLI. If any `spectra` command fails with "command not found" or similar, report the error and STOP.2425**Steps**26271. **Determine the requirement source**2829 a. **Argument provided** (e.g., "add dark mode") → use it as the requirement description, skip to deriving the change name below.3031 b. **Plan file available**:32 - Check if the conversation context mentions a plan file path (plan mode system messages include the path like `~/.claude/plans/<name>.md`)33 - If found, check if the file exists at `~/.claude/plans/`34 - If a plan file is found, use the **AskUserQuestion tool** to ask:35 - Option 1: Use the plan file36 - Option 2: Use conversation context37 - If conversation context has no relevant discussion, mention this when presenting the choice38 - If the user picks the plan file → read it and extract:39 - `plan_title` (H1 heading) → use as requirement description40 - `plan_context` (Context section) → use as proposal Why/Motivation content41 - `plan_stages` (numbered implementation stages) → use for artifact creation42 - `plan_files` (all file paths mentioned) → use for Impact section43 - If the user picks conversation context → fall through to (c)4445 c. **Conversation context** → attempt to extract requirements from conversation history46 - If context is insufficient, use the **AskUserQuestion tool** to ask what they want to build4748 From the resolved description, derive a kebab-case change name (e.g., "add dark mode" → `add-dark-mode`).4950 **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.51522. **Classify the change type**5354 Based on the requirement, classify the change into one of three types:5556 | Type | When to use |57 | -------- | ------------------------------------------------------------------- |58 | Feature | New functionality, new capabilities |59 | Bug Fix | Fixing existing behavior, resolving errors |60 | Refactor | Architecture improvements, performance optimization, UI adjustments |6162 This determines the proposal template format in step 5.63643. **Scan existing specs for relevance**6566 Before creating the change, check if any existing specs overlap:67 1. Use the **Glob tool** to list all files matching `openspec/specs/*/spec.md`68 2. Extract directory names as the spec identifier list69 3. Compare against the user's description to identify related specs (max 5 candidates)70 4. For each candidate (max 3), read the first 10 lines to retrieve the Purpose section71 5. If related specs are found, display them as an informational summary7273 **IMPORTANT**:74 - If related specs are found, display them but do NOT stop or ask for confirmation — continue to the next step75 - If no related specs are found, silently proceed without mentioning the scan76774. **Create the change directory**7879 ```bash80 spectra new change "<name>" --agent claude81 ```8283 If a change with that name already exists, suggest continuing the existing change instead of creating a new one.84855. **Write the proposal**8687 Get instructions:8889 ```bash90 spectra instructions proposal --change "<name>" --json91 ```9293 Write the proposal file using the template from instructions, with the following format based on change type:9495 ### Feature9697 ```markdown98 ## Why99100 <!-- Why this functionality is needed -->101102 ## What Changes103104 <!-- What will be different -->105106 ## Capabilities107108 ### New Capabilities109110 - `<capability-name>`: <brief description>111112 ### Modified Capabilities113114 (none)115116 ## Impact117118 - Affected specs: <new or modified capabilities>119 - Affected code: <list of affected files>120 ```121122 ### Bug Fix123124 ```markdown125 ## Problem126127 <!-- Current broken behavior -->128129 ## Root Cause130131 <!-- Why it happens -->132133 ## Proposed Solution134135 <!-- How to fix -->136137 ## Success Criteria138139 <!-- Expected behavior after fix, verifiable conditions -->140141 ## Impact142143 - Affected code: <list of affected files>144 ```145146 ### Refactor / Enhancement147148 ```markdown149 ## Summary150151 <!-- One sentence description -->152153 ## Motivation154155 <!-- Why this is needed -->156157 ## Proposed Solution158159 <!-- How to do it -->160161 ## Alternatives Considered (optional)162163 <!-- Other approaches considered and why not -->164165 ## Impact166167 - Affected specs: <affected capabilities>168 - Affected code: <list of affected files>169 ```1701716. **Get the artifact build order**172173 ```bash174 spectra status --change "<name>" --json175 ```176177 Parse the JSON to get:178 - `applyRequires`: array of artifact IDs needed before implementation179 - `artifacts`: list of all artifacts with their status and dependencies1801817. **Create remaining artifacts in sequence**182183 Loop through artifacts in dependency order (skip proposal since it's already done):184185 a. **For each artifact that is `ready` (dependencies satisfied)**:186 - Get instructions:187 ```bash188 spectra instructions <artifact-id> --change "<name>" --json189 ```190 - The instructions JSON includes:191 - `context`: Project background (constraints for you - do NOT include in output)192 - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)193 - `template`: The structure to use for your output file194 - `instruction`: Schema-specific guidance195 - `outputPath`: Where to write the artifact196 - `dependencies`: Completed artifacts to read for context197 - `locale`: The language to write the artifact in (e.g., "Japanese (日本語)"). If present, you MUST write the artifact content in this language. Exception: spec files (specs/\*_/_.md) MUST always be written in English regardless of locale, because they use normative language (SHALL/MUST).198 - Read any completed dependency files for context199 - Create the artifact file using `template` as the structure200 - Apply `context` and `rules` as constraints - but do NOT copy them into the file201 - Show brief progress: "✓ Created <artifact-id>"202203 b. **Continue until all `applyRequires` artifacts are complete**204 - After creating each artifact, re-run `spectra status --change "<name>" --json`205 - Check if every artifact ID in `applyRequires` has `status: "done"`206 - Stop when all `applyRequires` artifacts are done207208 c. **If an artifact requires user input** (unclear context):209 - Use **AskUserQuestion tool** to clarify210 - Then continue with creation2112128. **Analyze-Fix Loop** (max 2 iterations)213 1. Run `spectra analyze <change-name> --json`214 2. Filter findings to **Critical and Warning only** (ignore Suggestion)215 3. If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed216 4. If Critical/Warning findings exist:217 a. Show: "Found N issue(s), fixing... (attempt M/2)"218 b. Fix each finding in the affected artifact219 c. Re-run `spectra analyze <change-name> --json`220 d. Repeat up to 2 total iterations221 5. After 2 attempts, if findings remain:222 - Show remaining findings as a summary223 - Proceed normally (do NOT block)2242259. **Validation**226227 ```bash228 spectra validate "<name>"229 ```230231 If validation fails, fix errors and re-validate.23223310. **Show final status and end workflow**234235 Show summary:236 - Change name and location237 - List of artifacts created238 - Validation result239240 Use **AskUserQuestion tool** to ask what to do next. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:241 - **First option (will be auto-selected)**: "Park" — Execute `spectra park "<name>"` to park the change, then inform the user they can run `/spectra-apply <change-name>` when ready (which will auto-unpark).242 - **Second option**: "Apply" — Invoke `/spectra-apply <change-name>` to start implementation.243244 If **AskUserQuestion tool** is not available, execute `spectra park "<name>"` and inform the user to run `/spectra-apply <change-name>` when ready. Then STOP — do not continue.245246 **After the user responds**, if they chose "Park", execute `spectra park "<name>"` and the workflow is OVER. If they chose "Apply", invoke `/spectra-apply <change-name>` to begin implementation.247248**Artifact Creation Guidelines**249250- Follow the `instruction` field from `spectra instructions` for each artifact type251- Read dependency artifacts for context before creating new ones252- Use `template` as the structure for your output file - fill in its sections253- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file254 - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact255 - These guide what you write, but should never appear in the output256- **Parallel task markers (`[P]`)**: When creating the **tasks** artifact, first read `openspec/config.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.257258**Guardrails**259260- Create ALL artifacts needed for implementation261- Always read dependency artifacts before creating a new one262- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum263- If a change with that name already exists, suggest continuing that change instead264- Verify each artifact file exists after writing before proceeding to next265- **NEVER** write application code or implement features during this workflow266- **NEVER** skip the artifact workflow to write code directly267- **NEVER** reinterpret requirements by ignoring the proposal file268- **NEVER** invoke `/spectra-apply` — this workflow ends after artifact creation. The user decides when to start implementation269- If **AskUserQuestion tool** is not available, ask the same questions as plain text and wait for the user's response