@atlashub/smartstack-cli 1.13.2 → 1.14.0

package/templates/skills/business-analyse/steps/step-04-validate.md

@@ -0,0 +1,239 @@
+---
+name: step-04-validate
+description: Validation gate - APPROVED or REJECTED decision
+model: haiku
+prev_step: steps/step-03-specify.md
+next_step: steps/step-05-handoff.md
+---
+
+<objective>
+Validate that all specifications are complete and consistent.
+Gate decision: APPROVED or REJECTED with reasons.
+</objective>
+
+## EXECUTION SEQUENCE
+
+### 1. Read Current State
+
+Read `{output_dir}/00-context.md` for state variables.
+Read all previous outputs:
+- `1-discovery.md`
+- `2-business-requirements.md`
+- `3-functional-specification.md`
+
+Update progress: `04-validate` -> "In Progress"
+
+---
+
+### 2. Completeness Checklist
+
+**Discovery validation:**
+- [ ] Business problem clearly defined
+- [ ] All stakeholders identified
+- [ ] Scope (In/Out) explicit
+- [ ] Acceptance criteria defined
+- [ ] No critical open questions
+
+**BRD validation:**
+- [ ] All business objectives measurable
+- [ ] All business rules have BR-ID
+- [ ] Rules are testable (conditions + examples)
+- [ ] Process flow documented
+- [ ] Data entities complete
+
+**FRD validation:**
+- [ ] All UC have permission mapping
+- [ ] All FR trace to BR
+- [ ] Permission matrix complete
+- [ ] UI wireframes provided
+- [ ] Gherkin scenarios cover happy path + errors
+- [ ] i18n keys defined for messages
+
+---
+
+### 3. Consistency Checks
+
+**Cross-reference validation:**
+
+| Check | Source | Target | Status |
+|-------|--------|--------|--------|
+| BR -> FR | 2-brd.md | 3-frd.md | {OK/FAIL} |
+| AC -> UC | 1-discovery.md | 3-frd.md | {OK/FAIL} |
+| Stakeholder -> Actor | 1-discovery.md | 3-frd.md | {OK/FAIL} |
+| Entity -> Endpoint | 2-brd.md | 3-frd.md | {OK/FAIL} |
+
+**Identify gaps:**
+- BR without FR coverage
+- AC without UC coverage
+- Endpoints without permissions
+
+---
+
+### 4. SmartStack Convention Validation
+
+**Permission path format:**
+```
+VALID:   business.{app}.{module}.{action}
+INVALID: business.{app}.{action}
+INVALID: {app}.{module}.{action}
+```
+
+**NavRoute compliance:**
+- Controller route must match: `business.{app}.{module}`
+- Permissions must use same base path
+
+**Entity naming:**
+- PascalCase for entity names
+- Matches module naming convention
+
+---
+
+### 5. Risk Assessment
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| {identified risk} | High/Medium/Low | {mitigation strategy} |
+
+**Common risks to check:**
+- [ ] Missing error handling for integrations
+- [ ] Performance concerns for large datasets
+- [ ] Security gaps in permission model
+- [ ] Complex workflow without clear rollback
+
+---
+
+### 6. Make Decision
+
+**APPROVED if:**
+- All completeness checks pass (100%)
+- All consistency checks pass
+- No HIGH severity risks unmitigated
+- SmartStack conventions respected
+
+**REJECTED if:**
+- Any critical completeness check fails
+- Consistency gap found
+- HIGH severity risk without mitigation
+- Convention violations
+
+---
+
+### 7. Generate Validation Report
+
+```json
+{
+  "featureId": "{feature_id}",
+  "validatedAt": "{timestamp}",
+  "validatedBy": "Business Analyst (Claude)",
+  "decision": "APPROVED" | "REJECTED",
+  "completeness": {
+    "discovery": {
+      "score": "5/5",
+      "issues": []
+    },
+    "brd": {
+      "score": "5/5",
+      "issues": []
+    },
+    "frd": {
+      "score": "6/6",
+      "issues": []
+    }
+  },
+  "consistency": {
+    "brToFr": "OK",
+    "acToUc": "OK",
+    "stakeholderToActor": "OK",
+    "entityToEndpoint": "OK"
+  },
+  "conventions": {
+    "permissions": "OK",
+    "navRoute": "OK",
+    "naming": "OK"
+  },
+  "risks": [
+    {
+      "risk": "{description}",
+      "severity": "Medium",
+      "mitigation": "{strategy}",
+      "status": "Mitigated"
+    }
+  ],
+  "summary": "{Overall assessment}",
+  "nextStep": "step-05-handoff" | "Revision required"
+}
+```
+
+---
+
+### 8. Save Output
+
+Write to: `{output_dir}/validation.json`
+
+Update `00-context.md`:
+- Progress: `04-validate` -> "Complete"
+- Add validation status
+
+---
+
+### 9. Handle Decision
+
+**If APPROVED:**
+
+Display:
+```
+VALIDATION - {feature_id}
+├── Status: APPROVED
+├── Completeness: 100%
+├── Consistency: All checks passed
+├── Conventions: SmartStack compliant
+├── Risks: {count} mitigated
+├── Output: {output_dir}/validation.json
+└── Next: step-05-handoff (Development prompt)
+```
+
+Load next step: `steps/step-05-handoff.md`
+
+**If REJECTED:**
+
+Display:
+```
+VALIDATION - {feature_id}
+├── Status: REJECTED
+├── Issues found:
+│   ├── {issue 1}
+│   ├── {issue 2}
+│   └── {issue 3}
+├── Required actions:
+│   ├── {action 1}
+│   └── {action 2}
+└── Next: Revise specifications
+```
+
+**Ask user:**
+```json
+{
+  "questions": [
+    {
+      "question": "How would you like to proceed?",
+      "header": "Action",
+      "options": [
+        {"label": "Auto-revise", "description": "Claude fixes the identified issues"},
+        {"label": "Manual revision", "description": "You fix and relaunch validation"},
+        {"label": "Force approval", "description": "Continue despite issues (not recommended)"}
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+---
+
+## OUTPUT
+
+This step produces:
+- `{output_dir}/validation.json` (created)
+- `{output_dir}/00-context.md` (updated)
+
+Gate decision enables or blocks next step.

package/templates/skills/business-analyse/steps/step-05-handoff.md

@@ -0,0 +1,336 @@
+---
+name: step-05-handoff
+description: Handoff phase - Generate autonomous development prompt
+model: opus
+prev_step: steps/step-04-validate.md
+next_step: steps/step-06-doc-html.md
+---
+
+<objective>
+Generate a complete, autonomous development prompt for `/implement`.
+The handoff must be zero-ambiguity: a developer (or Claude) can implement without questions.
+</objective>
+
+<ultrathink>
+ULTRATHINK MODE - Handoff Generation:
+- Every implementation detail must be explicit
+- File paths must be exact
+- Patterns must reference existing code
+- No assumptions about "obvious" behavior
+</ultrathink>
+
+## EXECUTION SEQUENCE
+
+### 1. Read Current State
+
+Read `{output_dir}/00-context.md` for state variables.
+Read validation: `{output_dir}/validation.json`
+Read specs: `{output_dir}/3-functional-specification.md`
+
+Update progress: `05-handoff` -> "In Progress"
+
+---
+
+### 2. Verify Validation Passed
+
+```
+IF validation.decision != "APPROVED" THEN
+  DISPLAY ERROR: "Validation must pass before handoff"
+  EXIT to step-04-validate
+END IF
+```
+
+---
+
+### 3. Load Handoff Template
+
+```
+Read: templates/frd-handoff.md    # ~100 lines
+```
+
+---
+
+### 4. Explore Existing Patterns
+
+**CRITICAL: Handoff must reference ACTUAL code patterns!**
+
+If `{economy_mode}` = false, launch parallel agents:
+
+```
+Agent 1: Backend patterns
+  "Explore src/SmartStack.Domain/Entities/ and
+   src/SmartStack.Application/Features/ to document:
+   - Entity naming pattern
+   - CQRS handler pattern
+   - Validation pattern
+   - Repository pattern"
+
+Agent 2: Frontend patterns
+  "Explore web/smartstack-web/src/pages/business/ to document:
+   - Page component structure
+   - API service pattern
+   - i18n usage pattern
+   - Form handling pattern"
+
+Agent 3: Infrastructure patterns
+  "Explore src/SmartStack.Infrastructure/ to document:
+   - EF Core configuration pattern
+   - DbContext registration
+   - Migration naming convention"
+```
+
+If `{economy_mode}` = true:
+- Use Glob/Grep to find similar modules
+- Read 2-3 reference files directly
+
+---
+
+### 5. Map Specifications to Files
+
+**Backend files to create:**
+
+| Layer | File | Template/Pattern |
+|-------|------|------------------|
+| Domain | `src/SmartStack.Domain/Entities/Business/{Entity}.cs` | Standard entity |
+| Application | `src/SmartStack.Application/Features/{Module}/Commands/` | CQRS pattern |
+| Application | `src/SmartStack.Application/Features/{Module}/Queries/` | CQRS pattern |
+| Application | `src/SmartStack.Application/Features/{Module}/DTOs/` | Request/Response DTOs |
+| Application | `src/SmartStack.Application/Features/{Module}/Validators/` | FluentValidation |
+| Infrastructure | `src/SmartStack.Infrastructure/Persistence/Configurations/` | EF Core config |
+| API | `src/SmartStack.Api/Controllers/Business/{Module}Controller.cs` | NavRoute controller |
+
+**Frontend files to create:**
+
+| Layer | File | Pattern |
+|-------|------|---------|
+| Pages | `web/smartstack-web/src/pages/business/{app}/{module}/` | Page components |
+| Services | `web/smartstack-web/src/services/api/{module}Api.ts` | Axios service |
+| i18n | `web/smartstack-web/src/i18n/locales/{lang}/{module}.json` | 4 languages |
+
+---
+
+### 6. Generate Implementation Instructions
+
+For each file, provide explicit instructions:
+
+```markdown
+### Backend: {Entity}.cs
+
+**Path:** `src/SmartStack.Domain/Entities/Business/{Entity}.cs`
+
+**Reference:** Copy pattern from `src/SmartStack.Domain/Entities/Business/[ExistingEntity].cs`
+
+**Properties to add:**
+| Property | Type | Attributes | From BR |
+|----------|------|------------|---------|
+| Id | Guid | [Key] | - |
+| {attr1} | string | [Required, MaxLength(100)] | BR-001 |
+| {attr2} | decimal | [Precision(18,2)] | BR-002 |
+| TenantId | Guid | [Required] | Multi-tenant |
+| CreatedAt | DateTime | Audit | - |
+| UpdatedAt | DateTime | Audit | - |
+
+**Business rules to implement:**
+- BR-001: {rule} -> Implement in Validator
+- BR-002: {rule} -> Implement in Entity method
+```
+
+---
+
+### 7. Map Business Rules to Code
+
+| BR-ID | Rule | Implementation Location | Code Pattern |
+|-------|------|------------------------|--------------|
+| BR-001 | {rule} | `{Entity}Validator.cs` | `.RuleFor(x => x.Field).NotEmpty()` |
+| BR-002 | {rule} | `{Entity}.cs` method | `public bool CanXXX() { ... }` |
+| BR-003 | {rule} | `{Handler}.cs` | `if (!entity.CanXXX()) throw` |
+
+---
+
+### 8. Define API Endpoints
+
+| Endpoint | Method | Handler | Permission | Request DTO | Response DTO |
+|----------|--------|---------|------------|-------------|--------------|
+| `/api/business/{module}` | GET | `GetAll{Entity}Query` | `.read` | - | `{Entity}ListResponse` |
+| `/api/business/{module}` | POST | `Create{Entity}Command` | `.create` | `Create{Entity}Request` | `{Entity}Response` |
+| `/api/business/{module}/{id}` | GET | `Get{Entity}ByIdQuery` | `.read` | - | `{Entity}Response` |
+| `/api/business/{module}/{id}` | PUT | `Update{Entity}Command` | `.update` | `Update{Entity}Request` | `{Entity}Response` |
+| `/api/business/{module}/{id}` | DELETE | `Delete{Entity}Command` | `.delete` | - | `204` |
+
+---
+
+### 9. Generate Test Requirements
+
+**Unit tests:**
+- [ ] `{Entity}ValidatorTests.cs` - Validation rules
+- [ ] `{Entity}Tests.cs` - Entity methods
+
+**Integration tests:**
+- [ ] `{Module}ControllerTests.cs` - All endpoints
+- [ ] Permission tests - 403 for unauthorized
+- [ ] Validation tests - 400 for invalid data
+
+**Gherkin reference:** Copy scenarios from FRD section 7
+
+---
+
+### 10. Generate i18n Keys
+
+**Keys to create:**
+
+```json
+{
+  "{module}": {
+    "title": "{Module display name}",
+    "fields": {
+      "{field1}": "{Label}",
+      "{field2}": "{Label}"
+    },
+    "messages": {
+      "created": "{Entity} created successfully",
+      "updated": "{Entity} updated successfully",
+      "deleted": "{Entity} deleted successfully"
+    },
+    "errors": {
+      "{field1}Required": "{Field1} is required",
+      "notFound": "{Entity} not found",
+      "permissionDenied": "You don't have permission to perform this action"
+    },
+    "buttons": {
+      "create": "Create {Entity}",
+      "edit": "Edit",
+      "delete": "Delete",
+      "save": "Save",
+      "cancel": "Cancel"
+    }
+  }
+}
+```
+
+---
+
+### 11. Compile Handoff Document
+
+```markdown
+# Development Handoff - {feature_id} {feature_description}
+
+> **Module:** business/{application_name}/{module_name}
+> **Version:** 1.0
+> **Validated Specs:** FRD v1.0 (validation.json: APPROVED)
+> **Implementation:** `/implement {feature_id}`
+
+## DEVELOPER INSTRUCTIONS
+
+This document is a standalone prompt for Claude Code. Execute:
+```
+/implement {feature_id}
+```
+
+---
+
+## 1. QUICK CONTEXT
+
+| Attribute | Value |
+|-----------|-------|
+| Feature ID | {feature_id} |
+| Module | business/{application_name}/{module_name} |
+| Permission base | `business.{app}.{module}` |
+| Complexity | {Simple/Medium/Complex} |
+| Entities | {entity count} |
+| Endpoints | {endpoint count} |
+
+## 2. [EXPLORE] EXISTING PATTERNS
+
+{Patterns discovered in step 4}
+
+## 3. FILES TO CREATE
+
+{File mapping table}
+
+## 4. DETAILED SPECIFICATIONS
+
+{Per-file instructions}
+
+## 5. BUSINESS RULES → CODE
+
+{BR to code mapping}
+
+## 6. REQUIRED TESTS
+
+{Test checklist}
+
+## 7. POST-IMPLEMENTATION CHECKLIST
+
+- [ ] Build backend OK (`dotnet build`)
+- [ ] Build frontend OK (`pnpm build`)
+- [ ] Tests pass (`dotnet test`)
+- [ ] EF Core migration created
+- [ ] Permissions in PermissionConfiguration.cs
+- [ ] i18n complete (FR, EN, IT, DE)
+- [ ] Documentation: `/business-analyse:6-doc-html {feature_id}`
+
+---
+
+## EXECUTION
+
+```bash
+/implement {feature_id}
+```
+```
+
+---
+
+### 12. Save Output
+
+Write to: `{output_dir}/4-development-handoff.md`
+
+Update `00-context.md`:
+- Progress: `05-handoff` -> "Complete"
+
+---
+
+### 13. Display Summary and Offer Next Step
+
+**Display:**
+```
+HANDOFF - {feature_id}
+├── Status: Complete
+├── Files to create: {file count}
+├── Tests to write: {test count}
+├── Output: {output_dir}/4-development-handoff.md
+├── Execute: /implement {feature_id}
+└── Optional: step-06-doc-html (React documentation)
+```
+
+**Ask user:**
+```json
+{
+  "questions": [
+    {
+      "question": "What would you like to do now?",
+      "header": "Next",
+      "options": [
+        {"label": "Generate HTML documentation", "description": "Create the React documentation page"},
+        {"label": "Launch implementation", "description": "Execute /implement {feature_id}"},
+        {"label": "End BA", "description": "Stop here, implement later"}
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+If "Generate HTML documentation":
+```
+Read and execute: steps/step-06-doc-html.md
+```
+
+---
+
+## OUTPUT
+
+This step produces:
+- `{output_dir}/4-development-handoff.md` (created)
+- `{output_dir}/00-context.md` (updated)
+
+Handoff is ready for `/implement {feature_id}`.