@ngocsangairvds/vsaf 3.0.3 → 3.0.5

package/assets/templates/CLAUDE.md

@@ -2,13 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-> VSAF v3 — Agentic AI SDLC Framework. Spec-driven development. 3-layer review. 7 integrated tools.
+> VSAF v3 — Agentic AI SDLC Framework. 4 integrated tools. 2-layer review.
 
 ---
 
 ## Prerequisites
 
-Node.js ≥18, Python ≥3.10, Git, jq, Claude Code subscription. Run `npx vsaf init` (idempotent) to install all tools.
+Node.js ≥18, Python ≥3.10, Git, Claude Code subscription. Run `npx vsaf init` (idempotent) to install all tools.
 
 ---
 
@@ -18,12 +18,12 @@ VSAF is a meta-framework for AI-driven SDLC — not an application. It has no so
 
 | Layer | Tools | Purpose |
 |-------|-------|---------|
-| Planning | BMAD Method, OpenSpec | PRD, architecture docs, spec proposals |
-| Code Intelligence | GitNexus (MCP), Graphify | Impact analysis, dependency graphs, path tracing |
-| Memory | claude-mem, MemPalace | Session continuity (auto), architecture decisions (manual) |
-| Implementation | Superpowers, Claude Code | TDD execution, code review |
+| Planning | BMAD Method | PRD, architecture docs, sprint stories |
+| Code Intelligence | GitNexus (MCP) | Impact analysis, call graph, blast radius |
+| Memory | MemPalace | Architecture decisions, team knowledge (permanent) |
+| Implementation | Superpowers, Claude Code | Brainstorm, TDD execution, code review |
 
-Key directories: `.claude/` (settings + skills), `openspec/` (spec proposals), `.gitnexus/` (knowledge graph index).
+Key directories: `.claude/` (settings + skills), `_bmad/` (BMAD workspace), `.gitnexus/` (knowledge graph index).
 
 ---
 
@@ -31,10 +31,8 @@ Key directories: `.claude/` (settings + skills), `openspec/` (spec proposals), `
 
 ```bash
 npx vsaf init    # Install all tools (one-time, idempotent)
-vsaf index       # Re-index: gitnexus analyze + graphify update
-vsaf verify      # Check implementation against OpenSpec specs
-vsaf review      # Full 3-layer review coordinator
-vsaf archive     # Archive specs + re-index (post-merge)
+vsaf index       # Re-index: gitnexus analyze
+vsaf review      # 2-layer review coordinator
 vsaf mine        # Mine conversations into MemPalace
 vsaf status      # Show status of all tools
 vsaf clean       # Clean GitNexus index
@@ -45,18 +43,12 @@ vsaf clean       # Clean GitNexus index
 ## Identity
 
 This project uses the **VSAF v3 (Agentic AI SDLC Framework)**. All development
-follows the 10-step workflow below. No code ships without spec compliance and
-3-layer review.
+follows the 8-step workflow below. No code ships without 2-layer review.
 
 ---
 
 ## Memory Management
 
-### claude-mem (auto-pilot)
-- claude-mem handles session continuity automatically. **Do not duplicate** its work.
-- Session context is auto-injected on start. No manual action needed.
-- Web viewer: http://localhost:37777
-
 ### MemPalace (knowledge base)
 - Call `mempalace_search` **BEFORE** answering about past decisions, architecture
   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
 - Write `mempalace_diary_write` at end of meaningful sessions.
 - Run `mempalace mine ~/chats/ --mode convos` weekly to capture decision history.
 
-### Separation of Concerns
-| claude-mem | MemPalace |
-|---|---|
-| Session recall, debug history | Architecture decisions, team knowledge |
-| Auto-compressed summaries | Verbatim lossless storage |
-| "What file did I change yesterday?" | "Why did we choose Patroni over Stolon?" |
-| Lossy — may lose reasoning chain | Temporal KG with stale fact invalidation |
-
-**Anti-pattern:** Do not use MemPalace for session recall. Do not use claude-mem
-for architecture decisions. Do not dump knowledge into CLAUDE.md.
+**Anti-pattern:** Do not dump knowledge into CLAUDE.md. CLAUDE.md = rules. MemPalace = decisions.
 
 ---
 
