@atlashub/smartstack-cli 3.39.0 → 3.41.0

package/templates/skills/apex/steps/step-01-analyze.md

@@ -1,165 +1,165 @@
----
-name: step-01-analyze
-description: Explore existing code to understand what exists — do NOT plan yet
-model: opus
-prev_step: steps/step-00-init.md
-next_step: steps/step-02-plan.md
----
-
-# Step 1: Analyze
-
-**Goal:** Understand what EXISTS in the codebase. Pure exploration, NO planning.
-
-## LOAD CONDITIONALLY
-
-- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
-- If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
-
----
-
-## 0. Fresh Project Detection (Early Exit)
-
-```
-IF .smartstack/init-state.json exists:
-  Read it → check if project was recently initialized
-  Glob("src/**/Entities/**/*.cs") → count entity files
-
-  IF entity count == 0 AND no PRD AND no feature.json:
-    → SKIP full code exploration (sections 2-3)
-    → Declare: "Fresh project — all elements need to be CREATED"
-    → Jump directly to section 4 (Gap Analysis) with all items marked "create"
-```
-
-This saves ~2 minutes of Glob searches on an empty project.
-
----
-
-## 0b. Delegate Mode Fast Path (if delegate_mode)
-
-> **When called via `/ralph-loop -d`, PRD tasks provide pre-computed scope. Reduce exploration to verification only.**
-
-```
-IF delegate_mode:
-  Read PRD from {delegate_prd_path} (already loaded in step-00)
-
-  1. Extract entity list from domain tasks:
-     entities[] = prd.tasks.filter(category == 'domain').map(entity name from description)
-
-  2. Extract FK relationships from frontend tasks with _frontendMeta:
-     fkFields[] = _frontendMeta.fkFields[] (e.g., ["DepartmentId→Department", "CompanyId→Company"])
-
-  3. Determine tenant modes per entity:
-     IF feature.json exists at {feature_path}:
-       Read entity definitions → extract tenantMode per entity
-     ELSE:
-       Default all entities to tenantMode: "strict"
-
-  4. Read feature.json for wireframes/componentMapping if {feature_path} exists:
-     → enriches frontend generation in step-03
-
-  5. Perform LIGHTWEIGHT code exploration (verification only):
-     - Glob("**/Domain/Entities/**/{module_code}/**/*.cs") → what already exists?
-     - Glob("**/Infrastructure/Persistence/Seeding/Data/**/*SeedData*.cs") → existing seed data?
-     - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
-     → Only to determine create vs modify vs skip (NOT deep analysis)
-
-  6. Gap Analysis: Mark all PRD tasks as "create" unless existing code found
-
-  SKIP: Full Agent Teams exploration (section 2), challenge question follow-up
-  Jump to section 5 (Gap Analysis summary) → section 7 (Analysis Summary)
-```
-
----
-
-## 1. Context Sources
-
-Read available context (in order of priority):
-
-| Source | Action |
-|--------|--------|
-| PRD (`{prd_path}`) | Extract: filesToCreate, brToCodeMapping, permissionMatrix, acceptance criteria |
-| Feature.json (`{feature_path}`) | Extract: module structure, business rules, entity definitions, permissions |
-| Task description only | Rely on task description and code exploration |
-
----
-
-## 2. Code Exploration
-
-### If economy_mode: Direct Tools
-
-```
-Backend:
-- Glob("**/Domain/Entities/**/{module_code}/**/*.cs")
-- Glob("**/Infrastructure/Persistence/Configurations/**/{module_code}/**/*.cs")
-- Glob("**/Application/Services/**/{module_code}/**/*.cs")
-- Glob("**/Api/Controllers/**/*{module_code}*Controller.cs")
-- Glob("**/Infrastructure/Persistence/Seeding/Data/{module_code}/**/*.cs")
-
-Frontend:
-- Glob("src/pages/**/{module_code}/**/*.tsx")
-- Glob("src/components/**/{module_code}/**/*.tsx")
-
-MCP:
-- mcp__smartstack__api_docs → existing API surface
-- mcp__smartstack__analyze_extension_points → React extension points
-```
-
-### If NOT economy_mode: Agent Teams
-
-> **Protocol:** See `references/agent-teams-protocol.md`
-
-```
-TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")
-
-Spawn 3 teammates (subagent_type: "Explore", model: "sonnet"):
-
-1. scan-backend:
-   "Scan backend for module {module_code}: entities, EF configs, services,
-    DTOs, validators, controllers in Domain/ + Infrastructure/ + Application/ + Api/"
-
-2. scan-frontend:
-   "Scan frontend for module {module_code}: pages, components, hooks,
-    i18n files, route definitions in src/pages/ + src/components/ + src/locales/"
-
-3. scan-context:
-   "Read context artifacts for module {module_code}: .ralph/prd-{module_code}.json,
-    docs/business/**/feature.json → extract sections, entities, rules, permissions, ACs"
-
-Wait for all 3 → aggregate results → shutdown → TeamDelete("apex-analyze")
-```
-
----
-
-## 3. Seed Data Inventory
-
-```
-Glob("**/Seeding/Data/{module_code}/*SeedData.cs")
-Glob("**/Seeding/*SeedDataProvider.cs")
-```
-
-Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedConstants, IClientSeedDataProvider (+ DI registration).
-
----
-
-## 4-7. Analysis Methods & Validation
-
-> **Reference:** Load `references/analysis-methods.md` for detailed analysis procedures:
-> - FK field detection (frontend EntityLookup + backend search support)
-> - Tenant mode decision (strict/optional/scoped/none)
-> - Code pattern detection (auto-generated strategies)
-> - Gap analysis (exists/missing/modify classification)
-> - Scope re-check (entity count validation)
-> - Analysis validation checkpoint (user confirmation)
-> - Analysis summary output format
-
----
-
-## 8. Save Output (if save_mode)
-
-Write to `{output_dir}/01-analyze.md` with analysis results.
-
----
-
-## NEXT STEP
-
-Load `steps/step-02-plan.md`
+---
+name: step-01-analyze
+description: Explore existing code to understand what exists — do NOT plan yet
+model: opus
+prev_step: steps/step-00-init.md
+next_step: steps/step-02-plan.md
+---
+
+# Step 1: Analyze
+
+**Goal:** Understand what EXISTS in the codebase. Pure exploration, NO planning.
+
+## LOAD CONDITIONALLY
+
+- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
+- If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
+
+---
+
+## 0. Fresh Project Detection (Early Exit)
+
+```
+IF .smartstack/init-state.json exists:
+  Read it → check if project was recently initialized
+  Glob("src/**/Entities/**/*.cs") → count entity files
+
+  IF entity count == 0 AND no PRD AND no feature.json:
+    → SKIP full code exploration (sections 2-3)
+    → Declare: "Fresh project — all elements need to be CREATED"
+    → Jump directly to section 4 (Gap Analysis) with all items marked "create"
+```
+
+This saves ~2 minutes of Glob searches on an empty project.
+
+---
+
+## 0b. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks provide pre-computed scope. Reduce exploration to verification only.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path} (already loaded in step-00)
+
+  1. Extract entity list from domain tasks:
+     entities[] = prd.tasks.filter(category == 'domain').map(entity name from description)
+
+  2. Extract FK relationships from frontend tasks with _frontendMeta:
+     fkFields[] = _frontendMeta.fkFields[] (e.g., ["DepartmentId→Department", "CompanyId→Company"])
+
+  3. Determine tenant modes per entity:
+     IF feature.json exists at {feature_path}:
+       Read entity definitions → extract tenantMode per entity
+     ELSE:
+       Default all entities to tenantMode: "strict"
+
+  4. Read feature.json for wireframes/componentMapping if {feature_path} exists:
+     → enriches frontend generation in step-03
+
+  5. Perform LIGHTWEIGHT code exploration (verification only):
+     - Glob("**/Domain/Entities/**/{module_code}/**/*.cs") → what already exists?
+     - Glob("**/Infrastructure/Persistence/Seeding/Data/**/*SeedData*.cs") → existing seed data?
+     - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
+     → Only to determine create vs modify vs skip (NOT deep analysis)
+
+  6. Gap Analysis: Mark all PRD tasks as "create" unless existing code found
+
+  SKIP: Full Agent Teams exploration (section 2), challenge question follow-up
+  Jump to section 5 (Gap Analysis summary) → section 7 (Analysis Summary)
+```
+
+---
+
+## 1. Context Sources
+
+Read available context (in order of priority):
+
+| Source | Action |
+|--------|--------|
+| PRD (`{prd_path}`) | Extract: filesToCreate, brToCodeMapping, permissionMatrix, acceptance criteria |
+| Feature.json (`{feature_path}`) | Extract: module structure, business rules, entity definitions, permissions |
+| Task description only | Rely on task description and code exploration |
+
+---
+
+## 2. Code Exploration
+
+### If economy_mode: Direct Tools
+
+```
+Backend:
+- Glob("**/Domain/Entities/**/{module_code}/**/*.cs")
+- Glob("**/Infrastructure/Persistence/Configurations/**/{module_code}/**/*.cs")
+- Glob("**/Application/Services/**/{module_code}/**/*.cs")
+- Glob("**/Api/Controllers/**/*{module_code}*Controller.cs")
+- Glob("**/Infrastructure/Persistence/Seeding/Data/{module_code}/**/*.cs")
+
+Frontend:
+- Glob("src/pages/**/{module_code}/**/*.tsx")
+- Glob("src/components/**/{module_code}/**/*.tsx")
+
+MCP:
+- mcp__smartstack__api_docs → existing API surface
+- mcp__smartstack__analyze_extension_points → React extension points
+```
+
+### If NOT economy_mode: Agent Teams
+
+> **Protocol:** See `references/agent-teams-protocol.md`
+
+```
+TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")
+
+Spawn 3 teammates (subagent_type: "Explore", model: "sonnet"):
+
+1. scan-backend:
+   "Scan backend for module {module_code}: entities, EF configs, services,
+    DTOs, validators, controllers in Domain/ + Infrastructure/ + Application/ + Api/"
+
+2. scan-frontend:
+   "Scan frontend for module {module_code}: pages, components, hooks,
+    i18n files, route definitions in src/pages/ + src/components/ + src/locales/"
+
+3. scan-context:
+   "Read context artifacts for module {module_code}: .ralph/prd-{module_code}.json,
+    docs/business/**/feature.json → extract sections, entities, rules, permissions, ACs"
+
+Wait for all 3 → aggregate results → shutdown → TeamDelete("apex-analyze")
+```
+
+---
+
+## 3. Seed Data Inventory
+
+```
+Glob("**/Seeding/Data/{module_code}/*SeedData.cs")
+Glob("**/Seeding/*SeedDataProvider.cs")
+```
+
+Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedConstants, IClientSeedDataProvider (+ DI registration).
+
+---
+
+## 4-7. Analysis Methods & Validation
+
+> **Reference:** Load `references/analysis-methods.md` for detailed analysis procedures:
+> - FK field detection (frontend EntityLookup + backend search support)
+> - Tenant mode decision (strict/optional/scoped/none)
+> - Code pattern detection (auto-generated strategies)
+> - Gap analysis (exists/missing/modify classification)
+> - Scope re-check (entity count validation)
+> - Analysis validation checkpoint (user confirmation)
+> - Analysis summary output format
+
+---
+
+## 8. Save Output (if save_mode)
+
+Write to `{output_dir}/01-analyze.md` with analysis results.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-02-plan.md`

