openspec-new-change
Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
When & Why to Use This Skill
The openspec-new-change skill automates the initiation of software development tasks using a structured, artifact-driven workflow. It streamlines the process of creating new features or fixes by scaffolding directories, selecting workflow schemas (like spec-driven or TDD), and providing step-by-step instructions for artifact creation, ensuring consistency and architectural integrity in technical projects.
Use Cases
- Feature Scaffolding: Quickly set up the directory structure and initial templates for a new software feature using a standardized kebab-case naming convention.
- Workflow Standardization: Enforce specific development methodologies, such as spec-driven design or Test-Driven Development (TDD), to maintain high-quality engineering standards.
- Change Management: Track the progress of various development artifacts (proposals, specs, designs) to ensure all dependencies are satisfied before moving to the implementation phase.
- Automated Documentation: Generate initial templates and context for technical artifacts, reducing the manual overhead of starting new engineering tasks.
| name | openspec-new-change |
|---|---|
| description | Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach. |
Start a new change using the experimental artifact-driven approach.
Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.
Steps
If no clear input provided, ask what they want to build
Use the AskUserQuestion tool (open-ended, no preset options) to ask:
"What change do you want to work on? Describe what you want to build or fix."
From their description, derive a kebab-case name (e.g., "add user authentication" →
add-user-auth).IMPORTANT: Do NOT proceed without understanding what the user wants to build.
Select a workflow schema
Run
openspec schemas --jsonto get available schemas with descriptions.Use the AskUserQuestion tool to let the user choose a workflow:
- Present each schema with its description
- Mark
spec-drivenas "(default)" if it's available - Example options: "spec-driven - proposal → specs → design → tasks (default)", "tdd - tests → implementation → docs"
If user doesn't have a preference, default to
spec-driven.Create the change directory
openspec new change "<name>" --schema "<selected-schema>"This creates a scaffolded change at
openspec/changes/<name>/with the selected schema.Show the artifact status
openspec status --change "<name>"This shows which artifacts need to be created and which are ready (dependencies satisfied).
Get instructions for the first artifact The first artifact depends on the schema (e.g.,
proposalfor spec-driven,specfor tdd). Check the status output to find the first artifact with status "ready".openspec instructions <first-artifact-id> --change "<name>"This outputs the template and context for creating the first artifact.
STOP and wait for user direction
Output
After completing the steps, summarize:
- Change name and location
- Selected schema/workflow and its artifact sequence
- Current status (0/N artifacts complete)
- The template for the first artifact
- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
Guardrails
- Do NOT create any artifacts yet - just show the instructions
- Do NOT advance beyond showing the first artifact template
- If the name is invalid (not kebab-case), ask for a valid name
- If a change with that name already exists, suggest continuing that change instead
- Always pass --schema to preserve the user's workflow choice