@atlashub/smartstack-cli 2.3.0 → 2.4.0

package/package.json

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

package/templates/agents/ba-reader.md

@@ -10,7 +10,11 @@ You are a business analysis reader agent specialized in extracting and synthesiz
 
 ## Mission
 
-Read feature.json files in `docs/business/{app}/{module}/business-analyse/v{X.Y}/` and provide structured answers, context summaries, or cross-feature insights. Support discovery, documentation, and skill orchestration.
+Read feature.json files at both application-level and module-level, and provide structured answers, context summaries, or cross-feature insights. Support discovery, documentation, and skill orchestration.
+
+**File locations:**
+- Application-level: `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
+- Module-level: `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 
 ## Core Operations
 
@@ -20,20 +24,115 @@ Locate a feature by ID and return its latest version path.
 **Input:**
 - featureId: FEAT-NNN (e.g., FEAT-042)
 - Optional: versionFilter (e.g., "1.0", "2.x", "latest")
+- Optional: scope ("application" | "module" | "any") — default: "any"
 
 **Process:**
 1. Glob pattern: `docs/business/**/business-analyse/*/feature.json`
 2. Read each feature.json and check id field
-3. If multiple versions exist, sort numerically by version
-4. Return highest matching version path
-5. If not found, check legacy `.business-analyse/` format
+3. If scope filter provided, also check scope field
+4. If multiple versions exist, sort numerically by version
+5. Return highest matching version path
+6. If not found, check legacy `.business-analyse/` format
 
 **Output:**
 - Full path to feature.json
 - Version number
+- Scope (application or module)
 - Status
 - Last updated timestamp
 
+### findApplicationFeature
+Locate the master (application-level) feature.json for a given app.
+
+**Input:**
+- app: string (application code, e.g., "Sales")
+- OR featureId: FEAT-NNN
+
+**Process:**
+1. Glob: `docs/business/{app}/business-analyse/*/feature.json`
+2. Read and verify scope = "application"
+3. Return latest version path
+
+**Output:**
+- Full path to master feature.json
+- Workflow state (mode, currentModuleIndex, completedModules)
+
+### readApplicationContext
+Read the master feature.json and extract application-level context.
+
+**Input:**
+- featureId: FEAT-NNN of the master
+
+**Process:**
+1. Find master feature.json
+2. Extract: cadrage.applicationRoles, modules[], dependencyGraph, metadata.workflow
+3. Format as compact context block
+
+**Output (max 50 lines):**
+```markdown
+# Application Context: {app_name}
+
+**Mode:** application | **Status:** {status} | **Modules:** {count}
+
+## Roles
+- {Role1}: {permissions summary}
+- {Role2}: {permissions summary}
+
+## Modules ({current}/{total} specified)
+| # | Module | Status | Complexity | Dependencies |
+|---|--------|--------|------------|--------------|
+{for each module}
+
+## Current: {currentModule} (index {currentModuleIndex})
+```
+
+### getModuleStatus
+Get status overview of all modules in the application.
+
+**Input:**
+- featureId: FEAT-NNN of the master
+
+**Process:**
+1. Read master feature.json
+2. Extract modules[].status for each module
+3. Return status table
+
+**Output:**
+- Markdown table: Module | Status | Complexity | Entities | BRs
+
+### getCompletedModulesSummary
+Get a compact summary of all completed (specified) modules, for use as context when specifying the next module.
+
+**Input:**
+- featureId: FEAT-NNN of the master
+
+**Process:**
+1. Read master feature.json → get list of completed modules
+2. For each completed module, read its module-level feature.json
+3. Extract compact summary:
+   - Entity names (list only)
+   - Key business rules (IDs + 1-line descriptions)
+   - Permission paths (list only)
+   - Key relationships / FK references
+4. Keep total output under 100 lines
+
+**Output:**
+```markdown
+## Completed Modules Summary
+
+### Customers (FEAT-011)
+Entities: Customer, Address, Contact
+BRs: BR-VAL-001 (email unique), BR-WF-001 (activation flow)
+Permissions: business.sales.customers.{read|create|update|delete}
+FKs exposed: Customer.Id, Address.Id
+
+### Products (FEAT-012)
+Entities: Product, Category, PriceHistory
+BRs: BR-VAL-002 (SKU format), BR-CALC-001 (price calculation)
+Permissions: business.sales.products.{read|create|update}
+FKs exposed: Product.Id, Category.Id
+```
+
 ### readSection
 Extract and format a specific section from a feature.json.
 
