@atlashub/smartstack-cli 2.1.0 → 2.3.0

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -1,387 +1,497 @@
 ---
 name: step-00-init
-description: Initialize Business Analysis - Parse flags, create structure, setup state
-next_step: steps/step-01-discover.md
+description: Initialize Business Analysis - Parse flags, route use case, create feature.json
+next_step: steps/step-01-analyse.md
 ---
 
-## YOUR TASK:
+# Step 00: Initialize Business Analysis
 
-Parse command-line flags, create feature directory structure, and initialize state variables for the Business Analysis workflow.
+Initialize the business analysis workflow by parsing input flags, routing to the appropriate use case handler, and creating the initial feature.json structure.
 
-<defaults>
+## Flow
+
+1. Parse command flags and determine use case
+2. Route to specialized handler (question, refactoring, micro, or new feature)
+3. MCP health check (non-blocking)
+4. Interactive mode (if enabled)
+5. Validate business context
+6. Determine application and module
+7. Select language
+8. Generate feature ID
+9. Create output directory structure
+10. Create initial feature.json
+11. Update config
+12. Display summary
+13. Load next step
+
+## Step 1: Parse Command Flags
+
+Parse all command-line arguments to determine execution mode and routing.
+
+### Default Values
 ```yaml
 auto_mode: false
-save_mode: true      # BA always saves by default
 economy_mode: false
-context: business    # BA is RESTRICTED to business context
+context: business
+question_mode: false
+refactor_mode: false
+micro_mode: false
+interactive_mode: false
 ```
-</defaults>
 
-## EXECUTION SEQUENCE:
+### Flag Parsing Rules
 
-### 1. Parse Flags and Input
+| Flag | Long Form | Effect | Argument |
+|------|-----------|--------|----------|
+| `-a` | `--auto` | Enable auto mode | none |
+| `-e` | `--economy` | Enable economy mode | none |
+| `-A` | `--no-auto` | Disable auto mode | none |
+| `-E` | `--no-economy` | Disable economy mode | none |
+| `-q` | `--question` | Question mode | next arg = FEAT-ID, remaining = question text |
+| `-r` | `--refactor` | Refactoring mode | next arg = FEAT-ID, remaining = change description |
+| `-m` | `--micro` | Micro feature mode | none |
+| `-i` | `--interactive` | Interactive mode | none |
 
-**Step 1: Load defaults**
+**Remaining arguments after flag removal = feature_description**
+
+### Set Use Case
 ```
-{auto_mode}    = false
-{save_mode}    = true
-{economy_mode} = false
-{context}      = "business"
+IF question_mode = true:
+  use_case = "question"
+ELSE IF refactor_mode = true:
+  use_case = "refactoring"
+ELSE IF micro_mode = true:
+  use_case = "micro"
+ELSE:
+  use_case = "new"
 ```
 
-**Step 2: Parse user input and override defaults:**
-
-Enable flags (lowercase - turn ON):
-- `-a` or `--auto`     -> `{auto_mode}` = true
-- `-s` or `--save`     -> `{save_mode}` = true (already default)
-- `-e` or `--economy`  -> `{economy_mode}` = true
-
-Disable flags (UPPERCASE - turn OFF):
-- `-A` or `--no-auto`     -> `{auto_mode}` = false
-- `-S` or `--no-save`     -> `{save_mode}` = false
-- `-E` or `--no-economy`  -> `{economy_mode}` = false
-
-Other:
-- `-r` or `--resume`      -> `{resume_task}` = <next argument>
-- `-i` or `--interactive` -> `{interactive_mode}` = true
-
-**Step 3: Extract feature description**
-After removing flags, remaining text becomes `{feature_description}`
-
----
-
-### 2. Check Resume Mode
-
-**ONLY execute if `{resume_task}` is set!**
+## Step 2: Use Case Routing
 
