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
{{ message }}
Repository navigation
Commit e4e1b3a
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .opencode/commands/opsx-apply.md
+5-33Lines changed: 5 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
---
2
-
description: 'Implement tasks from an OpenSpec change (Experimental)'
2
+
description: Implement tasks from an OpenSpec change (Experimental)
3
3
---
4
4
5
5
Implement tasks from an OpenSpec change.
6
6
7
-
**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`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. 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.
7
+
**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`). 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.
8
8
9
9
**Input**: Optionally specify a change name (e.g., `/opsx-apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
10
10
@@ -15,7 +15,7 @@ Implement tasks from an OpenSpec change.
15
15
If a name is provided, use it. Otherwise:
16
16
- Infer from conversation context if the user mentioned a change
17
17
- Auto-select if only one active change exists
18
-
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
18
+
- If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool**to let the user select
19
19
20
20
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
21
21
@@ -37,43 +37,23 @@ Implement tasks from an OpenSpec change.
37
37
```
38
38
39
39
This returns:
40
-
-`contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
40
+
-`contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
41
41
- Progress (total, complete, remaining)
42
42
- Task list with status
43
43
- Dynamic instruction based on current state
44
-
- Optional `context`: current required project instruction input from the selected root
45
-
- Optional `operationGuidance`: current advisory guidance for apply
46
44
47
45
**Handle states:**
48
-
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx-continue` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
46
+
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx-continue`
49
47
- If `state: "all_done"`: congratulate, suggest archive
50
48
- Otherwise: proceed to implementation
51
49
52
-
Treat `context` as a required prompt-level input. Read and consider it, and
53
-
apply relevant project facts, conventions, and constraints while implementing.
54
-
Treat `operationGuidance` as optional additive advice. Read and consider every
55
-
entry, and follow entries that are applicable and compatible with the built-in
56
-
workflow.
57
-
58
-
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
59
-
progress, `contextFiles`, and the built-in `instruction`. They are not
60
-
evidence of task completion, do not replace the built-in instruction, and do
61
-
not permit bypassing a blocked state. If context conflicts with the built-in
62
-
instruction, an explicit user choice, or a CLI-controlled value, report the
63
-
conflict and preserve the controlling value. If guidance is inapplicable or
64
-
conflicts with those controlling inputs, do not follow it and explain why.
65
-
These are prompt-level behavior contracts, not enforceable checks.
66
-
67
50
4.**Read context files**
68
51
69
52
Read every file path listed under `contextFiles` from the apply instructions output.
70
53
The files depend on the schema being used:
71
54
-**spec-driven**: proposal, specs, design, tasks
72
55
- Other schemas: follow the contextFiles from CLI output
73
56
74
-
Do not copy `context` or `operationGuidance` verbatim into implementation
75
-
files or planning artifacts unless the user separately asks for that content.
76
-
77
57
5.**Show current progress**
78
58
79
59
Display:
@@ -94,7 +74,6 @@ Implement tasks from an OpenSpec change.
94
74
**Pause if:**
95
75
- Task is unclear → ask for clarification
96
76
- Implementation reveals a design issue → suggest updating artifacts
97
-
- A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
98
77
- Error or blocker encountered → report and wait for guidance
99
78
- User interrupts
100
79
@@ -166,14 +145,7 @@ What would you like to do?
166
145
- Keep code changes minimal and scoped to each task
167
146
- Update task checkbox immediately after completing each task
168
147
- Pause on errors, blockers, or unclear requirements - don't guess
169
-
- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
170
-
- Only mark a task `- [x]` when its specified behavior is fully implemented, not when it is partially done or deferred
171
148
- Use contextFiles from CLI output, don't assume specific file names
172
-
- Do not use context or operation guidance as proof that a task is complete
description: 'Archive a completed change in the experimental workflow'
2
+
description: Archive a completed change in the experimental workflow
3
3
---
4
4
5
5
Archive a completed change in the experimental workflow.
6
6
7
-
**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`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. 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.
8
-
9
-
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
7
+
**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`). 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.
10
8
11
9
**Input**: Optionally specify a change name after `/opsx-archive` (e.g., `/opsx-archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
12
10
13
11
**Steps**
14
12
15
-
1.**Select the change**
13
+
1.**If no change name provided, prompt for selection**
16
14
17
-
If a name is provided, use it. Otherwise:
18
-
- Infer from conversation context if the user mentioned a change
19
-
- Auto-select if only one active change exists
20
-
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
15
+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
21
16
22
-
When prompting, show only active changes (not already archived).
17
+
Show only active changes (not already archived).
23
18
Include the schema used for each change if available.
24
19
25
-
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-archive <other>`).
26
-
27
-
**Load current archive inputs before the existing archive checks:**
28
-
29
-
After resolving the selected change and planning root, run:
Keep the same selected-root flags on this command. This lookup is advisory and
36
-
optional: it only supplies extra prompt inputs, so it must never block archiving.
37
-
If it exits non-zero or returns invalid JSON — for example on an older CLI that
38
-
does not support this command yet — continue the archive workflow with no
39
-
context and no operation guidance. Do not report an error and do not stop.
40
-
41
-
A successful response may omit both optional fields. Treat `context` as a
42
-
required prompt-level input: read and consider it, and apply relevant project
43
-
facts, conventions, and constraints. Treat `operationGuidance` as optional
44
-
additive advice: read and consider every entry, and follow entries that are
45
-
applicable and compatible with the built-in archive workflow.
46
-
47
-
Keep both fields separate from built-in steps, explicit user choices, resolved
48
-
paths, CLI checks, and command contracts. If context conflicts with one of those
49
-
controlling inputs, report the conflict and preserve the controlling value. If
50
-
guidance is inapplicable or conflicts with a controlling input, do not follow it
51
-
and explain why. Do not infer replacement paths, skipped prompts, or flags from
52
-
either field, and do not copy their text verbatim into specs, change artifacts,
53
-
or archive summaries unless the user separately asks for it. These are
54
-
prompt-level behavior contracts, not enforceable checks.
20
+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
55
21
56
22
2.**Check artifact completion status**
57
23
@@ -60,9 +26,9 @@ Archive a completed change in the experimental workflow.
60
26
Parse the JSON to understand:
61
27
-`schemaName`: The workflow being used
62
28
-`planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
63
-
-`artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
29
+
-`artifacts`: List of artifacts with their status (`done` or other)
64
30
65
-
**If any artifacts are neither`done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
31
+
**If any artifacts are not`done`:**
66
32
- Display warning listing incomplete artifacts
67
33
- Prompt user for confirmation to continue
68
34
- Proceed if user confirms
@@ -82,44 +48,18 @@ Archive a completed change in the experimental workflow.
82
48
83
49
4.**Assess delta spec sync state**
84
50
85
-
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
86
-
delta-spec source. If the `specs` entry is missing or
87
-
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
88
-
delta specs from other artifacts.
51
+
Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
89
52
90
53
**If delta specs exist:**
91
-
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
54
+
- Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
92
55
- Determine what changes would be applied (adds, modifications, removals, renames)
93
56
- Show a combined summary before prompting
94
57
95
58
**Prompt options:**
96
59
- If changes needed: "Sync now (recommended)", "Archive without syncing"
97
60
- If already synced: "Archive now", "Sync anyway", "Cancel"
98
61
99
-
Route on the answer:
100
-
- "Cancel" — stop, do not archive
101
-
- "Archive without syncing" or "Archive now" — proceed to archive
102
-
- "Sync now" or "Sync anyway" — sync, then verify (below)
103
-
- Anything else — ask again rather than archiving
104
-
105
-
Before a selected sync writes any main spec, run
106
-
`openspec instructions specs --change "<name>" --json` once with the same
107
-
selected-root flags. Require a zero exit status and valid artifact-instruction
108
-
JSON. If the lookup fails or returns invalid JSON, report the error and stop
109
-
before writing any main spec or moving the change. A valid response with omitted
110
-
`rules` is the no-rules case. Apply returned `rules` only to the content and
111
-
form of main specs produced by this merge; do not use them as archive guidance,
112
-
change CLI behavior, or copy the rule text into any output file.
113
-
114
-
Then run the `/opsx-sync` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
115
-
116
-
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
117
-
- ADDED requirements present
118
-
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
119
-
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
120
-
- RENAMED requirements present under the new name and absent under the old one
121
-
122
-
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
62
+
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: <includetheanalyzeddeltaspecsummary>"). Proceed to archive regardless of choice.
123
63
124
64
5.**Perform the archive**
125
65
@@ -129,14 +69,14 @@ Archive a completed change in the experimental workflow.
129
69
mkdir -p "<planningHome.changesDir>/archive"
130
70
```
131
71
132
-
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive`).
72
+
Generate target name using current date: `YYYY-MM-DD-<change-name>`
133
73
134
74
**Check if target already exists:**
135
75
- If yes: Fail with error, suggest renaming existing archive or using different date
136
76
- If no: Move `changeRoot` to the archive directory
0 commit comments