@@ -69,11 +168,14 @@ Answer natural language questions about a feature.
 
 **Common Question Types:**
 - "What are the business rules?" → return analysis.businessRules with full details
-- "What permissions are needed?" → extract from specification.functionalRequirements
-- "What are the main entities?" → return specification.entities with relationships
-- "Who are the actors?" → extract from specification.useCases actors
+- "What permissions are needed?" → extract from specification.permissionMatrix
+- "What are the main entities?" → return specification.entities / analysis.entities with relationships
+- "Who are the actors?" → extract from specification.actors or cadrage.applicationRoles
 - "What use cases are covered?" → return specification.useCases with descriptions
 - "What's the current status?" → return status, steps timeline, and next actions
+- "Which modules are defined?" → return modules[] from master (application-level)
+- "What are the cross-module interactions?" → return consolidation.crossModuleInteractions
+- "What roles does the application have?" → return cadrage.applicationRoles from master
 
 **Output:**
 - Answer formatted as markdown
@@ -196,8 +298,9 @@ Generate compact context for use by other skills and agents.
 
 When searching for feature data:
 
-1. **Primary:** `docs/business/` (new feature.json format)
-2. **Fallback:** `.business-analyse/` (legacy format)
+1. **Primary (application):** `docs/business/{app}/business-analyse/*/feature.json` (scope: application)
+2. **Primary (module):** `docs/business/{app}/{module}/business-analyse/*/feature.json` (scope: module)
+3. **Fallback:** `.business-analyse/` (legacy format)
    - Read: `00-context.md` + `3-functional-specification.md`
    - Warn user about old format
    - Suggest migration to new format
@@ -231,6 +334,8 @@ This agent provides context for:
 - **feature-full**: Source for comprehensive feature documentation
 - **Code generation**: Permission paths and entity definitions
 - **ba-writer**: Finding features for enrichment operations
+- **step-03-specify**: Completed module summaries for cross-module references
+- **step-04-consolidation**: Application context and module summaries for cross-module validation
 - Other skills needing business analysis context
 
 ## Example Usage

package/templates/agents/ba-writer.md

@@ -10,7 +10,11 @@ You are a business analysis writer agent specialized in managing feature.json fi
 
 ## Mission
 
-Write and update feature.json files located in `docs/business/{app}/{module}/business-analyse/v{X.Y}/`. Handle progressive enrichment of features as they move through analysis phases, manage versioning for refactoring, and enforce schema consistency.
+Write and update feature.json files for both application-level (master) and module-level documents. Handle progressive enrichment of features as they move through analysis phases, manage versioning for refactoring, and enforce schema consistency.
+
+**Directory structure:**
+- Application-level: `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
+- Module-level: `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 
 ## Core Operations
 
@@ -19,60 +23,129 @@ Create an initial feature.json with metadata and draft status.
 
 **Input:**
 - metadata: object with app, module, language, featureDescription, featureType, useCase
+- scope: "application" or "module" (default: "module")
+- Optional: applicationRef (FEAT-NNN of master, required when scope = "module" in app mode)
 - Optional: initialSections for pre-populated content
 
 **Process:**
 1. Read `.business-analyse/config.json` to get lastFeatureId
 2. Increment FEAT-NNN identifier
-3. Create directory structure: `docs/business/{app}/{module}/business-analyse/v1.0/`
+3. Create directory structure based on scope:
+   - If scope = "application": `docs/business/{app}/business-analyse/v1.0/`
+   - If scope = "module": `docs/business/{app}/{module}/business-analyse/v1.0/`
 4. Generate initial feature.json with:
    - id: FEAT-NNN (from config)
    - version: "1.0"
    - status: "draft"
