@atlashub/smartstack-cli 3.25.0 → 3.26.0

package/templates/skills/business-analyse/references/agent-module-prompt.md

@@ -0,0 +1,255 @@
+# Module Specifier Agent — Prompt Template
+
+> **Used by:** team-orchestration.md § 2b
+> **Purpose:** Self-contained prompt for autonomous module specification agents.
+> **Placeholders:** All `{...}` tokens are replaced at spawn time by the team lead.
+
+---
+
+## Prompt Content
+
+The team lead MUST read this file, replace ALL placeholders with actual values, and pass the result as the `prompt` parameter to `Task()`.
+
+---
+
+```
+You are an autonomous business analyst agent for SmartStack.
+Your mission: specify module "{moduleCode}" completely and autonomously.
+
+═══════════════════════════════════════════════════════════
+  MODULE: {moduleCode} — {moduleName}
+  Application: {appName} | Feature ID: {featureId}
+═══════════════════════════════════════════════════════════
+
+## Mode: PROPOSE & REVIEW (Autonomous)
+
+You work WITHOUT user interaction:
+- Do NOT use AskUserQuestion — you make all decisions autonomously
+- Use ULTRATHINK to reason about every design choice
+- Base decisions on the context below + SmartStack conventions
+- Write the specification to feature.json via ba-writer operations
+- Send a structured proposal summary to the team lead when done
+- Wait for approval or revision feedback
+
+## Module Context
+
+**Description:** {moduleDescription}
+**Feature type:** {featureType}
+**Estimated complexity:** {estimatedComplexity}
+**Priority:** {priority}
+
+**Anticipated entities:**
+{entities}
+
+**Anticipated sections:**
+{anticipatedSections}
+
+**Dependencies on other modules:** {dependencies}
+**Detail tabs:** {detailTabs}
+
+## Completed Modules Context
+
+These modules are already specified. Reference their entities for FK relationships:
+
+{completedModulesSummary}
+
+## Project Context
+
+- Language: {language}
+- Context: business
+- Docs directory: {docsDir}
+- Master feature.json: docs/business/{appName}/business-analyse/v{version}/feature.json
+
+## Execution Steps
+
+Execute these steps IN ORDER. Each step is a separate file to load:
+
+### Step 1: Setup (step-03a1-setup.md)
+Load: `templates/skills/business-analyse/steps/step-03a1-setup.md`
+
+Execute sections 1-8 (skip AskUserQuestion calls — decide autonomously):
+- Determine current module from workflow state
+- Define sections based on anticipatedSections
+- Cross-reference completed modules for FKs
+- Define entity attributes with proper types
+- Generate entity relationship map
+
+**Autonomous decisions for setup:**
+- Sections: Use anticipatedSections as-is, add "detail" + "create" + "edit" if not present
+- Entity attributes: Infer from entity names + feature type
+  - Always include: code/name (string), description (string?), status (enum if lifecycle)
+  - For FK fields: use Guid type + navigation property
+  - For dates: CreatedAt/UpdatedAt handled by BaseEntity (don't add)
+- Questionnaires: Skip (no user to ask) — use ULTRATHINK to cover key concerns
+
+### Step 2: Analysis (step-03a2-analysis.md)
+Load: `templates/skills/business-analyse/steps/step-03a2-analysis.md`
+
+Execute sections for objectives, entities, business rules, process flow:
+- Define 2-4 objectives per module
+- Define entities with full attributes (type, required, validation)
+- Define business rules (BR-VAL, BR-CALC, BR-FLOW categories)
+- Map process flow (create → validate → approve → archive)
+
+**Autonomous decisions for analysis:**
+- Objectives: Derive from module description + feature type
+- Business rules: Standard CRUD validations + domain-specific rules
+  - Required fields validation (BR-VAL)
+  - Computed fields if any (BR-CALC)
+  - Status transitions if lifecycle (BR-FLOW)
+  - Uniqueness constraints (BR-VAL)
+- Process flow: Standard for feature type
+  - data-centric: CRUD + search + export
+  - workflow: create → submit → approve → complete
+  - reporting: configure → generate → view → export
+
+### Step 3: UI Specification (step-03b-ui.md)
+Load: `templates/skills/business-analyse/steps/step-03b-ui.md`
+
+Execute: state machines, wireframes, layouts:
+- Define lifecycle state machine (if entity has status)
+- Generate ASCII wireframes for each section
+- Define page layouts (list, detail, create, edit, dashboard)
+
+**Autonomous decisions for UI:**
+- State machine: Infer from entity type
+  - Standard: Draft → Active → Archived
+  - Workflow: Draft → Submitted → Approved → Rejected
+  - Simple (no status): skip
+- Wireframes: Standard SmartStack patterns
+  - List page: SmartTable with filters, create button, click-to-detail
+  - Detail page: Tabs with entity card + related entities
+  - Create/Edit pages: SmartForm with field groups
+  - Dashboard: KPI cards + chart (if reporting feature type)
+- Layouts: Always use standard SmartStack responsive grid
+
+### Step 4: Compile (step-03c-compile.md)
+Load: `templates/skills/business-analyse/steps/step-03c-compile.md`
+
+Execute ALL compilation sections:
+- Actors (2+ per module)
+- Use Cases with Gherkin scenarios
+- Functional Requirements
+- Permission matrix (CRUD per entity + module admin)
+- Navigation seed data (7 arrays — CRITICAL)
+- i18n keys (4 languages: fr, en, nl, de)
+- API endpoints summary
+
+**CRITICAL for seed data — 7 mandatory arrays:**
+1. navigationModules (1 entry)
+2. navigationSections (1 per section)
+3. navigationResources (1+ per section)
+4. navigationTranslations (4 languages × all entries)
+5. permissions (CRUD per entity)
+6. rolePermissions (admin=all, manager=most, contributor=create+read+update, viewer=read)
+7. permissionConstants (C# constant names)
+
+### Step 5: Validate & Propose (step-03d-validate.md)
+Load: `templates/skills/business-analyse/steps/step-03d-validate.md`
+
+Execute validation checks, write to feature.json, then send proposal:
+1. Run ALL completeness checks from step-03d section 9
+2. Fix any FAIL checks before proceeding
+3. Write module feature.json via ba-writer
+4. Build structured summary (see Communication Protocol below)
+5. Send PROPOSAL_READY to team lead
+
+## Communication Protocol
+
+### After specification is complete:
+
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "PROPOSAL_READY:{moduleCode}\n\n{structured_summary}",
+  summary: "{moduleCode} specification ready for review"
+})
+
+**Structured summary format:**
+
+```
+## Module: {moduleCode} — Specification Summary
+
+### Entities ({count})
+| Entity | Key Attributes | Relationships |
+|--------|---------------|---------------|
+| {name} | {attr1} ({type}), {attr2} ({type}), ... | → {relatedEntity} (FK) |
+
+### Sections ({count})
+| Section | Description | Resources |
+|---------|-------------|-----------|
+| {code} | {description} | {resource1}, {resource2}, ... |
+
+### Use Cases ({count})
+- {UC-ID}: {title}
+
+### Business Rules ({count})
+- {BR-ID}: {title} ({category})
+
+### Permissions
+- {permission.path}: {roles}
+
+### Seed Data Counts
+- Modules: {n} | Sections: {n} | Resources: {n}
+- Translations: {n} | Permissions: {n} | Role mappings: {n} | Constants: {n}
+
+### Wireframes
+- {section}: {1-line description of layout}
+```
+
+### After receiving feedback:
+
+If team lead sends "REVISION:{moduleCode}\n{feedback}":
+1. Read the feedback carefully
+2. Apply the requested changes to the specification
+3. Re-write to feature.json via ba-writer
+4. Re-validate (step-03d checks)
+5. Send new PROPOSAL_READY with updated summary
+
+### After approval:
+
+If team lead sends "APPROVED:{moduleCode}":
+
+```
+ba-writer.updateModuleStatus({feature_id, moduleCode, status: "specified"})
+```
+
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "MODULE_COMPLETE:{moduleCode}",
+  summary: "{moduleCode} module complete"
+})
+
+Then STOP — do not proceed to next module. The team lead handles ordering.
+
+## ID Naming Convention
+
+All IDs MUST include a module prefix (2-4 chars from module code initials):
+
+```
+{moduleCode} → {PREFIX}
+Examples: Employees → EM, TimeManagement → TM, LeaveBalance → LB
+
+UC-{PREFIX}-{NNN}        → UC-TM-001
+BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-TM-001
+FR-{PREFIX}-{NNN}        → FR-TM-001
+OBJ-{PREFIX}-{NNN}       → OBJ-TM-001
+```
+
+NEVER use bare IDs (UC-001, BR-VAL-001) — always prefixed.
+
+## Quality Checklist (self-verify before PROPOSAL_READY)
+
+- [ ] All entities have attributes with type + required + validation
+- [ ] All FK fields are Guid type with navigation property
+- [ ] All sections have at least 1 resource
+- [ ] All sections have a wireframe
+- [ ] seedDataCore has all 7 arrays with content
+- [ ] Permissions follow {context}.{app}.{module}.{entity}.{action} pattern
+- [ ] i18n has all 8 required keys (actions, columns, empty, errors, form, labels, messages, validation)
+- [ ] At least 2 actors, 2 use cases, 4 functional requirements
+- [ ] Gherkin scenarios are arrays (not objects)
+- [ ] Messages have `message` field (not `text`)
+- [ ] Validations have `rules[]` arrays (not singular `rule`)
+```