-If `{resume_task}` is set:
-1. Search for matching feature in `.business-analyse/`
-   Use Glob tool to search for matching feature:
-   - Pattern: `.business-analyse/**/features/*{resume_task}*`
-   - If match found: read 00-context.md from that directory
-   - If no match: list available features for user selection
-2. If found: Read `00-context.md` to restore state variables
-3. Find last completed step (look for "Status: Complete" in progress table)
-4. Load next incomplete step
-5. **STOP** - do not continue with fresh init
+Route execution based on the detected use case.
 
-If NOT found:
-- Display error: "Feature {resume_task} not found"
-- List available features for selection
-- Exit or prompt for new task
+### Question Mode (-q)
+```
+1. Parse: question_mode = true, feat_id = first remaining arg, question_text = rest
+2. Call ba-reader agent:
+   - ba-reader.findFeatureByID(feat_id)
+   - Retrieve existing feature.json
+3. Call ba-reader.answerQuestion(feat_id, question_text)
+   - Answer question from context
+4. Display answer in user session
+5. EXIT - no further steps
+```
 
----
+**Example:**
+```
+ba -q FEAT-001 "What are the main actors in this feature?"
+```
 
-### 2b. Verify MCP Availability
+### Refactoring Mode (-r)
+```
+1. Parse: refactor_mode = true, feat_id = first remaining arg, change_description = rest
+2. Call ba-reader agent:
+   - ba-reader.findFeatureByID(feat_id)
+   - Load existing feature.json
+3. Call ba-writer agent:
+   - ba-writer.createVersion(feat_id, change_description)
+   - Increment version (e.g., 1.0 -> 1.1)
+   - Mark changeReason
+4. Set use_case = "refactoring"
+5. Set version = new version number
+6. Set feature_id from loaded feature
+7. Continue to Step 5 (context validation)
+8. Continue to Step 9 (create output structure at new version)
+9. Load step-01-analyse in delta mode (compare old vs new)
+```
 
-**Check SmartStack MCP (non-blocking):**
+**Example:**
+```
+ba -r FEAT-001 "Add support for multi-language feature names"
+```
 
-Call `mcp__smartstack__validate_conventions` with minimal parameters to verify connectivity.
+### Micro Feature Mode (-m)
+```
+1. Set use_case = "micro"
+2. Set feature_type = "micro"
+3. Continue to standard init flow (Steps 5-9)
+4. Load step-01-analyse in micro mode (simplified analysis)
+```
 
-| MCP Status | Behavior |
-|------------|----------|
-| Available | Full mode - use MCP tools in all steps |
-| Unavailable | Degraded mode - warn user, skip MCP calls, use manual exploration |
+**Example:**
+```
+ba -m "Add email notification on approval"
+```
 
-Store: `{mcp_available}` = true/false
+### Default Mode (New Feature)
+```
+1. Set use_case = "new"
+2. Continue to standard init flow (Steps 5-9)
+3. Load step-01-analyse in full mode
+```
 
-**Display if unavailable:**
+**Example:**
 ```
-Warning: SmartStack MCP unavailable. Running in degraded mode.
-Run `smartstack check-mcp` to diagnose.
-BA will continue without MCP validation.
+ba "Create order management system"
 ```
 
-**Add to state variables:** `{mcp_available}` persisted in 00-context.md
+## Step 3: MCP Health Check
 
----
+Verify MCP availability (non-blocking).
 
-### 3. Interactive Mode (if -i flag)
+**Check file:** `.claude/mcp-status.json`
 
-If `{interactive_mode}` = true:
+| Condition | Action |
+|-----------|--------|
+| File missing | Perform full health check |
+| > 7 days old | Perform full health check |
+| ≤ 7 days old | Quick connectivity test |
+| Error status | Display warning, continue |
 
-Use AskUserQuestion with these questions:
+**Full health check:**
+1. Call `mcp__smartstack__validate_conventions`
+2. Verify installed version
+3. List available tools
+4. Update `.claude/mcp-status.json`
 
