@atlashub/smartstack-cli 1.33.0 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/docs-context-reader.md

@@ -0,0 +1,125 @@
+---
+name: docs-context-reader
+description: Reads project documentation (.business-analyse/, web docs, docs-manifest.json) and produces a structured summary for context injection into skills and agents
+color: green
+tools: Read, Glob, Grep
+model: haiku
+---
+
+You are a documentation context specialist. Your mission is to read existing project documentation and produce a compact, structured summary that other agents and skills can consume for context injection.
+
+## Search Strategy
+
+### 1. Read Documentation Manifest
+
+```
+Read: docs-manifest.json (project root)
+```
+
+If the manifest exists, use it as the primary source of truth for module discovery and status.
+
+If absent, fall back to directory scanning.
+
+### 2. Scan Documentation Sources
+
+**Business Analysis outputs:**
+```
+Glob: .business-analyse/business/**/features/FEAT-*
+```
+
+For each feature found, read:
+- `00-context.md` (state variables, progress)
+- `3-functional-specification.md` (use cases, requirements, permissions)
+- `validation.json` (approval status)
+
+**Web documentation pages:**
+```
+Glob: web/smartstack-web/src/pages/docs/business/**/*frd-data.ts
+Glob: web/smartstack-web/src/pages/docs/**/*DocPage.tsx
+```
+
+**i18n documentation:**
+```
+Glob: web/smartstack-web/src/i18n/locales/fr/docs-*.json
+```
+
+### 3. Extract Structured Data
+
+For each module found, extract:
+- Module path (e.g., `business/support/sla`)
+- Feature ID (FEAT-NNN)
+- Use Case IDs (UC-001, UC-002...)
+- Business Rule IDs (BR-001, BR-002...)
+- Permission paths (business.app.module.action)
+- Last update dates
+- Validation status (APPROVED/REJECTED/PENDING)
+- Documentation completeness (which of the 8 sections exist)
+
+## Output Format
+
+**CRITICAL**: Output all findings directly in your response. NEVER create markdown files.
+
+```markdown
+# Documentation Context Summary
+
+**Manifest:** {found|missing}
+**Modules found:** {count}
+**Last scan:** {timestamp}
+
+## Module: {business/app/module}
+
+| Attribute | Value |
+|-----------|-------|
+| Feature ID | FEAT-NNN |
+| Status | synced / drift / missing |
+| Last code change | {date} |
+| Last doc update | {date} |
+| Validation | APPROVED / PENDING |
+
+### Use Cases
+- UC-001: {name} ({actor}, {permission})
+- UC-002: {name} ({actor}, {permission})
+
+### Business Rules
+- BR-001: {name} ({category})
+- BR-002: {name} ({category})
+
+### Permissions
+- business.{app}.{module}.read → [roles]
+- business.{app}.{module}.create → [roles]
+
+### Documentation Sections (8 business-first)
+- [x] Valeur Métier
+- [x] Cas d'usage
+- [x] Bénéfices concrets
+- [ ] Avant/Après (missing)
+- [x] Fonctionnalités
+- [x] Comment ça marche
+- [ ] FAQ Métier (missing)
+- [x] Référence technique
+
+### Screenshots
+- step1: /assets/docs/{module}/step-1.png (exists|missing)
+```
+
+## Execution Rules
+
+- **NEVER create files** - output everything directly
+- **Compact over verbose** - max 200 lines total output
+- **Structured data** - every section must be parseable
+- **Skip empty modules** - only report modules with actual documentation
+- **Report drift** - explicitly flag modules where code > doc timestamp
+- **Parallel reads** when scanning multiple modules
+- **Handle missing manifest gracefully** - fall back to directory scan
+
+## Module Filter
+
+If invoked with a specific module name (e.g., "SLA", "Tickets"):
+- Only report on that module
+- Include full detail (all UC, BR, permissions, sections)
+- Include file paths for each artifact
+
+If invoked without filter:
+- Report all modules in summary format
+- Max 20 lines per module
+- Focus on status and completeness

package/templates/agents/docs-sync-checker.md

