133 lines
4.1 KiB
Markdown
133 lines
4.1 KiB
Markdown
---
|
||
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
|