@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/controller/steps/step-03-generate.md

@@ -1,48 +1,189 @@
 ---
 name: step-03-generate
-description: Generate controller file and DTOs
+description: Generate controller using MCP scaffold_extension with NavRoute
 next_step: steps/step-04-perms.md
 ---
 
 # Step 3: Generate Controller
 
-## YOUR TASK:
+## MANDATORY EXECUTION RULES
 
-Generate the controller file following SmartStack conventions. Use templates from `templates.md`.
+- ALWAYS use MCP `scaffold_extension` tool - NEVER use templates
+- ALWAYS generate Controller + DTOs as a unit
+- ALWAYS include NavRoute attribute for frontend/backend sync
+- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+- MCP is the SOURCE OF TRUTH for code generation
 
-**ULTRA THINK about security and patterns.**
+## YOUR TASK
+
+Call the SmartStack MCP `scaffold_extension` tool with type "controller" to generate:
+1. API Controller with NavRoute attribute
+2. DTOs (Response, Create, Update)
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{area}` | Controller folder (Admin, Business, Support, User) |
+| `{module}` | kebab-case module identifier |
+| `{entity}` | Entity name (PascalCase) |
+| `{permission_path}` | Complete navigation path (navRoute) |
+| `{controller_type}` | crud, readonly, custom, auth |
 
 ---
 
-## EXECUTION SEQUENCE:
+## EXECUTION SEQUENCE
 
-### 1. Load Templates
+### 1. Derive Entity Name
 
-**Read template file:**
+Convert `{module}` to PascalCase for entity name:
 
 ```
-Read: templates/templates.md
+module: "products"        → entityName: "Product"
+module: "order-items"     → entityName: "OrderItem"
+module: "user-profiles"   → entityName: "UserProfile"
 ```
 
-**Select appropriate template based on {controller_type}:**
-- CRUD Controller template
-- Auth Controller template
-- ReadOnly Controller template
+### 2. Determine Table Prefix
+
+Based on navigation context extracted from `{permission_path}`:
+
+| Context | Table Prefix | Controller Folder |
+|---------|--------------|-------------------|
+| platform.administration | `auth_` or `cfg_` | `Admin` |
+| platform.support | `support_` | `Support` |
+| business.* | `ref_` or domain-specific | `Business` |
+| personal.* | `usr_` | `User` |
+
+### 3. Call MCP scaffold_extension (TWO CALLS)
+
+**First call: Generate DTOs**
+
+```
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "dto"
+  name: "{entityName}"  # PascalCase from step 1
+  options:
+    navRoute: "{permission_path}"  # For proper namespace hierarchy
+    schema: "core"
+    dryRun: false
+```
 
-### 2. Generate Controller File
+**Second call: Generate Controller with NavRoute**
 
-**Target path:**
 ```
