@atlashub/smartstack-cli 2.3.0 → 2.5.0

package/templates/skills/mcp/SKILL.md

@@ -73,7 +73,7 @@ mcp__smartstack__validate_conventions({
 
    Actions:
    1. Verify MCP is configured: claude mcp list
-   2. Re-register: claude mcp add smartstack -- npx -p @atlashub/smartstack-cli smartstack-mcp
+   2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
    3. Restart Claude Code
 ```
 
@@ -150,7 +150,7 @@ MCP HEALTH CHECK ❌
 
   Troubleshooting:
   1. Check registration: claude mcp list
-  2. Re-register: claude mcp add smartstack -- npx -p @atlashub/smartstack-cli smartstack-mcp
+  2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
   3. Update CLI: npm update -g @atlashub/smartstack-cli
   4. Restart Claude Code
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/templates/skills/business-analyse/steps/step-01-analyse.md

@@ -1,523 +0,0 @@
----
-name: step-01-analyse
-description: Merged Discovery + Analysis - Elicitation, business rules, entities, proactive suggestions
-next_step: steps/step-02-specify.md
----
-
-## YOUR TASK:
-
-Execute combined discovery and analysis: elicit requirements using ULTRATHINK mode, formalize business rules and entities, and suggest complementary modules.
-
-> **ULTRATHINK MODE:**
-> - Consider ALL edge cases before formulating questions
-> - Challenge EVERY stakeholder assumption
-> - Anticipate UNEXPRESSED needs
-> - Validate completeness before proceeding
-> - DO NOT accept vague answers
-> - Extract IMPLICIT rules from discovery responses
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Read Current State
-
-Use **ba-reader** agent to read feature.json:
-- `feature_id`, `application_name`, `module_name`, `use_case`, `language`, `economy_mode`
-- Determine if delta mode (refactoring) or new feature
-
-Use **ba-writer** agent to update feature.json:
-- Set `metadata.steps.analyse.status = "in-progress"`
-
-**Language Config:**
-All AskUserQuestion calls must use `{language}` (default: fr).
-See `_shared.md` for language configuration.
-
-> **⚠️ BRANDING:** Never use "SmartStack" in user-facing communication.
-> Use "la plateforme", "l'application", or "le système" instead.
-
----
-
-### 2. Determine Feature Type (for use_case = "new" or "micro")
-
-Analyze `feature.description` to classify:
-
-| Type | Keywords | Categories to Load |
-|------|----------|------------------|
-| **Data-centric** | management, CRUD, entity, data | 01, 02, 03, 04, 06, 11 |
-| **Integration** | API, sync, import, export, external | 01, 02, 03, 05, 06 |
-| **UI-centric** | screen, form, dashboard, interface | 01, 02, 03, 06, 07 |
-| **Workflow** | process, validation, workflow, steps | 01, 02, 03, 06, 09 |
-| **Reporting** | report, export, statistics, KPI | 01, 02, 03, 04, 08 |
-| **Full-module** | module, complete, feature | ALL |
-| **Micro** | (from -m flag) | 01, 02, 03, 06 (minimal) |
-
-Use **ba-writer** to set `metadata.featureType = {feature_type}`
-
----
-
-### 3. Codebase Pre-Research (3 Phases)
-
-> **RULE: Explore BEFORE asking questions. Informed questions > generic questions.**
-
-**Phase 3a: MCP SmartStack (if available)**
-
-Call MCP tools (if not already done in step-00):
-- `mcp__smartstack__analyze_extension_points` → discover existing modules/entities
-- `mcp__smartstack__api_docs` → check existing API
-- `mcp__smartstack__validate_conventions` → validate module naming
-
-**Phase 3b: Parallel agents (if NOT economy_mode)**
-
-```
-Agent 1: "Search for existing domain entities in {application_name}.
-  List entities, attributes, relationships."
-
-Agent 2: "Search for integrations, services, SignalR, background jobs
-  that {module_name} might connect with."
-
-Agent 3: "Search for existing page patterns in {application_name}
-  (if UI-centric). List structures, components, navigation."
-```
-
-**Phase 3c: Economy mode**
-
-Use Glob/Grep directly:
-- Find 2-3 reference modules
-- Read key files to understand patterns
-- Extract domain context
-
-**Store findings:**
-Use **ba-writer** to add to `discovery.codebaseContext`:
-- Existing modules in {application_name}
-- Reusable entities and patterns
-- Potential integration points
-- RBAC patterns observed
-
----
-
-### 4. Load Questionnaire Categories (Progressive)
-
-**ALWAYS load (core):**
-```
-questionnaire/01-context.md      # ~50 lines
-questionnaire/02-stakeholders.md # ~70 lines
-questionnaire/03-scope.md        # ~60 lines
-questionnaire/06-security.md     # ~70 lines
-```
-
-**Conditional (based on feature_type):**
-```
-Data-centric OR Full → questionnaire/04-data.md, 11-data-lifecycle.md
-Integration OR Full → questionnaire/05-integrations.md
-UI-centric OR Full → questionnaire/07-ui.md
-Reporting OR Critical → questionnaire/08-performance.md
-Workflow OR Constraints → questionnaire/09-constraints.md
-New module → questionnaire/12-migration.md, 13-cross-module.md
-```
-
-**Micro mode shortcut:**
-Load ONLY questionnaire/01-context.md (minimal 4 questions):
-- What entity/feature?
-- What fields/attributes?
-- What values/states?
-- Who can view/edit?
-- Any business rules?
-- Validation: correct summary?
-
-**Delta mode (refactoring):**
-Load only categories relevant to the CHANGE description.
-Skip categories already answered in previous version.
-
----
-
-### 5. Interactive Elicitation
-
-> **RULE: Use `AskUserQuestion` for EVERY question batch. NEVER list questions as text.**
-> **RULE: Question field does NOT support markdown. Use direct output for summaries.**
-
-**Flow per category:**
-
-1. Load questionnaire file for the category
-2. Ask batches of max 4 questions via AskUserQuestion with predefined options
-3. Process answers → apply ULTRATHINK + 5 Elicitation Techniques (see `_shared.md`)
-4. If vague → follow-up with targeted probes
-5. After category: display summary as direct text output (supports markdown)
-6. Ask validation with SHORT question: "Is this summary correct?"
-7. If corrections needed → apply follow-ups
-8. Move to next category
-
-**ULTRATHINK checkpoints during elicitation:**
-- After Q1: If answer is solution-oriented → reframe to problem
-- After Q2: If only 1-2 stakeholder types → probe for hidden users
-- After Q3: If > 5 Must-Have → ask to prioritize implementation order
-- If answer is vague → apply Technique 3 (Concrete Scenario)
-- If any answer contains permission attributes → flag as RBAC violation
-
-**Reformulation loop (after each category):**
-
-Step 1: Display summary as direct text (supports markdown):
-```
-## Synthèse - {category_name}
-
-- **Point 1:** {summary}
-- **Point 2:** {summary}
-```
-
-Step 2: Ask validation with SHORT question via AskUserQuestion:
-```
-question: "Cette synthèse est-elle correcte ?"
-options: [
-  { label: "Correct" },
-  { label: "Partiellement" },
-  { label: "Incorrect" }
-]
-```
-
-- **Correct** → proceed to next category
-- **Partiellement** → ask: "Quelles corrections ?"
-- **Incorrect** → re-ask with refined questions
-
----
-
-### 6. Business Rules Extraction (from discovery + ULTRATHINK)
-
-Scan all elicitation answers for implicit and explicit rules:
-
-**Sources to analyze:**
-- Scope constraints (category 03)
-- Data validations (category 04)
-- Security restrictions (category 06)
-- Process conditions from flow descriptions
-- Stakeholder-mentioned constraints
-
-**Rule categories:**
-| Category | Example | BR-ID Pattern |
-|----------|---------|---|
-| Validation | "Email must be unique" | BR-VAL-XXX |
-| Calculation | "Total = sum of lines" | BR-CALC-XXX |
-| Workflow | "Manager must approve > 1000$" | BR-WF-XXX |
-| Security | "Only admin can delete" | BR-SEC-XXX |
-| Data | "Created date is immutable" | BR-DATA-XXX |
-
-**Rule formalization:**
-
-For each identified rule, create:
-```json
-{
-  "id": "BR-{category}-NNN",
-  "name": "Rule name",
-  "category": "validation|calculation|workflow|security|data",
-  "statement": "IF {condition} THEN {result} ELSE {alternative}",
-  "priority": "must|should|could",
-  "conditions": ["condition 1", "condition 2"],
-  "examples": [
-    { "input": "example input", "expected": "example output" }
-  ],
-  "testability": "How to verify this rule"
-}
-```
-
-**ULTRATHINK checkpoint:**
-- Each rule is testable?
-- Rules don't contradict each other?
-- No rule is solution-oriented (HOW instead of WHAT)?
-- Priority aligns with scope (Must-Have → must, etc.)?
-
-Use **ba-writer** to add all rules to `analysis.businessRules[]`
-
----
-
-### 7. Business Objectives Extraction
-
-From discovery context, formalize measurable objectives:
-
-```json
-{
-  "id": "OBJ-NNN",
-  "objective": "description",
-  "metric": "what to measure",
-  "target": "target value"
-}
-```
-
-Examples:
-- OBJ-001: Reduce manual data entry time by 50%
-- OBJ-002: Achieve 95% first-pass accuracy
-- OBJ-003: Enable 100% of stakeholders to access real-time KPIs
-
-Use **ba-writer** to add to `analysis.businessObjectives[]`
-
----
-
-### 8. Entity Definition - Business View (NO technical fields)
-
-From data questions and scope, define entities:
-
-**CRITICAL RULES:**
-- Business attributes ONLY (NO Id, TenantId, CreatedBy, UpdatedBy, etc.)
-- NO role attributes (User.Role, User.IsAdmin, User.AccessLevel)
-- RBAC is separate (step-02)
-- Relationships: 1:1, 1:N, N:M
-
-**Per entity, document:**
-```json
-{
-  "name": "EntityName (PascalCase)",
-  "description": "Business description",
-  "businessAttributes": [
-    { "name": "field", "type": "string", "required": true, "description": "meaning" }
-  ],
-  "relationships": [
-    { "name": "RelationshipName", "cardinality": "1:N", "with": "OtherEntity" }
-  ]
-}
-```
-
-**ULTRATHINK checkpoint:**
-- All entities from discovery captured?
-- Relationships complete?
-- No orphan entities?
-- **NO RBAC CHECK:** No role/permission/access-level as attribute?
-
-If permission attributes detected → FLAG error: "RBAC violation detected in entity {name}. Roles belong in Permission Matrix (step-02), not data model."
-
-Use **ba-writer** to add to `analysis.entities[]`
-
----
-
-### 9. Process Flow Modeling
-
-Model the main business flow:
-
-```
-Entry Points → [Decision Points] → [Actions/Validations] → Exit Points
-   ↓              ↓                      ↓                    ↓
-  Trigger      Link to BR-WF rules    Link to BR-VAL      Success/Failure
-```
-
-For each decision point, link to relevant BR-WF rules.
-Document alternative flows (error paths, exceptions).
-
-Example structure:
-```
-1. User submits request → BR-VAL-001 (validation)
-   ├─ Valid → BR-WF-001 (workflow: awaiting approval)
-   │  └─ Manager approves → BR-WF-002 (accept)
-   │     └─ Request processed
-   └─ Invalid → BR-VAL-002 (error: required field missing)
-      └─ User corrected
-```
-
-Use **ba-writer** to add to `analysis.processFlow` (text or ASCII diagram)
-
----
-
-### 10. Integrations & Cross-Module Impact
-
-From discovery, identify:
-
-| System | Direction | Data | Frequency | Format |
-|--------|-----------|------|-----------|--------|
-| {system} | In/Out/Bi | {data} | Real-time/Batch | JSON/CSV/API |
-
-For each integration:
-- Data format expected
-- Error handling strategy
-- Fallback behavior
-
-Document cross-module dependencies:
-- Which existing entities are referenced?
-- Which modules depend on this module?
-
-Use **ba-writer** to add to `analysis.integrations[]` and `analysis.crossModuleImpact`
-
----
-
-### 11. Proactive Suggestions (NEW - skip for micro mode)
-
-After scope and entities are defined:
-
-1. Load `patterns/suggestion-catalog.md` (if available)
-2. Match module type against catalog patterns
-3. Present via AskUserQuestion:
-
-```json
-{
-  "question": "Based on your {module} module, I suggest complementary additions. Which interest you?",
-  "header": "Suggestions",
-  "options": [
-    { "label": "{Suggestion 1}", "description": "{reason}" },
-    { "label": "{Suggestion 2}", "description": "{reason}" },
-    { "label": "None", "description": "No additional modules needed" }
-  ],
-  "multiSelect": true
-}
-```
-
-Examples (for each module type):
-- **Data-centric:** Bulk import, Audit trail, Export templates, Archive strategy
-- **Integration:** Error recovery, Health monitoring, Retry policy, Logging
-- **UI-centric:** Mobile-responsive design, Accessibility audit, Dark mode, Offline support
-- **Workflow:** Escalation rules, SLA tracking, Approval chains, Notifications
-- **Reporting:** Scheduled exports, Data freshness, Custom dashboards, Mobile reports
-
-For each accepted suggestion:
-```json
-{
-  "suggestion": "...",
-  "description": "...",
-  "acceptedStatus": true,
-  "impactOnTimeline": "{days if any}",
-  "linkedRules": ["BR-IDs affected"]
-}
-```
-
-Use **ba-writer** to add to `analysis.suggestions[]`
-
----
-
-### 12. Risk Analysis
-
-Identify risks from elicitation answers (skip for micro mode):
-
-Ask via AskUserQuestion:
-
-```json
-{
-  "question": "Quels risques métier identifiez-vous ?",
-  "options": [
-    { "label": "Adoption", "description": "Users might not adopt the module" },
-    { "label": "Data quality", "description": "Migration of existing data problematic" },
-    { "label": "Process gaps", "description": "Current process is misunderstood or will change" },
-    { "label": "Dependencies", "description": "Depends on another module not ready" }
-  ],
-  "multiSelect": true
-}
-```
-
-For each identified risk, classify:
-
-| Probability | Impact | Priority |
-|---|---|---|
-| High | High | **Critical** — mitigation required |
-| High | Low | **Medium** — monitor |
-| Low | High | **Medium** — contingency plan |
-| Low | Low | **Low** — accept |
-
-Store each risk:
-```json
-{
-  "id": "RISK-NNN",
-  "type": "business|technical|organizational",
-  "description": "...",
-  "probability": "high|medium|low",
-  "impact": "high|medium|low",
-  "priority": "critical|medium|low",
-  "mitigation": "..."
-}
-```
-
-Use **ba-writer** to add to `discovery.risks[]`
-
----
-
-### 13. Write to feature.json
-
-Use **ba-writer** agent to enrich:
-- `discovery` section: problem, asIs, toBe, trigger, stakeholders, scope, risks, codebaseContext, openQuestions
-- `analysis` section: objectives, businessRules, entities, processFlow, integrations, crossModuleImpact, dataLifecycle, suggestions
-- Update `metadata.steps.analyse.status = "completed"`
-- **Initialize changelog** with first entry:
-
-```json
-{
-  "changelog": [
-    {
-      "step": "step-01-analyse",
-      "timestamp": "2025-02-01T09:00:00Z",
-      "changes": [
-        "Discovery: {stakeholder_count} stakeholders, {scope_must} must-haves",
-        "Analysis: {br_count} business rules, {entity_count} entities, {obj_count} objectives",
-        "Suggestions: {accepted_count}/{total_count} accepted",
-        "Risks: {risk_count} identified ({critical_count} critical)"
-      ]
-    }
-  ]
-}
-```
-
----
-
-### 14. Display Summary and Load Next Step
-
-**Display:**
-
-```
-ANALYSE - {feature_id}
-├── Status: analysed
-├── Feature Type: {feature_type}
-├── Stakeholders: {count}
-├── Scope: {must} Must, {should} Should, {could} Could
-├── Business Rules: {br_count}
-├── Business Objectives: {obj_count}
-├── Entities: {entity_count}
-├── Integrations: {integration_count}
-├── Risks: {risk_count} ({critical_count} critical)
-├── Suggestions: {accepted}/{total}
-├── feature.json: {location}
-└── Next: step-02-specify.md
-```
-
-Load next step:
-```
-Read and execute: steps/step-02-specify.md
-```
-
----
-
-## OUTPUT FORMAT:
-
-This step enriches `feature.json` with:
-- `discovery` section: complete elicitation findings
-- `analysis` section: rules, objectives, entities, flows, integrations, suggestions
-- Status: draft → analysed
-
-**Context reduction strategy:**
-- Use feature.json as single source of truth
-- Load questionnaires progressively (max 150-200 lines at a time)
-- Use agents (ba-reader, ba-writer) to avoid re-reading
-
----
-
-## ERROR HANDLING:
-
-**If user abandons mid-way:**
-1. Save partial analysis with answers collected
-2. Mark incomplete sections with "[INCOMPLETE]"
-3. Update status to "in-progress"
-4. Allow resume with same feature_id
-
-**If MCP unavailable:**
-1. Use Glob/Grep for codebase exploration
-2. Continue with discovery
-3. Note in codebaseContext: "MCP unavailable"
-
-**If business rules contradict:**
-1. Identify conflicting BR-IDs
-2. Ask user to resolve via AskUserQuestion
-3. Document resolution in rule notes
-
-**If permission paths detected in entities:**
-STOP and flag error: "RBAC violation in entity attributes. Roles must be in Permission Matrix (step-02)."
-
-**If micro mode and user provides complex requirements:**
-1. Warn: "Micro mode is for simple features. Consider full analysis mode."
-2. Allow upgrade to full mode
-3. Preserve micro answers in feature.json
-
----
-
-## NEXT STEP:
-
-After completion, proceed to `steps/step-02-specify.md`