@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/_resources/formatting-guide.md

@@ -1,124 +1,124 @@
-# Formatting Guide - Clickable References & Copyable Commands
-
-This guide defines formatting standards for all command templates.
-
-## File References (clickable)
-
-### Standard format
-
-```markdown
-<!-- Simple file -->
-[filename.ts](path/to/filename.ts)
-
-<!-- File with line -->
-[filename.ts:42](path/to/filename.ts#L42)
-
-<!-- File with line range -->
-[filename.ts:42-51](path/to/filename.ts#L42-L51)
-
-<!-- Folder -->
-[src/components/](src/components/)
-```
-
-### Concrete examples
-
-| Context | Format | Result |
-|---------|--------|--------|
-| GitFlow Config | `[config.json](.claude/gitflow/config.json)` | [config.json](.claude/gitflow/config.json) |
-| Specific line | `[installer.ts:45](src/lib/installer.ts#L45)` | [installer.ts:45](src/lib/installer.ts#L45) |
-| Range | `[utils.ts:10-25](src/utils.ts#L10-L25)` | [utils.ts:10-25](src/utils.ts#L10-L25) |
-| Folder | `[templates/](templates/)` | [templates/](templates/) |
-
-### Avoid
-
-```markdown
-<!-- INCORRECT -->
-`config.json`
-`.claude/gitflow/config.json`
-The config.json file
-```
-
-## Commands (copyable)
-
-### Claude Code Commands
-
-Always in simple code block:
-
-```markdown
-```
-/gitflow init --exec
-```
-```
-
-### Bash/Shell Commands
-
-With language specified:
-
-```markdown
-```bash
-npm run build
-dotnet ef migrations add Initial
-```
-```
-
-### Multiple commands
-
-```markdown
-```bash
-# Step 1: Build
-npm run build
-
-# Step 2: Test
-npm test
-```
-```
-
-### Avoid
-
-```markdown
-<!-- INCORRECT -->
-Execute `/gitflow init`
-Run the command `npm run build`
-```
-
-## Command Tables
-
-Recommended format for listing commands:
-
-```markdown
-| Command | Description |
-|---------|-------------|
-| `/test-web --quick` | Quick tests |
-| `/test-web --chrome` | E2E tests |
-```
-
-## Paths in Instructions
-
-### Good example
-
-```markdown
-1. Create file [config.json](.claude/test-web/config.json)
-2. Execute:
-   ```
-   /test-web --quick
-   ```
-3. Check report in [reports/](.claude/test-web/reports/)
-```
-
-### Bad example
-
-```markdown
-1. Create file `.claude/test-web/config.json`
-2. Execute `/test-web --quick`
-3. Check report in `.claude/test-web/reports/`
-```
-
-## Summary
-
-| Element | Format | Example |
-|---------|--------|---------|
-| File | `[name](path)` | `[config.json](.claude/config.json)` |
-| File:line | `[name:L](path#LX)` | `[utils.ts:42](src/utils.ts#L42)` |
-| Folder | `[name/](path/)` | `[templates/](templates/)` |
-| Claude Command | ` ``` code ``` ` | `/command --flag` |
-| Bash Command | ` ```bash code ``` ` | `npm run build` |
+# Formatting Guide - Clickable References & Copyable Commands
+
+This guide defines formatting standards for all command templates.
+
+## File References (clickable)
+
+### Standard format
+
+```markdown
+<!-- Simple file -->
+[filename.ts](path/to/filename.ts)
+
+<!-- File with line -->
+[filename.ts:42](path/to/filename.ts#L42)
+
+<!-- File with line range -->
+[filename.ts:42-51](path/to/filename.ts#L42-L51)
+
+<!-- Folder -->
+[src/components/](src/components/)
+```
+
+### Concrete examples
+
+| Context | Format | Result |
+|---------|--------|--------|
+| GitFlow Config | `[config.json](.claude/gitflow/config.json)` | [config.json](.claude/gitflow/config.json) |
+| Specific line | `[installer.ts:45](src/lib/installer.ts#L45)` | [installer.ts:45](src/lib/installer.ts#L45) |
+| Range | `[utils.ts:10-25](src/utils.ts#L10-L25)` | [utils.ts:10-25](src/utils.ts#L10-L25) |
+| Folder | `[templates/](templates/)` | [templates/](templates/) |
+
+### Avoid
+
+```markdown
+<!-- INCORRECT -->
+`config.json`
+`.claude/gitflow/config.json`
+The config.json file
+```
+
+## Commands (copyable)
+
+### Claude Code Commands
+
+Always in simple code block:
+
+```markdown
+```
+/gitflow init --exec
+```
+```
+
+### Bash/Shell Commands
+
+With language specified:
+
+```markdown
+```bash
+npm run build
+dotnet ef migrations add Initial
+```
+```
+
+### Multiple commands
+
+```markdown
+```bash
+# Step 1: Build
+npm run build
+
+# Step 2: Test
+npm test
+```
+```
+
+### Avoid
+
+```markdown
+<!-- INCORRECT -->
+Execute `/gitflow init`
+Run the command `npm run build`
+```
+
+## Command Tables
+
+Recommended format for listing commands:
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `/test-web --quick` | Quick tests |
+| `/test-web --chrome` | E2E tests |
+```
+
+## Paths in Instructions
+
+### Good example
+
+```markdown
+1. Create file [config.json](.claude/test-web/config.json)
+2. Execute:
+   ```
+   /test-web --quick
+   ```
+3. Check report in [reports/](.claude/test-web/reports/)
+```
+
+### Bad example
+
+```markdown
+1. Create file `.claude/test-web/config.json`
+2. Execute `/test-web --quick`
+3. Check report in `.claude/test-web/reports/`
+```
+
+## Summary
+
+| Element | Format | Example |
+|---------|--------|---------|
+| File | `[name](path)` | `[config.json](.claude/config.json)` |
+| File:line | `[name:L](path#LX)` | `[utils.ts:42](src/utils.ts#L42)` |
+| Folder | `[name/](path/)` | `[templates/](templates/)` |
+| Claude Command | ` ``` code ``` ` | `/command --flag` |
+| Bash Command | ` ```bash code ``` ` | `npm run build` |

package/templates/skills/_resources/mcp-validate-documentation-spec.md

@@ -1,181 +1,181 @@
-# MCP Tool Specification: validate_documentation
-
-## Status: FUTURE
-
-> This tool does not yet exist in SmartStack.mcp. This file is a specification for its implementation.
-> Until implemented, use the `docs-sync-checker` agent as a fallback.
-
-## Tool Definition
-
-```typescript
-{
-  name: "mcp__smartstack__validate_documentation",
-  description: "Validate documentation freshness, completeness, and accuracy for SmartStack modules",
-  parameters: {
-    module: {
-      type: "string",
-      description: "Module path (e.g., 'business/support/sla'). Empty for all modules.",
-      required: false
-    },
-    checkType: {
-      type: "string",
-      enum: ["freshness", "completeness", "accuracy", "all"],
-      default: "all",
-      description: "Type of validation to perform"
-    },
-    path: {
-      type: "string",
-      description: "Project path (default: SmartStack.app path from config)",
-      required: false
-    }
-  }
-}
-```
-
-## Check Types
-
-### freshness
-Compare `docs-manifest.json` with git history to detect stale documentation.
-
-**Input:** manifest entries, git log
-**Logic:**
-```
-FOR each module in manifest:
-  lastCodeCommit = git log -1 --format="%aI" -- {codeFiles}
-  IF lastCodeCommit > module.lastDocUpdate:
-    status = "drift"
-    driftDays = daysBetween(module.lastDocUpdate, lastCodeCommit)
-```
-
-**Output:**
-```json
-{
-  "modules": [
-    {
-      "path": "business/support/sla",
-      "status": "drift",
-      "driftDays": 15,
-      "lastCodeChange": "2026-01-28",
-      "lastDocUpdate": "2026-01-13"
-    }
-  ]
-}
-```
-
-### completeness
-Verify that documented modules have all 8 business-first sections.
-
-**Input:** doc-data.ts files, i18n JSON files
-**Logic:**
-```
-FOR each module with documentation:
-  Read doc-data.ts
-  Check presence of:
-    1. overview (valeur métier)
-    2. useCases (cas d'usage)
-    3. benefits (bénéfices concrets) — in i18n
-    4. beforeAfter (avant/après) — in i18n
-    5. features (fonctionnalités)
-    6. steps (comment ça marche)
-    7. faq (FAQ métier) — in i18n
-    8. technicalRef (référence technique)
-  Report missing sections
-```
-
-**Output:**
-```json
-{
-  "modules": [
-    {
-      "path": "business/support/sla",
-      "completeness": "6/8",
-      "missingSections": ["beforeAfter", "faq"],
-      "i18nComplete": { "fr": true, "en": false, "it": false, "de": false }
-    }
-  ]
-}
-```
-
-### accuracy
-Compare documented permissions, endpoints, and entities against actual code.
-
-**Input:** doc-data.ts, controllers, PermissionConfiguration.cs, entities
-**Logic:**
-```
-FOR each module:
-  documentedPermissions = docData.permissions
-  actualPermissions = scan PermissionConfiguration.cs for module path
-  IF documentedPermissions != actualPermissions:
-    issues.push("permission mismatch")
-
-  documentedEndpoints = docData.apiEndpoints
-  actualEndpoints = scan Controller for [Http*] attributes
-  IF documentedEndpoints != actualEndpoints:
-    issues.push("endpoint mismatch")
-
-  documentedEntities = docData (entity references)
-  actualEntities = scan Domain/Entities for module
-  IF documentedEntities != actualEntities:
-    issues.push("entity mismatch")
-```
-
-**Output:**
-```json
-{
-  "modules": [
-    {
-      "path": "business/support/sla",
-      "accuracy": "partial",
-      "issues": [
-        {
-          "type": "endpoint_mismatch",
-          "documented": ["GET /api/support/sla", "POST /api/support/sla"],
-          "actual": ["GET /api/support/sla", "POST /api/support/sla", "PATCH /api/support/sla/{id}/status"],
-          "message": "Endpoint PATCH /api/support/sla/{id}/status exists in code but not in documentation"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Combined Output (checkType: "all")
-
-```json
-{
-  "summary": {
-    "totalModules": 5,
-    "synced": 2,
-    "drift": 2,
-    "missing": 1,
-    "overallScore": "60%"
-  },
-  "modules": [
-    {
-      "path": "business/support/sla",
-      "freshness": { "status": "drift", "driftDays": 15 },
-      "completeness": { "score": "6/8", "missingSections": ["beforeAfter", "faq"] },
-      "accuracy": { "status": "partial", "issues": 1 }
-    }
-  ],
-  "recommendations": [
-    "Run `/documentation` for business/support/sla to sync documentation",
-    "Run `/business-analyse` for business/support/tickets to create documentation"
-  ]
-}
-```
-
-## Integration Points
-
-| Consumer | When | Fallback |
-|----------|------|----------|
-| BA step-04 (validate) | During specification validation | Read manifest + git log |
-| Drift hook (pre-commit) | Before commit | Bash script reading manifest |
-
-## Implementation Notes
-
-- Tool should read `docs-manifest.json` from project root
-- Must handle missing manifest gracefully (return "no manifest" status)
-- Git operations should use `--no-pager` flag
-- Performance: cache git log results across modules
-- The tool should be idempotent (no side effects)
+# MCP Tool Specification: validate_documentation
+
+## Status: FUTURE
+
+> This tool does not yet exist in SmartStack.mcp. This file is a specification for its implementation.
+> Until implemented, use the `docs-sync-checker` agent as a fallback.
+
+## Tool Definition
+
+```typescript
+{
+  name: "mcp__smartstack__validate_documentation",
+  description: "Validate documentation freshness, completeness, and accuracy for SmartStack modules",
+  parameters: {
+    module: {
+      type: "string",
+      description: "Module path (e.g., 'business/support/sla'). Empty for all modules.",
+      required: false
+    },
+    checkType: {
+      type: "string",
+      enum: ["freshness", "completeness", "accuracy", "all"],
+      default: "all",
+      description: "Type of validation to perform"
+    },
+    path: {
+      type: "string",
+      description: "Project path (default: SmartStack.app path from config)",
+      required: false
+    }
+  }
+}
+```
+
+## Check Types
+
+### freshness
+Compare `docs-manifest.json` with git history to detect stale documentation.
+
+**Input:** manifest entries, git log
+**Logic:**
+```
+FOR each module in manifest:
+  lastCodeCommit = git log -1 --format="%aI" -- {codeFiles}
+  IF lastCodeCommit > module.lastDocUpdate:
+    status = "drift"
+    driftDays = daysBetween(module.lastDocUpdate, lastCodeCommit)
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "status": "drift",
+      "driftDays": 15,
+      "lastCodeChange": "2026-01-28",
+      "lastDocUpdate": "2026-01-13"
+    }
+  ]
+}
+```
+
+### completeness
+Verify that documented modules have all 8 business-first sections.
+
+**Input:** doc-data.ts files, i18n JSON files
+**Logic:**
+```
+FOR each module with documentation:
+  Read doc-data.ts
+  Check presence of:
+    1. overview (valeur métier)
+    2. useCases (cas d'usage)
+    3. benefits (bénéfices concrets) — in i18n
+    4. beforeAfter (avant/après) — in i18n
+    5. features (fonctionnalités)
+    6. steps (comment ça marche)
+    7. faq (FAQ métier) — in i18n
+    8. technicalRef (référence technique)
+  Report missing sections
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "completeness": "6/8",
+      "missingSections": ["beforeAfter", "faq"],
+      "i18nComplete": { "fr": true, "en": false, "it": false, "de": false }
+    }
+  ]
+}
+```
+
+### accuracy
+Compare documented permissions, endpoints, and entities against actual code.
+
+**Input:** doc-data.ts, controllers, PermissionConfiguration.cs, entities
+**Logic:**
+```
+FOR each module:
+  documentedPermissions = docData.permissions
+  actualPermissions = scan PermissionConfiguration.cs for module path
+  IF documentedPermissions != actualPermissions:
+    issues.push("permission mismatch")
+
+  documentedEndpoints = docData.apiEndpoints
+  actualEndpoints = scan Controller for [Http*] attributes
+  IF documentedEndpoints != actualEndpoints:
+    issues.push("endpoint mismatch")
+
+  documentedEntities = docData (entity references)
+  actualEntities = scan Domain/Entities for module
+  IF documentedEntities != actualEntities:
+    issues.push("entity mismatch")
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "accuracy": "partial",
+      "issues": [
+        {
+          "type": "endpoint_mismatch",
+          "documented": ["GET /api/support/sla", "POST /api/support/sla"],
+          "actual": ["GET /api/support/sla", "POST /api/support/sla", "PATCH /api/support/sla/{id}/status"],
+          "message": "Endpoint PATCH /api/support/sla/{id}/status exists in code but not in documentation"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Combined Output (checkType: "all")
+
+```json
+{
+  "summary": {
+    "totalModules": 5,
+    "synced": 2,
+    "drift": 2,
+    "missing": 1,
+    "overallScore": "60%"
+  },
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "freshness": { "status": "drift", "driftDays": 15 },
+      "completeness": { "score": "6/8", "missingSections": ["beforeAfter", "faq"] },
+      "accuracy": { "status": "partial", "issues": 1 }
+    }
+  ],
+  "recommendations": [
+    "Run `/documentation` for business/support/sla to sync documentation",
+    "Run `/business-analyse` for business/support/tickets to create documentation"
+  ]
+}
+```
+
+## Integration Points
+
+| Consumer | When | Fallback |
+|----------|------|----------|
+| BA step-04 (validate) | During specification validation | Read manifest + git log |
+| Drift hook (pre-commit) | Before commit | Bash script reading manifest |
+
+## Implementation Notes
+
+- Tool should read `docs-manifest.json` from project root
+- Must handle missing manifest gracefully (return "no manifest" status)
+- Git operations should use `--no-pager` flag
+- Performance: cache git log results across modules
+- The tool should be idempotent (no side effects)