@ngocsangairvds/vsaf 3.0.4 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,13 +2,13 @@
2
2
 
3
3
  This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
4
 
5
- > VSAF v3 — Agentic AI SDLC Framework. Spec-driven development. 3-layer review. 7 integrated tools.
5
+ > VSAF v3 — Agentic AI SDLC Framework. 4 integrated tools. 2-layer review.
6
6
 
7
7
  ---
8
8
 
9
9
  ## Prerequisites
10
10
 
11
- Node.js ≥18, Python ≥3.10, Git, jq, Claude Code subscription. Run `npx vsaf init` (idempotent) to install all tools.
11
+ Node.js ≥18, Python ≥3.10, Git, Claude Code subscription. Run `npx vsaf init` (idempotent) to install all tools.
12
12
 
13
13
  ---
14
14
 
@@ -18,12 +18,12 @@ VSAF is a meta-framework for AI-driven SDLC — not an application. It has no so
18
18
 
19
19
  | Layer | Tools | Purpose |
20
20
  |-------|-------|---------|
21
- | Planning | BMAD Method, OpenSpec | PRD, architecture docs, spec proposals |
22
- | Code Intelligence | GitNexus (MCP), Graphify | Impact analysis, dependency graphs, path tracing |
23
- | Memory | claude-mem, MemPalace | Session continuity (auto), architecture decisions (manual) |
24
- | Implementation | Superpowers, Claude Code | TDD execution, code review |
21
+ | Planning | BMAD Method | PRD, architecture docs, sprint stories |
22
+ | Code Intelligence | GitNexus (MCP) | Impact analysis, call graph, blast radius |
23
+ | Memory | MemPalace | Architecture decisions, team knowledge (permanent) |
24
+ | Implementation | Superpowers, Claude Code | Brainstorm, TDD execution, code review |
25
25
 
26
- Key directories: `.claude/` (settings + skills), `openspec/` (spec proposals), `.gitnexus/` (knowledge graph index).
26
+ Key directories: `.claude/` (settings + skills), `_bmad/` (BMAD workspace), `.gitnexus/` (knowledge graph index).
27
27
 
28
28
  ---
29
29
 
@@ -31,10 +31,8 @@ Key directories: `.claude/` (settings + skills), `openspec/` (spec proposals), `
31
31
 
32
32
  ```bash
33
33
  npx vsaf init # Install all tools (one-time, idempotent)
34
- vsaf index # Re-index: gitnexus analyze + graphify update
35
- vsaf verify # Check implementation against OpenSpec specs
36
- vsaf review # Full 3-layer review coordinator
37
- vsaf archive # Archive specs + re-index (post-merge)
34
+ vsaf index # Re-index: gitnexus analyze
35
+ vsaf review # 2-layer review coordinator
38
36
  vsaf mine # Mine conversations into MemPalace
39
37
  vsaf status # Show status of all tools
40
38
  vsaf clean # Clean GitNexus index
@@ -45,18 +43,12 @@ vsaf clean # Clean GitNexus index
45
43
  ## Identity
46
44
 
47
45
  This project uses the **VSAF v3 (Agentic AI SDLC Framework)**. All development
48
- follows the 10-step workflow below. No code ships without spec compliance and
49
- 3-layer review.
46
+ follows the 8-step workflow below. No code ships without 2-layer review.
50
47
 
51
48
  ---
52
49
 
53
50
  ## Memory Management
54
51
 
55
- ### claude-mem (auto-pilot)
56
- - claude-mem handles session continuity automatically. **Do not duplicate** its work.
57
- - Session context is auto-injected on start. No manual action needed.
58
- - Web viewer: http://localhost:37777
59
-
60
52
  ### MemPalace (knowledge base)
61
53
  - Call `mempalace_search` **BEFORE** answering about past decisions, architecture
62
54
  rationale, or "why did we choose X" questions.
@@ -64,42 +56,19 @@ follows the 10-step workflow below. No code ships without spec compliance and
64
56
  - Write `mempalace_diary_write` at end of meaningful sessions.
65
57
  - Run `mempalace mine ~/chats/ --mode convos` weekly to capture decision history.
66
58
 