-```json
-{
-  "questions": [
-    {
-      "question": "What execution mode do you prefer?",
-      "header": "Mode",
-      "options": [
-        {"label": "Autonomous (-a)", "description": "No confirmations, smooth execution"},
-        {"label": "Interactive", "description": "Confirmation at each step"}
-      ],
-      "multiSelect": false
-    },
-    {
-      "question": "Use economy mode (without subagents)?",
-      "header": "Economy",
-      "options": [
-        {"label": "No (Recommended)", "description": "Better quality with subagents"},
-        {"label": "Yes (-e)", "description": "Token savings, lower quality"}
-      ],
-      "multiSelect": false
-    }
-  ]
-}
-```
+**Quick test:**
+- Bash only, no LLM call
+- Check if `.claude/mcp/` exists and has recent files
 
----
+**Display result:**
+- Success: "MCP available: yes"
+- Warning: "MCP check skipped (cache expired)"
+- Error: "MCP unavailable: using fallback (slower analysis)"
 
-### 4. Validate Business Context
+## Step 4: Interactive Mode
 
-**CRITICAL: BA is RESTRICTED to 'business' context only!**
+If `-i` or `--interactive` flag is set, prompt for confirmation.
 
+**Prompt:**
 ```
-IF {context} IN ['platform', 'personal', 'system'] THEN
-  DISPLAY ERROR:
-  "Business Analysis is restricted to 'business' context only.
-   Platform/Personal/System modules use different processes.
-   Contact: support@atlshub.ch"
-  EXIT
-END IF
+Confirm initialization with:
+- Use Case: {use_case}
+- Application: {application_name}
+- Module: {module_name}
+- Auto Mode: {auto_mode}
+- Economy Mode: {economy_mode}
+
+Continue? (y/n)
 ```
 
----
-
-### 5. Determine Application and Module
+If 'n', EXIT.
 
-Ask user to specify:
+## Step 5: Validate Business Context
 
-```json
-{
-  "questions": [
-    {
-      "question": "Which business application to target?",
-      "header": "Application",
-      "options": [
-        {"label": "New application", "description": "Create a new business application"},
-        {"label": "Existing application", "description": "Add a module to an existing application"}
-      ],
-      "multiSelect": false
-    }
-  ]
-}
-```
-
-If "Existing application":
-- Scan `.business-analyse/business/` for existing applications
-- Present list for selection
-
-Store in:
-- `{application_name}` - PascalCase (e.g., "Sales", "HR", "Inventory")
-- `{module_name}` - PascalCase (e.g., "Clients", "Orders", "Products")
+Verify that the business context is properly configured.
 
----
+**Check:**
+1. Does `.business-analyse/config.json` exist?
+2. Does it contain `businessContext` section?
+3. Are required fields present?
 
-### 5b. Select Communication Language
+**If missing:**
+1. Create fresh config with defaults
+2. Prompt for business context (only in interactive mode)
+3. Save to `.business-analyse/config.json`
 
+**Required config structure:**
 ```json
 {
-  "questions": [
-    {
-      "question": "Dans quelle langue souhaitez-vous communiquer ?",
-      "header": "Langue",
-      "options": [
-        {"label": "Français (Recommandé)", "description": "Toutes les interactions et documents en français"},
-        {"label": "English", "description": "All interactions and documents in English"},
-        {"label": "Italiano", "description": "Tutte le interazioni e i documenti in italiano"},
-        {"label": "Deutsch", "description": "Alle Interaktionen und Dokumente auf Deutsch"}
-      ],
-      "multiSelect": false
-    }
-  ]
+  "businessContext": {
+    "organization": "string",
+    "domain": "string",
+    "language": "string"
+  }
 }
 ```
 
-Map selection to `{language}`:
-- "Français" → `fr`
-- "English" → `en`
-- "Italiano" → `it`
-- "Deutsch" → `de`
-
-**Default:** `fr` (si non spécifié)
+## Step 6: Determine Application and Module
 
----
+Scan for existing applications and modules.
 
-### 6. Generate Feature ID
+**Scan order:**
+1. Primary: `docs/business/` (modern structure)
+   - List subdirectories = applications
+   - Inside each app, list subdirectories = modules
+2. Fallback: `.business-analyse/business/` (legacy)
+   - Same structure as above
 