-   - metadata: createdAt, updatedAt, createdBy, updatedBy, previousVersion: null
-   - discovery: empty object
-   - analysis: empty object with businessRules: []
-   - specification: empty object with useCases: [], functionalRequirements: [], entities: []
-   - validation: empty object with testCases: []
-   - handoff: empty object
-   - suggestions: empty array
+   - scope: "application" or "module"
+   - metadata: createdAt, updatedAt, createdBy, updatedBy, previousVersion: null, scope, applicationRef
+   - For application scope: cadrage: {}, modules: [], dependencyGraph: {}, consolidation: {}, suggestions: [], changelog: []
+   - For module scope: discovery: {}, analysis: {}, specification: {}, validation: {}, handoff: {}, suggestions: [], applicationContext: {}
 5. Update `.business-analyse/config.json` with new lastFeatureId
 6. Append entry to changelog
 
+### createApplicationFeature
+Create a master application-level feature.json. Shorthand for `create` with `scope: "application"`.
+
+**Input:**
+- metadata: object with app, language, featureDescription
+- workflow: object with mode ("application" or "module"), moduleOrder: [], currentModuleIndex: 0
+
+**Process:**
+1. Call `create` with scope = "application"
+2. Initialize `metadata.workflow` with mode, moduleOrder: [], currentModuleIndex: 0, completedModules: [], currentModule: null
+3. Return feature ID and path
+
 ### enrichSection
 Merge a section into an existing feature.json.
 
 **Input:**
 - featureId: FEAT-NNN or full path to feature.json
-- section: one of [discovery, analysis, specification, validation, handoff, suggestions]
+- section: one of [discovery, analysis, specification, validation, handoff, suggestions, cadrage, consolidation, modules, dependencyGraph, metadata.workflow]
 - data: object to replace the entire section
 
 **Process:**
 1. Find and read feature.json (use findFeature if given ID)
 2. Replace the named section entirely (no deep merge)
-3. Update metadata.updatedAt with current timestamp
-4. Update metadata.updatedBy with agent name
-5. Write back with pretty-print (2-space indent)
-6. Validate schema before writing
-7. Return confirmation with section size and status
+3. For nested paths like "metadata.workflow", navigate to the parent and replace the child
+4. Update metadata.updatedAt with current timestamp
+5. Update metadata.updatedBy with agent name
+6. Write back with pretty-print (2-space indent)
+7. Validate schema before writing
+8. Return confirmation with section size and status
 
 ### updateStatus
 Transition the status through defined workflow.
 
-**Valid transitions:**
+**Valid transitions (module-level):**
 - draft → analysed
 - analysed → specified
 - specified → approved
 - specified → rejected (stays as specified)
 - approved → handed-off
 
+**Valid transitions (application-level):**
+- draft → framed
+- framed → decomposed
+- decomposed → specified
+- specified → consolidated
+- consolidated → handed-off
+
 **Process:**
 1. Read feature.json
-2. Verify current status allows transition
-3. Update status field
-4. Update metadata.steps object with timestamp for the corresponding step
+2. Detect scope (application or module) to determine valid transitions
+3. Verify current status allows transition
+4. Update status field
+5. Update metadata.steps object with timestamp for the corresponding step
+6. Write back
+7. Return confirmation with new status
+
+### enrichModuleRegistry
+Update the modules array and dependency graph in a master (application-level) feature.json.
+
+**Input:**
+- featureId: FEAT-NNN of the master feature.json
+- modules: array of module objects (code, description, featureType, entities, priority, estimatedComplexity, sortOrder)
+- dependencyGraph: object with edges[], topologicalOrder[], layers[]
+
+**Process:**
+1. Find master feature.json (verify scope = "application")
+2. Replace `modules` array entirely
+3. Replace `dependencyGraph` object entirely
+4. For each module, set initial status: "pending"
+5. Update metadata.updatedAt
+6. Write back
+7. Return confirmation
+
+### updateModuleStatus
+Update the status of a specific module in the master feature.json.
+
+**Input:**
+- featureId: FEAT-NNN of the master
+- moduleCode: string (PascalCase module code)
+- status: "pending" | "in-progress" | "specified" | "validated"
+
+**Process:**
+1. Find master feature.json
+2. Find module by code in `modules[]`
+3. Update module.status
+4. Update metadata.updatedAt
 5. Write back