67
- ### Separation of Concerns
68
- | claude-mem | MemPalace |
69
- |---|---|
70
- | Session recall, debug history | Architecture decisions, team knowledge |
71
- | Auto-compressed summaries | Verbatim lossless storage |
72
- | "What file did I change yesterday?" | "Why did we choose Patroni over Stolon?" |
73
- | Lossy — may lose reasoning chain | Temporal KG with stale fact invalidation |
74
-
75
- **Anti-pattern:** Do not use MemPalace for session recall. Do not use claude-mem
76
- for architecture decisions. Do not dump knowledge into CLAUDE.md.
59
+ **Anti-pattern:** Do not dump knowledge into CLAUDE.md. CLAUDE.md = rules. MemPalace = decisions.
77
60
 
78
61
  ---
79
62
 
80
- ## Knowledge Graph
63
+ ## Knowledge Graph (GitNexus MCP backbone)
81
64
 
82
- ### GitNexus (MCP backbone)
83
- - Use GitNexus MCP tools for impact analysis before any code change.
65
+ - Use GitNexus MCP tools for impact analysis **before any code change**.
84
66
  - Query: "What breaks if I change X?" before touching cross-module code.
85
67
  - Re-index after every merge: `gitnexus analyze`
86
68
 
87
- ### Graphify (multimodal KG)
88
- - Read `graphify-out/GRAPH_REPORT.md` **before** answering architecture questions.
89
- - Use `/graphify query "question"` for structural queries.
90
- - Use `/graphify path ServiceA ServiceB` to trace dependency paths.
91
- - Re-build after merge: `/graphify . --update`
92
-
93
- ### Mandatory Re-indexing
94
- After every merge or significant change:
95
- ```
96
- gitnexus analyze && /graphify . --update
97
- ```
98
- Or: `vsaf index`
99
-
100
69
  ---
101
70
 
102
- ## 10-Step Workflow
71
+ ## 8-Step Workflow
103
72
 
104
73
  ### Step 0: Setup (one-time)
105
74
  ```bash
@@ -107,83 +76,64 @@ npx vsaf init
107
76
  ```
108
77
 
109
78
  ### Step 1: Understand Codebase
110
- - Read `graphify-out/GRAPH_REPORT.md` first.
111
79
  - Run `gitnexus serve` for web UI exploration.
112
- - Query MemPalace for past team decisions.
80
+ - Use `gitnexus_query` to find execution flows for the area you'll work in.
81
+ - Query MemPalace for past team decisions: `mempalace_search("<domain>")`
113
82
  - Do not modify code on day one.
114
83
 
115
84
  ### Step 2: Scope
116
85
  ```
117
86
  *agent analyst # BMAD: clarify scope
118
- *workflow-init # Quick/Standard/Enterprise
87
+ *workflow-init # Quick/Standard flow
119
88
  bmad-help # What's next?
120
89
  ```
121
- Quick Flow (bug fix) --> skip to Step 6.
90
+ Quick Flow (bug fix) skip to Step 5.
122
91
 
123
92
  ### Step 3: Planning (skip for Quick Flow)
124
93
  ```
125
94
  *agent pm # PRD: FRs, NFRs, Epics
126
- *agent architect # Architecture doc
95
+ *agent architect # Architecture doc
127
96
  *agent po # Sprint stories
128
97
  git add docs/ && git commit -m "feat: PRD + arch for <feature>"
129
98
  ```
130
99
 
131
- ### Step 4: Specs (skip for Quick Flow)
100
+ ### Step 4: Impact Analysis
132
101
  ```
133
- /opsx:propose <feature>
134
- /opsx:ff # Fast-forward all docs
135
- git add openspec/ && git commit -m "spec: <feature>"
102
+ gitnexus_impact({target: "X", direction: "upstream"}) # Blast radius
103
+ mempalace_search("<module> refactor") # Past attempts
136
104
  ```
137
- Tasks must be atomic (2-5 min). Include edge cases.
105
+ Impact > 3 modules split PRs.
138
106
 
139
- ### Step 5: Impact Analysis
140
- ```
141
- "What breaks if I change PaymentService?" # GitNexus MCP
142
- /graphify path PaymentService NotificationService
143
- mempalace search "PaymentService refactor" # Past attempts
144
- ```
145
- Impact > 3 modules --> split PRs. Update specs if new edge cases found.
146
-
147
- ### Step 6: Brainstorm + Plan
107
+ ### Step 5: Brainstorm + Plan
148
108
  ```
149
109
  /superpowers:brainstorm # Socratic Q&A, explore alternatives
150
110
  /superpowers:write-plan # Bite-sized tasks + verification steps
151
111
  ```