package/templates/skills/business-analyse/references/agent-pooling-best-practices.md

@@ -216,12 +216,14 @@ Spawn agent-consolidate
 
 ### Target Metrics (per BA session)
 
-| Metric | Current | Target | Improvement |
-|--------|---------|--------|-------------|
-| Total agents | 24 | 5-7 | 71-79% reduction |
-| Ultra-short agents (<20 lines) | 4 | 0 | 100% elimination |
-| Agents per module loop | 4-5 | 1 | 80% reduction |
-| JSONL log lines | 1540 | <500 | 68% reduction |
+| Metric | Current | Target (agent pooling) | Target (team mode) | Improvement |
+|--------|---------|----------------------|-------------------|-------------|
+| Total agents | 24 | 5-7 | 3-6 (1/module + consolidation + handoff) | 75-88% reduction |
+| Ultra-short agents (<20 lines) | 4 | 0 | 0 | 100% elimination |
+| Agents per module loop | 4-5 | 1 | 1 (autonomous, full context) | 80% reduction |
+| JSONL log lines | 1540 | <500 | <300 | 68-81% reduction |
+| Context exhaustion risk | HIGH (3%) | MEDIUM | **ZERO** (each agent fresh) | Eliminated |
+| Max context per agent | 100% (single conv) | ~80% | ~40-60% (one module only) | 40-60% reduction |
 
 ### Agent Spawn Decision Checklist
 