-6. Return confirmation with new status
+6. Return confirmation
+
+### advanceModuleLoop
+Increment the module loop counter in the master feature.json.
+
+**Process:**
+1. Find master feature.json
+2. Read `metadata.workflow.currentModuleIndex` and `metadata.workflow.moduleOrder`
+3. Add current module to `metadata.workflow.completedModules`
+4. Increment `metadata.workflow.currentModuleIndex`
+5. If new index < moduleOrder.length: set `currentModule` to next module
+6. If new index >= moduleOrder.length: set `currentModule` to null
+7. Update metadata.updatedAt
+8. Write back
+9. Return new index and whether loop is complete
 
 ### createVersion
 Create a new version for refactoring or major changes.
@@ -103,27 +176,35 @@ Perform these structural checks before every write:
 - BR IDs: must match `BR-(VAL|CALC|WF|SEC|DATA)-\d{3}` (e.g., BR-SEC-042)
 - UC IDs: must match `UC-\d{3}` (e.g., UC-007)
 - FR IDs: must match `FR-\d{3}` (e.g., FR-012)
-- Permission paths: must match `business\.{app}\.{module}\.{action}` (e.g., business.crm.contacts.create)
+- Permission paths: must match `business\.{app}\.{module}\.{resource}\.{action}` (e.g., business.crm.contacts.read)
 
 **Metadata:**
-- id, version, status are required
+- id, version, status, scope are required
 - metadata.createdAt, metadata.updatedAt must be valid ISO timestamps
-- status must be in [draft, analysed, specified, approved, rejected, handed-off]
+- For application scope: status must be in [draft, framed, decomposed, specified, consolidated, handed-off]
+- For module scope: status must be in [draft, analysed, specified, approved, rejected, handed-off]
 
 **Cross-references:**
 - All BR-XXX, UC-XXX, FR-XXX referenced must be defined in their respective sections
-- Permission paths must use valid naming convention
+- Permission paths must use full format with 5 segments: `business.{app}.{module}.{resource}.{action}`
+
+**Application-scope specific:**
+- `modules[]` must exist and be non-empty after decomposition
+- `metadata.workflow` must exist with mode, moduleOrder, currentModuleIndex
+- Each module in `modules[]` must have: code, description, status
 
 ## Directory Structure
 
 ```
+docs/business/{app}/business-analyse/
+  v1.0/
+    feature.json                          ← APPLICATION (master)
+
 docs/business/{app}/{module}/business-analyse/
   v1.0/
-    feature.json
+    feature.json                          ← MODULE (detailed)
   v1.1/
     feature.json
-  v2.0/
-    feature.json
 ```
 
 Versions are stored as separate files in versioned directories. Always store feature.json at the root of each version folder.

package/templates/agents/mcp-healthcheck.md

@@ -122,7 +122,7 @@ MCP HEALTH CHECK
 MCP HEALTH CHECK
   Status: ❌ ERROR
   Issue: MCP server not responding
-  Action: claude mcp add smartstack -- npx -p @atlashub/smartstack-cli smartstack-mcp
+  Action: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
 ```
 
 ## Integration

package/templates/ralph/README.md

@@ -35,7 +35,7 @@ npm install -g @upstash/context7-mcp
 
 ### 2. Register in Claude Code
 ```bash
-claude mcp add smartstack -- npx -p @atlashub/smartstack-cli smartstack-mcp
+claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
 claude mcp add context7 -- npx @upstash/context7-mcp
 ```
 

package/templates/ralph/ralph.config.yaml

@@ -14,7 +14,7 @@ mcp:
 
     - name: smartstack
       description: "SmartStack validation and scaffolding (bundled in CLI)"
-      install_command: "claude mcp add smartstack -- npx -p @atlashub/smartstack-cli smartstack-mcp"
+      install_command: "claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp"
       health_check: true
 
   # Behavior when MCP is unavailable

package/templates/skills/_shared.md

@@ -109,6 +109,66 @@ if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin
 □ API documentation (ProducesResponseType)
 ```
 
