@ngocsangairvds/vsaf 4.0.1 → 4.0.3

package/skills/vds-skill/pack.yaml

@@ -0,0 +1,24 @@
+name: vds-skill
+version: 1.0.0
+description: Viettel VDS automation skills — opt-in pack wrapping vds-cli for Confluence/Jira/Bitbucket integration with SDLC flow
+author: "@ngocsangairvds/vsaf"
+
+# Skills deployed WITH prefix: /vds-skill-<name>
+skills:
+  # Knowledge sync
+  - pull                      # /vds-skill-pull — git pull + stale index detection
+
+  # Discovery enrichment (helper for Phase 1)
+  - search-confluence         # /vds-skill-search-confluence — search Confluence + Jira for historical context
+
+  # PRD/SRS publication (helper for Phase 2/4)
+  - push-prd                  # /vds-skill-push-prd — push PRD to Confluence via vds-cli
+  - push-srs                  # /vds-skill-push-srs — push SRS to Confluence via vds-cli + link PRD
+
+  # Epic/PR creation (helper for Phase 2/9)
+  - create-jira-epic          # /vds-skill-create-jira-epic — create Jira Epic from PRD
+  - create-bitbucket-pr       # /vds-skill-create-bitbucket-pr — create Bitbucket PR after ship
+
+# Bundled external skills — deployed WITHOUT prefix (as-is)
+bundled:
+  - vds-scripts-skill         # /vds-scripts-skill — platform-routing skill (imported from /Downloads/vds-scripts/)

package/skills/vds-skill/pull/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: vds-skill-pull
+description: Pull latest code via `git pull` then detect stale local knowledge index (`.gitnexus/`, `graphify-out/graph.json`) by comparing mtime with `.git/FETCH_HEAD`. Suggest `/sdlc-onboard-code` if stale. Use instead of bare `git pull` for projects using SDLC pack.
+---
+
+# /vds-skill-pull
+
+Wrapper for `git pull` that detects stale local knowledge index after pull and suggests rebuild.
+
+## Usage
+
+```bash
+/vds-skill-pull              # equivalent to `git pull`
+/vds-skill-pull --rebase     # forwards args to git pull
+/vds-skill-pull origin main  # also forwards
+```
+
+## Behavior
+
+1. Run `git pull` with all passed args
+2. If pull succeeds, check `.gitnexus/` and `graphify-out/graph.json` mtime vs `.git/FETCH_HEAD`
+3. If any stale → print suggestion to run `/sdlc-onboard-code`
+4. Exit 0 (advisory, does not block workflow)
+
+## Implementation
+
+Invoke the bundled script:
+
+```bash
+bash .claude/skills/vds-skill-pull/scripts/pull.sh "$@"
+```
+
+## Notes
+
+- Works for both Viettel and non-Viettel projects (no vds-cli dependency).
+- If `.gitnexus/` or `graphify-out/` does not exist, that's OK — only flagged if present-but-stale.
+- Skill exits 0 even when knowledge is stale (advisory only — user decides whether to onboard now or later).
+- `.gitnexus/` staleness uses directory mtime — this catches new files but may miss in-place edits. If GitNexus rewrites files without re-creating them, the check could give a false "fresh" reading. Acceptable for advisory mode.

