@ngocsangairvds/vsaf 3.1.25 → 3.1.27

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.25",
-  "description": "fix gitnexus skip git",
+  "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,19 +9,22 @@ 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 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
 - Confluence MCP must be configured (`vsaf init` sets this up)
-- A PRD file must exist in `.vsaf/docs/planning-artifacts/`
+- A PRD markdown file must exist
 
 ## 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 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
 Read `.vsaf/_bmad/bmm/config.yaml` and extract:
@@ -33,37 +36,108 @@ 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
-Page title format: `[PRD] {feature-name}` — derive feature name from the filename (e.g. `prd-user-management.md` → `[PRD] User Management`)
+### 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 — Check if page exists
-Use the `confluence` MCP to search for a page with that exact title in the configured space:
+**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.
+
+### Step 4 — Convert markdown → Confluence storage format
+
+**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:**
+```
+# 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:**
 ```
-CQL: title = "[PRD] {feature-name}" AND space = "{space_key}"
+| H1 | H2 |   →  <table><tbody>
+|----|----| →       <tr><th>H1</th><th>H2</th></tr>
+| a  | b  |          <tr><td>a</td><td>b</td></tr>
+               </tbody></table>
 ```
-- **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
+**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:**
+```
+> [!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>
+```
+
+### Step 5 — Check if page exists
+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 `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 `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
 
-### 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)
+> The `bodyStorageValue` parameter takes Confluence Storage Format (XHTML) directly — do not add a separate `representation` field.
 
-### Step 7 — Output to user
+### Step 8 — Output to user
 ```
 ## PRD pushed to Confluence
 
-- Page:    [PRD] {feature-name}
+- Page:    {page_title}
 - Action:  [Created / Updated]
 - Space:   {space_key}
 - Comment: {comment}
@@ -76,4 +150,5 @@ 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
+- Do not modify the local file during this step
+- The file argument accepts any markdown file path or directory, not just files under `.vsaf/`

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

@@ -9,19 +9,22 @@ 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 or directory (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 file must exist in `.vsaf/docs/srs/`
+- An SRS markdown file must exist
 
 ## 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 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
 Read `.vsaf/_bmad/bmm/config.yaml` and extract:
@@ -33,46 +36,123 @@ 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
-Page title format: `[SRS] {feature-name}` — derive feature name from the filename (e.g. `user-management.md` → `[SRS] User Management`)
+### 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 — Check if page exists
-Use the `confluence` MCP to search for a page with that exact title in the configured space:
+**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.
+
+### Step 4 — Convert markdown → Confluence storage format
+
+**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:**
+```
+# 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:**
 ```
-CQL: title = "[SRS] {feature-name}" AND space = "{space_key}"
+| H1 | H2 |   →  <table><tbody>
+|----|----| →       <tr><th>H1</th><th>H2</th></tr>
+| a  | b  |          <tr><td>a</td><td>b</td></tr>
+               </tbody></table>
 ```
-- **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
+**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:**
+```
+> [!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>
+```
+
+### Step 5 — Check if page exists
+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 `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 `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
 
-### 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)
+> The `bodyStorageValue` parameter takes Confluence Storage Format (XHTML) directly — do not add a separate `representation` field.
 
-### Step 7 — Link SRS page to PRD page (if PRD page exists)
+### Step 8 — 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
+- 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>
+    <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 8 — Output to user
+### Step 9 — Output to user
 ```
 ## SRS pushed to Confluence
 
-- Page:    [SRS] {feature-name}
-- Action:  [Created / Updated]
-- Space:   {space_key}
-- Comment: {comment}
-- URL:     {confluence_page_url}
+- Page:     {page_title}
+- Action:   [Created / Updated]
+- Space:    {space_key}
+- Comment:  {comment}
+- URL:      {confluence_page_url}
 - PRD link: [linked / not found]
 
 ## Next step
@@ -81,5 +161,6 @@ 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
+- 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 or directory, not just files under `.vsaf/`