-src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "controller"
+  name: "{entityName}"  # PascalCase from step 1
+  options:
+    navRoute: "{permission_path}"  # MANDATORY for NavRoute attribute
+    navRouteSuffix: null            # Optional (e.g., "details" → [NavRoute("path", Suffix = "details")])
+    dryRun: false
 ```
-> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
 
-See [references/controller-code-templates.md](../references/controller-code-templates.md) for all C# templates:
-- **Controller class** with DI constructor (IApplicationDbContext, ICurrentUserService, ILogger)
-- **GET endpoint** with pagination (PagedResult, AsNoTracking)
-- **DTOs** (CreateDto, UpdateDto, ResponseDto with entity mapping constructor)
-- **Security logging** (Create/Update at Info, Delete at Warning)
-- **System account protection** guard (UserType.System/LocalAdmin)
+**CRITICAL: NavRoute is MANDATORY** - Without it, frontend/backend sync will fail.
+
+**Why two calls?**
+- The skill `/controller` assumes the Entity already exists (verified in step-01-analyze.md)
+- Type "dto" generates DTOs without regenerating the Entity
+- Type "controller" generates the Controller with NavRoute and references to DTOs
+
+### 4. Parse MCP Responses
+
+**From first call (DTOs):**
+- `Application/{Context}/{Application}/{Module}/DTOs/{entityName}ResponseDto.cs` - Response DTO
+- `Application/{Context}/{Application}/{Module}/DTOs/Create{entityName}Dto.cs` - Create request
+- `Application/{Context}/{Application}/{Module}/DTOs/Update{entityName}Dto.cs` - Update request
+
+**From second call (Controller):**
+- `Api/Controllers/{area}/{entityName}Controller.cs` - REST Controller **with [NavRoute]**
+
+### 5. Present Output to User
+
+```markdown
+## Controller Generated via MCP
+
+### API Layer
+- `Controllers/{area}/{entityName}Controller.cs`
+  - **NavRoute: `{permission_path}`** ✅
+  - Endpoints:
+    - GET /api/{module} - List all
+    - GET /api/{module}/{id} - Get by ID
+    - POST /api/{module} - Create
+    - PUT /api/{module}/{id} - Update
+    - DELETE /api/{module}/{id} - Delete
+
+### Application Layer (DTOs)
+- `{Context}/{Application}/{Module}/DTOs/{entityName}ResponseDto.cs`
+- `{Context}/{Application}/{Module}/DTOs/Create{entityName}Dto.cs`
+- `{Context}/{Application}/{Module}/DTOs/Update{entityName}Dto.cs`
+
+### ✅ NavRoute Integration
+The controller uses `[NavRoute("{permission_path}")]` which enables:
+- ✅ Automatic frontend route generation
+- ✅ Permission-based navigation sync
+- ✅ Dynamic API routing from Navigation entities
+
+### Next Steps
+1. Permissions will be synchronized in step-04-perms.md
+2. Validate conventions with MCP `validate_conventions`
+```
+
+---
+
+## MCP RESPONSE HANDLING
+
+### Success Case
+
+**After first call (DTOs):**
+- Display all generated DTO files
+- Verify DTOs match entity properties
+- Continue to second call
+
+**After second call (Controller):**
+- Display controller file
+- Show NavRoute attribute included
+- Highlight frontend/backend sync enabled
+- Store controller info for permission sync
+- Proceed to step-04-perms.md
+
+### Error Case
+
+**If first call (DTOs) fails:**
+- Display error message
+- Suggest checking entity name format
+- Verify entity properties are defined
+- Verify MCP server is running (`/mcp:healthcheck`)
+- Do NOT proceed to second call
+
+**If second call (Controller) fails:**
+- Display error message
+- Note that DTOs were generated successfully
+- Suggest checking navRoute format
+- Verify MCP server is running (`/mcp:healthcheck`)
+- Do NOT proceed to step-04-perms.md
+
+---
+
+## NAVROUTE VALIDATION
+
+**After generation, verify NavRoute is present:**
+
+```
+Generated controller MUST contain:
+[NavRoute("{permission_path}")]
+
+WITHOUT NavRoute:
+❌ Frontend routes will be hardcoded
+❌ No automatic permission sync
+❌ Manual navigation management required
+```
 
 ---
 
@@ -53,7 +194,7 @@ Generated Files:
 
 | File | Path | Status |
 |------|------|--------|
-| Controller | src/.../Controllers/{area}/{module}Controller.cs | ✅ Created |
+| Controller | src/.../Controllers/{area}/{entity}Controller.cs | ✅ Created with [NavRoute] |
 | CreateDto | src/.../DTOs/{module}/{entity}CreateDto.cs | ✅ Created |
 | UpdateDto | src/.../DTOs/{module}/{entity}UpdateDto.cs | ✅ Created |
 | ResponseDto | src/.../DTOs/{module}/{entity}ResponseDto.cs | ✅ Created |
@@ -63,6 +204,25 @@ Generated Files:
 
 ---
 
+## SUCCESS METRICS
+
+- MCP scaffold_extension called successfully (DTOs)
+- DTOs generated (ResponseDto, CreateDto, UpdateDto)
+- MCP scaffold_extension called successfully (Controller)
+- Controller generated with **[NavRoute]** attribute
+- NavRoute matches permission_path
+- Controller references DTOs correctly
+- Proceeded to step-04-perms.md
+
+## FAILURE MODES
+
+- MCP call failed (display error, run /mcp:healthcheck, stop)
+- Invalid entity name (must be PascalCase)
+- Invalid navRoute format
+- MCP server not running
+
+---
+
 ## NEXT STEP:
 
-After generation complete, proceed to `./step-04-perms.md`
+After controller generation complete, proceed to `./step-04-perms.md`

package/templates/skills/controller/templates.md

@@ -1,7 +1,16 @@
 # SmartStack Controller Templates
 
-> **Note:** These templates are used by the `controller` skill and `/controller:create` command.
-> Adapt variables `{Area}`, `{Module}`, `{Entity}`, `{PermissionPath}` according to context.
+> **⚠️ OBSOLETE - DO NOT USE THESE TEMPLATES MANUALLY**
+>
+> **The `/controller` skill now uses the MCP `scaffold_extension` tool to generate controllers.**
+> These templates are kept for reference only. All controller generation MUST go through the MCP to ensure:
+> - ✅ `[NavRoute]` attribute is included for frontend/backend sync
+> - ✅ Permissions are correctly generated
+> - ✅ Consistency with SmartStack conventions
+>
+> **To generate a controller, use:** `/controller` skill which calls MCP `scaffold_extension` automatically.
+>
+> **If you modify these templates, they will NOT be used.** The MCP templates in `templates/mcp-scaffolding/controller.cs.hbs` are the source of truth.
 
 ---
 

package/templates/skills/debug/SKILL.md

@@ -10,6 +10,7 @@ $ARGUMENTS
 
 <objective>
 Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs.
+Uses **Agent Teamwork** for parallel investigation with real-time collaboration.
 **ULTRA THINK** at each phase transition.
 </objective>
 
@@ -23,95 +24,194 @@ Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs
 
 <workflow>
 
-## 1. ANALYZE: Deep Log/Error Analysis
+## 1. ANALYZE: Deep Log/Error Analysis (inline)
 
 - Parse the provided log/error message carefully
 - Extract key error patterns, stack traces, and symptoms
 - Identify error types: runtime, compile-time, logic, performance
 - **CRITICAL**: Document exact error context and reproduction steps
+- Determine investigation scope (see decision matrix below)
 
-## 2. EXPLORE: Targeted Codebase Investigation
+### Decision Matrix — Team vs. Inline
 
-Launch **parallel subagents** to search for error-related code:
+| Condition | Action |
+|-----------|--------|
+| Simple error, obvious from stack trace | NO team — investigate inline |
+| Error involves code + data | Team: `code-investigator` + `data-inspector` |
+| Error involves unknown library | Team: `code-investigator` + `doc-researcher` |
+| Complex bug, multiple suspects | Full team: all 3 agents |
+| Performance issue (no error) | `code-investigator` only (profiling inline) |
 
-**Agent 1: Codebase Search** (`explore-codebase`)
+**If team NOT needed** → skip to phase 3 (ULTRA-THINK) with inline investigation.
+**If team needed** → proceed to phase 2.
+
+## 2. EXPLORE: Team Investigation
+
+> **Reference:** Load `references/team-protocol.md` for full protocol details.
+
+### 2.1 Create Team
+
+```yaml
+TeamCreate:
+  team_name: "debug-investigate"
+  description: "Parallel bug investigation"
+```
+
+### 2.2 Spawn Teammates (single message, parallel Task calls)
+
+Spawn all relevant teammates simultaneously:
+
+**code-investigator** (`general-purpose`, haiku)
 ```