package/skills/vds-skill/pull/scripts/pull.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# vds-skill-pull: git pull + detect stale local knowledge index
+# Exit codes: forwards `git pull` exit code (0 on success even if knowledge stale)
+
+# Run git pull, forwarding all args. Capture exit code for explicit forwarding.
+# (No `set -e` — we want full control of the exit-code path for the advisory stale check.)
+git pull "$@"
+EXIT=$?
+
+if [[ $EXIT -ne 0 ]]; then
+    exit $EXIT
+fi
+
+# Skip stale check if not a fetch-based pull (e.g., --no-rebase --quiet might skip FETCH_HEAD)
+if [[ ! -f .git/FETCH_HEAD ]]; then
+    exit 0
+fi
+
+FETCH_HEAD_MTIME=$(stat -c %Y .git/FETCH_HEAD 2>/dev/null || stat -f %m .git/FETCH_HEAD 2>/dev/null || echo 0)
+STALE_REASONS=()
+
+# Check .gitnexus/
+if [[ -d .gitnexus ]]; then
+    GITNEXUS_MTIME=$(stat -c %Y .gitnexus 2>/dev/null || stat -f %m .gitnexus 2>/dev/null || echo 0)
+    if [[ $GITNEXUS_MTIME -lt $FETCH_HEAD_MTIME ]]; then
+        STALE_REASONS+=(".gitnexus/ index older than fetched commits")
+    fi
+fi
+# Note: .gitnexus missing is OK (project may not use GitNexus)
+
+# Check graphify-out/graph.json
+if [[ -f graphify-out/graph.json ]]; then
+    GRAPH_MTIME=$(stat -c %Y graphify-out/graph.json 2>/dev/null || stat -f %m graphify-out/graph.json 2>/dev/null || echo 0)
+    if [[ $GRAPH_MTIME -lt $FETCH_HEAD_MTIME ]]; then
+        STALE_REASONS+=("graphify-out/graph.json older than fetched commits")
+    fi
+fi
+# Note: graphify-out missing is OK
+
+# Print suggestion if anything stale
+if [[ ${#STALE_REASONS[@]} -gt 0 ]]; then
+    echo ""
+    echo "⚠️  Knowledge index có thể stale sau pull:"
+    for reason in "${STALE_REASONS[@]}"; do
+        echo "   - $reason"
+    done
+    echo ""
+    echo "   Khuyến nghị: chạy /sdlc-onboard-code để rebuild GitNexus + Graphify locally."
+    echo ""
+fi
+
+exit 0

package/skills/vds-skill/push-prd/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: vds-skill-push-prd
+description: Push PRD markdown to Viettel Confluence via vds-cli. Converts markdown → Confluence Storage Format (XHTML), searches for existing page, creates or updates. Use after /sdlc-prd has produced 02-prd.md. Viettel-only (requires vds-cli).
+---
+
+# /vds-skill-push-prd
+
+Publish the current PRD to Viettel Confluence via `vds-cli` — create a new page if it doesn't exist, or update the existing one. The optional `[comment]` becomes the Confluence version note.
+
+## Input
+
+- `[file]` — optional path to a specific markdown file. Default: scan `.vsaf/docs/features/*/02-prd.md`
+- `[comment]` — optional version note (e.g., "Initial draft", "Updated after stakeholder review")
+
+## Config Check (run FIRST)
+
+Before doing anything, run this check via Bash tool:
+
+```bash
+source .claude/skills/_shared/vds-skill/credentials.sh 2>/dev/null
+MISSING=""
+command -v vds-cli >/dev/null 2>&1 || MISSING="$MISSING vds-cli"
+[[ -z "${VDS_CONFLUENCE_TOKEN:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_TOKEN"
+[[ -z "${VDS_CONFLUENCE_SPACE_DEFAULT:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_SPACE_DEFAULT"
+if [[ -n "$MISSING" ]]; then
+  echo "BLOCKED — missing:$MISSING"
+  echo "Fix: edit ~/.vds/sdlc-config.env (or run: vsaf install vds-skill)"
+else
+  echo "OK"
+fi
+```
+
+If BLOCKED: tell the user exactly what's missing and how to fix, then STOP. Do NOT fabricate output.
+
+## Prerequisites
+
+- `vds-cli` installed (`command -v vds-cli`)
+- A PRD markdown file must exist
+- `VDS_CONFLUENCE_TOKEN` + `VDS_CONFLUENCE_SPACE_DEFAULT` in `~/.vds/sdlc-config.env`
+- Confluence parent page configured in `.vsaf/config.yaml` (or lazy-prompted)
+
+## Steps
+
+### Step 1 — Find PRD file
+
+- If `[file]` given: use directly
+- Otherwise: list `.vsaf/docs/features/*/02-prd.md`
+  - Multiple: ask user which one
+  - None: STOP — tell user to run `/sdlc-prd` first
+- Read full file content
+
+### Step 2 — Load Confluence config
+
+Read `.vsaf/config.yaml` (or `.vsaf/_bmad/bmm/config.yaml`) and extract:
+- `confluence_space_key`
+- `confluence_parent_page`
+
+If missing: lazy-prompt + persist via `_shared/credentials.sh ensure_env`.
+
+### Step 3 — Determine page title
+
+- For `02-prd.md` under `features/{feature-name}/`: title = `[PRD] {Feature Name}` (derived from folder name)
+- Otherwise: use first `# Heading` in file, or filename stem
+
+### Step 4 — Convert markdown → Confluence storage format (XHTML)
+
+**CRITICAL RULES:**
+
+1. **Never send raw markdown.** All content must be converted to Confluence Storage Format (XHTML).
+2. **Never wrap entire body in `<![CDATA[...]]>`.** CDATA is ONLY valid inside `<ac:plain-text-body>` within code macros.
+3. **All Confluence macro attributes MUST use `ac:` namespace prefix.** The tag is `<ac:parameter ac:name="...">`, never `<parameter name="...">`.
+4. **Escape HTML entities in regular text:** `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`.
+5. **Every opened tag must be closed.** Confluence XML parser is strict.
+
+**Block elements:**
+
+```
+# Heading      → <h1>Heading</h1>
+## Heading     → <h2>Heading</h2>
+### Heading    → <h3>Heading</h3>
+#### Heading   → <h4>Heading</h4>
+paragraph      → <p>paragraph</p>
+---            → <hr/>
+```
+
+**Inline elements:**
+
+```
+**bold**       → <strong>bold</strong>
+*italic*       → <em>italic</em>
+`code`         → <code>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 (ONLY 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>
+```
+
+**Info/warning/tip boxes:**
+
+```
+> [!NOTE]      →  <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>
+```
+
+Save converted XHTML to a temp file: `BODY_FILE=$(mktemp --suffix=.html)`.
+
+### Step 5 — Search for existing page
+
+Use Bash tool to run:
+
+```bash
+source .claude/skills/_shared/vds-skill/credentials.sh
+ensure_env VDS_CONFLUENCE_TOKEN "Enter VDS Confluence personal access token"
+
+SPACE_KEY="<from config>"
+PAGE_TITLE="<title from Step 3>"
+
+SEARCH_RESULT=$(vds-cli confluence search \
+    --cql "space=$SPACE_KEY AND title = \"$PAGE_TITLE\"" \
+    --limit 1 --json-only)
+
+EXISTING_PAGE_ID=$(echo "$SEARCH_RESULT" | python3 -c \
+    'import json,sys; d=json.load(sys.stdin); print(d["results"][0]["id"] if d.get("results") else "")')
+```
+
+If `$EXISTING_PAGE_ID` non-empty → Step 6 (update). Otherwise → Step 7 (create).
+
+### Step 6 — Update existing page (via vds-cli)
+
+```bash
+EXISTING_VERSION=$(echo "$SEARCH_RESULT" | python3 -c \
+    'import json,sys; d=json.load(sys.stdin); print(d["results"][0].get("version",{}).get("number",1))')
+
+VERSION_COMMENT="${COMMENT:-Updated via vds-skill-push-prd}"
+
+vds-cli confluence content update \
+    --page-id "$EXISTING_PAGE_ID" \
+    --body-file "$BODY_FILE" \
+    --version $((EXISTING_VERSION + 1)) \
+    --version-comment "$VERSION_COMMENT" \
+    --json-only
+
+rm -f "$BODY_FILE"
+```
+
+**Conflict handling:** if `vds-cli` returns version mismatch error, retry once with fresh version:
+
+```bash
+LATEST_VERSION=$(vds-cli confluence content page "$EXISTING_PAGE_ID" --json-only \
+    | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"]["number"])')
+
+vds-cli confluence content update \
+    --page-id "$EXISTING_PAGE_ID" \
+    --body-file "$BODY_FILE" \
+    --version $((LATEST_VERSION + 1)) \
+    --version-comment "$VERSION_COMMENT" \
+    --json-only
+```
+
+### Step 7 — Create new page (via vds-cli)
+
+```bash
+# Resolve parent page ID via search
+PARENT_ID=""
+if [[ -n "$CONFLUENCE_PARENT_PAGE" ]]; then
+    PARENT_ID=$(vds-cli confluence search \
+        --cql "space=$SPACE_KEY AND title = \"$CONFLUENCE_PARENT_PAGE\"" \
+        --limit 1 --json-only \
+        | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["results"][0]["id"] if d.get("results") else "")')
+fi
+
+CREATE_ARGS=(vds-cli confluence content create-page
+    --space "$SPACE_KEY"
+    --title "$PAGE_TITLE"
+    --body-file "$BODY_FILE"
+    --version-comment "${COMMENT:-Initial PRD push via vds-skill-push-prd}"
+    --json-only)
+[[ -n "$PARENT_ID" ]] && CREATE_ARGS+=(--parent-id "$PARENT_ID")
+
+"${CREATE_ARGS[@]}"
+rm -f "$BODY_FILE"
+```
+
+### 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
+Optionally run /vds-skill-create-jira-epic to create a Jira epic from this PRD,
+or continue with /sdlc-architecture (Phase 3).
+```
+
+## Notes
+
+- Never push a PRD that has failed validation
+- If `vds-cli` is not installed, tell user to install vds-scripts first
+- Do not modify the local file during this step
+- Conflict handling: version mismatch → auto-retry once with fresh version number

package/skills/vds-skill/push-srs/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: vds-skill-push-srs
+description: Push SRS markdown to Viettel Confluence via vds-cli. Same flow as push-prd plus link to the corresponding PRD page. Use after /sdlc-srs has produced 05-srs.md. Viettel-only (requires vds-cli).
+---
+
+# /vds-skill-push-srs
+
+Publish the current SRS to Viettel Confluence via `vds-cli` — create or update the page, and link to the corresponding PRD page if it exists.
+
+## Input
+
+- `[file]` — optional path to a specific markdown file. Default: scan `.vsaf/docs/features/*/05-srs.md`
+- `[comment]` — optional version note
+
+## Config Check (run FIRST)
+
+Before doing anything, run this check via Bash tool:
+
+```bash
+source .claude/skills/_shared/vds-skill/credentials.sh 2>/dev/null
+MISSING=""
+command -v vds-cli >/dev/null 2>&1 || MISSING="$MISSING vds-cli"
+[[ -z "${VDS_CONFLUENCE_TOKEN:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_TOKEN"
+[[ -z "${VDS_CONFLUENCE_SPACE_DEFAULT:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_SPACE_DEFAULT"
+if [[ -n "$MISSING" ]]; then
+  echo "BLOCKED — missing:$MISSING"
+  echo "Fix: edit ~/.vds/sdlc-config.env (or run: vsaf install vds-skill)"
+else
+  echo "OK"
+fi
+```
+
+If BLOCKED: tell the user exactly what's missing and how to fix, then STOP. Do NOT fabricate output.
+
+## Prerequisites
+
+- `vds-cli` installed
+- An SRS markdown file must exist
+- `VDS_CONFLUENCE_TOKEN` + `VDS_CONFLUENCE_SPACE_DEFAULT` in `~/.vds/sdlc-config.env`
+- Confluence parent page in config or lazy-prompted
+
+## Steps
+
+### Step 1 — Find SRS file
+
+- If `[file]` given: use directly
+- Otherwise: list `.vsaf/docs/features/*/05-srs.md` (exclude `*-results.md`)
+- Multiple: ask user
+- None: STOP — tell user to run `/sdlc-srs` first
+- Read full content
+
+### Step 2 — Load Confluence config
+
+Same as `/vds-skill-push-prd` Step 2.
+
+### Step 3 — Determine page title
+
+- For `05-srs.md` under `features/{feature-name}/`: title = `[SRS] {Feature Name}` (derived from folder name)
+- Otherwise: first `# Heading` or filename stem
+
+### Step 4 — Convert markdown → Confluence storage format (XHTML)
+
+Same conversion rules as `/vds-skill-push-prd` Step 4 (see that skill for full reference). Save converted body to `$BODY_FILE`.
+
+### Step 5 — Search for existing page
+
+Same as `/vds-skill-push-prd` Step 5 — search for `[SRS] {Feature Name}` page in the space, store `EXISTING_PAGE_ID` and `SEARCH_RESULT`.
+
+### Step 6 — Update existing page (via vds-cli)
+
+Same as `/vds-skill-push-prd` Step 6 (with auto-retry on conflict). Use `Updated via vds-skill-push-srs` as default version comment.
+
+### Step 7 — Create new page (via vds-cli)
+
+Same as `/vds-skill-push-prd` Step 7. Use `Initial SRS push via vds-skill-push-srs` as default version comment.
+
+### Step 8 — Link SRS page to PRD page (if PRD exists)
+
+```bash
+source .claude/skills/_shared/vds-skill/credentials.sh
+ensure_env VDS_CONFLUENCE_TOKEN "Enter VDS Confluence personal access token"
+
+# Derive PRD page title from feature name
+FEATURE_NAME="<from folder>"
+PRD_TITLE="[PRD] $FEATURE_NAME"
+
+PRD_PAGE=$(vds-cli confluence search \
+    --cql "space=$SPACE_KEY AND title = \"$PRD_TITLE\"" \
+    --limit 1 --json-only)
+
+PRD_URL=$(echo "$PRD_PAGE" | python3 -c \
+    'import json,sys; d=json.load(sys.stdin); r=d.get("results"); print(r[0].get("url","") if r else "")')
+
+if [[ -n "$PRD_URL" ]]; then
+    # Prepend "Related Documents" macro to SRS body BEFORE push (modify $BODY_FILE)
+    RELATED_BLOCK='<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_TITLE"'</a></p></ac:rich-text-body></ac:structured-macro>'
+
+    NEW_BODY=$(mktemp --suffix=.html)
+    { echo "$RELATED_BLOCK"; cat "$BODY_FILE"; } > "$NEW_BODY"
+    mv "$NEW_BODY" "$BODY_FILE"
+fi
+```
+
+This block runs BEFORE Step 6/7 actually executes the create/update — i.e., the Related Documents banner is part of the body content pushed to 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
+Continue to Phase 5: /sdlc-test-design
+```
+
+## Notes
+
+- If `vds-cli` is not installed, tell user to install vds-scripts first
+- Do not modify the local file during this step
+- SRS result files (`*-results.md`) are test outputs — push those separately if needed
+- Conflict handling: version mismatch → auto-retry once with fresh version number
+- PRD link is best-effort — if PRD page doesn't exist in Confluence yet, SRS pushes without the link

package/skills/vds-skill/search-confluence/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: vds-skill-search-confluence
+description: Search Viettel Confluence + Jira for historical context related to a feature, write index to .vsaf/docs/features/{name}/01-discovery-historical.{md,json}. Run BEFORE /sdlc-discovery to enrich grill session context. Viettel-only (requires vds-cli).
+---
+
+# /vds-skill-search-confluence
+
+Search Viettel Confluence + Jira for pages/tickets related to a feature, then write a Markdown + JSON index into the feature folder. Output is consumed by `/sdlc-discovery` (Phase 1) to enrich the grill session.
+
+## Config Check (run FIRST)
+
+Before doing anything, run this check via Bash tool:
+
+```bash
+source .claude/skills/_shared/vds-skill/credentials.sh 2>/dev/null
+MISSING=""
+command -v vds-cli >/dev/null 2>&1 || MISSING="$MISSING vds-cli"
+[[ -z "${VDS_CONFLUENCE_TOKEN:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_TOKEN"
+[[ -z "${VDS_JIRA_TOKEN:-}" ]] && MISSING="$MISSING VDS_JIRA_TOKEN"
+[[ -z "${VDS_CONFLUENCE_SPACE_DEFAULT:-}" ]] && MISSING="$MISSING VDS_CONFLUENCE_SPACE_DEFAULT"
+[[ -z "${VDS_JIRA_PROJECT_DEFAULT:-}" ]] && MISSING="$MISSING VDS_JIRA_PROJECT_DEFAULT"
+if [[ -n "$MISSING" ]]; then
+  echo "BLOCKED — missing:$MISSING"
+  echo "Fix: edit ~/.vds/sdlc-config.env (or run: vsaf install vds-skill)"
+else
+  echo "OK"
+fi
+```
+
+If BLOCKED: tell the user exactly what's missing and how to fix, then STOP. Do NOT fabricate output. `--dry-run` mode skips vds-cli check.
+
+## Prerequisites
+
+- `vds-cli` installed
+- `python3` installed
+- Inside a project root with `.vsaf/docs/features/`
+- `VDS_CONFLUENCE_TOKEN`, `VDS_JIRA_TOKEN`, `VDS_CONFLUENCE_SPACE_DEFAULT`, `VDS_JIRA_PROJECT_DEFAULT` in `~/.vds/sdlc-config.env`
+
+## Usage
+
+```bash
+/vds-skill-search-confluence --feature user-management --query "auth jwt"
+/vds-skill-search-confluence --feature payment --query "payment flow" --days 90 --limit 50
+/vds-skill-search-confluence --feature billing --query "billing" --dry-run
+```
+
+## Behavior
+
+1. Build CQL: `space=<DEFAULT> AND text ~ "<QUERY>" AND lastmodified > now("-Nd")`
+2. Build JQL: `project = <DEFAULT> AND text ~ "<QUERY>" AND created > -Nd ORDER BY created DESC`
+3. Execute `vds-cli confluence search` + `vds-cli jira search` (sequential)
+4. Combine into JSON at `<feature-dir>/01-discovery-historical.json`
+5. Generate Markdown summary at `<feature-dir>/01-discovery-historical.md` (top 10 Confluence + top 15 Jira)
+
+## Implementation
+
+```bash
+bash .claude/skills/vds-skill-search-confluence/scripts/search.sh "$@"
+```
+
+## Notes
+
+- Run BEFORE `/sdlc-discovery` to enrich grill session.
+- Default `--days 180`, `--limit 30`.
+- Empty results are OK — Markdown still generated, sdlc-discovery proceeds normally.
+- Dry-run skips `vds-cli` invocation — preview mode works without `vds-cli` installed.

package/skills/vds-skill/search-confluence/scripts/search.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# vds-skill-search-confluence: search Confluence + Jira for feature discovery context
+# Usage: search.sh --feature NAME --query KEYWORDS [--dry-run] [--days N] [--limit N]
+
+# NOTE: No `set -e` — we want full control of the exit-code path.
+
+# Source credentials helper (deployed path: .claude/skills/_shared/vds-skill/credentials.sh)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/../../_shared/vds-skill/credentials.sh"
+
+require_command python3
+# Note: require_command vds-cli moved AFTER dry-run check so --dry-run
+#       works without vds-cli installed (preview mode).
+
+FEATURE=""
+QUERY=""
+DAYS=180
+LIMIT=30
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --feature) FEATURE="$2"; shift 2 ;;
+        --query) QUERY="$2"; shift 2 ;;
+        --days) DAYS="$2"; shift 2 ;;
+        --limit) LIMIT="$2"; shift 2 ;;
+        --dry-run) DRY_RUN=true; shift ;;
+        *) echo "Unknown arg: $1" >&2; exit 2 ;;
+    esac
+done
+
+if [[ -z "$FEATURE" ]]; then
+    echo "ERROR: --feature is required" >&2
+    exit 2
+fi
+if [[ -z "$QUERY" ]]; then
+    echo "ERROR: --query (search keywords) is required" >&2
+    exit 2
+fi
+
+# Determine output dir
+OUT_DIR=".vsaf/docs/features/$FEATURE"
+
+OUT_JSON="$OUT_DIR/01-discovery-historical.json"
+OUT_MD="$OUT_DIR/01-discovery-historical.md"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    SPACE="${VDS_CONFLUENCE_SPACE_DEFAULT:-<VDS_CONFLUENCE_SPACE_DEFAULT>}"
+    PROJECT="${VDS_JIRA_PROJECT_DEFAULT:-<VDS_JIRA_PROJECT_DEFAULT>}"
+    CQL="space=$SPACE AND text ~ \"$QUERY\" AND lastmodified > now(\"-${DAYS}d\")"
+    JQL="project = $PROJECT AND text ~ \"$QUERY\" AND created > -${DAYS}d ORDER BY created DESC"
+    echo "DRY-RUN — would execute:"
+    echo "  vds-cli confluence search --cql \"$CQL\" --limit $LIMIT --json-only"
+    echo "  vds-cli jira search \"$JQL\" --limit $LIMIT --json-only"
+    echo "  Write to: $OUT_JSON + $OUT_MD"
+    exit 0
+fi
+
+require_command vds-cli
+
+# Ensure credentials
+ensure_env VDS_CONFLUENCE_TOKEN "Enter VDS Confluence personal access token"
+ensure_env VDS_JIRA_TOKEN "Enter VDS Jira personal access token"
+ensure_env VDS_CONFLUENCE_SPACE_DEFAULT "Enter default Confluence space key (e.g. ENG)" false
+ensure_env VDS_JIRA_PROJECT_DEFAULT "Enter default Jira project key (e.g. NTTC)" false
+
+# Build CQL + JQL (now using real env vars)
+CQL="space=$VDS_CONFLUENCE_SPACE_DEFAULT AND text ~ \"$QUERY\" AND lastmodified > now(\"-${DAYS}d\")"
+JQL="project = $VDS_JIRA_PROJECT_DEFAULT AND text ~ \"$QUERY\" AND created > -${DAYS}d ORDER BY created DESC"
+
+# Create output dir now (after dry-run exits early)
+mkdir -p "$OUT_DIR"
+
+# Execute searches
+echo "Searching Confluence (limit $LIMIT, last ${DAYS}d)..."
+CONF_RESULTS=$(vds-cli confluence search --cql "$CQL" --limit "$LIMIT" --json-only 2>/dev/null || echo '{"results":[]}')
+
+echo "Searching Jira (limit $LIMIT, last ${DAYS}d)..."
+JIRA_RESULTS=$(vds-cli jira search "$JQL" --limit "$LIMIT" --json-only 2>/dev/null || echo '{"issues":[]}')
+
+# Combined JSON output + Markdown summary
+python3 - "$CONF_RESULTS" "$JIRA_RESULTS" "$OUT_JSON" "$OUT_MD" "$QUERY" "$DAYS" <<'PYEOF'
+import json, sys
+conf_raw, jira_raw, out_json, out_md, query, days = sys.argv[1:7]
+conf = json.loads(conf_raw) if conf_raw.strip() else {"results":[]}
+jira = json.loads(jira_raw) if jira_raw.strip() else {"issues":[]}
+
+combined = {
+    "query": query,
+    "days_back": int(days),
+    "confluence": conf.get("results", []),
+    "jira": jira.get("issues", []),
+}
+with open(out_json, "w") as f:
+    json.dump(combined, f, indent=2, ensure_ascii=False)
+
+lines = [
+    f"# Discovery Historical Context — {query}",
+    f"",
+    f"> Generated by /vds-skill-search-confluence — searched last {days} days",
+    f"",
+    f"## Confluence pages ({len(combined['confluence'])} results)",
+    f"",
+]
+for page in combined["confluence"][:10]:
+    title = page.get("title", "<no title>")
+    url = page.get("url", page.get("_links", {}).get("webui", ""))
+    modified = page.get("lastModified", page.get("version", {}).get("when", "?"))
+    lines.append(f"- [{title}]({url}) — modified {modified}")
+
+lines += [
+    f"",
+    f"## Jira tickets ({len(combined['jira'])} results)",
+    f"",
+]
+for issue in combined["jira"][:15]:
+    key = issue.get("key", "?")
+    summary = issue.get("fields", {}).get("summary", "<no summary>")
+    status = issue.get("fields", {}).get("status", {}).get("name", "?")
+    lines.append(f"- **{key}** — {summary} ({status})")
+
+with open(out_md, "w") as f:
+    f.write("\n".join(lines) + "\n")
+
+print(f"Wrote: {out_json}")
+print(f"Wrote: {out_md}")
+PYEOF

package/skills/vds-skill/vds-scripts-skill/.openskills.json

@@ -0,0 +1,6 @@
+{
+  "source": "./.agent/skills/vds-scripts-skill",
+  "sourceType": "local",
+  "localPath": "/Users/vds-ai/Library/Mobile Documents/com~apple~CloudDocs/project/vds/.agent/skills/vds-scripts-skill",
+  "installedAt": "2026-01-26T07:07:42.597Z"
+}