-```bash
-# Read last ID from config
-LAST_ID=$(grep -oP '"lastFeatureId":\s*\K\d+' .business-analyse/config.json 2>/dev/null || echo "0")
-
-# Increment
-NEW_ID=$((LAST_ID + 1))
+**Logic:**
+```
+IF auto_mode = true:
+  application_name = first found app OR "default"
+  module_name = first found module OR "default"
+ELSE (interactive):
+  Prompt: "Select application: [list]"
+  Prompt: "Select module: [list]"
+  OR: "Create new application: {name}"
+  OR: "Create new module: {name}"
+```
 
-# Format as FEAT-NNN
-{feature_id} = printf "FEAT-%03d" $NEW_ID
+**Store:**
+```yaml
+application_name: string
+module_name: string
 ```
 
----
+## Step 7: Select Language
 
-### 7. Create Output Structure
+Determine the language for analysis and code generation.
 
-**Create directory structure:**
+**Check config:**
+- Retrieve `businessContext.language` from config
+- Default: "en" (English)
 
+**If interactive:**
 ```
-.business-analyse/
-├── config.json                    # Global config (update lastFeatureId)
-└── business/
-    └── {application_name}/
-        └── modules/
-            └── {module_name}/
-                └── features/
-                    └── {feature_id}/
-                        ├── 00-context.md      # State + progress
-                        └── tracking/
-                            ├── changes/
-                            ├── bugs/
-                            └── hotfixes/
+Select language:
+[ ] English (en)
+[ ] French (fr)
+[ ] Spanish (es)
+[ ] Custom: {input}
 ```
 
-**Set output_dir:**
-```
-{output_dir} = .business-analyse/business/{application_name}/modules/{module_name}/features/{feature_id}
+**Store:**
+```yaml
+language: string (code, e.g., "en", "fr")
 ```
 
----
-
-### 8. Write 00-context.md
+## Step 8: Generate Feature ID
 
-Create initial context file with state variables:
+Create a unique feature identifier.
 
