@ngocsangairvds/vsaf 3.1.17 → 3.1.19

package/assets/templates/.codex/instructions.md

@@ -0,0 +1,143 @@
+# Codex Instructions
+
+This file provides guidance to OpenAI Codex CLI when working with code in this repository.
+
+> VSAF v3 — Agentic AI SDLC Framework. 3 integrated tools. 2-layer review.
+
+---
+
+## Prerequisites
+
+Node.js ≥18, Git. Run `npx vsaf init` (idempotent) to install all tools.
+
+---
+
+## Architecture
+
+VSAF is a meta-framework for AI-driven SDLC — not an application. It has no source code to compile. The 3-tool stack:
+
+| Layer | Tools | Purpose |
+|-------|-------|---------|
+| Planning | BMAD Method | PRD, SRS, architecture docs, sprint stories |
+| Code Intelligence | GitNexus | Impact analysis, call graph, blast radius |
+| Implementation | Superpowers, Codex | Brainstorm, TDD execution, code review |
+
+Key directories: `.codex/` (skills + instructions), `.vsaf/_bmad/` (BMAD workspace), `.vsaf/docs/` (artifacts), `.vsaf/_gitnexus/` (knowledge graph index).
+
+---
+
+## Commands
+
+```bash
+npx vsaf init    # Install all tools (one-time, idempotent)
+vsaf index       # Re-index: gitnexus analyze
+vsaf review      # 2-layer review coordinator
+vsaf status      # Show status of all tools
+vsaf clean       # Clean GitNexus index
+```
+
+---
+
+## Identity
+
+This project uses the **VSAF v3 (Agentic AI SDLC Framework)**. All development
+follows the SRS-first workflow below. No code ships without 2-layer review.
+
+---
+
+## Knowledge Graph (GitNexus backbone)
+
+- Run impact analysis before any code change: `gitnexus impact <symbol>`
+- Query: "What breaks if I change X?" before touching cross-module code.
+- Re-index after every merge: `gitnexus analyze`
+
+---
+
+## SRS-First Workflow
+
+### Step 0: Setup (one-time)
+```bash
+npx vsaf init
+```
+
+### Step 1: Onboard Project
+- Run `gitnexus serve` for web UI exploration.
+- Use `/vsaf-onboard` for the structured onboarding sequence.
+- Do not modify code on day one.
+
+### Step 2: Planning + Requirement → PRD → SRS
+```
+/vsaf-plan <requirement>    # scope + impact + approach
+/vsaf-doc-prd               # write PRD from approved scope
+/vsaf-doc-srs               # write SRS from PRD
+```
+
+### Step 3: Testcase from SRS
+```
+/vsaf-test <path/to/srs>
+```
+
+### Step 4: Impact Analysis
+```
+gitnexus impact <symbol> --direction upstream   # Blast radius
+```
+Impact > 3 modules → split PRs.
+
+### Step 5: Implement from SRS + Testcases
+```
+/vsaf-build <path/to/srs> <path/to/testcases>
+```
+TDD discipline: 1 commit per task.
+
+### Step 6: Review + Ship
+```
+/bmad-code-review
+vsaf index
+/vsaf-ship
+```
+```bash
+git push origin feature/<name>
+```
+
+---
+
+## Tool Commands — Quick Reference
+
+| Action | Command |
+|---|---|
+| VSAF onboard | `/vsaf-onboard` |
+| VSAF plan | `/vsaf-plan <requirement>` |
+| VSAF doc PRD | `/vsaf-doc-prd` |
+| VSAF doc SRS | `/vsaf-doc-srs` |
+| VSAF testcase | `/vsaf-test <path/to/srs>` |
+| VSAF implement | `/vsaf-build <srs> <testcases>` |
+| VSAF ship | `/vsaf-ship` |
+| GitNexus index | `gitnexus analyze` |
+| GitNexus web | `gitnexus serve` |
+
+---
+
+## Anti-Patterns
+
+| Do Not | Instead |
+|---|---|
+| Write code before PRD/SRS/testcase | `/vsaf-plan` → `/vsaf-doc-prd` → `/vsaf-doc-srs` → `/vsaf-test` |
+| Implement without impact gate | `gitnexus impact` before editing any symbol |
+| Push without review | 2-layer: 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 → review → human approves |
+
+---
+
+## Commit Discipline
+
+- 1 commit per task from the plan.
+- Each commit message: `<type>: <description>` (feat, fix, refactor, docs, test).
+- Tests must pass after every commit.
+
+---
+
+## Security
+
+- Never hardcode credentials. Use environment variables.

