@ngocsangairvds/vsaf 3.1.23 → 3.1.25

package/assets/templates/CLAUDE.md

@@ -2,19 +2,19 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-> VSAF v3 — Agentic AI SDLC Framework. 4 integrated tools. 2-layer review.
+> VSAF v3 — Agentic AI SDLC Framework. 3 integrated tools. 2-layer review.
 
 ---
 
 ## Prerequisites
 
-Node.js ≥18, Python ≥3.10, Git, Claude Code subscription. Run `npx vsaf init` (idempotent) to install all tools.
+Node.js ≥18, Git, Claude Code subscription. 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 4-layer stack:
+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 |
 |-------|-------|---------|
@@ -66,11 +66,13 @@ npx vsaf init
 - Use `/vsaf-onboard` for the structured onboarding sequence.
 - Do not modify code on day one.
 
-### Step 2: Planning + Requirement -> PRD -> SRS
+### Step 2: Planning + Requirement -> PRD -> SRS -> Confluence
 ```
 /vsaf-plan <requirement>    # scope + impact + approach
 /vsaf-doc-prd              # write PRD from approved scope
+/vsaf-push-prd <comment>   # publish PRD to Confluence
 /vsaf-doc-srs              # write SRS from PRD
+/vsaf-push-srs <comment>   # publish SRS to Confluence
 ```
 Quick Flow (bug fix) may use a mini-SRS, but impact analysis is still mandatory.
 
@@ -118,7 +120,9 @@ PR description must include: impact summary (from GitNexus), test results.
 | VSAF onboard | `/vsaf-onboard` |
 | VSAF plan | `/vsaf-plan <requirement>` |
 | VSAF doc PRD | `/vsaf-doc-prd` |
+| VSAF push PRD → Confluence | `/vsaf-push-prd <comment>` |
 | VSAF doc SRS | `/vsaf-doc-srs` |
+| VSAF push SRS → Confluence | `/vsaf-push-srs <comment>` |
 | VSAF testcase | `/vsaf-test <path/to/srs>` |
 | VSAF implement | `/vsaf-build <srs> <testcases>` |
 | VSAF ship | `/vsaf-ship` |

package/bin/vsaf.js

@@ -24,7 +24,7 @@ GLOBAL  (once per machine → ~/.claude/)
 PER PROJECT  (per repo, run inside the repo root)
   .claude/settings.json   Local AI settings
   .claude/skills + .codex/skills  BMAD skills synced for local clients
-  _bmad + _bmad-output    BMAD workspace + generated artifacts folders
+  .vsaf/_bmad             BMAD workspace (planning configs + templates)
   CLAUDE.md               8-step workflow rules
 
 EXAMPLES

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.23",
-  "description": "fix gitnexus with windows",
+  "version": "3.1.25",
+  "description": "fix gitnexus skip git",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "superpowers"],
   "bin": {
     "vsaf": "./bin/vsaf.js"

package/src/global.js

@@ -1,6 +1,7 @@
 'use strict';
 const path = require('path');
 const fs = require('fs');
+const readline = require('readline');
 const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME, CODEX_HOME } = require('./utils');
 
 const PKG_ROOT        = path.join(__dirname, '..');
@@ -14,8 +15,9 @@ async function installGlobal() {
   console.log(  '\x1b[1m╚══════════════════════════════════════════╝\x1b[0m');
 
   installSkills();
-  installBinary('gitnexus', () => exec('npm install -g gitnexus@1.6.4-rc.64'));
+  installBinary('gitnexus', () => exec('npm install -g gitnexus@1.6.4-rc.79'));
   setupGitnexusMcp();
+  await setupConfluenceMcp();
 
   console.log('\n\x1b[32m\x1b[1m✓ Global infra ready.\x1b[0m\n');
 }
@@ -64,9 +66,100 @@ function setupGitnexusMcp() {
   }
 
   info('Configuring GitNexus MCP...');
-  exec('claude mcp add gitnexus -- npx -y gitnexus@1.6.4-rc.64 mcp')
+  exec('claude mcp add gitnexus -- npx -y gitnexus@1.6.4-rc.79 mcp')
     ? ok('GitNexus MCP configured')