152
112
  Do not approve until every task has a verification step.
153
113
 
154
- ### Step 7: Execute
114
+ ### Step 6: Execute
155
115
  ```
156
116
  /superpowers:execute-plan # RED -> GREEN -> REFACTOR per task
157
117
  ```
158
118
  - 1 commit per task.
159
119
  - Tests after EVERY task.
160
- - Fail 3x on same task --> stop, do architectural review.
120
+ - Fail 3x on same task stop, do architectural review.
161
121
 
162
- ### Step 8: Self-Review (3-layer -- MANDATORY)
122
+ ### Step 7: Self-Review (2-layer MANDATORY)
163
123
  ```bash
164
124
  # Layer 1: Methodology compliance
165
125
  /superpowers:code-review
166
126
 
167
- # Layer 2: Spec compliance
168
- /opsx:verify # or: vsaf verify
169
-
170
- # Layer 3: Knowledge graph sync
171
- vsaf index # gitnexus analyze + graphify update
127
+ # Layer 2: Knowledge graph sync
128
+ vsaf index # gitnexus analyze
172
129
  ```
173
- If Layer 2 fails --> return to Step 7.
174
130
 
175
- ### Step 9: Push PR
131
+ ### Step 8: Push + Archive
176
132
  ```bash
177
133
  git push origin feature/<name>
134
+ vsaf mine # weekly — mine decisions into MemPalace
178
135
  ```
179
- PR description must include: OpenSpec proposal link, impact summary, test results.
180
-
181
- ### Step 10: Archive + Ship
182
- ```bash
183
- vsaf archive # openspec archive + re-index
184
- mempalace mine ~/chats/ --mode convos # Mine decisions
185
- git tag v<version> && git push --tags
186
- ```
136
+ PR description must include: impact summary (from GitNexus), test results.
187
137
 
188
138
  ---
189
139
 
@@ -195,23 +145,16 @@ git tag v<version> && git push --tags
195
145
  | BMAD PRD | `*agent pm` |
196
146
  | BMAD architect | `*agent architect` |
197
147
  | BMAD next step | `bmad-help` |
198
- | OpenSpec propose | `/opsx:propose <feature>` |
199
- | OpenSpec fast-forward | `/opsx:ff` |
200
- | OpenSpec verify | `/opsx:verify` |
201
- | OpenSpec archive | `/opsx:archive` |
202
148
  | Superpowers brainstorm | `/superpowers:brainstorm` |
203
149
  | Superpowers plan | `/superpowers:write-plan` |
204
150
  | Superpowers execute | `/superpowers:execute-plan` |
205
151
  | Superpowers review | `/superpowers:code-review` |
206
152
  | GitNexus index | `gitnexus analyze` |
207
153
  | GitNexus web | `gitnexus serve` |
208
- | Graphify build | `/graphify .` |
209
- | Graphify query | `/graphify query "question"` |
210
- | Graphify update | `/graphify . --update` |
211
- | MemPalace search | `mempalace search "query"` |
154
+ | GitNexus impact | `gitnexus_impact({target: "X", direction: "upstream"})` |
155
+ | MemPalace search | `mempalace_search("query")` |
212
156
  | MemPalace mine | `mempalace mine ~/chats/ --mode convos` |
213
- | MemPalace status | `mempalace status` |
214
- | claude-mem viewer | `http://localhost:37777` |
157
+ | MemPalace add | `mempalace_add_drawer` |
215
158
 
216
159
  ---
217
160
 
@@ -219,16 +162,14 @@ git tag v<version> && git push --tags
219
162
 
220
163
  | Do Not | Instead |
221
164
  |---|---|
222
- | Write code before specs | Spec first, code second: `/opsx:propose` |
165
+ | Write code before planning | BMAD analyst + Superpowers brainstorm first |
223
166
  | Skip brainstorm | `/superpowers:brainstorm` before planning |