package/templates/skills/apex/steps/step-02-plan.md

@@ -1,144 +1,144 @@
----
-name: step-02-plan
-description: Create layer-by-layer execution plan with skill/MCP mapping per file
-model: opus
-prev_step: steps/step-01-analyze.md
-next_step: steps/step-03-execute.md
----
-
-# Step 2: Plan
-
-**Goal:** Create a precise, file-by-file plan. Each file mapped to a SKILL or MCP tool.
-
-## LOAD CONDITIONALLY
-
-Read `references/smartstack-layers.md` for layer execution rules and skill/MCP mapping.
-
----
-
-## 0. Delegate Mode Fast Path (if delegate_mode)
-
-> **When called via `/ralph-loop -d`, PRD tasks already define the scope. Map directly to layers.**
-
-```
-IF delegate_mode:
-  Read PRD from {delegate_prd_path}
-
-  Map each PRD task to a layer based on task.category:
-    domain          → Layer 0
-    infrastructure  → Layer 0
-    application     → Layer 1
-    api             → Layer 1
-    seedData        → Layer 1
-    frontend        → Layer 2
-    test            → Layer 3
-
-  For each task:
-    file_path    = task.files_changed.created[0] (primary file)
-    action       = "create" (default for delegate mode)
-    tool         = infer from category:
-                   domain/infrastructure → MCP scaffold_extension
-                   api → /controller skill or MCP scaffold_extension
-                   seedData → MCP generate_permissions + ref core-seed-data.md
-                   frontend → /ui-components skill + MCP scaffold_api_client + MCP scaffold_routes
-                   test → MCP scaffold_tests
-    acceptance_criteria = task.acceptance_criteria
-
-  Use task._seedDataMeta, _frontendMeta, _migrationMeta for enriched context.
-
-  SKIP: User checkpoint (section 6) — auto_mode implied
-  Jump to section 5 (Estimated Commits) → NEXT STEP
-```
-
----
-
-## 1-3. Layer Mapping, Skill Assignment, Parallelization
-
-> **Reference:** Load `references/planning-layer-mapping.md` for detailed planning procedures:
-> - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
-> - Entity definition template (tenantMode, codePattern, fkFields, ACs)
-> - Skill/MCP assignment table (per file, per layer)
-> - Layer 0/1/2b/3 file lists with tools
-> - FK field guidance (EntityLookup + backend ?search= parameter)
-> - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
-> - Delegate mode fast path (PRD task mapping to layers)
-
-```
-Layer 0: SEQUENTIAL (agent principal)
-  → domain + infra + migration
-  → dotnet build --no-restore (BLOCKING)
-
-Layer 1: PARALLEL (Agent Teams)
-  → exec-backend: application + api + seed data
-  → exec-frontend: frontend + i18n
-
-Layer 2: SEQUENTIAL (agent principal)
-  → final validation + tests
-```
-
-If economy_mode: ALL layers sequential, agent principal only.
-
----
-
-## 4. Dependency Validation
-
-Verify the plan respects dependencies:
-
-```
-- Migration AFTER EF configs (always)
-- Application services AFTER domain entities (always)
-- Code generator service AFTER entity + EF config (needs DbSet for sequence query)
-- CreateDto adjustments AFTER code pattern decision (remove Code property if auto-generated)
-- Controllers AFTER application services (always)
-- Frontend AFTER API controllers (API contract needed)
-- Seed data AFTER navigation module exists
-- Tests AFTER all code layers complete
-- Build check between Layer 0 and Layer 1 (BLOCKING)
-```
-
----
-
-## 5. Estimated Commits
-
-```
-feat({module}): [domain+infra] {description}
-feat({module}): [app+api] {description}
-feat({module}): [frontend] {description}
-feat({module}): [seed] {description}
-feat({module}): [tests] {description}
-```
-
----
-
-## 6. User Checkpoint (if NOT auto_mode)
-
-Present the plan and ask for validation:
-
-```yaml
-questions:
-  - header: "Plan"
-    question: "Does this execution plan look correct?"
-    options:
-      - label: "Approve and execute (Recommended)"
-        description: "Proceed with the plan as described"
-      - label: "Modify plan"
-        description: "I want to adjust some items"
-      - label: "Cancel"
-        description: "Abort the workflow"
-    multiSelect: false
-```
-
-If "Modify plan": ask what to change, update plan, re-present.
-If "Cancel": abort workflow.
-
----
-
-## 7. Save Output (if save_mode)
-
-Write to `{output_dir}/02-plan.md` with the complete plan.
-
----
-
-## NEXT STEP
-
-Load `steps/step-03-execute.md`
+---
+name: step-02-plan
+description: Create layer-by-layer execution plan with skill/MCP mapping per file
+model: opus
+prev_step: steps/step-01-analyze.md
+next_step: steps/step-03-execute.md
+---
+
+# Step 2: Plan
+
+**Goal:** Create a precise, file-by-file plan. Each file mapped to a SKILL or MCP tool.
+
+## LOAD CONDITIONALLY
+
+Read `references/smartstack-layers.md` for layer execution rules and skill/MCP mapping.
+
+---
+
+## 0. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks already define the scope. Map directly to layers.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path}
+
+  Map each PRD task to a layer based on task.category:
+    domain          → Layer 0
+    infrastructure  → Layer 0
+    application     → Layer 1
+    api             → Layer 1
+    seedData        → Layer 1
+    frontend        → Layer 2
+    test            → Layer 3
+
+  For each task:
+    file_path    = task.files_changed.created[0] (primary file)
+    action       = "create" (default for delegate mode)
+    tool         = infer from category:
+                   domain/infrastructure → MCP scaffold_extension
+                   api → /controller skill or MCP scaffold_extension
+                   seedData → MCP generate_permissions + ref core-seed-data.md
+                   frontend → /ui-components skill + MCP scaffold_api_client + MCP scaffold_routes
+                   test → MCP scaffold_tests
+    acceptance_criteria = task.acceptance_criteria
+
+  Use task._seedDataMeta, _frontendMeta, _migrationMeta for enriched context.
+
+  SKIP: User checkpoint (section 6) — auto_mode implied
+  Jump to section 5 (Estimated Commits) → NEXT STEP
+```
+
+---
+
+## 1-3. Layer Mapping, Skill Assignment, Parallelization
+
+> **Reference:** Load `references/planning-layer-mapping.md` for detailed planning procedures:
+> - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
+> - Entity definition template (tenantMode, codePattern, fkFields, ACs)
+> - Skill/MCP assignment table (per file, per layer)
+> - Layer 0/1/2b/3 file lists with tools
+> - FK field guidance (EntityLookup + backend ?search= parameter)
+> - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
+> - Delegate mode fast path (PRD task mapping to layers)
+
+```
+Layer 0: SEQUENTIAL (agent principal)
+  → domain + infra + migration
+  → dotnet build --no-restore (BLOCKING)
+
+Layer 1: PARALLEL (Agent Teams)
+  → exec-backend: application + api + seed data
+  → exec-frontend: frontend + i18n
+
+Layer 2: SEQUENTIAL (agent principal)
+  → final validation + tests
+```
+
+If economy_mode: ALL layers sequential, agent principal only.
+
+---
+
+## 4. Dependency Validation
+
+Verify the plan respects dependencies:
+
+```
+- Migration AFTER EF configs (always)
+- Application services AFTER domain entities (always)
+- Code generator service AFTER entity + EF config (needs DbSet for sequence query)
+- CreateDto adjustments AFTER code pattern decision (remove Code property if auto-generated)
+- Controllers AFTER application services (always)
+- Frontend AFTER API controllers (API contract needed)
+- Seed data AFTER navigation module exists
+- Tests AFTER all code layers complete
+- Build check between Layer 0 and Layer 1 (BLOCKING)
+```
+
+---
+
+## 5. Estimated Commits
+
+```
+feat({module}): [domain+infra] {description}
+feat({module}): [app+api] {description}
+feat({module}): [frontend] {description}
+feat({module}): [seed] {description}
+feat({module}): [tests] {description}
+```
+
+---
+
+## 6. User Checkpoint (if NOT auto_mode)
+
+Present the plan and ask for validation:
+
+```yaml
+questions:
+  - header: "Plan"
+    question: "Does this execution plan look correct?"
+    options:
+      - label: "Approve and execute (Recommended)"
+        description: "Proceed with the plan as described"
+      - label: "Modify plan"
+        description: "I want to adjust some items"
+      - label: "Cancel"
+        description: "Abort the workflow"
+    multiSelect: false
+```
+
+If "Modify plan": ask what to change, update plan, re-present.
+If "Cancel": abort workflow.
+
+---
+
+## 7. Save Output (if save_mode)
+
+Write to `{output_dir}/02-plan.md` with the complete plan.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-03-execute.md`