@@ -0,0 +1,122 @@
+---
+name: docs-sync-checker
+description: Detects documentation drift by comparing code changes (git diff) against docs-manifest.json. Reports modules with stale documentation.
+color: orange
+tools: Read, Bash, Glob, Grep
+model: haiku
+---
+
+You are a documentation drift detection specialist. Your mission is to compare code changes against the documentation manifest and report which modules have stale or missing documentation.
+
+## Execution Sequence
+
+### 1. Read Documentation Manifest
+
+```
+Read: docs-manifest.json (project root)
+```
+
+If absent:
+- Report "No docs-manifest.json found. Cannot detect drift."
+- Suggest: "Run /business-analyse or /documentation to create the manifest."
+- EXIT
+
+### 2. Detect Code Changes
+
+**Option A: Compare against manifest timestamps**
+
+For each module in manifest, check if code files have been modified:
+
+```bash
+# Get last commit date for each code file
+git log -1 --format="%aI" -- "{codeFile}"
+```
+
+Compare with `module.lastDocUpdate`. If code is newer → drift.
+
+**Option B: Compare specific range (if provided)**
+
+If a commit range or branch is specified:
+
+```bash
+# Get all changed files since last doc update
+git diff --name-only {gitCommitDoc}..HEAD
+```
+
+Match changed files against `module.codeFiles`.
+
+### 3. Classify Changes
+
+For each drifted module, identify the type of changes:
+
+| Change Pattern | Impact |
+|----------------|--------|
+| `**/Entities/**` modified | Business Rules, Features sections |
+| `**/Controllers/**` modified | API Endpoints, Technical Ref sections |
+| `**/Permissions*` modified | Permissions section |
+| `**/Validators/**` modified | Business Rules section |
+| `**/i18n/**` modified | Use Cases (labels), FAQ sections |
+| `**/Migrations/**` created | Technical Ref (schema) section |
+
+### 4. Generate Drift Report
+
+## Output Format
+
+**CRITICAL**: Output all findings directly in your response. NEVER create markdown files.
+
+```markdown
+# Documentation Drift Report
+
+**Scan date:** {timestamp}
+**Manifest version:** {version}
+**Modules scanned:** {count}
+**Modules in drift:** {count}
+**Modules missing docs:** {count}
+
+## Drift Summary
+
+| Module | Status | Days Since Doc Update | Changed Files | Impacted Sections |
+|--------|--------|----------------------|---------------|-------------------|
+| business/support/sla | DRIFT | 15 days | 3 files | API, Permissions |
+| business/support/tickets | MISSING | - | - | All |
+| business/hr/employees | SYNCED | 0 days | 0 files | - |
+
+## Detailed Drift: business/support/sla
+
+**Last code change:** 2026-01-28 (commit: a1b2c3d)
+**Last doc update:** 2026-01-13 (commit: e4f5g6h)
+**Drift days:** 15
+
+### Changed Files
+- `src/.../SlaController.cs` → API Endpoints section
+- `src/.../Sla.cs` → Business Rules, Features sections
+- `src/.../CreateSlaCommand.cs` → Use Cases section
+
+### Recommended Action
+Run `/apex -d` to sync documentation, or `/documentation:update business/support/sla`
+
+## Actions Required
+
+1. **DRIFT modules ({count}):** Run `/apex -d` or `/documentation` to update
+2. **MISSING modules ({count}):** Run `/business-analyse` to create documentation
+3. **SYNCED modules ({count}):** No action needed
+```
+
+## Execution Rules
+
+- **NEVER create files** - output everything directly
+- **Non-blocking** - always report, never fail
+- **Handle missing manifest** - report clearly and suggest creation
+- **Handle git errors** - if git commands fail, report the error and continue
+- **Compact format** - max 100 lines total output
+- **Actionable** - every drift must have a recommended action
+- **Skip synced details** - only expand drift/missing modules
+
+## Severity Classification
+
+| Drift Days | Severity | Icon |
+|------------|----------|------|
+| 0-7 | Low | Minor drift, not urgent |
+| 8-30 | Medium | Should update soon |
+| 31+ | High | Critical drift, update immediately |
+| Missing | Critical | No documentation exists |

package/templates/hooks/docs-drift-check.md