224
- | Push without review | 3-layer: Superpowers + OpenSpec verify + re-index |
167
+ | Push without review | 2-layer: Superpowers code-review + vsaf index |
225
168
  | Forget to re-index | `vsaf index` after every merge |
226
169
  | Create PRs > 400 lines | Split into smaller PRs |
227
- | Trust AI output blindly | AI writes -> Superpowers reviews -> human approves |
228
- | Skip impact analysis | GitNexus + Graphify + MemPalace BEFORE coding |
229
- | Dump knowledge into CLAUDE.md | CLAUDE.md = rules. claude-mem = sessions. MemPalace = decisions |
230
- | Use MemPalace for session recall | claude-mem auto-handles session continuity |
231
- | Use claude-mem for architecture decisions | MemPalace verbatim + temporal KG for decisions |
170
+ | Trust AI output blindly | AI writes Superpowers reviews human approves |
171
+ | Skip impact analysis | GitNexus BEFORE coding |
172
+ | Dump knowledge into CLAUDE.md | CLAUDE.md = rules. MemPalace = decisions |
232
173
  | Skip MemPalace mining | `mempalace mine` weekly for architecture decisions |
233
174
 
234
175
  ---
@@ -236,7 +177,7 @@ git tag v<version> && git push --tags
236
177
  ## Commit Discipline
237
178
 
238
179
  - 1 commit per task from the plan.
239
- - Each commit message: `<type>: <description>` (feat, fix, refactor, spec, docs, test).
180
+ - Each commit message: `<type>: <description>` (feat, fix, refactor, docs, test).
240
181
  - Tests must pass after every commit.
241
182
  - If a task fails 3 times, stop and trigger an architectural review.
242
183
 
package/bin/vsaf.js CHANGED
@@ -11,27 +11,24 @@ USAGE
11
11
  vsaf global Install global infra only (skills, binaries)
12
12
  vsaf project Scaffold project files only (assumes global done)
13
13
  vsaf status Show installation status
14
- vsaf index Re-index codebase (GitNexus + Graphify)
15
- vsaf verify Check implementation against OpenSpec specs (manual pre-push gate)
16
- vsaf review Run 3-layer review flow
17
- vsaf archive Archive specs and re-index
14
+ vsaf index Re-index codebase (GitNexus)
15
+ vsaf review Run 2-layer review flow
18
16
  vsaf mine Mine conversations into MemPalace
19
17
  vsaf clean Clean GitNexus index
20
18
 
21
19
  GLOBAL (once per machine → ~/.claude/)
22
- Skills : bmad (41), openspec (4), vsaf (5), gitnexus (6)
23
- Binaries: gitnexus, openspec, graphify, mempalace, bun, claude-mem
20
+ Skills : bmad (41), vsaf (5), gitnexus (6)
21
+ Binaries: gitnexus, mempalace
24
22
 
25
23
  PER PROJECT (per repo, run inside the repo root)
26
- .claude/settings.json Local AI settings (optional hook policy)
24
+ .claude/settings.json Local AI settings (hook policy)
27
25
  .claude/skills + .codex/skills BMAD skills synced for local clients
28
26
  _bmad + _bmad-output BMAD workspace + generated artifacts folders
29
- CLAUDE.md 10-step workflow rules
27
+ CLAUDE.md 8-step workflow rules
30
28
 
31
29
  EXAMPLES
32
30
  npx vsaf init # New machine + new project (recommended)
33
- npx vsaf verify # Validate current implementation
34
- npx vsaf index # Refresh code intelligence indexes
31
+ npx vsaf index # Refresh GitNexus knowledge graph
35
32
  npx vsaf status # Check what is installed
