new

New Change Scaffold (Expanded Workflow)

You are starting a new change scaffold. This creates the change directory and waits for you to generate artifacts with /openspec:continue or /openspec:ff.

Note: This is part of the expanded workflow. For the simple path, use /openspec:propose which creates all artifacts in one step.

Upstream source: Fission-AI/OpenSpec

About the Expanded Workflow

The expanded workflow gives you granular control:

/openspec:new        → scaffold only (no artifacts yet)
/openspec:continue   → create one artifact at a time
/openspec:ff         → create all planning artifacts at once
/openspec:apply      → implement the tasks
/openspec:archive    → archive when done

Use this when you want to:

• Review and refine each artifact before moving to the next
• Experiment with different approaches for specific artifacts
• Customize the workflow at each step

Workflow

Step 1: Determine Change Name

If the user provided a name or description, derive a kebab-case name:

• "add user authentication" → add-user-auth
• "fix payment timeout" → fix-payment-timeout

If no name was provided, ask: "What's the name for this change? (kebab-case, e.g., add-dark-mode)"

Validate that the name doesn't already exist in openspec/changes/.

Step 2: Check Schema

If the user specified a schema (e.g., /openspec:new add-auth --schema spec-driven), use that. Otherwise, check openspec/config.yaml for a default schema. Default to spec-driven if no config exists.

Step 3: Create the Change Directory

Create the following structure:

openspec/changes/<change-name>/
└── .openspec.yaml

Create openspec/changes/<change-name>/.openspec.yaml:

schema: [schema-name]
created: [TODAY'S DATE ISO FORMAT]

Step 4: Show What's Ready

Display the first artifact that's ready to create (the one with no dependencies):

Change scaffold created: openspec/changes/[change-name]/
Schema: [schema-name]

Planning artifacts (in dependency order):
  → proposal.md    [READY — no dependencies]
  ⋯ specs/         [waiting for proposal]
  ⋯ design.md      [waiting for proposal]
  ⋯ tasks.md       [waiting for specs, design]

Next step options:
  /openspec:continue  → create proposal.md (one artifact at a time)
  /openspec:ff        → create all planning artifacts at once

Schema: spec-driven (Default)

The spec-driven schema has these artifacts and dependencies:

proposal  →  specs  →  tasks
     ↓                   ↑
   design  ─────────────┘

Artifact	Generates	Depends on
proposal	proposal.md	(none)
specs	specs/**/*.md	proposal
design	design.md	proposal
tasks	tasks.md	specs, design

Notes

• The .openspec.yaml file tracks the schema and creation date for this change
• Use --schema <name> to use a different schema (if custom schemas are configured)
• Custom schemas can be created in openspec/schemas/ following the schema.yaml format