@@ -0,0 +1,97 @@
+---
+description: Documentation drift warning on commit (non-blocking)
+trigger: tool-use
+match: git commit*
+blocking: false
+---
+
+# Documentation Drift Check (Low Token)
+
+Lightweight pre-commit check that warns about documentation drift. Reads manifest only, non-blocking.
+
+## Script
+
+```bash
+#!/bin/bash
+MANIFEST="docs-manifest.json"
+
+# Skip if no manifest exists
+if [ ! -f "$MANIFEST" ]; then
+  exit 0
+fi
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+  exit 0
+fi
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null)
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+# Check each module in manifest for drift
+DRIFT_FOUND=false
+DRIFT_MODULES=""
+
+for MODULE_PATH in $(jq -r '.modules | keys[]' "$MANIFEST" 2>/dev/null); do
+  # Get code files for this module
+  CODE_FILES=$(jq -r ".modules[\"$MODULE_PATH\"].codeFiles[]?" "$MANIFEST" 2>/dev/null)
+
+  for CODE_FILE in $CODE_FILES; do
+    # Check if any staged file matches a module's code files
+    if echo "$STAGED_FILES" | grep -q "$CODE_FILE"; then
+      STATUS=$(jq -r ".modules[\"$MODULE_PATH\"].status" "$MANIFEST" 2>/dev/null)
+      LAST_DOC=$(jq -r ".modules[\"$MODULE_PATH\"].lastDocUpdate" "$MANIFEST" 2>/dev/null)
+      FEATURE_ID=$(jq -r ".modules[\"$MODULE_PATH\"].featureId" "$MANIFEST" 2>/dev/null)
+
+      if [ "$STATUS" != "synced" ] || [ "$LAST_DOC" = "null" ]; then
+        DRIFT_FOUND=true
+        DRIFT_MODULES="$DRIFT_MODULES\n  - $MODULE_PATH ($FEATURE_ID) — last doc update: ${LAST_DOC:-never}"
+      fi
+      break
+    fi
+  done
+done
+
+if [ "$DRIFT_FOUND" = true ]; then
+  echo ""
+  echo "Documentation drift detected:"
+  echo -e "$DRIFT_MODULES"
+  echo ""
+  echo "Consider running /apex -d or /documentation to update."
+  echo ""
+fi
+
+exit 0
+```
+
+## Behavior
+
+| Condition | Output | Blocks? |
+|-----------|--------|---------|
+| No manifest file | Silent | No |
+| No jq available | Silent | No |
+| No staged files | Silent | No |
+| Staged files match synced modules | Silent | No |
+| Staged files match drifted modules | Warning with module list | No |
+
+## Token Cost
+
+- **Normal case (no drift):** 0 tokens (pure bash, no LLM)
+- **Drift detected:** ~10 tokens (displays warning message)
+
+## Integration
+
+This hook integrates with:
+- `docs-manifest.json` (created by BA step-06 and APEX step-04b)
+- `/apex -d` flag for automatic documentation sync
+- `/documentation` skill for manual documentation updates
+
+## Notes
+
+- **Non-blocking by design:** Documentation drift should never prevent commits
+- The warning suggests running `/apex -d` (documentation sync) or `/documentation` (manual update)
+- If `jq` is not installed, the hook silently exits (graceful degradation)
+- Cross-platform: Works on Linux, macOS, and Windows (Git Bash/WSL)

package/templates/skills/_resources/context-digest-template.md

@@ -0,0 +1,53 @@
+# Context Digest Pattern
+
+## Purpose
+
+Reduces token usage between multi-step skill executions (APEX, BA) by compressing step outputs into compact summaries.
+
+## How It Works
+
+```
+Step N completes
+    ↓
+Generate digest (max 50 lines)
+    ↓
+Pass digest to Step N+1 (in-context)
+    ↓
+Step N+1 reads:
+  - Digest from previous step (compact)
+  - 00-context.md for state variables
+  - Full output files ONLY if digest indicates need
+```
+
+## Digest Sections
+
+| Section | Max Lines | Content |
+|---------|-----------|---------|
+| Changes | 10 | Files modified with brief description |
+| Decisions | 10 | Key architectural decisions |
+| Findings | 10 | Issues found, patterns identified |
+| State | 5 | Updated state variables |
+| Blockers | 5 | Open issues, unresolved questions |
+| Next | 5 | What the next step needs to know |
+
+## Token Savings Estimate
+
+| Scenario | Without Digest | With Digest | Savings |
+|----------|---------------|-------------|---------|
+| step-01 → step-02 | ~2000 tokens | ~500 tokens | 75% |
+| step-02 → step-03 | ~1500 tokens | ~400 tokens | 73% |
+| step-03 → step-04 | ~1800 tokens | ~450 tokens | 75% |
+| **Total workflow** | ~5300 tokens | ~1350 tokens | **~75%** |
+
+## Applies To
+
+- APEX skill (all step transitions)
+- BA skill (between phases)
+- Any future multi-step skill
+
+## Resume Exception
+
+When a skill resumes via `-r` flag:
+- Digest is ephemeral (not saved to disk)
+- Resume reads full output files from `.claude/output/` or `.business-analyse/`
+- This ensures complete state restoration after session break

