Skip to content

Commit ca693e7

Browse files
pproencapproenca
committed
chore: test openspec artifacts
1 parent d1c63b8 commit ca693e7

12 files changed

Lines changed: 1408 additions & 0 deletions

File tree

‎.claude/commands/opsx/apply.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: OPSX: Apply
3+
description: Implement tasks from an OpenSpec change (Experimental)
4+
category: Workflow
5+
tags: [workflow, artifacts, experimental]
6+
---
7+
8+
Implement tasks from an OpenSpec change.
9+
10+
**Input**: Optionally specify `--change <name>` after `/opsx:apply`. If omitted, MUST prompt for available changes.
11+
12+
**Steps**
13+
14+
1. **If no change name provided, prompt for selection**
15+
16+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
17+
18+
Show changes that are implementation-ready (have tasks artifact).
19+
Include the schema used for each change if available.
20+
Mark changes with incomplete tasks as "(In Progress)".
21+
22+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
23+
24+
2. **Check status to understand the schema**
25+
```bash
26+
openspec status --change "<name>" --json
27+
```
28+
Parse the JSON to understand:
29+
- `schemaName`: The workflow being used (e.g., "spec-driven", "tdd")
30+
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
31+
32+
3. **Get apply instructions**
33+
34+
```bash
35+
openspec instructions apply --change "<name>" --json
36+
```
37+
38+
This returns:
39+
- Context file paths (varies by schema)
40+
- Progress (total, complete, remaining)
41+
- Task list with status
42+
- Dynamic instruction based on current state
43+
44+
**Handle states:**
45+
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
46+
- If `state: "all_done"`: congratulate, suggest archive
47+
- Otherwise: proceed to implementation
48+
49+
4. **Read context files**
50+
51+
Read the files listed in `contextFiles` from the apply instructions output.
52+
The files depend on the schema being used:
53+
- **spec-driven**: proposal, specs, design, tasks
54+
- **tdd**: spec, tests, implementation, docs
55+
- Other schemas: follow the contextFiles from CLI output
56+
57+
5. **Show current progress**
58+
59+
Display:
60+
- Schema being used
61+
- Progress: "N/M tasks complete"
62+
- Remaining tasks overview
63+
- Dynamic instruction from CLI
64+
65+
6. **Implement tasks (loop until done or blocked)**
66+
67+
For each pending task:
68+
- Show which task is being worked on
69+
- Make the code changes required
70+
- Keep changes minimal and focused
71+
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
72+
- Continue to next task
73+
74+
**Pause if:**
75+
- Task is unclear → ask for clarification
76+
- Implementation reveals a design issue → suggest updating artifacts
77+
- Error or blocker encountered → report and wait for guidance
78+
- User interrupts
79+
80+
7. **On completion or pause, show status**
81+
82+
Display:
83+
- Tasks completed this session
84+
- Overall progress: "N/M tasks complete"
85+
- If all done: suggest archive
86+
- If paused: explain why and wait for guidance
87+
88+
**Output During Implementation**
89+
90+
```
91+
## Implementing: <change-name> (schema: <schema-name>)
92+
93+
Working on task 3/7: <task description>
94+
[...implementation happening...]
95+
✓ Task complete
96+
97+
Working on task 4/7: <task description>
98+
[...implementation happening...]
99+
✓ Task complete
100+
```
101+
102+
**Output On Completion**
103+
104+
```
105+
## Implementation Complete
106+
107+
**Change:** <change-name>
108+
**Schema:** <schema-name>
109+
**Progress:** 7/7 tasks complete ✓
110+
111+
### Completed This Session
112+
- [x] Task 1
113+
- [x] Task 2
114+
...
115+
116+
All tasks complete! Ready to archive this change.
117+
```
118+
119+
**Output On Pause (Issue Encountered)**
120+
121+
```
122+
## Implementation Paused
123+
124+
**Change:** <change-name>
125+
**Schema:** <schema-name>
126+
**Progress:** 4/7 tasks complete
127+
128+
### Issue Encountered
129+
<description of the issue>
130+
131+
**Options:**
132+
1. <option 1>
133+
2. <option 2>
134+
3. Other approach
135+
136+
What would you like to do?
137+
```
138+
139+
**Guardrails**
140+
- Keep going through tasks until done or blocked
141+
- Always read context files before starting (from the apply instructions output)
142+
- If task is ambiguous, pause and ask before implementing
143+
- If implementation reveals issues, pause and suggest artifact updates
144+
- Keep code changes minimal and scoped to each task
145+
- Update task checkbox immediately after completing each task
146+
- Pause on errors, blockers, or unclear requirements - don't guess
147+
- Use contextFiles from CLI output, don't assume specific file names
148+
149+
**Fluid Workflow Integration**
150+
151+
This skill supports the "actions on a change" model:
152+
153+
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
154+
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

