ai-qakit 1.0.0

package/templates/.claude/commands/qakit/kb/sync-confluence.md

@@ -0,0 +1,474 @@
+# Sync Confluence Space/Folder to Knowledge Base
+
+Bulk capture all pages from a Confluence space or under a parent page into the knowledge base.
+
+## ⚠️ IMPORTANT: Use Descendant API for Deep Nesting
+
+**Confluence pages can be nested 3-5+ levels deep.** Always use the `/descendant/page` endpoint (REST API v1) to fetch ALL pages, not just direct children.
+
+```bash
+# CORRECT - Gets ALL descendants (all levels)
+curl -s -u "$EMAIL:$TOKEN" "$BASE_URL/wiki/rest/api/content/$PAGE_ID/descendant/page?limit=500"
+
+# WRONG - Only gets direct children (level 1)
+curl -s -u "$EMAIL:$TOKEN" "$BASE_URL/wiki/api/v2/pages/$PAGE_ID/children"
+```
+
+## Usage
+
+```
+# Sync entire space
+/qakit:kb/sync-confluence --space=PROJ
+
+# Sync all child pages under a parent page (RECURSIVE by default)
+/qakit:kb/sync-confluence --parent=https://company.atlassian.net/wiki/spaces/PROJ/pages/123456
+
+# Sync with depth control
+/qakit:kb/sync-confluence --parent=URL --depth=2    # Only 2 levels deep
+/qakit:kb/sync-confluence --parent=URL --depth=all  # All levels (default)
+
+# Sync with filters
+/qakit:kb/sync-confluence --space=PROJ --label=requirements
+/qakit:kb/sync-confluence --space=PROJ --title-contains="PRD"
+
+# Sync with FULL CONTENT (not just structure)
+/qakit:kb/sync-confluence --parent=URL --full-content
+```
+
+## IMPORTANT: Full Content vs Structure Only
+
+By default, sync captures:
+- Page metadata (title, ID, labels)
+- Page structure (child pages list)
+- Basic content summary
+
+To capture **FULL CONTENT** of each page (recommended for business docs):
+```
+/qakit:kb/sync-confluence --parent=URL --full-content --depth=all
+```
+
+This will:
+1. Recursively fetch ALL child pages
+2. Extract FULL body content from each page
+3. Convert Confluence storage format to readable Markdown
+4. Preserve tables, lists, code blocks, images
+
+## Prerequisites
+
+```bash
+export CONFLUENCE_BASE_URL="https://yourcompany.atlassian.net"
+export CONFLUENCE_EMAIL="your.email@company.com"
+export CONFLUENCE_API_TOKEN="your-api-token"
+```
+
+## Instructions
+
+### Step 1: Validate Input
+
+```bash
+# Must provide either --space or --parent
+if [ -z "$SPACE" ] && [ -z "$PARENT_URL" ]; then
+  echo "Error: Provide --space=SPACE_KEY or --parent=PAGE_URL"
+  exit 1
+fi
+```
+
+### Step 2: List Pages to Sync
+
+**Option A: By Space Key**
+```bash
+# Get all pages in space
+curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/api/v2/spaces/$SPACE_KEY/pages?limit=250" \
+  | jq -r '.results[] | {id, title, status}'
+
+# With label filter
+curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/rest/api/content?spaceKey=$SPACE_KEY&type=page&label=$LABEL&limit=250"
+```
+
+**Option B: By Parent Page (get ALL descendants - RECOMMENDED)**
+
+**CRITICAL: Use `/descendant/page` endpoint to get ALL nested pages, not just direct children!**
+
+```bash
+# Extract page ID from URL
+PARENT_ID=$(echo "$PARENT_URL" | grep -oE 'pages/[0-9]+' | cut -d'/' -f2)
+
+# CORRECT: Get ALL descendant pages (all levels deep) using REST API v1
+# This returns ALL pages under the parent, regardless of nesting depth
+curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/rest/api/content/$PARENT_ID/descendant/page?limit=500&expand=ancestors"
+
+# WRONG: /children only returns direct children (1 level)
+# curl ... /wiki/api/v2/pages/$PARENT_ID/children  # DON'T USE THIS!
+```
+
+**Why `/descendant/page` is important:**
+- Confluence pages can be nested 3-5+ levels deep
+- `/children` only returns level 1 children
+- `/descendant/page` returns ALL pages under parent (all levels)
+
+**Example structure that `/children` would miss:**
+```
+LinkedMaps (root)
+└── BE Documentation (level 1) ← /children gets this
+      └── Features (level 2) ← /children MISSES this
+            └── Rule Engine (level 3) ← /children MISSES this
+                  └── Rule Engine > Management (level 4) ← /children MISSES this
+```
+
+**Fallback for API v2 (if v1 not available):**
+```bash
+# Recursive function to traverse all levels
+function get_all_descendants() {
+  local page_id=$1
+  local depth=${2:-0}
+  
+  # Get direct children
+  local children=$(curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+    "$CONFLUENCE_BASE_URL/wiki/api/v2/pages/$page_id/children?limit=250")
+  
+  # Process each child
+  for child_id in $(echo "$children" | jq -r '.results[].id'); do
+    echo "$child_id"
+    # Recursively get children of this child (no depth limit)
+    get_all_descendants "$child_id" $((depth + 1))
+  done
+}
+
+# Usage: get_all_descendants $PARENT_ID
+```
+
+### Step 3: Preview Pages
+
+```markdown
+## Confluence Sync Preview
+
+**Source:** Space PROJ / Parent "Product Requirements"
+**Pages found:** 25
+
+| # | Title | ID | Labels | Last Updated |
+|---|-------|-----|--------|--------------|
+| 1 | PRD - User Authentication | 123456 | prd, auth | 2024-12-20 |
+| 2 | PRD - Dashboard | 123457 | prd, dashboard | 2024-12-18 |
+| 3 | Technical Spec - API | 123458 | tech, api | 2024-12-15 |
+| ... | ... | ... | ... | ... |
+
+**Filters applied:**
+- Label: requirements
+- Title contains: "PRD"
+
+**Estimated time:** ~5 minutes
+
+**Options:**
+1. [Sync all] - Capture all 25 pages
+2. [Select pages] - Choose which to sync
+3. [Apply more filters] - Narrow down
+4. [Cancel] - Abort
+
+Select (1-4): _
+```
+
+### Step 4: Fetch Each Page Content (FULL CONTENT MODE)
+
+**CRITICAL: For business documentation, always use `--full-content` to capture actual content, not just structure.**
+
+For each page to sync:
+
+```bash
+# Fetch page with FULL body content
+PAGE_DATA=$(curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/api/v2/pages/$PAGE_ID?body-format=storage")
+
+# Extract fields
+TITLE=$(echo "$PAGE_DATA" | jq -r '.title')
+BODY_RAW=$(echo "$PAGE_DATA" | jq -r '.body.storage.value')
+SPACE=$(echo "$PAGE_DATA" | jq -r '.spaceId')
+VERSION=$(echo "$PAGE_DATA" | jq -r '.version.number')
+
+# Get labels
+LABELS=$(curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/api/v2/pages/$PAGE_ID/labels" | jq -r '.results[].name')
+
+# Get attachments (images, files)
+ATTACHMENTS=$(curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+  "$CONFLUENCE_BASE_URL/wiki/api/v2/pages/$PAGE_ID/attachments" | jq -r '.results[]')
+```
+
+### Step 4.1: Convert Confluence Storage Format to Markdown
+
+**Confluence uses XML-like storage format. Convert to clean Markdown:**
+
+```bash
+# Key conversions:
+# <h1> → # Heading
+# <h2> → ## Heading
+# <p> → paragraph
+# <table> → Markdown table
+# <ac:structured-macro ac:name="code"> → ```code block```
+# <ac:structured-macro ac:name="info"> → > [!INFO] callout
+# <ac:structured-macro ac:name="warning"> → > [!WARNING] callout
+# <ac:image> → ![alt](image-url)
+# <ac:link> → [text](url)
+# <ri:attachment ri:filename="..."> → reference to attachment
+```
+
+**Example conversion:**
+
+Input (Confluence storage):
+```xml
+<h2>Overview</h2>
+<p>This is the <strong>main</strong> description.</p>
+<ac:structured-macro ac:name="info">
+  <ac:rich-text-body><p>Important note here</p></ac:rich-text-body>
+</ac:structured-macro>
+<table>
+  <tr><th>Column 1</th><th>Column 2</th></tr>
+  <tr><td>Value 1</td><td>Value 2</td></tr>
+</table>
+```
+
+Output (Markdown):
+```markdown
+## Overview
+
+This is the **main** description.
+
+> [!INFO]
+> Important note here
+
+| Column 1 | Column 2 |
+|----------|----------|
+| Value 1 | Value 2 |
+```
+
+### Step 4.2: Download and Save Attachments
+
+```bash
+# For each attachment, download to docs/assets/
+for attachment in $(echo "$ATTACHMENTS" | jq -r '.title'); do
+  DOWNLOAD_URL="$CONFLUENCE_BASE_URL/wiki/rest/api/content/$PAGE_ID/child/attachment/$attachment/download"
+  curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
+    "$DOWNLOAD_URL" -o "docs/assets/screenshots/$attachment"
+done
+
+# Update image references in markdown to local paths
+# ![image](attachment:image.png) → ![image](../assets/screenshots/image.png)
+```
+
+### Step 5: Determine Document Type & Location
+
+Based on page title/labels, categorize:
+
+| Pattern | Type | Location |
+|---------|------|----------|
+| "PRD", "Requirements" | feature | docs/features/ |
+| "Flow", "Process" | flow | docs/flows/ |
+| "Rules", "Policy" | rule | docs/rules/ |
+| "Glossary", "Terms" | glossary | docs/_glossary.md (append) |
+| Other | reference | docs/references/ |
+
+### Step 6: Convert & Save Each Page
+
+**Convert Confluence storage format to Markdown:**
+- Parse HTML-like storage format
+- Convert tables, lists, headings
+- Extract images (save to assets/)
+- Convert Confluence macros
+
+**Create document:**
+
+```markdown
+---
+id: {kebab-case-title}
+title: {Title}
+type: {detected_type}
+status: active
+sources:
+  - type: confluence
+    id: "{PAGE_ID}"
+    spaceKey: "{SPACE_KEY}"
+    url: "{page_url}"
+    captured: "{timestamp}"
+    hash: "{content_hash}"
+labels: [{labels}]
+created: "{timestamp}"
+updated: "{timestamp}"
+---
+
+# {Title}
+
+{Converted markdown content}
+
+---
+_Synced from Confluence: {page_url}_
+_Last synced: {timestamp}_
+```
+
+### Step 7: Handle Hierarchy
+
+If pages have parent-child relationships, preserve structure:
+
+```
+docs/
+├── features/
+│   ├── product-requirements/           # Parent page
+│   │   ├── _index.md                   # Parent content
+│   │   ├── user-authentication.md      # Child
+│   │   ├── dashboard.md                # Child
+│   │   └── api-integration.md          # Child
+```
+
+Or use frontmatter to track:
+```yaml
+parent: "[[product-requirements]]"
+children:
+  - "[[user-authentication]]"
+  - "[[dashboard]]"
+```
+
+### Step 8: Update Index & Sources
+
+**Update docs/_index.md:**
+```markdown
+## Confluence Sync: PROJ Space
+
+Last synced: {timestamp}
+Pages: 25
+
+### Features (from PRDs)
+- [[user-authentication]] - User Authentication PRD
+- [[dashboard]] - Dashboard PRD
+...
+
+### Technical Specs
+- [[api-integration]] - API Technical Spec
+...
+```
+
+**Update docs/_sources.json:**
+```json
+{
+  "sources": [
+    {
+      "id": "confluence-sync-PROJ",
+      "type": "confluence-space",
+      "spaceKey": "PROJ",
+      "url": "https://company.atlassian.net/wiki/spaces/PROJ",
+      "syncedAt": "{timestamp}",
+      "pageCount": 25,
+      "pages": ["123456", "123457", "123458", ...]
+    },
+    {
+      "id": "123456",
+      "type": "confluence",
+      "title": "PRD - User Authentication",
+      ...
+    }
+  ]
+}
+```
+
+### Step 9: Output Summary
+
+```markdown
+✅ Confluence Sync Complete
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| **Source** | Space: PROJ |
+| **Pages synced** | 25 |
+| **New documents** | 20 |
+| **Updated** | 5 |
+| **Skipped** | 0 |
+| **Errors** | 0 |
+| **Time** | 3m 45s |
+
+## Documents Created
+
+### Features (12)
+- docs/features/user-authentication.md
+- docs/features/dashboard.md
+- docs/features/api-integration.md
+...
+
+### Flows (5)
+- docs/flows/user-onboarding.md
+- docs/flows/payment-process.md
+...
+
+### Rules (3)
+- docs/rules/security-policy.md
+...
+
+### References (5)
+- docs/references/architecture-overview.md
+...
+
+## Glossary Updates
+- Added 15 new terms to docs/_glossary.md
+
+## Next Steps
+
+1. Review synced documents:
+   /qakit:kb/list --source=confluence
+
+2. Check for duplicates:
+   /qakit:kb/dedupe
+
+3. Link related documents:
+   /qakit:kb/link user-authentication dashboard
+
+4. Re-sync later:
+   /qakit:kb/sync-confluence --space=PROJ --update
+```
+
+## Incremental Sync
+
+For subsequent syncs, only update changed pages:
+
+```bash
+# Check for updates since last sync
+/qakit:kb/sync-confluence --space=PROJ --update
+
+# Force full re-sync
+/qakit:kb/sync-confluence --space=PROJ --force
+```
+
+**Update detection:**
+- Compare page version/lastModified
+- Compare content hash
+- Only re-process changed pages
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--space=KEY` | Confluence space key | - |
+| `--parent=URL` | Parent page URL (sync children) | - |
+| `--depth=N\|all` | How deep to recurse (1, 2, 3... or "all") | all |
+| `--full-content` | **Capture full page content (recommended)** | false |
+| `--label=LABEL` | Filter by label | - |
+| `--title-contains=TEXT` | Filter by title | - |
+| `--type=TYPE` | Force document type | auto |
+| `--limit=N` | Max pages to sync | 100 |
+| `--update` | Only sync changed pages | false |
+| `--force` | Force full re-sync | false |
+| `--dry-run` | Preview without saving | false |
+| `--include-archived` | Include archived pages | false |
+| `--download-attachments` | Download images/files | true |
+
+## Recommended Usage for Business Docs
+
+```bash
+# Full sync with all content and attachments
+/qakit:kb/sync-confluence --parent=https://accionageotech.atlassian.net/wiki/spaces/LO/pages/1980989542 \
+  --full-content \
+  --depth=all \
+  --download-attachments
+```
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/metrics/coverage.md

@@ -0,0 +1,46 @@
+# Coverage Metrics
+
+Generate and analyze test coverage metrics.
+
+## Usage
+```
+/qakit:metrics/coverage [--format html|json|text]
+```
+
+## Instructions
+
+1. **Run Coverage Analysis**
+   - Execute test suite with coverage
+   - Parse coverage reports
+   - Calculate metrics
+
+2. **Generate Metrics Report**
+   ```markdown
+   # Coverage Metrics Report
+   
+   ## Overall Coverage
+   | Metric | Value | Trend |
+   |--------|-------|-------|
+   | Statements | 85% | ↑ +2% |
+   | Branches | 78% | ↓ -1% |
+   | Functions | 90% | → 0% |
+   | Lines | 84% | ↑ +1% |
+   
+   ## Coverage by Module
+   | Module | Coverage | Change |
+   |--------|----------|--------|
+   | core/ | 92% | ↑ +3% |
+   | api/ | 75% | ↓ -2% |
+   | ui/ | 88% | → 0% |
+   
+   ## Uncovered Areas
+   - `api/auth.ts`: Lines 45-60
+   - `core/validation.ts`: Branch at line 23
+   ```
+
+3. **Track Trends**
+   - Compare with previous runs
+   - Identify declining areas
+   - Highlight improvements
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/metrics/dashboard.md

@@ -0,0 +1,62 @@
+# Quality Dashboard
+
+Generate a comprehensive quality metrics dashboard.
+
+## Usage
+```
+/qakit:metrics/dashboard
+```
+
+## Instructions
+
+Generate quality dashboard with:
+
+1. **Test Metrics**
+   - Total tests, passing, failing, skipped
+   - Test execution time
+   - Flaky test count
+
+2. **Coverage Metrics**
+   - Statement, branch, function, line coverage
+   - Coverage trends
+
+3. **Bug Metrics**
+   - Open bugs by severity
+   - Bug resolution time
+   - Escape rate
+
+4. **Code Quality**
+   - Technical debt
+   - Code smells
+   - Duplications
+
+## Dashboard Output
+```markdown
+# Quality Dashboard
+
+## 📊 Test Health
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total Tests | 450 | - |
+| Passing | 448 | ✅ |
+| Failing | 2 | ⚠️ |
+| Skipped | 0 | ✅ |
+| Flaky | 1 | ⚠️ |
+
+## 📈 Coverage
+| Type | Current | Target | Status |
+|------|---------|--------|--------|
+| Statements | 85% | 80% | ✅ |
+| Branches | 72% | 75% | ❌ |
+
+## 🐛 Bugs
+| Severity | Open | In Progress |
+|----------|------|-------------|
+| Critical | 0 | 0 |
+| High | 2 | 1 |
+| Medium | 5 | 3 |
+
+## 🎯 Quality Score: 87/100
+```
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/metrics/trends.md

@@ -0,0 +1,42 @@
+# Quality Trends
+
+Analyze quality metrics trends over time.
+
+## Usage
+```
+/qakit:metrics/trends [--period week|month|quarter]
+```
+
+## Instructions
+
+Analyze trends for:
+- Test count growth
+- Coverage changes
+- Bug rates
+- Test execution time
+- Flaky test trends
+
+## Output
+```markdown
+# Quality Trends Report
+
+## Coverage Trend (Last 30 Days)
+| Date | Statements | Branches |
+|------|------------|----------|
+| Week 1 | 80% | 70% |
+| Week 2 | 82% | 72% |
+| Week 3 | 84% | 74% |
+| Week 4 | 85% | 75% |
+
+## Bug Trend
+- New bugs: 12 (↓ from 18)
+- Resolved: 15 (↑ from 10)
+- Net: -3 (improving)
+
+## Recommendations
+- Coverage improving steadily
+- Focus on branch coverage
+- Bug escape rate decreasing
+```
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/perf/analyze.md

@@ -0,0 +1,31 @@
+# Analyze Performance Results
+
+Analyze performance test results.
+
+## Usage
+```
+/qakit:perf/analyze <results-file>
+```
+
+## Output
+```markdown
+# Performance Analysis
+
+## Summary
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Avg Response | 250ms | 300ms | ✅ |
+| P95 Response | 450ms | 500ms | ✅ |
+| Throughput | 500 rps | 400 rps | ✅ |
+| Error Rate | 0.1% | 1% | ✅ |
+
+## Bottlenecks Identified
+- Database queries at /api/search
+- Memory usage spike at 80% load
+
+## Recommendations
+1. Add database indexes
+2. Implement caching
+```
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/perf/plan.md

@@ -0,0 +1,18 @@
+# Create Performance Test Plan
+
+Create performance testing plan.
+
+## Usage
+```
+/qakit:perf/plan <target-system>
+```
+
+## Instructions
+
+Define:
+- Performance objectives (response time, throughput)
+- Test scenarios (load, stress, spike, soak)
+- Workload model
+- Success criteria
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/perf/run.md

@@ -0,0 +1,17 @@
+# Run Performance Tests
+
+Execute performance tests.
+
+## Usage
+```
+/qakit:perf/run [--duration minutes] [--vus count]
+```
+
+## Instructions
+
+1. Set up test environment
+2. Execute performance tests
+3. Collect metrics
+4. Generate report
+
+$ARGUMENTS