Personal outliner built with Rust.
init openspec
graham.systems
(Jul 12, 2026, 2:52 PM -0700)
ea200b8b
+930
+156
.claude/skills/openspec-apply-change/SKILL.md
+156
.claude/skills/openspec-apply-change/SKILL.md
···
1
+
---
2
+
name: openspec-apply-change
3
+
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Implement tasks from an OpenSpec change.
13
+
14
+
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
15
+
16
+
**Steps**
17
+
18
+
1. **Select the change**
19
+
20
+
If a name is provided, use it. Otherwise:
21
+
- Infer from conversation context if the user mentioned a change
22
+
- Auto-select if only one active change exists
23
+
- If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
24
+
25
+
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
26
+
27
+
2. **Check status to understand the schema**
28
+
```bash
29
+
openspec status --change "<name>" --json
30
+
```
31
+
Parse the JSON to understand:
32
+
- `schemaName`: The workflow being used (e.g., "spec-driven")
33
+
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
34
+
35
+
3. **Get apply instructions**
36
+
37
+
```bash
38
+
openspec instructions apply --change "<name>" --json
39
+
```
40
+
41
+
This returns:
42
+
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
43
+
- Progress (total, complete, remaining)
44
+
- Task list with status
45
+
- Dynamic instruction based on current state
46
+
47
+
**Handle states:**
48
+
- If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
49
+
- If `state: "all_done"`: congratulate, suggest archive
50
+
- Otherwise: proceed to implementation
51
+
52
+
4. **Read context files**
53
+
54
+
Read every file path listed under `contextFiles` from the apply instructions output.
55
+
The files depend on the schema being used:
56
+
- **spec-driven**: proposal, specs, design, tasks
57
+
- Other schemas: follow the contextFiles from CLI output
58
+
59
+
5. **Show current progress**
60
+
61
+
Display:
62
+
- Schema being used
63
+
- Progress: "N/M tasks complete"
64
+
- Remaining tasks overview
65
+
- Dynamic instruction from CLI
66
+
67
+
6. **Implement tasks (loop until done or blocked)**
68
+
69
+
For each pending task:
70
+
- Show which task is being worked on
71
+
- Make the code changes required
72
+
- Keep changes minimal and focused
73
+
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
74
+
- Continue to next task
75
+
76
+
**Pause if:**
77
+
- Task is unclear → ask for clarification
78
+
- Implementation reveals a design issue → suggest updating artifacts
79
+
- Error or blocker encountered → report and wait for guidance
80
+
- User interrupts
81
+
82
+
7. **On completion or pause, show status**
83
+
84
+
Display:
85
+
- Tasks completed this session
86
+
- Overall progress: "N/M tasks complete"
87
+
- If all done: suggest archive
88
+
- If paused: explain why and wait for guidance
89
+
90
+
**Output During Implementation**
91
+
92
+
```
93
+
## Implementing: <change-name> (schema: <schema-name>)
94
+
95
+
Working on task 3/7: <task description>
96
+
[...implementation happening...]
97
+
✓ Task complete
98
+
99
+
Working on task 4/7: <task description>
100
+
[...implementation happening...]
101
+
✓ Task complete
102
+
```
103
+
104
+
**Output On Completion**
105
+
106
+
```
107
+
## Implementation Complete
108
+
109
+
**Change:** <change-name>
110
+
**Schema:** <schema-name>
111
+
**Progress:** 7/7 tasks complete ✓
112
+
113
+
### Completed This Session
114
+
- [x] Task 1
115
+
- [x] Task 2
116
+
...
117
+
118
+
All tasks complete! Ready to archive this change.
119
+
```
120
+
121
+
**Output On Pause (Issue Encountered)**
122
+
123
+
```
124
+
## Implementation Paused
125
+
126
+
**Change:** <change-name>
127
+
**Schema:** <schema-name>
128
+
**Progress:** 4/7 tasks complete
129
+
130
+
### Issue Encountered
131
+
<description of the issue>
132
+
133
+
**Options:**
134
+
1. <option 1>
135
+
2. <option 2>
136
+
3. Other approach
137
+
138
+
What would you like to do?
139
+
```
140
+
141
+
**Guardrails**
142
+
- Keep going through tasks until done or blocked
143
+
- Always read context files before starting (from the apply instructions output)
144
+
- If task is ambiguous, pause and ask before implementing
145
+
- If implementation reveals issues, pause and suggest artifact updates
146
+
- Keep code changes minimal and scoped to each task
147
+
- Update task checkbox immediately after completing each task
148
+
- Pause on errors, blockers, or unclear requirements - don't guess
149
+
- Use contextFiles from CLI output, don't assume specific file names
150
+
151
+
**Fluid Workflow Integration**
152
+
153
+
This skill supports the "actions on a change" model:
154
+
155
+
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
156
+
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+114
.claude/skills/openspec-archive-change/SKILL.md
+114
.claude/skills/openspec-archive-change/SKILL.md
···
1
+
---
2
+
name: openspec-archive-change
3
+
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Archive a completed change in the experimental workflow.
13
+
14
+
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
15
+
16
+
**Steps**
17
+
18
+
1. **If no change name provided, prompt for selection**
19
+
20
+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
21
+
22
+
Show only active changes (not already archived).
23
+
Include the schema used for each change if available.
24
+
25
+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
26
+
27
+
2. **Check artifact completion status**
28
+
29
+
Run `openspec status --change "<name>" --json` to check artifact completion.
30
+
31
+
Parse the JSON to understand:
32
+
- `schemaName`: The workflow being used
33
+
- `artifacts`: List of artifacts with their status (`done` or other)
34
+
35
+
**If any artifacts are not `done`:**
36
+
- Display warning listing incomplete artifacts
37
+
- Use **AskUserQuestion tool** to confirm user wants to proceed
38
+
- Proceed if user confirms
39
+
40
+
3. **Check task completion status**
41
+
42
+
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
43
+
44
+
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
45
+
46
+
**If incomplete tasks found:**
47
+
- Display warning showing count of incomplete tasks
48
+
- Use **AskUserQuestion tool** to confirm user wants to proceed
49
+
- Proceed if user confirms
50
+
51
+
**If no tasks file exists:** Proceed without task-related warning.
52
+
53
+
4. **Assess delta spec sync state**
54
+
55
+
Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
56
+
57
+
**If delta specs exist:**
58
+
- Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
59
+
- Determine what changes would be applied (adds, modifications, removals, renames)
60
+
- Show a combined summary before prompting
61
+
62
+
**Prompt options:**
63
+
- If changes needed: "Sync now (recommended)", "Archive without syncing"
64
+
- If already synced: "Archive now", "Sync anyway", "Cancel"
65
+
66
+
If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
67
+
68
+
5. **Perform the archive**
69
+
70
+
Create the archive directory if it doesn't exist:
71
+
```bash
72
+
mkdir -p openspec/changes/archive
73
+
```
74
+
75
+
Generate target name using current date: `YYYY-MM-DD-<change-name>`
76
+
77
+
**Check if target already exists:**
78
+
- If yes: Fail with error, suggest renaming existing archive or using different date
79
+
- If no: Move the change directory to archive
80
+
81
+
```bash
82
+
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
83
+
```
84
+
85
+
6. **Display summary**
86
+
87
+
Show archive completion summary including:
88
+
- Change name
89
+
- Schema that was used
90
+
- Archive location
91
+
- Whether specs were synced (if applicable)
92
+
- Note about any warnings (incomplete artifacts/tasks)
93
+
94
+
**Output On Success**
95
+
96
+
```
97
+
## Archive Complete
98
+
99
+
**Change:** <change-name>
100
+
**Schema:** <schema-name>
101
+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
102
+
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
103
+
104
+
All artifacts complete. All tasks complete.
105
+
```
106
+
107
+
**Guardrails**
108
+
- Always prompt for change selection if not provided
109
+
- Use artifact graph (openspec status --json) for completion checking
110
+
- Don't block archive on warnings - just inform and confirm
111
+
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
112
+
- Show clear summary of what happened
113
+
- If sync is requested, use openspec-sync-specs approach (agent-driven)
114
+
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
+288
.claude/skills/openspec-explore/SKILL.md
+288
.claude/skills/openspec-explore/SKILL.md
···
1
+
---
2
+
name: openspec-explore
3
+
description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
13
+
14
+
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
15
+
16
+
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
17
+
18
+
---
19
+
20
+
## The Stance
21
+
22
+
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
23
+
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
24
+
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
25
+
- **Adaptive** - Follow interesting threads, pivot when new information emerges
26
+
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
27
+
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
28
+
29
+
---
30
+
31
+
## What You Might Do
32
+
33
+
Depending on what the user brings, you might:
34
+
35
+
**Explore the problem space**
36
+
- Ask clarifying questions that emerge from what they said
37
+
- Challenge assumptions
38
+
- Reframe the problem
39
+
- Find analogies
40
+
41
+
**Investigate the codebase**
42
+
- Map existing architecture relevant to the discussion
43
+
- Find integration points
44
+
- Identify patterns already in use
45
+
- Surface hidden complexity
46
+
47
+
**Compare options**
48
+
- Brainstorm multiple approaches
49
+
- Build comparison tables
50
+
- Sketch tradeoffs
51
+
- Recommend a path (if asked)
52
+
53
+
**Visualize**
54
+
```
55
+
┌─────────────────────────────────────────┐
56
+
│ Use ASCII diagrams liberally │
57
+
├─────────────────────────────────────────┤
58
+
│ │
59
+
│ ┌────────┐ ┌────────┐ │
60
+
│ │ State │────────▶│ State │ │
61
+
│ │ A │ │ B │ │
62
+
│ └────────┘ └────────┘ │
63
+
│ │
64
+
│ System diagrams, state machines, │
65
+
│ data flows, architecture sketches, │
66
+
│ dependency graphs, comparison tables │
67
+
│ │
68
+
└─────────────────────────────────────────┘
69
+
```
70
+
71
+
**Surface risks and unknowns**
72
+
- Identify what could go wrong
73
+
- Find gaps in understanding
74
+
- Suggest spikes or investigations
75
+
76
+
---
77
+
78
+
## OpenSpec Awareness
79
+
80
+
You have full context of the OpenSpec system. Use it naturally, don't force it.
81
+
82
+
### Check for context
83
+
84
+
At the start, quickly check what exists:
85
+
```bash
86
+
openspec list --json
87
+
```
88
+
89
+
This tells you:
90
+
- If there are active changes
91
+
- Their names, schemas, and status
92
+
- What the user might be working on
93
+
94
+
### When no change exists
95
+
96
+
Think freely. When insights crystallize, you might offer:
97
+
98
+
- "This feels solid enough to start a change. Want me to create a proposal?"
99
+
- Or keep exploring - no pressure to formalize
100
+
101
+
### When a change exists
102
+
103
+
If the user mentions a change or you detect one is relevant:
104
+
105
+
1. **Read existing artifacts for context**
106
+
- `openspec/changes/<name>/proposal.md`
107
+
- `openspec/changes/<name>/design.md`
108
+
- `openspec/changes/<name>/tasks.md`
109
+
- etc.
110
+
111
+
2. **Reference them naturally in conversation**
112
+
- "Your design mentions using Redis, but we just realized SQLite fits better..."
113
+
- "The proposal scopes this to premium users, but we're now thinking everyone..."
114
+
115
+
3. **Offer to capture when decisions are made**
116
+
117
+
| Insight Type | Where to Capture |
118
+
|----------------------------|--------------------------------|
119
+
| New requirement discovered | `specs/<capability>/spec.md` |
120
+
| Requirement changed | `specs/<capability>/spec.md` |
121
+
| Design decision made | `design.md` |
122
+
| Scope changed | `proposal.md` |
123
+
| New work identified | `tasks.md` |
124
+
| Assumption invalidated | Relevant artifact |
125
+
126
+
Example offers:
127
+
- "That's a design decision. Capture it in design.md?"
128
+
- "This is a new requirement. Add it to specs?"
129
+
- "This changes scope. Update the proposal?"
130
+
131
+
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
132
+
133
+
---
134
+
135
+
## What You Don't Have To Do
136
+
137
+
- Follow a script
138
+
- Ask the same questions every time
139
+
- Produce a specific artifact
140
+
- Reach a conclusion
141
+
- Stay on topic if a tangent is valuable
142
+
- Be brief (this is thinking time)
143
+
144
+
---
145
+
146
+
## Handling Different Entry Points
147
+
148
+
**User brings a vague idea:**
149
+
```
150
+
User: I'm thinking about adding real-time collaboration
151
+
152
+
You: Real-time collab is a big space. Let me think about this...
153
+
154
+
COLLABORATION SPECTRUM
155
+
════════════════════════════════════════════
156
+
157
+
Awareness Coordination Sync
158
+
│ │ │
159
+
▼ ▼ ▼
160
+
┌────────┐ ┌────────┐ ┌────────┐
161
+
│Presence│ │Cursors │ │ CRDT │
162
+
│ "3 │ │ Multi │ │Conflict│
163
+
│online" │ │ select │ │ free │
164
+
└────────┘ └────────┘ └────────┘
165
+
│ │ │
166
+
trivial moderate complex
167
+
168
+
Where's your head at?
169
+
```
170
+
171
+
**User brings a specific problem:**
172
+
```
173
+
User: The auth system is a mess
174
+
175
+
You: [reads codebase]
176
+
177
+
┌─────────────────────────────────────────────┐
178
+
│ CURRENT AUTH FLOW │
179
+
└─────────────────────────────────────────────┘
180
+
│
181
+
┌─────────────┼─────────────┐
182
+
▼ ▼ ▼
183
+
┌─────────┐ ┌─────────┐ ┌─────────┐
184
+
│ Google │ │ GitHub │ │ Email │
185
+
│ OAuth │ │ OAuth │ │ Magic │
186
+
└────┬────┘ └────┬────┘ └────┬────┘
187
+
│ │ │
188
+
└─────────────┼─────────────┘
189
+
▼
190
+
┌───────────┐
191
+
│ Session │
192
+
└─────┬─────┘
193
+
│
194
+
▼
195
+
┌───────────┐
196
+
│ Perms │
197
+
└───────────┘
198
+
199
+
I see three tangles. Which one's burning?
200
+
```
201
+
202
+
**User is stuck mid-implementation:**
203
+
```
204
+
User: /opsx:explore add-auth-system
205
+
The OAuth integration is more complex than expected
206
+
207
+
You: [reads change artifacts]
208
+
209
+
You're on task 4: "Implement OAuth flow"
210
+
211
+
Let me trace what's involved...
212
+
213
+
[draws diagram, explores options, suggests paths]
214
+
215
+
Want to update the design to reflect this?
216
+
Or add a spike task to investigate?
217
+
```
218
+
219
+
**User wants to compare options:**
220
+
```
221
+
User: Should we use Postgres or SQLite?
222
+
223
+
You: Generic answer is boring. What's the context?
224
+
225
+
User: A CLI tool that tracks local dev environments
226
+
227
+
You: That changes everything.
228
+
229
+
┌─────────────────────────────────────────────────┐
230
+
│ CLI TOOL DATA STORAGE │
231
+
└─────────────────────────────────────────────────┘
232
+
233
+
Key constraints:
234
+
• No daemon running
235
+
• Must work offline
236
+
• Single user
237
+
238
+
SQLite Postgres
239
+
Deployment embedded ✓ needs server ✗
240
+
Offline yes ✓ no ✗
241
+
Single file yes ✓ no ✗
242
+
243
+
SQLite. Not even close.
244
+
245
+
Unless... is there a sync component?
246
+
```
247
+
248
+
---
249
+
250
+
## Ending Discovery
251
+
252
+
There's no required ending. Discovery might:
253
+
254
+
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
255
+
- **Result in artifact updates**: "Updated design.md with these decisions"
256
+
- **Just provide clarity**: User has what they need, moves on
257
+
- **Continue later**: "We can pick this up anytime"
258
+
259
+
When it feels like things are crystallizing, you might summarize:
260
+
261
+
```
262
+
## What We Figured Out
263
+
264
+
**The problem**: [crystallized understanding]
265
+
266
+
**The approach**: [if one emerged]
267
+
268
+
**Open questions**: [if any remain]
269
+
270
+
**Next steps** (if ready):
271
+
- Create a change proposal
272
+
- Keep exploring: just keep talking
273
+
```
274
+
275
+
But this summary is optional. Sometimes the thinking IS the value.
276
+
277
+
---
278
+
279
+
## Guardrails
280
+
281
+
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
282
+
- **Don't fake understanding** - If something is unclear, dig deeper
283
+
- **Don't rush** - Discovery is thinking time, not task time
284
+
- **Don't force structure** - Let patterns emerge naturally
285
+
- **Don't auto-capture** - Offer to save insights, don't just do it
286
+
- **Do visualize** - A good diagram is worth many paragraphs
287
+
- **Do explore the codebase** - Ground discussions in reality
288
+
- **Do question assumptions** - Including the user's and your own
+74
.claude/skills/openspec-new-change/SKILL.md
+74
.claude/skills/openspec-new-change/SKILL.md
···
1
+
---
2
+
name: openspec-new-change
3
+
description: Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Start a new change using the experimental artifact-driven approach.
13
+
14
+
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
15
+
16
+
**Steps**
17
+
18
+
1. **If no clear input provided, ask what they want to build**
19
+
20
+
Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
21
+
> "What change do you want to work on? Describe what you want to build or fix."
22
+
23
+
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
24
+
25
+
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
26
+
27
+
2. **Determine the workflow schema**
28
+
29
+
Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
30
+
31
+
**Use a different schema only if the user mentions:**
32
+
- A specific schema name → use `--schema <name>`
33
+
- "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
34
+
35
+
**Otherwise**: Omit `--schema` to use the default.
36
+
37
+
3. **Create the change directory**
38
+
```bash
39
+
openspec new change "<name>"
40
+
```
41
+
Add `--schema <name>` only if the user requested a specific workflow.
42
+
This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
43
+
44
+
4. **Show the artifact status**
45
+
```bash
46
+
openspec status --change "<name>"
47
+
```
48
+
This shows which artifacts need to be created and which are ready (dependencies satisfied).
49
+
50
+
5. **Get instructions for the first artifact**
51
+
The first artifact depends on the schema (e.g., `proposal` for spec-driven).
52
+
Check the status output to find the first artifact with status "ready".
53
+
```bash
54
+
openspec instructions <first-artifact-id> --change "<name>"
55
+
```
56
+
This outputs the template and context for creating the first artifact.
57
+
58
+
6. **STOP and wait for user direction**
59
+
60
+
**Output**
61
+
62
+
After completing the steps, summarize:
63
+
- Change name and location
64
+
- Schema/workflow being used and its artifact sequence
65
+
- Current status (0/N artifacts complete)
66
+
- The template for the first artifact
67
+
- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
68
+
69
+
**Guardrails**
70
+
- Do NOT create any artifacts yet - just show the instructions
71
+
- Do NOT advance beyond showing the first artifact template
72
+
- If the name is invalid (not kebab-case), ask for a valid name
73
+
- If a change with that name already exists, suggest continuing that change instead
74
+
- Pass --schema if using a non-default workflow
+110
.claude/skills/openspec-propose/SKILL.md
+110
.claude/skills/openspec-propose/SKILL.md
···
1
+
---
2
+
name: openspec-propose
3
+
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.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Propose a new change - create the change and generate all artifacts in one step.
13
+
14
+
I'll create a change with artifacts:
15
+
- proposal.md (what & why)
16
+
- design.md (how)
17
+
- tasks.md (implementation steps)
18
+
19
+
When ready to implement, run /opsx:apply
20
+
21
+
---
22
+
23
+
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
24
+
25
+
**Steps**
26
+
27
+
1. **If no clear input provided, ask what they want to build**
28
+
29
+
Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
30
+
> "What change do you want to work on? Describe what you want to build or fix."
31
+
32
+
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
33
+
34
+
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
35
+
36
+
2. **Create the change directory**
37
+
```bash
38
+
openspec new change "<name>"
39
+
```
40
+
This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
41
+
42
+
3. **Get the artifact build order**
43
+
```bash
44
+
openspec status --change "<name>" --json
45
+
```
46
+
Parse the JSON to get:
47
+
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
48
+
- `artifacts`: list of all artifacts with their status and dependencies
49
+
50
+
4. **Create artifacts in sequence until apply-ready**
51
+
52
+
Use the **TodoWrite tool** to track progress through the artifacts.
53
+
54
+
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
55
+
56
+
a. **For each artifact that is `ready` (dependencies satisfied)**:
57
+
- Get instructions:
58
+
```bash
59
+
openspec instructions <artifact-id> --change "<name>" --json
60
+
```
61
+
- The instructions JSON includes:
62
+
- `context`: Project background (constraints for you - do NOT include in output)
63
+
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
64
+
- `template`: The structure to use for your output file
65
+
- `instruction`: Schema-specific guidance for this artifact type
66
+
- `outputPath`: Where to write the artifact
67
+
- `dependencies`: Completed artifacts to read for context
68
+
- Read any completed dependency files for context
69
+
- Create the artifact file using `template` as the structure
70
+
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
71
+
- Show brief progress: "Created <artifact-id>"
72
+
73
+
b. **Continue until all `applyRequires` artifacts are complete**
74
+
- After creating each artifact, re-run `openspec status --change "<name>" --json`
75
+
- Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
76
+
- Stop when all `applyRequires` artifacts are done
77
+
78
+
c. **If an artifact requires user input** (unclear context):
79
+
- Use **AskUserQuestion tool** to clarify
80
+
- Then continue with creation
81
+
82
+
5. **Show final status**
83
+
```bash
84
+
openspec status --change "<name>"
85
+
```
86
+
87
+
**Output**
88
+
89
+
After completing all artifacts, summarize:
90
+
- Change name and location
91
+
- List of artifacts created with brief descriptions
92
+
- What's ready: "All artifacts created! Ready for implementation."
93
+
- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
94
+
95
+
**Artifact Creation Guidelines**
96
+
97
+
- Follow the `instruction` field from `openspec instructions` for each artifact type
98
+
- The schema defines what each artifact should contain - follow it
99
+
- Read dependency artifacts for context before creating new ones
100
+
- Use `template` as the structure for your output file - fill in its sections
101
+
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
102
+
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
103
+
- These guide what you write, but should never appear in the output
104
+
105
+
**Guardrails**
106
+
- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
107
+
- Always read dependency artifacts before creating a new one
108
+
- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
109
+
- If a change with that name already exists, ask if user wants to continue it or create a new one
110
+
- Verify each artifact file exists after writing before proceeding to next
+168
.claude/skills/openspec-verify-change/SKILL.md
+168
.claude/skills/openspec-verify-change/SKILL.md
···
1
+
---
2
+
name: openspec-verify-change
3
+
description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
4
+
license: MIT
5
+
compatibility: Requires openspec CLI.
6
+
metadata:
7
+
author: openspec
8
+
version: "1.0"
9
+
generatedBy: "1.3.1"
10
+
---
11
+
12
+
Verify that an implementation matches the change artifacts (specs, tasks, design).
13
+
14
+
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
15
+
16
+
**Steps**
17
+
18
+
1. **If no change name provided, prompt for selection**
19
+
20
+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
21
+
22
+
Show changes that have implementation tasks (tasks artifact exists).
23
+
Include the schema used for each change if available.
24
+
Mark changes with incomplete tasks as "(In Progress)".
25
+
26
+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
27
+
28
+
2. **Check status to understand the schema**
29
+
```bash
30
+
openspec status --change "<name>" --json
31
+
```
32
+
Parse the JSON to understand:
33
+
- `schemaName`: The workflow being used (e.g., "spec-driven")
34
+
- Which artifacts exist for this change
35
+
36
+
3. **Get the change directory and load artifacts**
37
+
38
+
```bash
39
+
openspec instructions apply --change "<name>" --json
40
+
```
41
+
42
+
This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`.
43
+
44
+
4. **Initialize verification report structure**
45
+
46
+
Create a report structure with three dimensions:
47
+
- **Completeness**: Track tasks and spec coverage
48
+
- **Correctness**: Track requirement implementation and scenario coverage
49
+
- **Coherence**: Track design adherence and pattern consistency
50
+
51
+
Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
52
+
53
+
5. **Verify Completeness**
54
+
55
+
**Task Completion**:
56
+
- If `contextFiles.tasks` exists, read every file path in it
57
+
- Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
58
+
- Count complete vs total tasks
59
+
- If incomplete tasks exist:
60
+
- Add CRITICAL issue for each incomplete task
61
+
- Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
62
+
63
+
**Spec Coverage**:
64
+
- If delta specs exist in `openspec/changes/<name>/specs/`:
65
+
- Extract all requirements (marked with "### Requirement:")
66
+
- For each requirement:
67
+
- Search codebase for keywords related to the requirement
68
+
- Assess if implementation likely exists
69
+
- If requirements appear unimplemented:
70
+
- Add CRITICAL issue: "Requirement not found: <requirement name>"
71
+
- Recommendation: "Implement requirement X: <description>"
72
+
73
+
6. **Verify Correctness**
74
+
75
+
**Requirement Implementation Mapping**:
76
+
- For each requirement from delta specs:
77
+
- Search codebase for implementation evidence
78
+
- If found, note file paths and line ranges
79
+
- Assess if implementation matches requirement intent
80
+
- If divergence detected:
81
+
- Add WARNING: "Implementation may diverge from spec: <details>"
82
+
- Recommendation: "Review <file>:<lines> against requirement X"
83
+
84
+
**Scenario Coverage**:
85
+
- For each scenario in delta specs (marked with "#### Scenario:"):
86
+
- Check if conditions are handled in code
87
+
- Check if tests exist covering the scenario
88
+
- If scenario appears uncovered:
89
+
- Add WARNING: "Scenario not covered: <scenario name>"
90
+
- Recommendation: "Add test or implementation for scenario: <description>"
91
+
92
+
7. **Verify Coherence**
93
+
94
+
**Design Adherence**:
95
+
- If `contextFiles.design` exists:
96
+
- Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
97
+
- Verify implementation follows those decisions
98
+
- If contradiction detected:
99
+
- Add WARNING: "Design decision not followed: <decision>"
100
+
- Recommendation: "Update implementation or revise design.md to match reality"
101
+
- If no design.md: Skip design adherence check, note "No design.md to verify against"
102
+
103
+
**Code Pattern Consistency**:
104
+
- Review new code for consistency with project patterns
105
+
- Check file naming, directory structure, coding style
106
+
- If significant deviations found:
107
+
- Add SUGGESTION: "Code pattern deviation: <details>"
108
+
- Recommendation: "Consider following project pattern: <example>"
109
+
110
+
8. **Generate Verification Report**
111
+
112
+
**Summary Scorecard**:
113
+
```
114
+
## Verification Report: <change-name>
115
+
116
+
### Summary
117
+
| Dimension | Status |
118
+
|--------------|------------------|
119
+
| Completeness | X/Y tasks, N reqs|
120
+
| Correctness | M/N reqs covered |
121
+
| Coherence | Followed/Issues |
122
+
```
123
+
124
+
**Issues by Priority**:
125
+
126
+
1. **CRITICAL** (Must fix before archive):
127
+
- Incomplete tasks
128
+
- Missing requirement implementations
129
+
- Each with specific, actionable recommendation
130
+
131
+
2. **WARNING** (Should fix):
132
+
- Spec/design divergences
133
+
- Missing scenario coverage
134
+
- Each with specific recommendation
135
+
136
+
3. **SUGGESTION** (Nice to fix):
137
+
- Pattern inconsistencies
138
+
- Minor improvements
139
+
- Each with specific recommendation
140
+
141
+
**Final Assessment**:
142
+
- If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
143
+
- If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
144
+
- If all clear: "All checks passed. Ready for archive."
145
+
146
+
**Verification Heuristics**
147
+
148
+
- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
149
+
- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
150
+
- **Coherence**: Look for glaring inconsistencies, don't nitpick style
151
+
- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
152
+
- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
153
+
154
+
**Graceful Degradation**
155
+
156
+
- If only tasks.md exists: verify task completion only, skip spec/design checks
157
+
- If tasks + specs exist: verify completeness and correctness, skip design
158
+
- If full artifacts: verify all three dimensions
159
+
- Always note which checks were skipped and why
160
+
161
+
**Output Format**
162
+
163
+
Use clear markdown with:
164
+
- Table for summary scorecard
165
+
- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
166
+
- Code references in format: `file.ts:123`
167
+
- Specific, actionable recommendations
168
+
- No vague suggestions like "consider reviewing"
+20
openspec/config.yaml
+20
openspec/config.yaml
···
1
+
schema: spec-driven
2
+
3
+
# Project context (optional)
4
+
# This is shown to AI when creating artifacts.
5
+
# Add your tech stack, conventions, style guides, domain knowledge, etc.
6
+
# Example:
7
+
# context: |
8
+
# Tech stack: TypeScript, React, Node.js
9
+
# We use conventional commits
10
+
# Domain: e-commerce platform
11
+
12
+
# Per-artifact rules (optional)
13
+
# Add custom rules for specific artifacts.
14
+
# Example:
15
+
# rules:
16
+
# proposal:
17
+
# - Keep proposals under 500 words
18
+
# - Always include a "Non-goals" section
19
+
# tasks:
20
+
# - Break tasks into chunks of max 2 hours