openspec-new-change

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

1. •

   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.

2. •

   Select a workflow schema

   Run openspec schemas --json to get available schemas with descriptions.

   Use the AskUserQuestion tool to let the user choose a workflow:

   • •Present each schema with its description
   • •Mark spec-driven as "(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.

3. •

   Create the change directory

   bash

   openspec new change "<name>" --schema "<selected-schema>"
   

   This creates a scaffolded change at openspec/changes/<name>/ with the selected schema.

4. •

   Show the artifact status

   bash

   openspec status --change "<name>"
   

   This shows which artifacts need to be created and which are ready (dependencies satisfied).

5. •

   Get instructions for the first artifact The first artifact depends on the schema (e.g., proposal for spec-driven, spec for tdd). Check the status output to find the first artifact with status "ready".

   bash

   openspec instructions <first-artifact-id> --change "<name>"
   

   This outputs the template and context for creating the first artifact.

6. •

   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