-Find code related to this error: {error_description}
-Search for:
-- Error source location from stack trace
-- Related error handling patterns
-- Similar code that works correctly
-Report file paths with line numbers.
+You are a code investigator on the debug team.
+
+## Bug Context
+Error: {error_description}
+Stack trace: {stack_trace}
+
+## Mission
+1. Locate the error source in code (from stack trace)
+2. Find related error handling patterns
+3. Identify similar code that works correctly (for comparison)
+4. Check recent commits on affected files (git log, git blame)
+5. Search for similar error patterns elsewhere in codebase
+
+## Communication
+- Send FINDING messages to team-lead for each significant discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description with file:line}", summary: "Found {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Rules
+- Bash ONLY for: git log, git blame, git diff (NEVER modify code)
+- Report file paths with line numbers
+- Be precise and factual
 ```
 
-**Agent 2: Documentation** (`explore-docs`)
+**doc-researcher** (`general-purpose`, haiku)
 ```
-Research documentation for: {libraries_in_stacktrace}
-Find:
-- Known issues or breaking changes
-- Correct usage patterns
-- Migration guides if version issues
+You are a documentation researcher on the debug team.
+
+## Bug Context
+Error: {error_description}
+Libraries: {libraries_in_stacktrace}
+
+## Mission
+1. Research documentation for libraries in the stack trace
+2. Find known issues or breaking changes
+3. Find correct usage patterns
+4. Search for similar issues reported online
+5. Look for migration guides if version issues suspected
+
+## Communication
+- Send FINDING messages to team-lead for each discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
+- If team-lead sends a LEAD_HINT, follow that direction
 ```
 
-**Agent 3: Web Research** (`websearch`)
+**data-inspector** (`general-purpose`, haiku) — *only if bug involves data/persistence/DB*
 ```
-Search for: {error_message}
-Find:
-- Similar issues reported by others
-- Solutions and workarounds
-- Root cause explanations
+You are a READ-ONLY database inspector on the debug team.
+
+## Bug Context
+Error: {error_description}
+
+## ABSOLUTE RESTRICTIONS
+YOU MUST NEVER EXECUTE: INSERT, UPDATE, DELETE, MERGE, TRUNCATE, DROP, ALTER, CREATE, EXEC, dotnet ef database update, dotnet ef migrations
+YOU MAY ONLY EXECUTE: SELECT, INFORMATION_SCHEMA, sys.* views, sp_help
+
+## Mission
+1. Find connection string (appsettings.json, appsettings.Development.json)
+2. Check record existence and field values for affected entities
+3. Verify FK integrity (orphaned records)
+4. Check tenant isolation (TenantId on all records)
+5. Verify soft delete and audit field consistency
+6. Compare schema vs expected EF Core model
+
+## Communication
+- Send FINDING messages to team-lead for each data anomaly:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Rules
+- Bash ONLY for SELECT queries (NEVER modify data)
+- If a fix is needed, DESCRIBE it — NEVER execute it
+- Mask sensitive data (passwords, tokens, PII)
+- Limit results with TOP/LIMIT
 ```
 
-Additional investigation:
-- Search for similar error patterns in codebase using Grep
-- Find all files related to the failing component/module
-- Examine recent changes that might have introduced the bug
-- **ULTRA THINK**: Connect error symptoms to potential root causes
+### 2.3 Orchestrate — Lead Actions During Investigation
 
-## 3. ULTRA-THINK: Deep Root Cause Analysis
+While teammates investigate in parallel:
 
-**THINK DEEPLY** about the error chain: symptoms -> immediate cause -> root cause
+- **Monitor** incoming `FINDING` messages from agents
+- **Cross-reference** findings between agents (code ↔ data ↔ docs)
+- **Send `LEAD_HINT`** when one agent's finding informs another:
+  ```yaml
+  SendMessage:
+    type: "message"
+    recipient: "data-inspector"
+    content: "LEAD_HINT: code-investigator found null FK at OrderService.cs:45 — check if Customer records exist for affected OrderIds"
+    summary: "Investigate FK from code finding"
+  ```
+- **Additional inline investigation**: Grep for error patterns, check related files, examine recent commits
 
-Consider all possible causes:
+### 2.4 Aggregate & Shutdown
+
+Wait for all `INVESTIGATION_COMPLETE` messages, then:
+
+1. Collect all `FINDING` messages from each agent
+2. Cross-reference: code issues ↔ data anomalies ↔ documentation
+3. Shutdown teammates:
+   ```yaml
+   SendMessage:
+     type: "shutdown_request"
+     recipient: "{each-teammate}"
+     content: "Investigation complete"
+   # Wait for shutdown_response, then:
+   TeamDelete
+   ```
+
+## 3. ULTRA-THINK: Deep Root Cause Analysis (inline)
+
+**THINK DEEPLY** about the error chain: symptoms → immediate cause → root cause
+
+Aggregate all team findings and consider:
 - Code logic errors
 - Configuration issues
+- Data integrity problems (from data-inspector findings)
 - Environment problems
 - Race conditions
 - Memory issues
 - Network problems
 
 **CRITICAL**: Map the complete failure path from root cause to visible symptom
-Validate hypotheses against the evidence
+Validate hypotheses against evidence from ALL agents
 
 ### WHY Technique
 
 Ask "why" at least 5 times:
-1. Why did the error occur? -> X happened
-2. Why did X happen? -> Y was in invalid state
-3. Why was Y invalid? -> Z didn't initialize properly
-4. Why didn't Z initialize? -> A dependency was missing
-5. Why was dependency missing? -> Configuration error
-
-## 4. RESEARCH: Solution Investigation
+1. Why did the error occur? → X happened
+2. Why did X happen? → Y was in invalid state
+3. Why was Y invalid? → Z didn't initialize properly
+4. Why didn't Z initialize? → A dependency was missing
+5. Why was dependency missing? → Configuration error
 
-Launch **parallel subagents** for solution research:
+## 4. RESEARCH: Solution Investigation (inline or websearch)
 
-**Agent: Solution Search** (`websearch`)
-```
-Search for solutions to: {root_cause}
-Find:
-- Recommended fixes
-- Best practices
-- Workarounds if fix is complex
-```
+If root cause needs further research:
 
-Evaluate solutions:
-- Search for similar issues and solutions online
+- Use `WebSearch` inline for targeted solution search
 - Check documentation for affected libraries/frameworks
 - Look for known bugs, workarounds, and best practices
 - **THINK**: Evaluate solution approaches for this specific context
 
-## 5. IMPLEMENT: Systematic Resolution
+## 5. IMPLEMENT: Systematic Resolution (inline, lead only)
 
 - Choose the most appropriate solution based on analysis
 - Follow existing codebase patterns and conventions
@@ -119,7 +219,7 @@ Evaluate solutions:
 - **STAY IN SCOPE**: Fix only what's needed for this specific bug
 - Add defensive programming where appropriate
 
-## 6. VERIFY: Comprehensive Testing
+## 6. VERIFY: Comprehensive Testing (inline)
 
 - Test the specific scenario that was failing
 - Run related tests to ensure no regressions
@@ -146,17 +246,19 @@ Evaluate solutions:
 - Consider environmental factors
 - Check for timing/concurrency issues
 - Validate assumptions about data/state
+- Cross-reference team findings (code ↔ data ↔ docs)
 
 </analysis_techniques>
 
 <execution_rules>
 
 - **ULTRA THINK** at each phase transition
-- Use parallel agents for comprehensive investigation
+- Use **Agent Teamwork** for parallel investigation (see decision matrix)
 - Document findings and reasoning at each step
-- **NEVER guess** - validate all hypotheses with evidence
+- **NEVER guess** — validate all hypotheses with evidence
 - **MINIMAL CHANGES**: Fix root cause, not symptoms
 - Test thoroughly before declaring resolution complete
+- **ALWAYS cleanup**: shutdown teammates + TeamDelete after investigation
 
 </execution_rules>
 
@@ -169,4 +271,5 @@ Understanding > Speed > Completeness. Every bug must be fully understood before
 - Fix implemented with minimal, targeted changes
 - Original error no longer reproducible
 - Related tests pass without regressions
+- Team properly shut down (no orphan agents)
 </success_criteria>