|
| 1 | +--- |
| 2 | +name: OpenSpec: Proposal |
| 3 | +description: Scaffold a new OpenSpec change and validate strictly. |
| 4 | +category: OpenSpec |
| 5 | +tags: [openspec, change] |
| 6 | +--- |
| 7 | +<!-- OPENSPEC:START --> |
| 8 | +**Guardrails** |
| 9 | +- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. |
| 10 | +- Keep changes tightly scoped to the requested outcome. |
| 11 | +- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. |
| 12 | +- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files. |
| 13 | +- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval. |
| 14 | + |
| 15 | +**Steps** |
| 16 | +1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification. |
| 17 | +2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`. |
| 18 | +3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing. |
| 19 | +4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs. |
| 20 | +5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant. |
| 21 | +6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. |
| 22 | +7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal. |
| 23 | + |
| 24 | +**Reference** |
| 25 | +- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails. |
| 26 | +- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones. |
| 27 | +- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities. |
| 28 | +<!-- OPENSPEC:END --> |
0 commit comments