---
name: openspec-propose
description: Propose a new change and generate all artifacts (proposal, design, tasks) in one step, ready for implementation. Use when the user wants to describe what they want to build and get a complete change proposal.
license: MIT
compatibility: Claude Code — no external CLI required.
metadata:
  author: openspec (adapted for Claude Code)
  version: "1.0-claude"
  source: SAP-samples/cap-agentic-engineered
---

Propose a new change — create the change folder and generate all artifacts in one step.

> **Adapted for Claude Code.** No `openspec` CLI. A change is a folder under
> `openspec/changes/<name>/` containing three Markdown files you create directly with
> the Write tool. Templates are embedded below.

I'll create a change with artifacts:
- `proposal.md` (what & why)
- `design.md` (how)
- `tasks.md` (implementation steps)

When ready to implement, use the `openspec-apply-change` skill.

---

**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) 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. **Create the change directory**

   ```bash
   mkdir -p openspec/changes/<name>
   ```

   If a folder with that name already exists, ask whether to continue the existing change
   (use `openspec-apply-change`) or pick a new name.

3. **Track progress**

   Use your task-tracking tool (`TaskCreate` / `TaskUpdate`) to track the three artifacts.

4. **Create the artifacts in order: proposal → design → tasks**

   For each artifact, read the previously created artifact(s) for context, then Write the
   file using the templates below. Apply project context and conventions as constraints —
   do NOT paste meta-instructions into the files.

   For SAP artifacts, **consult the relevant MCP server before writing design or tasks**
   that touch CDS, Fiori, or UI5 (see the `sap-cap`, `sap-fiori`, `sap-ui5` skills). Don't
   guess SAP behavior into a design.

   **`proposal.md` template**
   ```markdown
   # <Change Title>

   ## Why
   <the problem or motivation — what's broken or missing, and why now>

   ## What Changes
   <high-level summary of the change in 2–5 bullets>

   ## Scope
   - In scope: <...>
   - Out of scope: <...>

   ## Impact
   <affected capabilities, entities, services, UIs, integrations>
   ```

   **`design.md` template**
   ```markdown
   # Design: <Change Title>

   ## Approach
   <how it will be built>

   ## Architecture / Data Flow
   <entities, service handlers, annotations, UI; ASCII diagram if helpful>

   ## Decisions
   - <decision> — <rationale>

   ## Alternatives Considered
   - <alternative> — <why not>

   ## Risks & Open Questions
   - <...>
   ```

   **`tasks.md` template**
   ```markdown
   # Tasks: <Change Title>

   - [ ] 1. <task>
   - [ ] 2. <task>
   - [ ] 3. <task>
   ```

5. **Verify and show final status**

   Confirm all three files exist, then list them.

   ```bash
   ls -1 openspec/changes/<name>
   ```

**Output**

After completing all artifacts, summarize:
- Change name and location (`openspec/changes/<name>/`)
- The artifacts created with brief descriptions
- "All artifacts created! Ready for implementation."
- "Use the `openspec-apply-change` skill (or ask me to implement) to start working on the tasks."

**Guardrails**
- Create ALL three artifacts (proposal, design, tasks) before declaring the change apply-ready
- Always read dependency artifacts before creating the next one
- If context is critically unclear, ask the user — but prefer reasonable decisions to keep momentum
- If a change with that name already exists, ask whether to continue it or create a new one
- Verify each file exists after writing before proceeding to the next
- `context`/`rules` are constraints for YOU — never copy them into the artifact files