package/templates/skills/_resources/doc-context-cache.md

@@ -0,0 +1,62 @@
+# Documentation Context Cache
+
+## Purpose
+
+Caches the output of `docs-context-reader` agent to avoid redundant documentation scans.
+
+## Location
+
+`.claude/cache/docs-context.json`
+
+## Schema
+
+```json
+{
+  "generatedAt": "ISO-date",
+  "commitHash": "git-sha",
+  "ttl": 86400,
+  "summary": {
+    "totalModules": 5,
+    "documented": 3,
+    "synced": 2,
+    "drift": 1,
+    "missing": 2
+  },
+  "modules": {
+    "business/support/sla": {
+      "featureId": "FEAT-003",
+      "status": "synced",
+      "useCaseCount": 4,
+      "ruleCount": 6,
+      "permissionCount": 5,
+      "sections": ["overview", "useCases", "benefits", "features", "steps", "technicalRef"],
+      "missingSections": ["beforeAfter", "faq"]
+    }
+  }
+}
+```
+
+## TTL (Time To Live)
+
+| Condition | Cache Valid |
+|-----------|------------|
+| Same git commit hash | Yes |
+| Different git commit hash | No (invalidate) |
+| > 24 hours old | No (invalidate) |
+| docs-manifest.json modified | No (invalidate) |
+
+## Usage
+
+1. **Before launching docs-context-reader agent**: Check cache
+2. **If cache valid**: Use cached summary (0 tokens)
+3. **If cache invalid**: Launch agent, save result to cache
+4. **On commit**: Invalidate cache (commit changes may affect docs)
+
+## Integration Points
+
+| Consumer | Check Cache? |
+|----------|-------------|
+| APEX step-01 (analyze) | Yes |
+| APEX step-04b (doc-sync) | Yes |
+| BA step-01 (discover) | Yes |
+| docs-sync-checker agent | No (always fresh) |

package/templates/skills/_resources/docs-manifest-schema.md

