---
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}`.
