@ngocsangairvds/vsaf 3.1.24 → 3.1.26

package/assets/templates/CLAUDE.md

@@ -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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.24",
-  "description": "fix gitnexus skip git",
+  "version": "3.1.26",
+  "description": "fix confluence format",
   "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, '..');
@@ -16,6 +17,7 @@ async function installGlobal() {
   installSkills();
   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');
 }
@@ -69,4 +71,95 @@ function setupGitnexusMcp() {
     : 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/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,151 @@
+---
+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
+- `[file]` — optional path to a specific markdown file (defaults to scanning `.vsaf/docs/planning-artifacts/prd-*.md`)
+- `[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 markdown file must exist
+
+## Steps
+
+### Step 1 — Find PRD file
+- If a file path was given as argument, use that file directly
+- Otherwise 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 file 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
+- If file is from `prd-*.md`: title = `[PRD] {Feature Name}` (derive from filename: `prd-user-management.md` → `[PRD] User Management`)
+- Otherwise: use the first `# Heading` in the file as the page title, or the filename stem if no heading found
+
+### Step 4 — Convert markdown → Confluence storage format (HTML)
+
+**CRITICAL: Never send raw markdown or CDATA-wrapped content to Confluence.**
+**CRITICAL: Do NOT wrap the entire page body in `<![CDATA[...]]>`. CDATA is only valid inside `<ac:plain-text-body>` for code blocks.**
+
+Convert the full file content to Confluence storage format using these rules:
+
+**Block elements:**
+```
+# Heading      → <h1>Heading</h1>
+## Heading     → <h2>Heading</h2>
+### Heading    → <h3>Heading</h3>
+#### Heading   → <h4>Heading</h4>
+paragraph text → <p>paragraph text</p>
+---            → <hr/>
+```
+
+**Inline elements:**
+```
+**bold**       → <strong>bold</strong>
+*italic*       → <em>italic</em>
+`inline code`  → <code>inline code</code>
+[text](url)    → <a href="url">text</a>
+```
+
+**Lists:**
+```
+- item         → <ul><li>item</li></ul>
+1. item        → <ol><li>item</li></ol>
+```
+
+**Tables:**
+```
+| H1 | H2 |        →  <table><tbody>
+|----|----|              <tr><th>H1</th><th>H2</th></tr>
+| a  | b  |              <tr><td>a</td><td>b</td></tr>
+                       </tbody></table>
+```
+
+**Code blocks — the ONLY place CDATA is correct:**
+````
+```lang           →  <ac:structured-macro ac:name="code">
+code here              <ac:parameter ac:name="language">lang</ac:parameter>
+```                    <ac:plain-text-body><![CDATA[code here]]></ac:plain-text-body>
+                     </ac:structured-macro>
+````
+
+**Info/warning/tip boxes:**
+```
+> [!NOTE] title   →  <ac:structured-macro ac:name="info">
+> body                  <ac:parameter ac:name="title">title</ac:parameter>
+                        <ac:rich-text-body><p>body</p></ac:rich-text-body>
+                      </ac:structured-macro>
+
+> [!WARNING]      →  ac:name="warning"
+> [!TIP]          →  ac:name="tip"
+```
+
+**Blockquote:**
+```
+> text            → <blockquote><p>text</p></blockquote>
+```
+
+When calling the Confluence MCP create/update tool, set the content representation to **`storage`**.
+
+### Step 5 — Check if page exists
+Use the `confluence` MCP to search for a page with that exact title in the configured space:
+```
+CQL: title = "{page_title}" AND space = "{space_key}"
+```
+- **Found** → proceed to Step 6 (update)
+- **Not found** → proceed to Step 7 (create)
+
+### Step 6 — Update existing page
+Call the `confluence` MCP update tool with:
+- Page ID from search result
+- Content: the **converted wiki markup** from Step 4
+- Representation: `wiki`
+- Version comment: the `[comment]` argument (or "Updated via vsaf-push-prd" if blank)
+
+Confirm the two-stage update prompt if the MCP requires it.
+
+### Step 7 — Create new page
+Call the `confluence` MCP create tool with:
+- Space key from config
+- Parent page title from config (find its ID first if needed)
+- Title: determined in Step 3
+- Content: the **converted wiki markup** from Step 4
+- Representation: `wiki`
+- Version comment: the `[comment]` argument (or "Created via vsaf-push-prd" if blank)
+
+### Step 8 — Output to user
+```
+## PRD pushed to Confluence
+
+- Page:    {page_title}
+- 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 file during this step
+- The file argument accepts any markdown file path, not just files under `.vsaf/`

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

@@ -0,0 +1,163 @@
+---
+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
+- `[file]` — optional path to a specific markdown file (defaults to scanning `.vsaf/docs/srs/*.md`)
+- `[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 markdown file must exist
+
+## Steps
+
+### Step 1 — Find SRS file
+- If a file path was given as argument, use that file directly
+- Otherwise 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 file 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
+- If file is from `srs-*.md` or `SRS-*.md`: title = `[SRS] {Feature Name}` (derive from filename)
+- Otherwise: use the first `# Heading` in the file as the page title, or the filename stem if no heading found
+
+### Step 4 — Convert markdown → Confluence storage format (HTML)
+
+**CRITICAL: Never send raw markdown or CDATA-wrapped content to Confluence.**
+**CRITICAL: Do NOT wrap the entire page body in `<![CDATA[...]]>`. CDATA is only valid inside `<ac:plain-text-body>` for code blocks.**
+
+Convert the full file content to Confluence storage format using these rules:
+
+**Block elements:**
+```
+# Heading      → <h1>Heading</h1>
+## Heading     → <h2>Heading</h2>
+### Heading    → <h3>Heading</h3>
+#### Heading   → <h4>Heading</h4>
+paragraph text → <p>paragraph text</p>
+---            → <hr/>
+```
+
+**Inline elements:**
+```
+**bold**       → <strong>bold</strong>
+*italic*       → <em>italic</em>
+`inline code`  → <code>inline code</code>
+[text](url)    → <a href="url">text</a>
+```
+
+**Lists:**
+```
+- item         → <ul><li>item</li></ul>
+1. item        → <ol><li>item</li></ol>
+```
+
+**Tables:**
+```
+| H1 | H2 |        →  <table><tbody>
+|----|----|              <tr><th>H1</th><th>H2</th></tr>
+| a  | b  |              <tr><td>a</td><td>b</td></tr>
+                       </tbody></table>
+```
+
+**Code blocks — the ONLY place CDATA is correct:**
+````
+```lang           →  <ac:structured-macro ac:name="code">
+code here              <ac:parameter ac:name="language">lang</ac:parameter>
+```                    <ac:plain-text-body><![CDATA[code here]]></ac:plain-text-body>
+                     </ac:structured-macro>
+````
+
+**Info/warning/tip boxes:**
+```
+> [!NOTE] title   →  <ac:structured-macro ac:name="info">
+> body                  <ac:parameter ac:name="title">title</ac:parameter>
+                        <ac:rich-text-body><p>body</p></ac:rich-text-body>
+                      </ac:structured-macro>
+
+> [!WARNING]      →  ac:name="warning"
+> [!TIP]          →  ac:name="tip"
+```
+
+**Blockquote:**
+```
+> text            → <blockquote><p>text</p></blockquote>
+```
+
+When calling the Confluence MCP create/update tool, set the content representation to **`storage`**.
+
+### Step 5 — Check if page exists
+Use the `confluence` MCP to search for a page with that exact title in the configured space:
+```
+CQL: title = "{page_title}" AND space = "{space_key}"
+```
+- **Found** → proceed to Step 6 (update)
+- **Not found** → proceed to Step 7 (create)
+
+### Step 6 — Update existing page
+Call the `confluence` MCP update tool with:
+- Page ID from search result
+- Content: the **converted wiki markup** from Step 4
+- Representation: `wiki`
+- Version comment: the `[comment]` argument (or "Updated via vsaf-push-srs" if blank)
+
+Confirm the two-stage update prompt if the MCP requires it.
+
+### Step 7 — Create new page
+Call the `confluence` MCP create tool with:
+- Space key from config
+- Parent page title from config (find its ID first if needed)
+- Title: determined in Step 3
+- Content: the **converted wiki markup** from Step 4
+- Representation: `wiki`
+- Version comment: the `[comment]` argument (or "Created via vsaf-push-srs" if blank)
+
+### Step 8 — Link SRS page to PRD page (if PRD page exists)
+- Search Confluence for the corresponding `[PRD] {feature-name}` page
+- If found: prepend this storage-format block at the top of the SRS content before pushing:
+  ```xml
+  <ac:structured-macro ac:name="info">
+    <ac:parameter ac:name="title">Related Documents</ac:parameter>
+    <ac:rich-text-body><p><a href="{prd_url}">[PRD] {feature-name}</a></p></ac:rich-text-body>
+  </ac:structured-macro>
+  ```
+- This creates traceability in Confluence
+
+### Step 9 — Output to user
+```
+## SRS pushed to Confluence
+
+- Page:     {page_title}
+- 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 file during this step
+- SRS result files (`*-results.md`) are test outputs — push those separately if needed
+- The file argument accepts any markdown file path, not just files under `.vsaf/`