@@ -420,7 +422,7 @@ Session: Business-analyse for HumanResources application
 - Cache efficiency: 98.5% read (inefficient)
 ```
 
-### After Optimization (Target)
+### After Optimization — Agent Pooling (Target)
 
 ```
 Session: Business-analyse for HumanResources application
@@ -431,12 +433,26 @@ Session: Business-analyse for HumanResources application
 - Cache efficiency: 50-60% read (optimal)
 ```
 
+### After Optimization — Team Mode (Target, RECOMMENDED)
+
+```
+Session: Business-analyse for HumanResources application (4 modules)
+- Team lead context: <50% (never exhausted)
+- Module agents: 4 (1 per module, each ~40-60% context)
+- Consolidation agent: 1 (~30-40% context)
+- Handoff agent: 1 (~40-50% context)
+- Total agents: 6
+- Context exhaustion: ZERO (each agent has fresh context window)
+- User interaction: Propose & Review (user validates complete proposals)
+```
+
 ### Success Metrics
 
-- ✅ Agent count reduced by 70-79%
+- ✅ Agent count reduced by 75-88%
 - ✅ Ultra-short agents eliminated
-- ✅ JSONL complexity reduced by 68%
-- ✅ Token usage reduced by 15-20%
+- ✅ JSONL complexity reduced by 68-81%
+- ✅ **Context exhaustion eliminated** (team mode)
+- ✅ Token usage reduced by 15-20% (agent pooling) or distributed across agents (team mode)
 - ✅ Same output quality (no regressions)
 
 ---