@ngocsangairvds/vsaf 3.1.26 → 3.1.27

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.26",
-  "description": "fix confluence format",
+  "version": "3.1.27",
+  "description": "improve confluence format",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "superpowers"],
   "bin": {
     "vsaf": "./bin/vsaf.js"

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

@@ -9,7 +9,7 @@ description: Push PRD document to Confluence. Use after /vsaf-doc-prd or /vsaf-d
 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`)
+- `[file]` — optional path to a specific markdown file or directory (defaults to scanning `.vsaf/docs/planning-artifacts/prd-*.md`)
 - `[comment]` — optional version note (e.g. "Initial draft", "Updated scope after stakeholder review")
 
 ## Prerequisites
@@ -18,11 +18,12 @@ Publish the current PRD to Confluence — create a new page if it doesn't 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
+### Step 1 — Find PRD file(s)
+- If a **directory path** was given (e.g. `@docs/architecture/`): read all `*.md` files in that directory and combine them into a single page body, separated by `<hr/>`. Use the directory name as the page title base.
+- If a **specific file path** was given: 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
@@ -35,16 +36,23 @@ If either field is missing or empty:
 - 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
+### Step 3 — Determine page title and parent page ID
 - If file is from `prd-*.md`: title = `[PRD] {Feature Name}` (derive from filename: `prd-user-management.md` → `[PRD] User Management`)
+- If input was a directory: title = the numbered section label provided by the user (e.g. `3.4.2.12 VRoute — Architecture Design`)
 - 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)
+**Resolve parent page ID:**
+Use `confluence_search_pages` to search for the parent page title in the configured space. Extract the `id` field from the result — this is the `parentId` needed for page creation. Do NOT skip this step.
 
-**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.**
+### Step 4 — Convert markdown → Confluence storage format
 
-Convert the full file content to Confluence storage format using these rules:
+**CRITICAL RULES — read before writing a single tag:**
+
+1. **Never send raw markdown.** All content must be converted to Confluence Storage Format (XHTML).
+2. **Never wrap the entire body in `<![CDATA[...]]>`.** CDATA is ONLY valid inside `<ac:plain-text-body>` within code macros.
+3. **All Confluence macro attributes MUST use the `ac:` namespace prefix.** The tag is `<ac:parameter ac:name="...">`, never `<parameter name="...">`. Wrong namespace = XML parse error.
+4. **Escape HTML entities in regular text:** `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`.
+5. **Every opened tag must be closed.** Confluence's XML parser is strict — an unclosed tag aborts the entire page push.
 
 **Block elements:**
 ```
@@ -72,19 +80,20 @@ paragraph text → <p>paragraph text</p>
 
 **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>
+| 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>
-````
+**Code blocks — the ONLY correct place for CDATA:**
+```
+```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>
+```
+⚠️ The attribute is `ac:name` not `name`. Using `<ac:parameter name="language">` will cause an XML parse error.
 
 **Info/warning/tip boxes:**
 ```
@@ -102,33 +111,27 @@ code here              <ac:parameter ac:name="language">lang</ac:parameter>
 > 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}"
-```
+Use `confluence_search_pages` to search for a page with that exact title in the configured space.
 - **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`
+Call `confluence_update_page` with:
+- `pageId`: the ID from the search result
+- `bodyStorageValue`: the **storage format HTML** converted in Step 4
 - 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)
+Call `confluence_create_page` with:
+- `spaceKey`: the space key from config
+- `parentId`: the parent page ID resolved in Step 3
+- `title`: the page title determined in Step 3
+- `bodyStorageValue`: the **storage format HTML** converted in Step 4
+
+> The `bodyStorageValue` parameter takes Confluence Storage Format (XHTML) directly — do not add a separate `representation` field.
 
 ### Step 8 — Output to user
 ```
@@ -148,4 +151,4 @@ Run /vsaf-push-srs to also publish the SRS, or continue with /vsaf-build
 - 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/`
+- The file argument accepts any markdown file path or directory, not just files under `.vsaf/`

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

@@ -9,7 +9,7 @@ description: Push SRS document to Confluence. Use after /vsaf-doc-srs or SRS edi
 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`)
+- `[file]` — optional path to a specific markdown file or directory (defaults to scanning `.vsaf/docs/srs/*.md`)
 - `[comment]` — optional version note (e.g. "Initial draft", "Revised after tech review")
 
 ## Prerequisites
@@ -18,11 +18,12 @@ Publish the current SRS to Confluence — create a new page if it doesn't 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
+### Step 1 — Find SRS file(s)
+- If a **directory path** was given (e.g. `@docs/srs/`): read all `*.md` files in that directory (excluding `*-results.md`) and combine them into a single page body, separated by `<hr/>`. Use the directory name as the page title base.
+- If a **specific file path** was given: 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
@@ -35,16 +36,23 @@ If either field is missing or empty:
 - 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
+### Step 3 — Determine page title and parent page ID
 - If file is from `srs-*.md` or `SRS-*.md`: title = `[SRS] {Feature Name}` (derive from filename)
+- If input was a directory: title = the numbered section label provided by the user
 - 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)
+**Resolve parent page ID:**
+Use `confluence_search_pages` to search for the parent page title in the configured space. Extract the `id` field from the result — this is the `parentId` needed for page creation. Do NOT skip this step.
 
-**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.**
+### Step 4 — Convert markdown → Confluence storage format
 
-Convert the full file content to Confluence storage format using these rules:
+**CRITICAL RULES — read before writing a single tag:**
+
+1. **Never send raw markdown.** All content must be converted to Confluence Storage Format (XHTML).
+2. **Never wrap the entire body in `<![CDATA[...]]>`.** CDATA is ONLY valid inside `<ac:plain-text-body>` within code macros.
+3. **All Confluence macro attributes MUST use the `ac:` namespace prefix.** The tag is `<ac:parameter ac:name="...">`, never `<parameter name="...">`. Wrong namespace = XML parse error.
+4. **Escape HTML entities in regular text:** `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`.
+5. **Every opened tag must be closed.** Confluence's XML parser is strict — an unclosed tag aborts the entire page push.
 
 **Block elements:**
 ```
@@ -72,19 +80,20 @@ paragraph text → <p>paragraph text</p>
 
 **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>
+| 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>
-````
+**Code blocks — the ONLY correct place for CDATA:**
+```
+```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>
+```
+⚠️ The attribute is `ac:name` not `name`. Using `<ac:parameter name="language">` will cause an XML parse error.
 
 **Info/warning/tip boxes:**
 ```
@@ -102,37 +111,31 @@ code here              <ac:parameter ac:name="language">lang</ac:parameter>
 > 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}"
-```
+Use `confluence_search_pages` to search for a page with that exact title in the configured space.
 - **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`
+Call `confluence_update_page` with:
+- `pageId`: the ID from the search result
+- `bodyStorageValue`: the **storage format HTML** converted in Step 4
 - 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)
+Call `confluence_create_page` with:
+- `spaceKey`: the space key from config
+- `parentId`: the parent page ID resolved in Step 3
+- `title`: the page title determined in Step 3
+- `bodyStorageValue`: the **storage format HTML** converted in Step 4
+
+> The `bodyStorageValue` parameter takes Confluence Storage Format (XHTML) directly — do not add a separate `representation` field.
 
 ### 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:
+- If found: prepend this 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>
@@ -160,4 +163,4 @@ Run /vsaf-test to generate testcases from this SRS, or /vsaf-build to implement
 - 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/`
+- The file argument accepts any markdown file path or directory, not just files under `.vsaf/`