package/assets/templates/CLAUDE.md

@@ -22,7 +22,7 @@ VSAF is a meta-framework for AI-driven SDLC — not an application. It has no so
 | Code Intelligence | GitNexus (MCP) | Impact analysis, call graph, blast radius |
 | Implementation | Superpowers, Claude Code | Brainstorm, TDD execution, code review |
 
-Key directories: `.claude/` (settings + skills), `.vsaf/_bmad/` (BMAD workspace), `.vsaf/docs/` (artifacts), `.gitnexus/` (knowledge graph index).
+Key directories: `.claude/` (settings + skills), `.vsaf/_bmad/` (BMAD workspace), `.vsaf/docs/` (artifacts), `.vsaf/_gitnexus/` (knowledge graph index, `.gitnexus/` is a symlink here).
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.17",
-  "description": "Fix done bmad working with claude code and gitnexus, and add superpowers to vsaf",
+  "version": "3.1.19",
+  "description": "add method for codex",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "superpowers"],
   "bin": {
     "vsaf": "./bin/vsaf.js"

package/src/global.js

@@ -1,11 +1,12 @@
 'use strict';
 const path = require('path');
 const fs = require('fs');
-const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME } = require('./utils');
+const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME, CODEX_HOME } = require('./utils');
 
-const PKG_ROOT   = path.join(__dirname, '..');
-const SKILLS_SRC = path.join(PKG_ROOT, 'tools', 'skills');
-const SKILLS_DST = path.join(CLAUDE_HOME, 'skills');
+const PKG_ROOT        = path.join(__dirname, '..');
+const SKILLS_SRC      = path.join(PKG_ROOT, 'tools', 'skills');
+const SKILLS_DST      = path.join(CLAUDE_HOME, 'skills');
+const CODEX_SKILLS_DST = path.join(CODEX_HOME, 'skills');
 
 async function installGlobal() {
   console.log('\n\x1b[1m╔══════════════════════════════════════════╗\x1b[0m');
@@ -22,26 +23,26 @@ async function installGlobal() {
 // ── Skills ──────────────────────────────────────────────────────────────────
 
 function installSkills() {
-  step('Skills → ~/.claude/skills/');
+  step('Skills → ~/.claude/skills/ + ~/.codex/skills/');
 
   if (!fs.existsSync(SKILLS_SRC)) {
     warn('Skills directory not found in package — skipping');
     return;
   }
 
-  fs.mkdirSync(SKILLS_DST, { recursive: true });
-
+  const entries = fs.readdirSync(SKILLS_SRC, { withFileTypes: true });
   let installed = 0;
 
-  for (const entry of fs.readdirSync(SKILLS_SRC, { withFileTypes: true })) {
-    const src = path.join(SKILLS_SRC, entry.name);
-    const dst = path.join(SKILLS_DST, entry.name);
-
-    entry.isDirectory() ? copyDir(src, dst) : copyFile(src, dst);
-    installed++;
+  for (const dst of [SKILLS_DST, CODEX_SKILLS_DST]) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of entries) {
+      const src = path.join(SKILLS_SRC, entry.name);
+      entry.isDirectory() ? copyDir(src, path.join(dst, entry.name)) : copyFile(src, path.join(dst, entry.name));
+    }
+    installed = entries.length;
   }
 
-  ok(`${installed} skill(s) installed/updated`);
+  ok(`${installed} skill(s) installed/updated → ~/.claude/skills + ~/.codex/skills`);
 }
 
 // ── Binary helpers ───────────────────────────────────────────────────────────

package/src/project.js

@@ -1,7 +1,7 @@
 'use strict';
 const path = require('path');
 const fs   = require('fs');
-const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile } = require('./utils');
+const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, ensureGitnexusSymlink } = require('./utils');
 
 const PKG_ROOT  = path.join(__dirname, '..');
 const TEMPLATES = path.join(PKG_ROOT, 'assets', 'templates');
@@ -23,7 +23,9 @@ async function installProject() {
   console.log('\n  Next steps:');
   console.log('    vsaf status         check all tools');
   console.log('    vsaf index          build/update knowledge graph');
-  console.log('    /plugin install superpowers@claude-plugins-official\n');
+  console.log('\n  \x1b[1mActivate Superpowers:\x1b[0m');
+  console.log('    \x1b[36mClaude Code\x1b[0m  /plugin install superpowers@claude-plugins-official');
+  console.log('    \x1b[36mCodex\x1b[0m        skills auto-loaded — use /superpowers:brainstorming, /superpowers:code-review, etc.\n');
 }
 
 // ── File scaffold ────────────────────────────────────────────────────────────