-## Knowledge Graph
+## Knowledge Graph (GitNexus MCP backbone)
 
-### GitNexus (MCP backbone)
-- Use GitNexus MCP tools for impact analysis before any code change.
+- Use GitNexus MCP tools for impact analysis **before any code change**.
 - Query: "What breaks if I change X?" before touching cross-module code.
 - Re-index after every merge: `gitnexus analyze`
 
-### Graphify (multimodal KG)
-- Read `graphify-out/GRAPH_REPORT.md` **before** answering architecture questions.
-- Use `/graphify query "question"` for structural queries.
-- Use `/graphify path ServiceA ServiceB` to trace dependency paths.
-- Re-build after merge: `/graphify . --update`
-
-### Mandatory Re-indexing
-After every merge or significant change:
-```
-gitnexus analyze && /graphify . --update
-```
-Or: `vsaf index`
-
 ---
 
-## 10-Step Workflow
+## 8-Step Workflow
 
 ### Step 0: Setup (one-time)
 ```bash
@@ -107,83 +76,64 @@ npx vsaf init
 ```
 
 ### Step 1: Understand Codebase
-- Read `graphify-out/GRAPH_REPORT.md` first.
 - Run `gitnexus serve` for web UI exploration.
-- Query MemPalace for past team decisions.
+- Use `gitnexus_query` to find execution flows for the area you'll work in.
+- Query MemPalace for past team decisions: `mempalace_search("<domain>")`
 - Do not modify code on day one.
 
 ### Step 2: Scope
 ```
 *agent analyst          # BMAD: clarify scope
-*workflow-init          # Quick/Standard/Enterprise
+*workflow-init          # Quick/Standard flow
 bmad-help               # What's next?
 ```
-Quick Flow (bug fix) --> skip to Step 6.
+Quick Flow (bug fix) → skip to Step 5.
 
 ### Step 3: Planning (skip for Quick Flow)
 ```
 *agent pm               # PRD: FRs, NFRs, Epics
-*agent architect         # Architecture doc
+*agent architect        # Architecture doc
 *agent po               # Sprint stories
 git add docs/ && git commit -m "feat: PRD + arch for <feature>"
 ```
 
-### Step 4: Specs (skip for Quick Flow)
+### Step 4: Impact Analysis
 ```
-/opsx:propose <feature>
-/opsx:ff                # Fast-forward all docs
-git add openspec/ && git commit -m "spec: <feature>"
+gitnexus_impact({target: "X", direction: "upstream"})   # Blast radius
+mempalace_search("<module> refactor")                    # Past attempts
 ```
-Tasks must be atomic (2-5 min). Include edge cases.
+Impact > 3 modules → split PRs.
 
-### Step 5: Impact Analysis
-```
-"What breaks if I change PaymentService?"    # GitNexus MCP
-/graphify path PaymentService NotificationService
-mempalace search "PaymentService refactor"   # Past attempts
-```
-Impact > 3 modules --> split PRs. Update specs if new edge cases found.
-
-### Step 6: Brainstorm + Plan
+### Step 5: Brainstorm + Plan
 ```
 /superpowers:brainstorm       # Socratic Q&A, explore alternatives
 /superpowers:write-plan       # Bite-sized tasks + verification steps
 ```
 Do not approve until every task has a verification step.
 
-### Step 7: Execute
+### Step 6: Execute
 ```
 /superpowers:execute-plan     # RED -> GREEN -> REFACTOR per task
 ```
 - 1 commit per task.
 - Tests after EVERY task.
-- Fail 3x on same task --> stop, do architectural review.
+- Fail 3x on same task → stop, do architectural review.
 