-    : warn('MCP setup failed — run manually: claude mcp add gitnexus -- npx -y gitnexus@1.6.4-rc.64 mcp');
+    : warn('MCP setup failed — run manually: claude mcp add gitnexus -- npx -y gitnexus@1.6.4-rc.79 mcp');
+}
+
+async function setupConfluenceMcp() {
+  step('Confluence MCP');
+
+  if (!hasCommand('claude')) {
+    info('Claude Code CLI not found — skip Confluence MCP setup');
+    return;
+  }
+
+  const url = await promptInput(
+    '  Confluence URL (blank to skip, e.g. http://confluence.company.com): '
+  );
+
+  if (!url) {
+    warn('Confluence MCP skipped — run manually later:\n' +
+         '    claude mcp add confluence -e CONF_MODE=server \\\n' +
+         '      -e CONF_BASE_URL=<your-url> \\\n' +
+         '      -e CONF_AUTH_MODE=bearer \\\n' +
+         '      -e CONF_TOKEN=<your-token> \\\n' +
+         '      -- npx -y confluence-mcp-server');
+    return;
+  }
+
+  const token = await promptSecret(
+    '  Confluence Personal Access Token: '
+  );
+
+  if (!token) {
+    warn('Confluence MCP skipped — token is required');
+    return;
+  }
+
+  const cmd = [
+    'claude mcp add confluence',
+    '-e CONF_MODE=server',
+    `-e CONF_BASE_URL=${url}`,
+    '-e CONF_AUTH_MODE=bearer',
+    `-e CONF_TOKEN=${token}`,
+    '-- npx -y confluence-mcp-server',
+  ].join(' ');
+
+  exec(cmd)
+    ? ok('Confluence MCP configured')
+    : warn('Confluence MCP setup failed — run manually (see above)');
+}
+
+function promptInput(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+function promptSecret(question) {
+  return new Promise((resolve) => {
+    // Non-TTY (CI, pipe): fall back to plain readline without hiding
+    if (!process.stdin.isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+      return;
+    }
+
+    process.stdout.write(question);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+
+    let input = '';
+    const onData = (buf) => {
+      const ch = buf.toString('utf8');
+      if (ch === '\r' || ch === '\n' || ch === '\x00') {
+        // Enter — done
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdout.write('\n');
+        process.stdin.removeListener('data', onData);
+        resolve(input.trim());
+      } else if (ch === '\x03') {
+        // Ctrl+C
+        process.stdout.write('\n');
+        process.exit(0);
+      } else if (ch === '\x7f' || ch === '\b') {
+        // Backspace
+        input = input.slice(0, -1);
+      } else {
+        input += ch;
+      }
+    };
+
+    process.stdin.on('data', onData);
+  });
 }
 
 module.exports = { installGlobal };

package/src/workflow.js

@@ -33,7 +33,7 @@ function runIndex({ skipGit = false } = {}) {
     return false;
   }
 
-  if (!preflightCheck()) {
+  if (!skipGit && !preflightCheck()) {
     return false;
   }
 

package/tools/bmad/bmm/config.yaml

@@ -14,3 +14,7 @@ user_name: DuongOT
 communication_language: English
 document_output_language: English
 output_folder: "{project-root}/_bmad-output"
+
+# Confluence Integration (set by /vsaf-push-prd or /vsaf-push-srs on first use)
+confluence_space_key: ""
+confluence_parent_page: ""

package/tools/skills/vsaf-doc-prd/SKILL.md

@@ -48,7 +48,8 @@ Must have run `/vsaf-plan` and have its output before running this skill.
 - Validation: [PASS / FAIL — details if fail]
 
 ## Next step
-Run /vsaf-doc-srs to write SRS from this PRD
+- Run /vsaf-push-prd <comment> to publish this PRD to Confluence
+- Or run /vsaf-doc-srs to write SRS from this PRD
 ```
 
 ## Notes

package/tools/skills/vsaf-doc-srs/SKILL.md

@@ -159,7 +159,8 @@ Save the SRS document to: `.vsaf/docs/srs/SRS-[project-name]-[FR-ID]-[feature-na
 - [SRS sections still containing {{...}} that need additional input]
 
 ## Next step
-Run /vsaf-test .vsaf/docs/srs/SRS-[...].md to generate testcases
+- Run /vsaf-push-srs <comment> to publish this SRS to Confluence
+- Or run /vsaf-test .vsaf/docs/srs/SRS-[...].md to generate testcases
 ```
 
 ## Notes

package/tools/skills/vsaf-push-prd/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: vsaf-push-prd
+description: Push PRD document to Confluence. Use after /vsaf-doc-prd or /vsaf-doc-prd (edit) to publish or update the PRD page on Confluence. Accepts an optional comment as version note.
+---
+
+# VSAF Push PRD
+
+## Objective
+Publish the current PRD to Confluence — create a new page if it doesn't exist, or update the existing one. The comment becomes the Confluence version note.
+
+## Input
+- `[comment]` — optional version note (e.g. "Initial draft", "Updated scope after stakeholder review")
+
+## Prerequisites
+- Confluence MCP must be configured (`vsaf init` sets this up)
+- A PRD file must exist in `.vsaf/docs/planning-artifacts/`
+
+## Steps
+
+### Step 1 — Find PRD file
+- List files in `.vsaf/docs/planning-artifacts/` matching `prd-*.md`
+- If multiple found: ask user which one to push
+- If none found: STOP — tell user to run `/vsaf-doc-prd` first
+- Read full PRD content
+
+### Step 2 — Load Confluence config
+Read `.vsaf/_bmad/bmm/config.yaml` and extract:
+- `confluence_space_key` — Confluence space (e.g. `PROJ`)
+- `confluence_parent_page` — parent page title (e.g. `Project Documentation`)
+
+If either field is missing or empty:
+- Ask user: "Enter Confluence space key (e.g. PROJ):"
+- Ask user: "Enter parent page title in Confluence (blank = root of space):"
+- Save answers back to config so the user is not asked again
+
+### Step 3 — Determine page title
+Page title format: `[PRD] {feature-name}` — derive feature name from the filename (e.g. `prd-user-management.md` → `[PRD] User Management`)
+
+### Step 4 — Check if page exists
+Use the `confluence` MCP to search for a page with that exact title in the configured space:
+```
+CQL: title = "[PRD] {feature-name}" AND space = "{space_key}"
+```
+- **Found** → proceed to Step 5 (update)
+- **Not found** → proceed to Step 6 (create)
+
+### Step 5 — Update existing page
+- Use the `confluence` MCP update tool with:
+  - Page ID from search result
+  - New content: full PRD markdown converted to Confluence format
+  - Version comment: the `[comment]` argument (or "Updated via vsaf-push-prd" if blank)
+- Confirm the two-stage update if the MCP requires it
+
+### Step 6 — Create new page
+- Use the `confluence` MCP create tool with:
+  - Space key from config
+  - Parent page title from config (find its ID first if needed)
+  - Title: `[PRD] {feature-name}`
+  - Content: full PRD markdown
+  - Version comment: the `[comment]` argument (or "Created via vsaf-push-prd" if blank)
+
+### Step 7 — Output to user
+```
+## PRD pushed to Confluence
+
+- Page:    [PRD] {feature-name}
+- Action:  [Created / Updated]
+- Space:   {space_key}
+- Comment: {comment}
+- URL:     {confluence_page_url}
+
+## Next step
+Run /vsaf-push-srs to also publish the SRS, or continue with /vsaf-build
+```
+
+## Notes
+- Never push a PRD that has failed `/vsaf-validate-prd` validation
+- If the Confluence MCP is not configured, tell the user to run `vsaf init` and enter their token
+- Do not modify the local PRD file during this step

package/tools/skills/vsaf-push-srs/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: vsaf-push-srs
+description: Push SRS document to Confluence. Use after /vsaf-doc-srs or SRS edits to publish or update the SRS page on Confluence. Accepts an optional comment as version note.
+---
+
+# VSAF Push SRS
+
+## Objective
+Publish the current SRS to Confluence — create a new page if it doesn't exist, or update the existing one. The comment becomes the Confluence version note.
+
+## Input
+- `[comment]` — optional version note (e.g. "Initial draft", "Revised after tech review")
+
+## Prerequisites
+- Confluence MCP must be configured (`vsaf init` sets this up)
+- An SRS file must exist in `.vsaf/docs/srs/`
+
+## Steps
+
+### Step 1 — Find SRS file
+- List files in `.vsaf/docs/srs/` matching `*.md` (exclude `*-results.md`)
+- If multiple found: ask user which one to push
+- If none found: STOP — tell user to run `/vsaf-doc-srs` first
+- Read full SRS content
+
+### Step 2 — Load Confluence config
+Read `.vsaf/_bmad/bmm/config.yaml` and extract:
+- `confluence_space_key` — Confluence space (e.g. `PROJ`)
+- `confluence_parent_page` — parent page title (e.g. `Project Documentation`)
+
+If either field is missing or empty:
+- Ask user: "Enter Confluence space key (e.g. PROJ):"
+- Ask user: "Enter parent page title in Confluence (blank = root of space):"
+- Save answers back to config so the user is not asked again
+
+### Step 3 — Determine page title
+Page title format: `[SRS] {feature-name}` — derive feature name from the filename (e.g. `user-management.md` → `[SRS] User Management`)
+
+### Step 4 — Check if page exists
+Use the `confluence` MCP to search for a page with that exact title in the configured space:
+```
+CQL: title = "[SRS] {feature-name}" AND space = "{space_key}"
+```
+- **Found** → proceed to Step 5 (update)
+- **Not found** → proceed to Step 6 (create)
+
+### Step 5 — Update existing page
+- Use the `confluence` MCP update tool with:
+  - Page ID from search result
+  - New content: full SRS markdown converted to Confluence format
+  - Version comment: the `[comment]` argument (or "Updated via vsaf-push-srs" if blank)
+- Confirm the two-stage update if the MCP requires it
+
+### Step 6 — Create new page
+- Use the `confluence` MCP create tool with:
+  - Space key from config
+  - Parent page title from config (find its ID first if needed)
+  - Title: `[SRS] {feature-name}`
+  - Content: full SRS markdown
+  - Version comment: the `[comment]` argument (or "Created via vsaf-push-srs" if blank)
+
+### Step 7 — Link SRS page to PRD page (if PRD page exists)
+- Search Confluence for the corresponding `[PRD] {feature-name}` page
+- If found: add a "Related Documents" section or comment on the SRS page linking back to the PRD
+- This creates traceability in Confluence
+
+### Step 8 — Output to user
+```
+## SRS pushed to Confluence
+
+- Page:    [SRS] {feature-name}
+- Action:  [Created / Updated]
+- Space:   {space_key}
+- Comment: {comment}
+- URL:     {confluence_page_url}
+- PRD link: [linked / not found]
+
+## Next step
+Run /vsaf-test to generate testcases from this SRS, or /vsaf-build to implement
+```
+
+## Notes
+- If the Confluence MCP is not configured, tell the user to run `vsaf init` and enter their token
+- Do not modify the local SRS file during this step
+- SRS result files (`*-results.md`) are test outputs — push those separately if needed

package/assets/templates/Makefile

@@ -1,29 +0,0 @@
-# Optional compatibility wrapper for teams that still type `make`.
-# Preferred usage: run `vsaf <command>` directly.
-
-.PHONY: help index verify review archive status mine clean
-
-help: ## Show this help
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
-		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
-
-index: ## Run `vsaf index`
-	@vsaf index
-
-verify: ## Run `vsaf verify`
-	@vsaf verify
-
-review: ## Run `vsaf review`
-	@vsaf review
-
-archive: ## Run `vsaf archive`
-	@vsaf archive
-
-mine: ## Run `vsaf mine`
-	@vsaf mine
-
-status: ## Run `vsaf status`
-	@vsaf status
-
-clean: ## Run `vsaf clean`
-	@vsaf clean