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. •

   Determine the workflow schema

   Use the default schema (omit --schema) unless the user explicitly requests a different workflow.

   Use a different schema only if the user mentions:

   • •A specific schema name → use --schema <name>
   • •"show workflows" or "what workflows" → run openspec schemas --json and let them choose

   Otherwise: Omit --schema to use the default (spec-td).

3. •

   Acquire the epic_id (for spec-td schema)

   If using the spec-td schema (v1), you MUST acquire an epic ID for task tracking in td.

   This is a user-provided value. Help them get one:

   bash

   # Show existing epics they can associate with
   td list -t epic
   

   Ask the user:

   "Which epic should this change be associated with?

   • •Provide an existing epic ID (e.g., td-abc123)
   • •Or I can create a new epic for this work. What should it be called?"

   If user wants a new epic, create it:

   bash

   td create -t epic -d "<epic-description>"
   

   This returns the new epic ID.

   Store this epic_id: You'll include it in the proposal frontmatter.

   CRITICAL: Do NOT proceed without a valid, user-confirmed epic_id.

4. •

   Create the change directory

   bash

   openspec new change "<name>"
   

   Add --schema <name> only if the user requested a specific workflow. This creates a scaffolded change at openspec/changes/<name>/ with the selected schema.

5. •

   Show the artifact status

   bash

   openspec status --change "<name>"
   

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

6. •

   Get instructions for the first artifact The first artifact depends on the schema (e.g., proposal for spec-td). 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.

   For spec-td schema, the first artifact is proposal. When creating:

   TD Structure:

   • •Proposal corresponds to ONE feature/bug (parent=epic_id)
   • •Create it: td create -t feature -d "<proposal-description>" --parent <epic_id>
   • •Store the resulting ID as proposal_feature_id in proposal frontmatter
   • •Each spec created later will be a feature/bug with parent=proposal_feature_id

   You'll use the epic_id you acquired in step 3.

7. •

   STOP and wait for user direction

Output

After completing the steps, summarize:

• •Change name and location
• •Schema/workflow being used 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
• •CRITICAL (spec-td schema): Must acquire epic_id from user before creating change directory
• •Do NOT auto-generate or assume epic_id—it must be user-provided or user-confirmed
• •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
• •Pass --schema if using a non-default workflow
• •For spec-td schema, if epic_id not provided, block progress and ask user to provide or create one