+## MCP Prerequisite Guard (BLOCKING)
+
+Skills that depend on SmartStack MCP **MUST** verify connectivity before proceeding. This check is **BLOCKING** - the skill cannot continue without MCP.
+
+### Detection Method
+
+At skill initialization (step-00-init), attempt a minimal MCP call:
+
+```
+mcp__smartstack__validate_conventions({ checks: ["tables"] })
+```
+
+### Decision Matrix
+
+| Result | Action |
+|--------|--------|
+| Success response | Set `mcp_available = true`, continue workflow |
+| Connection error / tool not found | **STOP EXECUTION** - display error below |
+
+### Blocking Error (STOP)
+
+If MCP is not available, display this message and **STOP the skill immediately**:
+
+```
+═══════════════════════════════════════════════════════════════
+  MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
+═══════════════════════════════════════════════════════════════
+
+  The SmartStack MCP server is required for this skill but
+  could not be reached.
+
+  To install:
+    claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
+
+  To verify:
+    /mcp:healthcheck
+
+  After installation, restart Claude Code and retry.
+
+═══════════════════════════════════════════════════════════════
+```
+
+**DO NOT** offer fallback modes, manual instructions, or degraded execution. The skill MUST stop.
+
+### Skills Requiring MCP
+
+| Skill | MCP Required | Reason |
+|-------|:---:|--------|
+| business-analyse | **YES** | Analysis, specification, validation |
+| application | **YES** | Navigation + code generation |
+| controller | **YES** | Controller scaffolding |
+| apex | **YES** | Generation + validation |
+| ralph-loop | **YES** | Iterative code generation |
+| validate | **YES** | Convention validation |
+| efcore | **YES** | Migration management |
+| review-code | **YES** | Code review |
+| gitflow | NO | Git operations only |
+| explore | NO | Code search only |
+| mcp | NO | Self-check skill |
+
 ## MCP Tools References
 
 ### Outils Core

package/templates/skills/application/steps/step-00-init.md

@@ -51,19 +51,43 @@ displayOrder: number
 parentPath: "context.application.module" (dot-separated)
 ```
 
-### 3. Validate MCP Availability
+### 3. MCP Prerequisite Check (BLOCKING)
 
-**CRITICAL:** Before proceeding, verify SmartStack MCP is available:
+**CRITICAL:** This check is **BLOCKING** - the skill cannot proceed without MCP.
+
+> See `_shared.md` → "MCP Prerequisite Guard (BLOCKING)" for the full pattern.
 
 ```
 Call: mcp__smartstack__validate_conventions
-Args: { checks: ["all"] }
+Args: { checks: ["tables"] }
+```
+
+**On success:** Set `mcp_available = true`, continue to Step 4.
+
+**On failure (STOP):**
+
+```
+═══════════════════════════════════════════════════════════════
+  MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
+═══════════════════════════════════════════════════════════════
+
+  The SmartStack MCP server is required for the application
+  skill but could not be reached.
+
+  To install:
+    claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
+
+  To verify:
+    /mcp:healthcheck
+
+  After installation, restart Claude Code and retry.
+
+═══════════════════════════════════════════════════════════════
 ```
 
-If MCP call fails:
-- Display warning: "SmartStack MCP not available"
-- Provide manual instructions instead of automated generation
-- Do NOT proceed with step files
+**DO NOT** offer manual instructions or degraded execution.
+**DO NOT** proceed with step files.
+**STOP the skill immediately.**
 
 ### 4. Build Full Path
 
@@ -144,7 +168,7 @@ descriptions:
 
 - Missing required parameters (ask user)
 - Invalid level detection (clarify with user)
-- MCP not available (provide manual instructions)
+- MCP not available (STOP - display install instructions)
 
 ---