-### Step 8: Self-Review (3-layer -- MANDATORY)
+### Step 7: Self-Review (2-layer — MANDATORY)
 ```bash
 # Layer 1: Methodology compliance
 /superpowers:code-review
 
-# Layer 2: Spec compliance
-/opsx:verify               # or: vsaf verify
-
-# Layer 3: Knowledge graph sync
-vsaf index                  # gitnexus analyze + graphify update
+# Layer 2: Knowledge graph sync
+vsaf index              # gitnexus analyze
 ```
-If Layer 2 fails --> return to Step 7.
 
-### Step 9: Push PR
+### Step 8: Push + Archive
 ```bash
 git push origin feature/<name>
+vsaf mine               # weekly — mine decisions into MemPalace
 ```
-PR description must include: OpenSpec proposal link, impact summary, test results.
-
-### Step 10: Archive + Ship
-```bash
-vsaf archive                # openspec archive + re-index
-mempalace mine ~/chats/ --mode convos   # Mine decisions
-git tag v<version> && git push --tags
-```
+PR description must include: impact summary (from GitNexus), test results.
 
 ---
 
@@ -195,23 +145,16 @@ git tag v<version> && git push --tags
 | BMAD PRD | `*agent pm` |
 | BMAD architect | `*agent architect` |
 | BMAD next step | `bmad-help` |
-| OpenSpec propose | `/opsx:propose <feature>` |
-| OpenSpec fast-forward | `/opsx:ff` |
-| OpenSpec verify | `/opsx:verify` |
-| OpenSpec archive | `/opsx:archive` |
 | Superpowers brainstorm | `/superpowers:brainstorm` |
 | Superpowers plan | `/superpowers:write-plan` |
 | Superpowers execute | `/superpowers:execute-plan` |
 | Superpowers review | `/superpowers:code-review` |
 | GitNexus index | `gitnexus analyze` |
 | GitNexus web | `gitnexus serve` |
-| Graphify build | `/graphify .` |
-| Graphify query | `/graphify query "question"` |
-| Graphify update | `/graphify . --update` |
-| MemPalace search | `mempalace search "query"` |
+| GitNexus impact | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| MemPalace search | `mempalace_search("query")` |
 | MemPalace mine | `mempalace mine ~/chats/ --mode convos` |
-| MemPalace status | `mempalace status` |
-| claude-mem viewer | `http://localhost:37777` |
+| MemPalace add | `mempalace_add_drawer` |
 
 ---
 
@@ -219,16 +162,14 @@ git tag v<version> && git push --tags
 
 | Do Not | Instead |
 |---|---|
-| Write code before specs | Spec first, code second: `/opsx:propose` |
+| Write code before planning | BMAD analyst + Superpowers brainstorm first |
 | Skip brainstorm | `/superpowers:brainstorm` before planning |
-| Push without review | 3-layer: Superpowers + OpenSpec verify + re-index |
+| Push without review | 2-layer: Superpowers code-review + vsaf index |
 | Forget to re-index | `vsaf index` after every merge |
 | Create PRs > 400 lines | Split into smaller PRs |
-| Trust AI output blindly | AI writes -> Superpowers reviews -> human approves |
-| Skip impact analysis | GitNexus + Graphify + MemPalace BEFORE coding |
-| Dump knowledge into CLAUDE.md | CLAUDE.md = rules. claude-mem = sessions. MemPalace = decisions |
-| Use MemPalace for session recall | claude-mem auto-handles session continuity |
-| Use claude-mem for architecture decisions | MemPalace verbatim + temporal KG for decisions |
+| Trust AI output blindly | AI writes → Superpowers reviews → human approves |
+| Skip impact analysis | GitNexus BEFORE coding |
+| Dump knowledge into CLAUDE.md | CLAUDE.md = rules. MemPalace = decisions |
 | Skip MemPalace mining | `mempalace mine` weekly for architecture decisions |
 
 ---
@@ -236,7 +177,7 @@ git tag v<version> && git push --tags
 ## Commit Discipline
 
 - 1 commit per task from the plan.
