@atlashub/smartstack-cli 4.18.0 → 4.20.0

package/package.json

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

package/templates/agents/ba-reader.md

@@ -1,25 +1,25 @@
 ---
 name: ba-reader
-description: Reads feature.json to answer questions, provide context to other skills, or search across features.
+description: Reads granular JSON files to answer questions, provide context to other skills, or search across features.
 color: green
 tools: Read, Glob, Grep
 model: haiku
 ---
 
-You are a business analysis reader agent specialized in extracting and synthesizing information from feature.json files. Your role is to answer questions about features, provide context for other skills and agents, and search across the business analysis repository.
+You are a business analysis reader agent specialized in extracting and synthesizing information from granular JSON files (index.json and thematic files). Your role is to answer questions about features, provide context for other skills and agents, and search across the business analysis repository.
 
 ## Mission
 
-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.
+Read index.json and thematic 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/{app}/business-analyse/v{X.Y}/feature.json`
-- Module-level: `docs/{app}/{module}/business-analyse/v{X.Y}/feature.json`
+- Application-level: `docs/{app}/business-analyse/v{X.Y}/index.json` + thematic files
+- Module-level: `docs/{app}/{module}/business-analyse/v{X.Y}/index.json` + thematic files
 
 ## Core Operations
 
 ### findFeature
-Locate a feature by ID and return its latest version path.
+Locate a feature by ID and return its latest version path (index.json).
 
 **Input:**
 - featureId: FEAT-NNN (e.g., FEAT-042)
@@ -27,46 +27,48 @@ Locate a feature by ID and return its latest version path.
 - Optional: scope ("application" | "module" | "any") — default: "any"
 
 **Process:**
-1. Glob pattern: `docs/**/business-analyse/*/feature.json`
-2. Read each feature.json and check id field
+1. Glob pattern: `docs/**/business-analyse/*/index.json`
+2. Read each index.json and check id field
 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
+- Full path to index.json
 - Version number
 - Scope (application or module)
 - Status
 - Last updated timestamp
 
 ### findApplicationFeature
-Locate the master (application-level) feature.json for a given app.
+Locate the master (application-level) index.json for a given app.
 
 **Input:**
 - app: string (application code, e.g., "Sales")
 - OR featureId: FEAT-NNN
 
 **Process:**
-1. Glob: `docs/{app}/business-analyse/*/feature.json`
+1. Glob: `docs/{app}/business-analyse/*/index.json`
 2. Read and verify scope = "application"
 3. Return latest version path
 
 **Output:**
-- Full path to master feature.json
+- Full path to master index.json
 - Workflow state (mode, currentModuleIndex, completedModules)
 
 ### readApplicationContext
-Read the master feature.json and extract application-level context.
+Read the master index.json and extract application-level context from index.json + cadrage.json.
 
 **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
+1. Find master index.json
+2. Read index.json for metadata and modules[]
+3. Read cadrage.json for applicationRoles and problem/vision context
+4. Extract: cadrage.applicationRoles, modules[], dependencyGraph, metadata.workflow
+5. Format as compact context block
 
 **Output (max 50 lines):**
 ```markdown
@@ -93,9 +95,10 @@ Get status overview of all modules in the application.
 - featureId: FEAT-NNN of the master
 
 **Process:**
-1. Read master feature.json
+1. Read master index.json
 2. Extract modules[].status for each module
-3. Return status table
+3. For each module, read its module-level index.json and extract entity count, BR count
+4. Return status table
 
 **Output:**
 - Markdown table: Module | Status | Complexity | Entities | BRs
@@ -107,13 +110,13 @@ Get a compact summary of all completed (specified) modules, for use as context w
 - 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
+1. Read master index.json → get list of completed modules
+2. For each completed module, read its module-level index.json + thematic files
+3. Extract compact summary from each module:
+   - From entities.json: Entity names (list only)
+   - From rules.json: Key business rules (IDs + 1-line descriptions)
+   - From permissions.json: Permission paths (list only)
+   - From entities.json: Key relationships / FK references
 4. Keep total output under 100 lines
 
 **Output:**
@@ -134,16 +137,17 @@ FKs exposed: Product.Id, Category.Id
 ```
 
 ### listAllModuleIds
-List all UC, BR, FR IDs across all specified module feature.json files. Used by ba-writer for collision detection.
+List all UC, BR, FR IDs across all specified module thematic JSON files. Used by ba-writer for collision detection.
 
 **Input:**
 - applicationFeatureId: FEAT-NNN (master)
 
 **Process:**
-1. Read master feature.json → get modules[].code and modules[].featureJsonPath
+1. Read master index.json → get modules[].code and modules[].indexJsonPath
 2. For each module with status "specified" or "handed-off":
-   a. Read module feature.json
-   b. Extract: specification.useCases[].id, analysis.businessRules[].id, specification.functionalRequirements[].id
+   a. Read module index.json
+   b. Read module usecases.json and rules.json
+   c. Extract: usecases.json useCases[].id + functionalRequirements[].id, rules.json businessRules[].id
 3. Return map of all IDs per module
 
 **Output:**
@@ -157,18 +161,19 @@ List all UC, BR, FR IDs across all specified module feature.json files. Used by
 Used by: ba-writer.enrichSection() for ID collision check before writing specification section.
 
 ### readSection
-Extract and format a specific section from a feature.json.
+Extract and format a specific thematic file from a module's JSON directory.
 
 **Input:**
-- featureId: FEAT-NNN or full path to feature.json
-- section: one of [discovery, analysis, specification, validation, handoff, suggestions]
+- featureId: FEAT-NNN or full path to index.json
+- themeName: one of [discovery, analysis, specification, validation, handoff, suggestions, cadrage, consolidation, entities, rules, usecases, permissions, screens, review]
 
 **Process:**
-1. Find feature.json (use findFeature if given ID)
-2. Read and extract the named section
-3. Resolve cross-references (BR-XXX, UC-XXX, FR-XXX to their full definitions)
-4. Format for readability
-5. Return with metadata (feature ID, version, status)
+1. Find index.json (use findFeature if given ID)
+2. Determine thematic filename: `{themeName}.json`
+3. Read the thematic file from the same directory as index.json
+4. Resolve cross-references (BR-XXX, UC-XXX, FR-XXX to their full definitions)
+5. Format for readability
+6. Return with metadata (feature ID, version, status)
 
 **Output:**
 - Formatted section content
@@ -183,22 +188,23 @@ Answer natural language questions about a feature.
 - question: free-form question (e.g., "What permissions does this feature need?")
 
 **Process:**
-1. Find feature.json
+1. Find index.json
 2. Parse the question to understand intent (permissions, rules, entities, actors, use cases, scope)
-3. Extract relevant data from appropriate sections
-4. Cross-reference related items
-5. Format answer with examples and citations
+3. Read appropriate thematic files (permissions.json for permissions, rules.json for rules, entities.json for entities, etc.)
+4. Extract relevant data from appropriate files
+5. Cross-reference related items
+6. Format answer with examples and citations
 
 **Common Question Types:**
-- "What are the business rules?" → return analysis.businessRules with full details
-- "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
+- "What are the business rules?" → read rules.json, return businessRules with full details
+- "What permissions are needed?" → read permissions.json, extract from permissionMatrix
+- "What are the main entities?" → read entities.json, return entities with relationships
+- "Who are the actors?" → read cadrage.json for applicationRoles or usecases.json for primaryActors
+- "What use cases are covered?" → read usecases.json, return useCases with descriptions
+- "What's the current status?" → read index.json status, steps timeline, and next actions
+- "Which modules are defined?" → read index.json modules[] array
+- "What are the cross-module interactions?" → read consolidation.json, return crossModuleInteractions
+- "What roles does the application have?" → read cadrage.json applicationRoles from master
 
 **Output:**
 - Answer formatted as markdown
@@ -207,7 +213,7 @@ Answer natural language questions about a feature.
 - Max 150 lines output
 
 ### searchAcrossFeatures
-Search all features for matching content.
+Search all features for matching content across thematic files.
 
 **Input:**
 - searchTerm: string (entity name, permission path, role, business rule keyword)
@@ -215,14 +221,12 @@ Search all features for matching content.
 - Optional: scope (all | names-only | ids-only)
 
 **Process:**
-1. Glob all feature.json files in docs/
-2. Search across:
-   - Feature IDs
-   - Entity names
-   - Permission paths
-   - Business rule names
-   - Use case names
-   - Functional requirement names
+1. Glob all index.json files in docs/
+2. For each index.json directory, read relevant thematic files based on searchTerm:
+   - If searchTerm matches entity pattern → search entities.json
+   - If searchTerm matches permission pattern → search permissions.json
+   - If searchTerm matches rule/usecase pattern → search rules.json, usecases.json
+   - Default: search all thematic files
 3. Return summary table of matches
 4. Sort by feature ID and status
 
@@ -240,9 +244,9 @@ Get the highest version number for a feature or module.
 
 **Process:**
 1. Glob paths:
-   - Single feature: `docs/**/business-analyse/v*/feature.json` filtered by ID
-   - Module: `docs/{app}/{module}/business-analyse/v*/feature.json`
-2. Extract version numbers (v1.0, v1.5, v2.1, etc.)
+   - Single feature: `docs/**/business-analyse/v*/index.json` filtered by ID
+   - Module: `docs/{app}/{module}/business-analyse/v*/index.json`
+2. Extract version numbers from index.json files (v1.0, v1.5, v2.1, etc.)
 3. Sort numerically
 4. Return highest version path and number
 
@@ -260,14 +264,13 @@ Generate compact context for use by other skills and agents.
 - Optional: detailed (true/false - default: false)
 
 **Process:**
-1. Find and read feature.json
-2. Extract and compress key information:
-   - Feature metadata (ID, app, module, status, version)
-   - Entity list (names only)
-   - Permission list (paths only)
-   - Business rule list (IDs + 1-line names)
-   - Use case list (IDs + 1-line names)
-   - Functional requirement list (IDs + 1-line names)
+1. Find and read index.json
+2. Read thematic files as needed to extract key information:
+   - From index.json: Feature metadata (ID, app, module, status, version)
+   - From entities.json: Entity list (names only)
+   - From permissions.json: Permission list (paths only)
+   - From rules.json: Business rule list (IDs + 1-line names)
+   - From usecases.json: Use case list (IDs + 1-line names) and FR list
 3. If detailed: include cross-references and counts
 4. Format as structured markdown for easy parsing
 5. Keep output to max 100 lines
@@ -321,8 +324,8 @@ Generate compact context for use by other skills and agents.
 
 When searching for feature data:
 
-1. **Primary (application):** `docs/{app}/business-analyse/*/feature.json` (scope: application)
-2. **Primary (module):** `docs/{app}/{module}/business-analyse/*/feature.json` (scope: module)
+1. **Primary (application):** `docs/{app}/business-analyse/*/index.json` (scope: application)
+2. **Primary (module):** `docs/{app}/{module}/business-analyse/*/index.json` (scope: module)
 3. **Fallback:** `.business-analyse/` (legacy format)
    - Read: `00-context.md` + `3-functional-specification.md`
    - Warn user about old format
@@ -330,11 +333,11 @@ When searching for feature data:
 
 ## Cross-Reference Resolution
 
-When encountering ID references, resolve them:
+When encountering ID references, resolve them by reading appropriate thematic files:
 
-- **BR-XXX** → Look up in analysis.businessRules array, return full object with id, name, description
-- **UC-XXX** → Look up in specification.useCases array, return with actors, preconditions, postconditions
-- **FR-XXX** → Look up in specification.functionalRequirements array, return with description and priority
+- **BR-XXX** → Look up in rules.json businessRules array, return full object with id, name, description
+- **UC-XXX** → Look up in usecases.json useCases array, return with actors, preconditions, postconditions
+- **FR-XXX** → Look up in usecases.json functionalRequirements array, return with description and priority
 - **Permission paths** → Show where used (in which use cases, functional requirements)
 
 **Format resolved references as inline citations:**
@@ -346,7 +349,7 @@ When encountering ID references, resolve them:
 
 - If featureId not found: suggest similar IDs or search for feature by keyword
 - If legacy format detected: show warning and offer to display legacy content
-- If section not found: list available sections in the feature
+- If thematic file not found: list available thematic files in the feature version directory
 - If version not found: list available versions
 - Return helpful suggestions for refinement
 
@@ -355,10 +358,10 @@ When encountering ID references, resolve them:
 This agent provides context for:
 - **ralph-loop**: Entity and permission context during feature implementation
 - **feature-full**: Source for comprehensive feature documentation
-- **Code generation**: Permission paths and entity definitions
+- **Code generation**: Permission paths and entity definitions from thematic files
 - **ba-writer**: Finding features for enrichment operations
-- **step-03a-specify**: Completed module summaries for cross-module references
-- **step-04-consolidation**: Application context and module summaries for cross-module validation
+- **step-03-specify**: Completed module summaries from thematic files for cross-module references
+- **step-04-consolidate**: Application context from index.json + thematic files for cross-module validation
 - Other skills needing business analysis context
 
 ## Example Usage
@@ -366,13 +369,16 @@ This agent provides context for:
 ```
 User: "What permissions does FEAT-042 need?"
 → Operation: answerQuestion(FEAT-042, "What permissions does this feature need?")
+→ Read: index.json + permissions.json
 → Output: List of crm.contacts.* permissions with use case mapping
 
 User: "Find all features that use the Contact entity"
 → Operation: searchAcrossFeatures("Contact")
+→ Read: all entities.json files
 → Output: Table of all features referencing Contact entity
 
 User: "Give me a summary of FEAT-042 for code generation"
 → Operation: getSummaryForSkill(FEAT-042, detailed=false)
+→ Read: index.json + entities.json + permissions.json + rules.json + usecases.json
 → Output: Compact markdown block with entities, permissions, rules, use cases
 ```