124 lines
7.9 KiB
Markdown
124 lines
7.9 KiB
Markdown
---
|
|
name: openspec-propose
|
|
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
|
|
allowed-tools: Bash(openspec:*)
|
|
license: MIT
|
|
compatibility: Requires openspec CLI.
|
|
metadata:
|
|
author: openspec
|
|
version: "1.0"
|
|
generatedBy: "1.7.0"
|
|
---
|
|
|
|
Propose a new change - create the change and generate all artifacts in one step.
|
|
|
|
I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:
|
|
- proposal.md (what & why)
|
|
- `specs/<capability>/spec.md` (what the system must do - a delta, not the main spec)
|
|
- design.md (how)
|
|
- tasks.md (implementation steps)
|
|
|
|
When ready to implement, run $openspec-apply-change
|
|
|
|
---
|
|
|
|
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
|
|
|
|
**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**
|
|
|
|
Ask the user (open-ended, no preset options):
|
|
> "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
|
|
openspec new change "<name>"
|
|
```
|
|
This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
|
|
|
|
3. **Get the artifact build order**
|
|
```bash
|
|
openspec status --change "<name>" --json
|
|
```
|
|
Parse the JSON to get:
|
|
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
|
|
- `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on)
|
|
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
|
|
|
|
4. **Create every artifact in the required set**
|
|
|
|
Use a todo list to track progress through the artifacts.
|
|
|
|
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
|
|
|
|
a. **For each artifact that is `ready` (dependencies satisfied)**:
|
|
- Get instructions:
|
|
```bash
|
|
openspec instructions <artifact-id> --change "<name>" --json
|
|
```
|
|
- The instructions JSON includes:
|
|
- `context`: Project background (constraints for you - do NOT include in output)
|
|
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
|
|
- `template`: The structure to use for your output file
|
|
- `instruction`: Schema-specific guidance for this artifact type
|
|
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
|
|
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
|
|
- `dependencies`: Completed artifacts to read for context
|
|
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
|
|
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
|
|
- Otherwise create the artifact file using `template` as the structure and write it to `resolvedOutputPath`. If `resolvedOutputPath` is a glob, follow `instruction` to choose the concrete file path
|
|
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
|
|
- Show brief progress: "Created <artifact-id>"
|
|
|
|
b. **Continue until every artifact in the required set exists (not just `apply.requires`)**
|
|
- After creating each artifact, re-run `openspec status --change "<name>" --json`
|
|
- The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
|
|
- `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on
|
|
- An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one
|
|
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
|
|
- Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions <artifact-id> --change "<name>" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it
|
|
- Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway
|
|
- Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
|
|
|
|
c. **If an artifact requires user input** (unclear context):
|
|
- Ask the user to clarify
|
|
- Then continue with creation
|
|
|
|
5. **Show final status**
|
|
```bash
|
|
openspec status --change "<name>"
|
|
```
|
|
|
|
**Output**
|
|
|
|
After completing all artifacts, summarize:
|
|
- Change name and location
|
|
- List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
|
|
- What's ready: "All artifacts needed for implementation are ready."
|
|
- Prompt: "Run `$openspec-apply-change` or ask me to implement to start working on the tasks."
|
|
|
|
**Artifact Creation Guidelines**
|
|
|
|
- Follow the `instruction` field from `openspec instructions` for each artifact type - it is the authoritative guidance, even for familiar artifact names
|
|
- If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
|
|
- The schema defines what each artifact should contain - follow it
|
|
- Read dependency artifacts for context before creating new ones
|
|
- Use `template` as the structure for your output file - fill in its sections
|
|
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
|
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
|
- These guide what you write, but should never appear in the output
|
|
|
|
**Guardrails**
|
|
- Create every artifact the apply phase transitively depends on, not just the ids listed in `apply.requires`
|
|
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
|
|
- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
|
|
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
|
- Verify each artifact file exists after writing before proceeding to next
|