-- Each commit message: `<type>: <description>` (feat, fix, refactor, spec, docs, test).
+- Each commit message: `<type>: <description>` (feat, fix, refactor, docs, test).
 - Tests must pass after every commit.
 - If a task fails 3 times, stop and trigger an architectural review.
 

package/bin/vsaf.js

@@ -11,31 +11,35 @@ USAGE
   vsaf global     Install global infra only  (skills, binaries)
   vsaf project    Scaffold project files only (assumes global done)
   vsaf status     Show installation status
-  vsaf index      Re-index codebase (GitNexus + Graphify)
-  vsaf verify     Check implementation against OpenSpec specs
-  vsaf review     Run 3-layer review flow
-  vsaf archive    Archive specs and re-index
+  vsaf index      Re-index codebase (GitNexus)
+  vsaf review     Run 2-layer review flow
   vsaf mine       Mine conversations into MemPalace
   vsaf clean      Clean GitNexus index
 
 GLOBAL  (once per machine → ~/.claude/)
-  Skills  : bmad (41), openspec (4), vsaf (5), gitnexus (6)
-  Binaries: gitnexus, openspec, graphify, mempalace, bun, claude-mem
+  Skills  : bmad (41), vsaf (5), gitnexus (6)
+  Binaries: gitnexus, mempalace
 
 PER PROJECT  (per repo, run inside the repo root)
-  .claude/settings.json   Hooks: secret detection, protected files
+  .claude/settings.json   Local AI settings (hook policy)
   .claude/skills + .codex/skills  BMAD skills synced for local clients
   _bmad + _bmad-output    BMAD workspace + generated artifacts folders
-  CLAUDE.md               10-step workflow rules
+  CLAUDE.md               8-step workflow rules
 
 EXAMPLES
   npx vsaf init           # New machine + new project (recommended)