@@ -32,10 +34,13 @@ function scaffoldFiles() {
   step('Scaffolding project files');
 
   const files = [
-    { tpl: '.claude/settings.json', dst: '.claude/settings.json' },
-    { tpl: 'CLAUDE.md',             dst: 'CLAUDE.md'             },
+    { tpl: '.claude/settings.json',    dst: '.claude/settings.json'    },
+    { tpl: '.codex/instructions.md',   dst: '.codex/instructions.md'   },
+    { tpl: 'CLAUDE.md',                dst: 'CLAUDE.md'                },
   ];
 
+  patchGitignore();
+
   for (const { tpl, dst, chmod } of files) {
     const src    = path.join(TEMPLATES, tpl);
     const dstAbs = path.join(CWD, dst);
@@ -55,6 +60,26 @@ function scaffoldFiles() {
   }
 }
 
+/** Ensures .gitnexus (symlink) is ignored by git — it's a vsaf implementation detail. */
+function patchGitignore() {
+  const gitignorePath = path.join(CWD, '.gitignore');
+  const entry = '.gitnexus';
+
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf8');
+    if (content.split('\n').some((l) => l.trim() === entry)) {
+      ok('.gitignore — .gitnexus already ignored');
+      return;
+    }
+    // Append with a newline separator
+    content = content.endsWith('\n') ? content : content + '\n';
+  }
+
+  fs.writeFileSync(gitignorePath, content + entry + '\n');
+  ok('.gitignore — added .gitnexus');
+}
+
 // ── Tool initialisation ──────────────────────────────────────────────────────
 
 function scaffoldBmadWorkspace() {
@@ -135,6 +160,7 @@ function syncLocalBmadSkills() {
 function initGitNexus() {
   step('GitNexus');
   if (!hasCommand('gitnexus')) { warn('gitnexus not found — run: vsaf global'); return; }
+  ensureGitnexusSymlink();
   const analyzeCmd = 'gitnexus analyze --skip-git';
   info('Indexing repository (gitnexus analyze)...');
   exec(analyzeCmd, { cwd: CWD }) ? ok('Repository indexed') : warn('gitnexus analyze failed — run manually');

package/src/status.js

@@ -1,25 +1,28 @@
 'use strict';
 const path = require('path');
 const fs   = require('fs');
-const { hasCommand, CLAUDE_HOME } = require('./utils');
+const { hasCommand, CLAUDE_HOME, CODEX_HOME } = require('./utils');
 
 async function showStatus() {
   console.log('\n\x1b[1mVSAF Status\x1b[0m\n');
 
   // ── Global ─────────────────────────────────────────────────────────────────
-  console.log('\x1b[1mGlobal  (machine-wide → ~/.claude/)\x1b[0m');
+  console.log('\x1b[1mGlobal  (machine-wide)\x1b[0m');
   checkSkills();
-  checkCmd('gitnexus',  'GitNexus');
+  checkCodexSkills();
+  checkCmd('gitnexus', 'GitNexus');
 
   // ── Project ────────────────────────────────────────────────────────────────
   console.log('\n\x1b[1mProject  (current repo)\x1b[0m');
-  checkPath('.claude/settings.json', 'Project settings');
-  checkPath('CLAUDE.md',             'Workflow rules');
+  checkPath('.claude/settings.json',    'Claude settings');
+  checkPath('.codex/instructions.md',   'Codex instructions');
+  checkPath('CLAUDE.md',                'Workflow rules (Claude)');
+  checkPath('AGENTS.md',                'Workflow rules (Codex/Gemini)');
   checkPath('.vsaf/_bmad',           'BMAD workspace');
   checkPath('.vsaf/docs',            'Project artifact folder');
   checkProjectSkillDir('.claude/skills', 'Project BMAD skills (.claude)');
   checkProjectSkillDir('.codex/skills',  'Project BMAD skills (.codex)');
-  checkPath('.gitnexus',             'GitNexus index');
+  checkPath('.vsaf/_gitnexus',       'GitNexus index');
   console.log('');
 }
 
@@ -31,11 +34,21 @@ function checkCmd(cmd, label) {
 function checkSkills() {
   const dir = path.join(CLAUDE_HOME, 'skills');
   if (!fs.existsSync(dir)) {
-    console.log('  \x1b[31m✗\x1b[0m Skills (not installed)');
+    console.log('  \x1b[31m✗\x1b[0m Claude skills (not installed)');
     return;
   }
   const count = fs.readdirSync(dir).length;
-  console.log(`  \x1b[32m✓\x1b[0m Skills (${count} in ~/.claude/skills/)`);
+  console.log(`  \x1b[32m✓\x1b[0m Claude skills (${count} in ~/.claude/skills/)`);
+}
+
+function checkCodexSkills() {
+  const dir = path.join(CODEX_HOME, 'skills');
+  if (!fs.existsSync(dir)) {
+    console.log('  \x1b[31m✗\x1b[0m Codex skills (not installed)');
+    return;
+  }
+  const count = fs.readdirSync(dir).length;
+  console.log(`  \x1b[32m✓\x1b[0m Codex skills (${count} in ~/.codex/skills/)`);
 }
 
 function checkPath(rel, label) {

package/src/utils.js

@@ -5,6 +5,7 @@ const path = require('path');
 const os = require('os');
 
 const CLAUDE_HOME = path.join(os.homedir(), '.claude');
+const CODEX_HOME  = path.join(os.homedir(), '.codex');
 
 const ok   = (msg) => console.log(`  \x1b[32m✓\x1b[0m ${msg}`);
 const info = (msg) => console.log(`  \x1b[36m→\x1b[0m ${msg}`);
@@ -53,9 +54,33 @@ function hasGitCommits() {
   }
 }
 
+/**
+ * Ensures .gitnexus is a symlink → .vsaf/_gitnexus (actual data dir).
+ * Gitnexus hardcodes .gitnexus/ so we keep it at the root as a symlink
+ * while the real data lives inside .vsaf/.
+ */
+function ensureGitnexusSymlink() {
+  const cwd     = process.cwd();
+  const actual   = path.join(cwd, '.vsaf', '_gitnexus');
+  const linkPath = path.join(cwd, '.gitnexus');
+
+  fs.mkdirSync(actual, { recursive: true });
+
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) return; // already a symlink — nothing to do
+    // Real directory left behind (e.g. gitnexus recreated it after clean)
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  } catch {
+    // linkPath does not exist — will create below
+  }
+
+  fs.symlinkSync(actual, linkPath);
+}
+
 function getPlatform() {
   if (process.platform === 'darwin') return 'macos';
   return 'linux';
 }
 
-module.exports = { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME, getPlatform, hasGitCommits };
+module.exports = { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME, CODEX_HOME, getPlatform, hasGitCommits, ensureGitnexusSymlink };

package/src/workflow.js

@@ -2,7 +2,7 @@
 
 const path = require('path');
 const fs = require('fs');
-const { ok, info, warn, step, hasCommand, exec, hasGitCommits } = require('./utils');
+const { ok, info, warn, step, hasCommand, exec, hasGitCommits, ensureGitnexusSymlink } = require('./utils');
 
 function preflightCheck() {
   // Check: is this a git repo?
@@ -37,6 +37,7 @@ function runIndex() {
     return false;
   }
 
+  ensureGitnexusSymlink();
   info('Running gitnexus analyze...');
   const gitnexusOk = exec('gitnexus analyze --skip-git');
   if (gitnexusOk) {
@@ -78,7 +79,12 @@ function runClean() {
   }
 
   info('Running gitnexus clean...');
-  const cleanOk = exec('gitnexus clean');
+  const cleanOk = exec('gitnexus clean --force');
+  // gitnexus clean deletes the .gitnexus symlink — clear actual data dir too
+  const actualDir = path.join(process.cwd(), '.vsaf', '_gitnexus');
+  if (fs.existsSync(actualDir)) fs.rmSync(actualDir, { recursive: true, force: true });
+  // Restore symlink pointing at the now-empty dir
+  ensureGitnexusSymlink();
   cleanOk ? ok('GitNexus index cleaned') : warn('gitnexus clean failed — run manually');
   return cleanOk;
 }

package/tools/skills/vsaf-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vsaf-plan
-description: Plan a new feature/task. Use when receiving a requirement that needs scope analysis, impact assessment, and approach strategy. Dual brainstorm (Superpowers + BMAD). Example: /vsaf-plan create user management module
+description: "Plan a new feature/task. Use when receiving a requirement that needs scope analysis, impact assessment, and approach strategy. Dual brainstorm (Superpowers + BMAD). Example: /vsaf-plan create user management module"
 ---
 
 # VSAF Plan