---
type: agent/instruction
description: Guide for creating a new OpenSpec change
category: "openspec"
requires-openspec: true
instruction: Display errors to the user, otherwise follow the instructions and interact with the user to create a new openspec change
---
{{^args.0.value}}
**Error:** Missing required change-id argument.

Usage: `{{agent.prefix}}guide :openspec/change/new <change-id>`
Example: `{{agent.prefix}}guide :openspec/change/new add-user-authentication`

- The change-id should be kebab-case and verb-led (add-, update-, remove-, refactor-).

{{/args.0.value}}

{{#args.0.value}}
# Creating Change: {{args.0.value}}

**Instructions for Agent:**

Read `openspec/AGENTS.md` section "Creating Change Proposals" for complete technical details on file structure, validation, and formatting requirements.

**Your task:**

Gather requirements from the user through conversation to understand:
- What problem this solves or feature it adds
- Whether there are breaking changes
- Impact on architecture, performance, or security
- Which specs are affected (check `openspec list --specs`)
- Dependencies between specs if multiple are involved

Once you have sufficient context, create the proposal following the structure documented in `openspec/AGENTS.md`.

Keep it as a draft (no tasks.md) unless the user explicitly requests implementation planning.

After creating the change, refresh the cache by running `openspec list --json` and sending via {{tool_prefix}}send_file_content with path `.openspec-changes.json`.
{{/args.0.value}}