-  npx vsaf verify         # Validate current implementation
-  npx vsaf index          # Refresh code intelligence indexes
+  npx vsaf index          # Refresh GitNexus knowledge graph
   npx vsaf status         # Check what is installed
 `;
 
 async function main() {
+  const runAndExit = (result, label) => {
+    if (result === false) {
+      console.error(`\n${label} failed.`);
+      process.exit(1);
+    }
+  };
+
   switch (cmd) {
     case 'init': {
       const { installGlobal } = require('../src/global');
@@ -61,32 +65,22 @@ async function main() {
     }
     case 'index': {
       const { runIndex } = require('../src/workflow');
-      runIndex();
-      break;
-    }
-    case 'verify': {
-      const { runVerify } = require('../src/workflow');
-      runVerify();
+      runAndExit(runIndex(), 'Index');
       break;
     }
     case 'review': {
       const { runReview } = require('../src/workflow');
-      runReview();
-      break;
-    }
-    case 'archive': {
-      const { runArchive } = require('../src/workflow');
-      runArchive();
+      runAndExit(runReview(), 'Review');
       break;
     }
     case 'mine': {
       const { runMine } = require('../src/workflow');
-      runMine();
+      runAndExit(runMine(), 'Mine');
       break;
     }
     case 'clean': {
       const { runClean } = require('../src/workflow');
-      runClean();
+      runAndExit(runClean(), 'Clean');
       break;
     }
     default:

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.0.3",
-  "description": "VSAF — Agentic AI SDLC Framework. Spec-driven development, 3-layer review, 7 integrated tools.",
-  "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "openspec"],
+  "version": "3.0.5",
+  "description": "VSAF — Agentic AI SDLC Framework. 4 integrated tools: BMAD, GitNexus, Superpowers, MemPalace. 2-layer review.",
+  "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "mempalace"],
   "bin": {
     "vsaf": "./bin/vsaf.js"
   },

package/src/global.js

@@ -13,12 +13,8 @@ async function installGlobal() {
   console.log(  '\x1b[1m╚══════════════════════════════════════════╝\x1b[0m');
 
   installSkills();
-  installBinary('gitnexus',  () => exec('npm install -g gitnexus'));
-  installBinary('openspec',  () => exec('npm install -g @fission-ai/openspec@latest'));
-  installPipx('graphify',   'graphifyy');
-  installPipx('mempalace',  'mempalace');
-  installBun();
-  installClaudeMem();
+  installBinary('gitnexus', () => exec('npm install -g gitnexus'));
+  installPipx('mempalace', 'mempalace');
 
   console.log('\n\x1b[32m\x1b[1m✓ Global infra ready.\x1b[0m\n');
 }
@@ -78,21 +74,4 @@ function installPipx(cmd, pkg) {
     : warn(`${cmd} install failed — run: pipx install ${pkg}`);
 }
 
-function installBun() {
-  step('bun (claude-mem runtime)');
-  if (hasCommand('bun')) { ok('bun already installed'); return; }
-  info('Installing bun...');
-  exec('curl -fsSL https://bun.sh/install | bash')
-    ? ok('bun installed')
-    : warn('bun install failed — run: curl -fsSL https://bun.sh/install | bash');
-}
-
-function installClaudeMem() {
-  step('claude-mem');
-  info('Running claude-mem install...');
-  exec('npx claude-mem install')
-    ? ok('claude-mem installed')
-    : warn('claude-mem install had issues — check manually');
-}
-
 module.exports = { installGlobal };

package/src/project.js

@@ -17,10 +17,8 @@ async function installProject() {
   scaffoldFiles();
   scaffoldBmadWorkspace();
   syncLocalBmadSkills();
-  initOpenSpec();
   initGitNexus();
   initMemPalace();
-  configureGitHooks();
 
   console.log('\n\x1b[32m\x1b[1m✓ Project ready.\x1b[0m');
   console.log('\n  Next steps:');
@@ -139,16 +137,6 @@ function syncLocalBmadSkills() {
   ok(`${installed} BMAD skill copy(ies), ${skipped} already present`);
 }
 
-function initOpenSpec() {
-  step('OpenSpec');
-  if (!hasCommand('openspec')) { warn('openspec not found — run: vsaf global'); return; }
-  const already = fs.existsSync(path.join(CWD, 'openspec.json'))
-               || fs.existsSync(path.join(CWD, 'openspec'));
-  if (already) { ok('OpenSpec already initialised'); return; }
-  info('Initialising openspec...');
-  exec('openspec init', { cwd: CWD }) ? ok('OpenSpec initialised') : warn('openspec init failed — run manually');
-}
-
 function initGitNexus() {
   step('GitNexus');
   if (!hasCommand('gitnexus')) { warn('gitnexus not found — run: vsaf global'); return; }
@@ -164,12 +152,4 @@ function initMemPalace() {
   exec(`mempalace init --yes "${CWD}"`, { cwd: CWD }) ? ok('MemPalace initialised') : warn('mempalace init failed — run manually');
 }
 
-function configureGitHooks() {
-  step('Git hooks');
-  if (!fs.existsSync(path.join(CWD, '.git'))) { warn('Not a git repo — skipping'); return; }
-  fs.mkdirSync(path.join(CWD, 'githooks'), { recursive: true });
-  exec('git config core.hooksPath githooks/', { cwd: CWD });
-  ok('Git hooks path → githooks/');
-}
-
 module.exports = { installProject };

package/src/status.js

@@ -10,23 +10,18 @@ async function showStatus() {
   console.log('\x1b[1mGlobal  (machine-wide → ~/.claude/)\x1b[0m');
   checkSkills();
   checkCmd('gitnexus',  'GitNexus');
-  checkCmd('openspec',  'OpenSpec');
-  checkCmd('graphify',  'Graphify');
   checkCmd('mempalace', 'MemPalace');
-  checkCmd('bun',       'Bun');
 
   // ── Project ────────────────────────────────────────────────────────────────
   console.log('\n\x1b[1mProject  (current repo)\x1b[0m');
-  checkPath('.claude/settings.json', 'Project settings');
+  checkPath('.claude/settings.json', 'Project settings (hooks)');
   checkPath('CLAUDE.md',             'Workflow rules');
   checkPath('_bmad',                 'BMAD workspace');
   checkPath('_bmad-output',          'BMAD output folder');
   checkProjectSkillDir('.claude/skills', 'Project BMAD skills (.claude)');
   checkProjectSkillDir('.codex/skills',  'Project BMAD skills (.codex)');
   checkPath('.gitnexus',             'GitNexus index');
-  checkPath('openspec',              'OpenSpec');
   checkPath('mempalace.yaml',        'MemPalace');
-  checkPath('githooks',              'Git hooks');
   console.log('');
 }
 

package/src/workflow.js

@@ -7,77 +7,57 @@ function runIndex() {
 
   if (!hasCommand('gitnexus')) {
     warn('gitnexus not found — run: vsaf global');
-    return;
+    return false;
   }
 
   info('Running gitnexus analyze...');
-  exec('gitnexus analyze') ? ok('GitNexus index updated') : warn('gitnexus analyze failed — run manually');
+  const gitnexusOk = exec('gitnexus analyze');
+  gitnexusOk ? ok('GitNexus index updated') : warn('gitnexus analyze failed — run manually');
 
-  if (!hasCommand('graphify')) {
-    warn('graphify not found — skipping graphify update');
-    return;
-  }
-
-  info('Running graphify update...');
-  exec('graphify . --update') ? ok('Graphify updated') : warn('graphify update failed — run manually');
-}
-
-function runVerify() {
-  step('Verify');
-  if (!hasCommand('openspec')) {
-    warn('openspec not found — run: vsaf global');
-    return;
-  }
-
-  info('Running openspec validate --all...');
-  exec('openspec validate --all') ? ok('OpenSpec verification passed') : warn('OpenSpec verification failed');
+  return gitnexusOk;
 }
 
 function runReview() {
-  step('Review (3-layer)');
+  step('Review (2-layer)');
   info('Layer 1: Methodology review — run in Claude Code: /superpowers:code-review');
-  info('Layer 2: Spec compliance');
-  runVerify();
-  info('Layer 3: Knowledge graph sync');
-  runIndex();
-  ok('Review flow completed');
-}
+  info('Layer 2: Knowledge graph sync');
+  const indexOk = runIndex();
 
-function runArchive() {
-  step('Archive');
-  if (!hasCommand('openspec')) {
-    warn('openspec not found — run: vsaf global');
-    return;
+  if (indexOk) {
+    ok('Review flow completed');
+    return true;
   }
 
-  info('Running openspec archive...');
-  exec('openspec archive') ? ok('OpenSpec archived') : warn('openspec archive failed — run manually');
-  runIndex();
+  warn('Review flow completed with failures. Fix warnings and re-run.');
+  return false;
 }
 
 function runMine() {
   step('Mine');
   if (!hasCommand('mempalace')) {
     warn('mempalace not found — run: vsaf global');
-    return;
+    return false;
   }
 
   info('Running mempalace mine ~/chats/ --mode convos --extract general...');
-  exec('mempalace mine ~/chats/ --mode convos --extract general')
+  const mineOk = exec('mempalace mine ~/chats/ --mode convos --extract general');
+  mineOk
     ? ok('MemPalace mine completed')
     : warn('mempalace mine failed — run manually');
+  return mineOk;
 }
 
 function runClean() {
   step('Clean');
   if (!hasCommand('gitnexus')) {
     warn('gitnexus not found — run: vsaf global');
-    return;
+    return false;
   }
 
   info('Running gitnexus clean...');
-  exec('gitnexus clean') ? ok('GitNexus index cleaned') : warn('gitnexus clean failed — run manually');
+  const cleanOk = exec('gitnexus clean');
+  cleanOk ? ok('GitNexus index cleaned') : warn('gitnexus clean failed — run manually');
+  return cleanOk;
 }
 
-module.exports = { runIndex, runVerify, runReview, runArchive, runMine, runClean };
-
+module.exports = { runIndex, runReview, runMine, runClean };