@@ -0,0 +1,157 @@
+# Documentation Manifest Schema
+
+## Purpose
+
+The `docs-manifest.json` file maps code modules to their documentation artifacts. It is the single source of truth for documentation drift detection.
+
+**Location:** Project root (next to `package.json` or `.sln`)
+
+## Schema
+
+```json
+{
+  "version": "1.0",
+  "lastUpdated": "2026-01-30T10:00:00Z",
+  "modules": {
+    "business/{app}/{module}": {
+      "featureId": "FEAT-NNN",
+      "displayName": "Module Display Name",
+      "codeFiles": [
+        "src/SmartStack.Domain/Entities/Business/{Entity}.cs",
+        "src/SmartStack.Application/Features/{Module}/Commands/*.cs",
+        "src/SmartStack.Application/Features/{Module}/Queries/*.cs",
+        "src/SmartStack.Api/Controllers/Business/{Module}Controller.cs"
+      ],
+      "docFiles": [
+        "web/smartstack-web/src/pages/docs/business/{app}/{module}/frd-data.ts",
+        "web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json"
+      ],
+      "baOutputs": [
+        ".business-analyse/business/{app}/modules/{module}/features/FEAT-NNN/"
+      ],
+      "screenshots": {
+        "step1": "/assets/docs/{module}/step-1.png",
+        "step2": "/assets/docs/{module}/step-2.png"
+      },
+      "lastCodeChange": "2026-01-30T10:00:00Z",
+      "lastDocUpdate": "2026-01-30T10:00:00Z",
+      "gitCommitCode": "abc123",
+      "gitCommitDoc": "def456",
+      "status": "synced"
+    }
+  }
+}
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | string | Yes | Schema version (always "1.0") |
+| `lastUpdated` | ISO date | Yes | Last time manifest was modified |
+| `modules` | object | Yes | Map of module path → module entry |
+
+### Module Entry
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `featureId` | string | Yes | BA feature ID (FEAT-NNN) |
+| `displayName` | string | Yes | Human-readable module name |
+| `codeFiles` | string[] | Yes | Source code files for this module |
+| `docFiles` | string[] | Yes | Documentation files (frd-data.ts, i18n) |
+| `baOutputs` | string[] | No | Business Analysis output directory |
+| `screenshots` | object | No | Map of stepKey → image path |
+| `lastCodeChange` | ISO date | Yes | Last code modification timestamp |
+| `lastDocUpdate` | ISO date | Yes | Last documentation update timestamp |
+| `gitCommitCode` | string | Yes | Git SHA of last code commit |
+| `gitCommitDoc` | string | Yes | Git SHA of last doc commit |
+| `status` | enum | Yes | `synced`, `drift`, or `missing` |
+
+## Status Values
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `synced` | Documentation matches code | No action needed |
+| `drift` | Code changed after last doc update | Run `/apex -d` or `/documentation` to update |
+| `missing` | Module exists in code but has no documentation | Run `/business-analyse` or `/documentation` to create |
+
+## Usage
+
+### Created by
+- BA skill step-06 (doc-html) after generating documentation
+- Documentation skill after creating/updating a module page
+
+### Read by
+- `docs-context-reader` agent (for context injection)
+- `docs-sync-checker` agent (for drift detection)
+- APEX step-04b (doc-sync) to identify affected modules
+- BA step-04 (validate) for freshness check
+- Drift hook (pre-commit) for commit warnings
+
+### Updated by
+- BA step-06 (on doc generation)
+- APEX step-04b (on doc sync)
+- Documentation skill (on doc update)
+
+## Drift Detection Logic
+
+```
+IF module.lastCodeChange > module.lastDocUpdate:
+    module.status = "drift"
+ELSE:
+    module.status = "synced"
+```
+
+## Example
+
+```json
+{
+  "version": "1.0",
+  "lastUpdated": "2026-01-30T14:30:00Z",
+  "modules": {
+    "business/support/sla": {
+      "featureId": "FEAT-003",
+      "displayName": "SLA Management",
+      "codeFiles": [
+        "src/SmartStack.Domain/Entities/Business/Sla.cs",
+        "src/SmartStack.Application/Features/Sla/Commands/CreateSlaCommand.cs",
+        "src/SmartStack.Application/Features/Sla/Queries/GetSlaListQuery.cs",
+        "src/SmartStack.Api/Controllers/Business/SlaController.cs"
+      ],
+      "docFiles": [
+        "web/smartstack-web/src/pages/docs/business/support/sla/frd-data.ts",
+        "web/smartstack-web/src/i18n/locales/fr/docs-support-sla.json"
+      ],
+      "baOutputs": [
+        ".business-analyse/business/Support/modules/Sla/features/FEAT-003/"
+      ],
+      "screenshots": {
+        "step1": "/assets/docs/sla/step-1.png",
+        "step2": "/assets/docs/sla/step-2.png",
+        "step3": "/assets/docs/sla/step-3.png"
+      },
+      "lastCodeChange": "2026-01-28T16:00:00Z",
+      "lastDocUpdate": "2026-01-30T14:30:00Z",
+      "gitCommitCode": "a1b2c3d",
+      "gitCommitDoc": "e4f5g6h",
+      "status": "synced"
+    },
+    "business/support/tickets": {
+      "featureId": "FEAT-005",
+      "displayName": "Ticket Management",
+      "codeFiles": [
+        "src/SmartStack.Domain/Entities/Business/Ticket.cs",
+        "src/SmartStack.Api/Controllers/Business/TicketsController.cs"
+      ],
+      "docFiles": [],
+      "baOutputs": [],
+      "screenshots": {},
+      "lastCodeChange": "2026-01-29T10:00:00Z",
+      "lastDocUpdate": "1970-01-01T00:00:00Z",
+      "gitCommitCode": "x7y8z9a",
+      "gitCommitDoc": "",
+      "status": "missing"
+    }
+  }
+}
+```