You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## name: OpenSpec: Apply description: Implement an approved OpenSpec change and keep tasks in sync. category: OpenSpec tags: [openspec, apply]
4
4
5
5
<!-- OPENSPEC:START -->
6
-
7
6
**Guardrails**
8
-
9
7
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10
8
- 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
12
-
don't see it) if you need additional OpenSpec conventions or clarifications.
13
-
14
-
**Steps** Track these steps as TODOs and complete them one by one.
9
+
- 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.
15
10
11
+
**Steps**
12
+
Track these steps as TODOs and complete them one by one.
16
13
1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
17
14
2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
18
15
3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
19
16
4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
20
17
5. Reference `openspec list` or `openspec show <item>` when additional context is required.
21
18
22
19
**Reference**
23
-
24
20
- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
## name: OpenSpec: Archive description: Archive a deployed OpenSpec change and update specs. category: OpenSpec tags: [openspec, archive]
4
4
5
5
<!-- OPENSPEC:START -->
6
-
7
6
**Guardrails**
8
-
9
7
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10
8
- 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
12
-
don't see it) if you need additional OpenSpec conventions or clarifications.
9
+
- 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.
13
10
14
11
**Steps**
15
-
16
12
1. Determine the change ID to archive:
17
-
- If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by
18
-
slash-command arguments), use that value after trimming whitespace.
19
-
- If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface
20
-
likely IDs, share the relevant candidates, and confirm which one the user intends.
21
-
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a
22
-
confirmed change ID before proceeding.
13
+
- If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
14
+
- If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
15
+
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
23
16
- If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
24
-
2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing,
25
-
already archived, or otherwise not ready to archive.
26
-
3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use
27
-
`--skip-specs` only for tooling-only work).
17
+
2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
18
+
3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
28
19
4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
29
20
5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
30
21
31
22
**Reference**
32
-
33
23
- Use `openspec list` to confirm change IDs before archiving.
34
24
- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
## name: OpenSpec: Proposal description: Scaffold a new OpenSpec change and validate strictly. category: OpenSpec tags: [openspec, change]
4
4
5
5
<!-- OPENSPEC:START -->
6
-
7
6
**Guardrails**
8
-
9
7
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10
8
- 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
12
-
don't see it) if you need additional OpenSpec conventions or clarifications.
9
+
- 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.
13
10
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
14
-
- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and
15
-
spec deltas). Implementation happens in the apply stage after approval.
11
+
- 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.
16
12
17
13
**Steps**
18
-
19
-
1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs
20
-
(e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
21
-
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under
22
-
`openspec/changes/<id>/`.
23
-
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas
24
-
with clear relationships and sequencing.
25
-
4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or
26
-
demands trade-off discussion before committing to specs.
27
-
5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using
28
-
`## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference
29
-
related capabilities when relevant.
30
-
6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include
31
-
validation (tests, tooling), and highlight dependencies or parallelizable work.
14
+
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.
15
+
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
16
+
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
17
+
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.
18
+
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.
19
+
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.
32
20
7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
33
21
34
22
**Reference**
35
-
36
-
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation
37
-
fails.
23
+
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
38
24
- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
39
-
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation
40
-
realities.
41
-
25
+
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the
315
-
change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing
316
-
requirement.
317
-
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full,
318
-
updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you
319
-
provide here; partial deltas will drop previous details.
320
-
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content)
321
-
referencing the new name.
312
+
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
313
+
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
314
+
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
322
315
323
-
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at
324
-
archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
316
+
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
325
317
326
318
Authoring a MODIFIED requirement correctly:
327
319
@@ -439,7 +431,7 @@ notifications/spec.md
439
431
440
432
### Simplicity First
441
433
442
-
- Default to \<100 lines of new code
434
+
- Default to <100 lines of new code
443
435
- Single-file implementations until proven insufficient
0 commit comments