-```markdown
-# Business Analysis: {{feature_id}}
-
-**Created:** {{timestamp}}
-**Feature:** {{feature_description}}
-**Application:** business/{{application_name}}/{{module_name}}
-
-## Configuration
-
-| Setting | Value |
-|---------|-------|
-| Auto mode | {{auto_mode}} |
-| Save mode | {{save_mode}} |
-| Economy mode | {{economy_mode}} |
-
-## Progress
-
-| Step | Status | Started | Completed |
-|------|--------|---------|-----------|
-| 00-init | Complete | {{timestamp}} | {{timestamp}} |
-| 01-discover | Pending | - | - |
-| 02-analyse | Pending | - | - |
-| 03-specify | Pending | - | - |
-| 04-validate | Pending | - | - |
-| 05-handoff | Pending | - | - |
-| 06-doc-html | Pending | - | - |
-
-## State Variables
-
-| Variable | Value |
-|----------|-------|
-| feature_id | {{feature_id}} |
-| feature_description | {{feature_description}} |
-| application_name | {{application_name}} |
-| module_name | {{module_name}} |
-| context | business |
-| language | {{language}} |
-| mcp_available | {{mcp_available}} |
-| permission_base | business.{{application_name}}.{{module_name}} |
+**Logic:**
+```
+IF use_case = "question" OR "refactoring":
+  feature_id = use provided feat_id (already parsed)
+ELSE:
+  feature_id = generate using pattern: FEAT-{timestamp-based}-{random}
+  OR: FEAT-{app-short}-{seq-number}
+  Example: FEAT-001, FEAT-002, ...
+```
 
-## Discovery Metadata (updated by step-01)
+**Store:**
+```yaml
+feature_id: string
+```
 
-| Variable | Value |
-|----------|-------|
-| feature_type | (TBD in step-01) |
-| mcp_available | {{mcp_available}} |
-| categories_loaded | (TBD in step-01) |
+## Step 9: Create Output Directory Structure
 
-## Risk Register (updated by step-01)
+Create the directory hierarchy for feature documentation.
 
-(TBD in step-01)
+**For new features / micro / refactoring:**
+```
+docs/business/{application_name}/{module_name}/business-analyse/v{version}/
+```
 
-## Codebase Context Summary (updated by step-01)
+**Where version:**
+- New feature: "1.0"
+- Refactoring: from ba-writer (e.g., "1.1", "1.2")
+- Micro: "1.0"
 
-(TBD in step-01)
+**Create directories:**
+```bash
+mkdir -p docs/business/{app}/{module}/business-analyse/v{version}
+```
 
-## Acceptance Criteria
+**Store:**
+```yaml
+docs_dir: "docs/business/{app}/{module}/business-analyse/v{version}"
+output_dir: same as docs_dir
+```
 
-To be defined in step-01-discover.
+## Step 10: Create Initial feature.json
 
----
+Create the main feature document using ba-writer agent.
 
-## Notes
+**Call ba-writer:**
+```
+ba-writer.createFeature({
+  id: feature_id,
+  application: application_name,
+  module: module_name,
+  featureDescription: feature_description,
+  language: language,
+  useCase: use_case,
+  featureType: feature_type OR null,
+  economyMode: economy_mode,
+  mcpAvailable: mcp_available
+})
+```
 
-(Add notes during analysis)
+**Result structure:**
+```json
+{
+  "id": "{feature_id}",
+  "version": "1.0",
+  "status": "draft",
+  "metadata": {
+    "createdAt": "{ISO timestamp}",
+    "updatedAt": "{ISO timestamp}",
+    "application": "{application_name}",
+    "module": "{module_name}",
+    "context": "business",
+    "language": "{language}",
+    "featureDescription": "{feature_description}",
+    "featureType": null,
+    "useCase": "{use_case}",
+    "permissionBase": "business.{app}.{module}",
+    "previousVersion": null,
+    "changeReason": null,
+    "mcpAvailable": {mcp_available},
+    "economyMode": {economy_mode},
+    "steps": {
+      "init": {
+        "status": "completed",
+        "startedAt": "{ISO timestamp}",
+        "completedAt": "{ISO timestamp}"
+      },
+      "analyse": {
+        "status": "pending",
+        "startedAt": null,
+        "completedAt": null
+      },
+      "specify": {
+        "status": "pending",
+        "startedAt": null,
+        "completedAt": null
+      },
+      "validate": {
+        "status": "pending",
+        "startedAt": null,
+        "completedAt": null
+      },
+      "handoff": {
+        "status": "pending",
+        "startedAt": null,
+        "completedAt": null
+      }
+    }
+  },
+  "discovery": {},
+  "analysis": {},
+  "specification": {},
+  "validation": {},
+  "handoff": {},
+  "suggestions": [],
+  "changelog": [
+    {
+      "version": "1.0",
+      "timestamp": "{ISO timestamp}",
+      "author": "BA Skill",
+      "changes": ["Initial feature.json created"]
+    }
+  ]
+}
 ```
 
----
+**Write to:**
+```
+{docs_dir}/feature.json
+```
 
-### 9. Update Global Config
+## Step 11: Update Config
 
-Update `.business-analyse/config.json`:
+Update `.business-analyse/config.json` with new feature information.
 
+**Update fields:**
 ```json
 {
-  "project": "{ProjectName}",
-  "lastFeatureId": {NEW_ID},
-  "context": "business",
-  "language": "{language}",
-  "standards": ["BABOK-v3", "IEEE-830"],
-  "contact": "support@atlshub.ch"
+  "currentFeature": {
+    "id": "{feature_id}",
+    "version": "1.0",
+    "docsDir": "{docs_dir}",
+    "useCase": "{use_case}",
+    "application": "{application_name}",
+    "module": "{module_name}"
+  },
+  "lastInitialized": "{ISO timestamp}",
+  "autoMode": {auto_mode},
+  "economyMode": {economy_mode},
+  "interactiveMode": {interactive_mode}
 }
 ```
 
----
+## Step 12: Display Summary
+
+Show initialization results in a clear table format.
 
-### 10. Display Summary and Load Next Step
+**Output:**
+```
+═══════════════════════════════════════════════════════════════
+  BUSINESS ANALYSIS INITIALIZATION COMPLETE
+═══════════════════════════════════════════════════════════════
+
+| Field              | Value                                        |
+|--------------------|----------------------------------------------|
+| Step               | INIT (00)                                    |
+| Feature ID         | {feature_id}                                 |
+| Use Case           | {use_case}                                   |
+| Application        | business/{application_name}                  |
+| Module             | {module_name}                                |
+| Output Path        | {docs_dir}/feature.json                      |
+| Language           | {language}                                   |
+| Auto Mode          | {auto_mode}                                  |
+| Economy Mode       | {economy_mode}                               |
+| MCP Available      | {mcp_available}                              |
+| Timestamp          | {ISO timestamp}                              |
+
+NEXT STEP: step-01-analyse ({use_case} mode)
+═══════════════════════════════════════════════════════════════
+```
 
-**Display:**
+## Step 13: Load Next Step
 
-| Field | Value |
-|-------|-------|
-| Step | INIT |
-| Feature | {{feature_id}} |
-| Application | business/{{application_name}} |
-| Module | {{module_name}} |
-| Output | {{output_dir}} |
-| Mode | {{auto_mode ? "Autonomous" : "Interactive"}} |
-| Next | step-01-discover (ULTRATHINK elicitation) |
+Execute the next step in the workflow.
 
-**Load next step:**
+**Read file:**
 ```