‎.claude/commands/opsx/archive.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
name: OPSX: Archive
3+
description: Archive a completed change in the experimental workflow
4+
category: Workflow
5+
tags: [workflow, archive, experimental]
6+
---
7+
8+
Archive a completed change in the experimental workflow.
9+
10+
**Input**: Optionally specify `--change <name>` after `/opsx:archive`. If omitted, MUST prompt for available changes.
11+
12+
**Steps**
13+
14+
1. **If no change name provided, prompt for selection**
15+
16+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
17+
18+
Show only active changes (not already archived).
19+
Include the schema used for each change if available.
20+
21+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
22+
23+
2. **Check artifact completion status**
24+
25+
Run `openspec status --change "<name>" --json` to check artifact completion.
26+
27+
Parse the JSON to understand:
28+
- `schemaName`: The workflow being used
29+
- `artifacts`: List of artifacts with their status (`done` or other)
30+
31+
**If any artifacts are not `done`:**
32+
- Display warning listing incomplete artifacts
33+
- Prompt user for confirmation to continue
34+
- Proceed if user confirms
35+
36+
3. **Check task completion status**
37+
38+
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
39+
40+
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
41+
42+
**If incomplete tasks found:**
43+
- Display warning showing count of incomplete tasks
44+
- Prompt user for confirmation to continue
45+
- Proceed if user confirms
46+
47+
**If no tasks file exists:** Proceed without task-related warning.
48+
49+
4. **Check if delta specs need syncing**
50+
51+
Check if `specs/` directory exists in the change with spec files.
52+
53+
**If delta specs exist, perform a quick sync check:**
54+
55+
a. **For each delta spec** at `openspec/changes/<name>/specs/<capability>/spec.md`:
56+
- Extract requirement names (lines matching `### Requirement: <name>`)
57+
- Note which sections exist (ADDED, MODIFIED, REMOVED)
58+
59+
b. **Check corresponding main spec** at `openspec/specs/<capability>/spec.md`:
60+
- If main spec doesn't exist → needs sync
61+
- If main spec exists, check if ADDED requirement names appear in it
62+
- If any ADDED requirements are missing from main spec → needs sync
63+
64+
c. **Report findings:**
65+
66+
**If sync needed:**
67+
```
68+
⚠️ Delta specs may not be synced:
69+
- specs/auth/spec.md → Main spec missing requirement "Token Refresh"
70+
- specs/api/spec.md → Main spec doesn't exist yet
71+
72+
Would you like to sync now before archiving?
73+
```
74+
- Use **AskUserQuestion tool** with options: "Sync now", "Archive without syncing"
75+
- If user chooses sync, execute `/opsx:sync` logic
76+
77+
**If already synced (all requirements found):**
78+
- Proceed without prompting (specs appear to be in sync)
79+
80+
**If no delta specs exist:** Proceed without sync-related checks.
81+
82+
5. **Perform the archive**
83+
84+
Create the archive directory if it doesn't exist:
85+
```bash
86+
mkdir -p openspec/changes/archive
87+
```
88+
89+
Generate target name using current date: `YYYY-MM-DD-<change-name>`
90+
91+
**Check if target already exists:**
92+
- If yes: Fail with error, suggest renaming existing archive or using different date
93+
- If no: Move the change directory to archive
94+
95+
```bash
96+
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
97+
```
98+
99+
6. **Display summary**
100+
101+
Show archive completion summary including:
102+
- Change name
103+
- Schema that was used
104+
- Archive location
105+
- Spec sync status (synced / not synced / no delta specs)
106+
- Note about any warnings (incomplete artifacts/tasks)
107+
108+
**Output On Success**
109+
110+
```
111+
## Archive Complete
112+
113+
**Change:** <change-name>
114+
**Schema:** <schema-name>
115+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
116+
**Specs:** ✓ Synced to main specs
117+
118+
All artifacts complete. All tasks complete.
119+
```
120+
121+
**Output On Success (No Delta Specs)**
122+
123+
```
124+
## Archive Complete
125+
126+
**Change:** <change-name>
127+
**Schema:** <schema-name>
128+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
129+
**Specs:** No delta specs
130+
131+
All artifacts complete. All tasks complete.
132+
```
133+
134+
**Output On Success With Warnings**
135+
136+
```
137+
## Archive Complete (with warnings)
138+
139+
**Change:** <change-name>
140+
**Schema:** <schema-name>
141+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
142+
**Specs:** ⚠️ Not synced
143+
144+
**Warnings:**
145+
- Archived with 2 incomplete artifacts
146+
- Archived with 3 incomplete tasks
147+
- Delta specs were not synced (user chose to skip)
148+
149+
Review the archive if this was not intentional.
150+
```
151+
152+
**Output On Error (Archive Exists)**
153+
154+
```
155+
## Archive Failed
156+
157+
**Change:** <change-name>
158+
**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
159+
160+
Target archive directory already exists.
161+
162+
**Options:**
163+
1. Rename the existing archive
164+
2. Delete the existing archive if it's a duplicate
165+
3. Wait until a different date to archive
166+
```
167+
168+
**Guardrails**
169+
- Always prompt for change selection if not provided
170+
- Use artifact graph (openspec status --json) for completion checking
171+
- Don't block archive on warnings - just inform and confirm
172+
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
173+
- Quick sync check: look for requirement names in delta specs, verify they exist in main specs
174+
- Show clear summary of what happened
175+
- If sync is requested, use /opsx:sync approach (agent-driven)

0 commit comments

Comments
 (0)