36
33
  `;
37
34
 
@@ -71,21 +68,11 @@ async function main() {
71
68
  runAndExit(runIndex(), 'Index');
72
69
  break;
73
70
  }
74
- case 'verify': {
75
- const { runVerify } = require('../src/workflow');
76
- runAndExit(runVerify(), 'Verify');
77
- break;
78
- }
79
71
  case 'review': {
80
72
  const { runReview } = require('../src/workflow');
81
73
  runAndExit(runReview(), 'Review');
82
74
  break;
83
75
  }
84
- case 'archive': {
85
- const { runArchive } = require('../src/workflow');
86
- runAndExit(runArchive(), 'Archive');
87
- break;
88
- }
89
76
  case 'mine': {
90
77
  const { runMine } = require('../src/workflow');
91
78
  runAndExit(runMine(), 'Mine');
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@ngocsangairvds/vsaf",
3
- "version": "3.0.4",
4
- "description": "VSAF — Agentic AI SDLC Framework. Spec-driven development, 3-layer review, 7 integrated tools.",
5
- "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "openspec"],
3
+ "version": "3.0.5",
4
+ "description": "VSAF — Agentic AI SDLC Framework. 4 integrated tools: BMAD, GitNexus, Superpowers, MemPalace. 2-layer review.",
5
+ "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "mempalace"],
6
6
  "bin": {
7
7
  "vsaf": "./bin/vsaf.js"
8
8
  },
package/src/global.js CHANGED
@@ -13,12 +13,8 @@ async function installGlobal() {
13
13
  console.log( '\x1b[1m╚══════════════════════════════════════════╝\x1b[0m');
14
14
 
15
15
  installSkills();
16
- installBinary('gitnexus', () => exec('npm install -g gitnexus'));
17
- installBinary('openspec', () => exec('npm install -g @fission-ai/openspec@latest'));
18
- installPipx('graphify', 'graphifyy');
19
- installPipx('mempalace', 'mempalace');
20
- installBun();
21
- installClaudeMem();
16
+ installBinary('gitnexus', () => exec('npm install -g gitnexus'));
17
+ installPipx('mempalace', 'mempalace');
22
18
 
23
19
  console.log('\n\x1b[32m\x1b[1m✓ Global infra ready.\x1b[0m\n');
24
20
  }
@@ -78,21 +74,4 @@ function installPipx(cmd, pkg) {
78
74
  : warn(`${cmd} install failed — run: pipx install ${pkg}`);
79
75
  }
80
76
 
81
- function installBun() {
82
- step('bun (claude-mem runtime)');
83
- if (hasCommand('bun')) { ok('bun already installed'); return; }
84
- info('Installing bun...');
85
- exec('curl -fsSL https://bun.sh/install | bash')
86
- ? ok('bun installed')
87
- : warn('bun install failed — run: curl -fsSL https://bun.sh/install | bash');
88
- }
89
-
90
- function installClaudeMem() {
91
- step('claude-mem');
92
- info('Running claude-mem install...');
93
- exec('npx claude-mem install')
94
- ? ok('claude-mem installed')
95
- : warn('claude-mem install had issues — check manually');
96
- }
97
-
98
77
  module.exports = { installGlobal };
package/src/project.js CHANGED
@@ -17,7 +17,6 @@ async function installProject() {
17
17
  scaffoldFiles();
18
18
  scaffoldBmadWorkspace();
19
19
  syncLocalBmadSkills();
20
- initOpenSpec();
21
20
  initGitNexus();
22
21
  initMemPalace();
23
22
 
@@ -138,16 +137,6 @@ function syncLocalBmadSkills() {
138
137
  ok(`${installed} BMAD skill copy(ies), ${skipped} already present`);
139
138
  }
140
139
 
141
- function initOpenSpec() {
142
- step('OpenSpec');
143
- if (!hasCommand('openspec')) { warn('openspec not found — run: vsaf global'); return; }
144
- const already = fs.existsSync(path.join(CWD, 'openspec.json'))
145
- || fs.existsSync(path.join(CWD, 'openspec'));
146
- if (already) { ok('OpenSpec already initialised'); return; }
147
- info('Initialising openspec...');
148
- exec('openspec init', { cwd: CWD }) ? ok('OpenSpec initialised') : warn('openspec init failed — run manually');
149
- }
150
-
151
140
  function initGitNexus() {
152
141
  step('GitNexus');
153
142
  if (!hasCommand('gitnexus')) { warn('gitnexus not found — run: vsaf global'); return; }
@@ -163,5 +152,4 @@ function initMemPalace() {
163
152
  exec(`mempalace init --yes "${CWD}"`, { cwd: CWD }) ? ok('MemPalace initialised') : warn('mempalace init failed — run manually');
164
153
  }
165
154
 
166
-
167
155
  module.exports = { installProject };
package/src/status.js CHANGED
@@ -10,21 +10,17 @@ async function showStatus() {
10
10
  console.log('\x1b[1mGlobal (machine-wide → ~/.claude/)\x1b[0m');
11
11
  checkSkills();
12
12
  checkCmd('gitnexus', 'GitNexus');
13
- checkCmd('openspec', 'OpenSpec');
14
- checkCmd('graphify', 'Graphify');
15
13
  checkCmd('mempalace', 'MemPalace');
16
- checkCmd('bun', 'Bun');
17
14
 
18
15
  // ── Project ────────────────────────────────────────────────────────────────
19
16
  console.log('\n\x1b[1mProject (current repo)\x1b[0m');
20
- checkPath('.claude/settings.json', 'Project settings (optional hooks)');
17
+ checkPath('.claude/settings.json', 'Project settings (hooks)');
21
18
  checkPath('CLAUDE.md', 'Workflow rules');
22
19
  checkPath('_bmad', 'BMAD workspace');
23
20
  checkPath('_bmad-output', 'BMAD output folder');
24
21
  checkProjectSkillDir('.claude/skills', 'Project BMAD skills (.claude)');
25
22
  checkProjectSkillDir('.codex/skills', 'Project BMAD skills (.codex)');
26
23
  checkPath('.gitnexus', 'GitNexus index');
27
- checkPath('openspec', 'OpenSpec');
28
24
  checkPath('mempalace.yaml', 'MemPalace');
29
25
  console.log('');
30
26
  }
package/src/workflow.js CHANGED
@@ -14,40 +14,16 @@ function runIndex() {
14
14
  const gitnexusOk = exec('gitnexus analyze');
15
15
  gitnexusOk ? ok('GitNexus index updated') : warn('gitnexus analyze failed — run manually');
16
16
 
17
- if (!hasCommand('graphify')) {
18
- warn('graphify not found — skipping graphify update');
19
- return false;
20
- }
21
-
22
- info('Running graphify update...');
23
- const graphifyOk = exec('graphify update .');
24
- graphifyOk ? ok('Graphify updated') : warn('graphify update failed — run manually');
25
-
26
- return gitnexusOk && graphifyOk;
27
- }
28
-
29
- function runVerify() {
30
- step('Verify');
31
- if (!hasCommand('openspec')) {
32
- warn('openspec not found — run: vsaf global');
33
- return false;
34
- }
35
-
36
- info('Running openspec validate --all...');
37
- const okVerify = exec('openspec validate --all');
38
- okVerify ? ok('OpenSpec verification passed') : warn('OpenSpec verification failed');
39
- return okVerify;
17
+ return gitnexusOk;
40
18
  }
41
19
 
42
20
  function runReview() {
43
- step('Review (3-layer)');
21
+ step('Review (2-layer)');
44
22
  info('Layer 1: Methodology review — run in Claude Code: /superpowers:code-review');
45
- info('Layer 2: Spec compliance');
46
- const verifyOk = runVerify();
47
- info('Layer 3: Knowledge graph sync');
23
+ info('Layer 2: Knowledge graph sync');
48
24
  const indexOk = runIndex();
49
25
 
50
- if (verifyOk && indexOk) {
26
+ if (indexOk) {
51
27
  ok('Review flow completed');
52
28
  return true;
53
29
  }
@@ -56,20 +32,6 @@ function runReview() {
56
32
  return false;
57
33
  }
58
34
 
59
- function runArchive() {
60
- step('Archive');
61
- if (!hasCommand('openspec')) {
62
- warn('openspec not found — run: vsaf global');
63
- return false;
64
- }
65
-
66
- info('Running openspec archive...');
67
- const archiveOk = exec('openspec archive');
68
- archiveOk ? ok('OpenSpec archived') : warn('openspec archive failed — run manually');
69
- const indexOk = runIndex();
70
- return archiveOk && indexOk;
71
- }
72
-
73
35
  function runMine() {
74
36
  step('Mine');
75
37
  if (!hasCommand('mempalace')) {
@@ -98,5 +60,4 @@ function runClean() {
98
60
  return cleanOk;
99
61
  }
100
62
 
101
- module.exports = { runIndex, runVerify, runReview, runArchive, runMine, runClean };
102
-
63
+ module.exports = { runIndex, runReview, runMine, runClean };
@@ -1,156 +0,0 @@
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.0"
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
- - Context 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 the files listed in `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