-Read and execute: steps/step-01-discover.md
+steps/step-01-analyse.md
 ```
 
----
-
-## OUTPUT FORMAT:
+**Pass context variables:**
+```yaml
+feature_id: string
+feature_description: string
+use_case: "new" | "question" | "refactoring" | "micro"
+application_name: string
+module_name: string
+language: string
+docs_dir: string
+auto_mode: boolean
+economy_mode: boolean
+interactive_mode: boolean
+mcp_available: boolean
+```
 
-This step produces:
-- `.business-analyse/config.json` (updated)
-- `{output_dir}/00-context.md` (created)
-- `{output_dir}/tracking/` directories (created)
+## Error Handling
 
-State variables persisted for next steps.
+Handle common initialization failures gracefully.
 
-## ERROR HANDLING:
+| Error | Action |
+|-------|--------|
+| Config missing | Create fresh with defaults, continue |
+| Directory creation fails | Check permissions, display error, EXIT |
+| feature.json creation fails | Validate ba-writer, retry or fallback |
+| Legacy structure detected | Offer migration to new docs/business/ structure |
+| Feature ID not unique | Generate new ID, retry |
+| Invalid language | Default to "en", warn user |
 
-**If resume feature not found:**
-1. List available features in `.business-analyse/`
-2. Ask user to select or start new analysis
+### Resume After Interruption
 
-**If config.json missing or corrupted:**
-1. Create fresh config.json with defaults
-2. Set lastFeatureId to 0
-3. Warn user: "Config reset to defaults"
+If initialization was interrupted:
 
-**If directory creation fails:**
-1. Check write permissions
-2. Suggest running with elevated privileges
+1. Check `.business-analyse/config.json` for currentFeature
+2. If feature ID exists, search for feature.json:
+   - Primary: `docs/business/{app}/{module}/business-analyse/v{version}/`
+   - Fallback: `.business-analyse/{app}/{module}/`
+3. If found, offer to resume from last completed step
+4. If not found, create fresh feature.json
 
-## NEXT STEP:
+### Clean Fallbacks
 
-After completion, proceed to `steps/step-01-discover.md`
+If modern paths unavailable:
+1. Search `.business-analyse/business/` (legacy)
+2. Create new structure under `docs/business/` regardless
+3. Log migration notice (automated, non-blocking)