ai-flow-dev 2.7.0 → 2.8.0

package/prompts/backend/flow-build-phase-9.md

@@ -1,477 +1,477 @@
-## PHASE 9: Implementation Roadmap (5-10 min)
-
-> **Order for this phase:** OPTIONAL. Executed after Phase 8 or on demand.
-
-> **📌 Scope-based behavior:**
-> - **All Scopes:** Generate a complete Implementation Roadmap with atomic tasks.
-
-### Objective
-Translate all architectural and business specifications into a prioritized, actionable implementation plan (Roadmap) with clear milestones and tasks.
-
-## Context Variables (Extract from docs)
-
-**Before generating tasks, extract these from project documentation:**
-
-```
-From ai-instructions.md:
-├── LANG: {{LANGUAGE}}           # e.g., TypeScript, Python, Go, Java, PHP, Ruby
-├── EXT: {{FILE_EXTENSION}}      # e.g., .ts, .py, .go, .java, .php, .rb
-├── SRC: {{SOURCE_DIR}}          # e.g., src/, app/, lib/, internal/
-├── TESTS: {{TESTS_DIR}}         # e.g., tests/, __tests__/, test/, spec/
-└── ARCH: {{ARCHITECTURE}}       # e.g., Clean, Hexagonal, MVC, Layered
-
-From docs/architecture.md:
-├── ENTITY_DIR: {{ENTITY_PATH}}  # e.g., entities/, models/, domain/
-├── REPO_DIR: {{REPO_PATH}}      # e.g., repositories/, data/, infrastructure/
-├── SERVICE_DIR: {{SERVICE_PATH}}# e.g., services/, usecases/, application/
-├── CTRL_DIR: {{CONTROLLER_PATH}}# e.g., controllers/, handlers/, api/
-└── DTO_DIR: {{DTO_PATH}}        # e.g., dtos/, schemas/, types/
-```
-
-**Use these variables in ALL file paths. Never hardcode language-specific paths.**
-
----
-
-## Task Format (MANDATORY)
-
-**Every task MUST use this exact format:**
-
-```
-- [ ] TXXX [CAT] Description • 1 SP → {{path}} | deps: TXXX
-```
-
-**Components:**
-- `TXXX` - Sequential ID (T001, T002...)
-- `[CAT]` - Category (see below)
-- `Description` - Specific action (verb + what + where)
-- `1 SP` - Story Points (1 or 2 only)
-- `→ {{path}}` - Target file path using context variables
-- `deps: TXXX` - Dependencies (or `deps: none`)
-
----
-
-## Categories [CAT]
-
-| Cat | Name       | Description                        | SP Range |
-|-----|------------|------------------------------------|----------|
-| [E] | Entity     | Schema, model, migration           | 1 SP     |
-| [R] | Repository | Data access layer                  | 1 SP     |
-| [S] | Service    | Business logic, use cases          | 1-2 SP   |
-| [C] | Controller | Endpoints, routes, handlers        | 1 SP     |
-| [T] | Test       | Unit, integration, e2e tests       | 1-2 SP   |
-| [D] | Docs       | Documentation updates              | 1 SP     |
-| [I] | Infra      | Config, setup, DevOps              | 1-2 SP   |
-
----
-
-## Atomic Task Rules
-
-**Maximum 1-2 SP per task. Break down larger tasks:**
-
-**BAD (too large):**
-```
-- [ ] T001 [E] Create User entity with CRUD • 5 SP
-```
-
-**GOOD (atomic, language-agnostic):**
-```
-- [ ] T001 [E] Create User entity schema (id, email, password, role) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/User{{EXT}} | deps: none
-- [ ] T002 [E] Add User validation rules (email format, password min length) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/User{{EXT}} | deps: T001
-- [ ] T003 [R] Create UserRepository interface/contract • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T001
-- [ ] T004 [R] Implement UserRepository.create() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
-- [ ] T005 [R] Implement UserRepository.findById() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
-- [ ] T006 [R] Implement UserRepository.findByEmail() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
-- [ ] T007 [R] Implement UserRepository.update() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
-- [ ] T008 [R] Implement UserRepository.delete() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
-```
-
----
-
-## Workflow: 6 Steps
-
-// turbo
-### Step 9.1: Extract Context & Inventory (10-15 min)
-
-**1. Extract context variables from `ai-instructions.md`:**
-
-```
-CONTEXT EXTRACTED
-├── Language: Python
-├── Extension: .py
-├── Source dir: src/
-├── Tests dir: tests/
-├── Architecture: Clean Architecture
-├── Entity path: domain/entities/
-├── Repository path: infrastructure/repositories/
-├── Service path: application/services/
-├── Controller path: interfaces/api/
-└── DTO path: interfaces/dtos/
-```
-
-**2. Extract inventory from documentation:**
-
-**From `docs/data-model.md`:**
-```
-ENTITIES:
-| Entity   | Fields | Relations | Complexity |
-|----------|--------|-----------|------------|
-| User     | 8      | 3 (1:N)   | Medium     |
-| Product  | 12     | 2 (N:1)   | Medium     |
-
-Complexity: Simple (1-5 fields) | Medium (6-10) | Complex (11+)
-```
-
-**From `docs/api.md`:**
-```
-ENDPOINTS:
-| Method | Path           | Auth | Body | Complexity |
-|--------|----------------|------|------|------------|
-| POST   | /auth/login    | No   | Yes  | Medium     |
-| GET    | /users/:id     | Yes  | No   | Simple     |
-
-Complexity: Simple (no body) | Medium (body+validation) | Complex (transactions)
-```
-
-**From `docs/architecture.md`:**
-```
-INTEGRATIONS:
-| Service  | Type    | Priority |
-|----------|---------|----------|
-| Stripe   | Payment | P0       |
-| SendGrid | Email   | P1       |
-```
-
-**From `specs/security.md`:**
-```
-SECURITY:
-| Requirement       | Category | Priority |
-|-------------------|----------|----------|
-| JWT Auth          | Auth     | P0       |
-| Password Hashing  | Auth     | P0       |
-| Rate Limiting     | Security | P1       |
-```
-
-**Show summary:**
-```
-INVENTORY COMPLETE
-├── Context: {{LANGUAGE}} / {{ARCHITECTURE}}
-├── Entities: X (simple: X, medium: X, complex: X)
-├── Endpoints: X (simple: X, medium: X, complex: X)
-├── Integrations: X
-├── Security: X requirements
-└── Estimated tasks: XXX-XXX
-```
-
----
-
-### Step 9.2: Coverage Matrix (5-10 min)
-
-**BUILD MANDATORY COVERAGE MATRIX before generating tasks:**
-
-```
-COVERAGE MATRIX
-┌────────────┬─────┬─────┬─────┬─────┬─────┬─────┐
-│ Component  │ [E] │ [R] │ [S] │ [C] │ [T] │ [D] │
-├────────────┼─────┼─────┼─────┼─────┼─────┼─────┤
-│ User       │  ?  │  ?  │  ?  │  ?  │  ?  │  ?  │
-│ Product    │  ?  │  ?  │  ?  │  ?  │  ?  │  ?  │
-│ POST /auth │  -  │  -  │  ?  │  ?  │  ?  │  ?  │
-│ GET /users │  -  │  -  │  ?  │  ?  │  ?  │  ?  │
-└────────────┴─────┴─────┴─────┴─────┴─────┴─────┘
-
-Legend: ? = needs task | ✓ = has task | - = not applicable
-```
-
-**Rules:**
-- Every Entity MUST have: [E], [R], [S], [T], [D]
-- Every Endpoint MUST have: [S] or [C], [T], [D]
-- Every Integration MUST have: [S], [T], [D]
-
----
-
-### Step 9.3: Epic Definition (5-10 min)
-
-**Standard Epic Structure:**
-
-```
-EP-000: Foundation (ALWAYS FIRST)
-├── Config, error handling, logging
-├── Database connection, base classes
-└── Priority: P0 | Duration: Week 1
-
-EP-001: Authentication (ALWAYS SECOND if auth exists)
-├── Auth mechanism, password hashing, sessions/tokens
-├── Security requirements from specs/security.md
-└── Priority: P0 | Duration: Week 1-2
-
-EP-XXX: Domain Epics (Group by bounded context)
-├── Related entities + endpoints
-└── Priority: P0/P1/P2
-
-EP-ZZZ: Operations (ALWAYS LAST)
-├── CI/CD, monitoring, deployment
-└── Priority: P1 | Duration: Final week
-```
-
----
-
-### Step 9.4: Task Generation by Component Type (30-45 min)
-
-**For each Entity, generate tasks using context variables:**
-
-```markdown
-### Entity: {{NAME}} ({{COMPLEXITY}})
-
-**[E] Schema (2-3 tasks):**
-- [ ] T0XX [E] Create {{NAME}} entity schema (fields: ...) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/{{NAME}}{{EXT}} | deps: none
-- [ ] T0XX [E] Add {{NAME}} validation rules (field constraints) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/{{NAME}}{{EXT}} | deps: T0XX
-- [ ] T0XX [E] Create {{NAME}} database migration • 1 SP → {{MIGRATIONS_DIR}}/XXX_{{name}}{{MIGRATION_EXT}} | deps: T0XX
-
-**[R] Repository (4-6 tasks):**
-- [ ] T0XX [R] Create {{NAME}}Repository interface/contract • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-- [ ] T0XX [R] Implement {{NAME}}Repository.create() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-- [ ] T0XX [R] Implement {{NAME}}Repository.findById() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-- [ ] T0XX [R] Implement {{NAME}}Repository.findAll() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-- [ ] T0XX [R] Implement {{NAME}}Repository.update() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-- [ ] T0XX [R] Implement {{NAME}}Repository.delete() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
-
-**[S] Service (2-4 tasks based on business logic):**
-- [ ] T0XX [S] Create {{NAME}}Service with dependency injection • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
-- [ ] T0XX [S] Implement {{NAME}}Service.create() with validation • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
-- [ ] T0XX [S] Implement {{NAME}}Service business rules • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
-
-**[T] Tests (3-5 tasks):**
-- [ ] T0XX [T] Write {{NAME}} entity unit tests (5+ cases) • 2 SP → {{TESTS}}/unit/{{NAME}}{{TEST_EXT}} | deps: T0XX
-- [ ] T0XX [T] Write {{NAME}}Repository integration tests • 2 SP → {{TESTS}}/integration/{{NAME}}Repository{{TEST_EXT}} | deps: T0XX
-- [ ] T0XX [T] Write {{NAME}}Service unit tests • 2 SP → {{TESTS}}/unit/{{NAME}}Service{{TEST_EXT}} | deps: T0XX
-
-**[D] Documentation (1 task):**
-- [ ] T0XX [D] Update data-model.md with {{NAME}} schema • 1 SP → docs/data-model.md | deps: T0XX
-```
-
-**For each Endpoint, generate tasks:**
-
-```markdown
-### Endpoint: {{METHOD}} {{PATH}}
-
-**[C] Controller (2-3 tasks):**
-- [ ] T0XX [C] Create {{METHOD}} {{PATH}} handler • 1 SP → {{SRC}}/{{CTRL_DIR}}/{{Controller}}{{EXT}} | deps: T0XX
-- [ ] T0XX [C] Add request validation schema • 1 SP → {{SRC}}/{{DTO_DIR}}/{{DTO}}{{EXT}} | deps: T0XX
-- [ ] T0XX [C] Add response schema • 1 SP → {{SRC}}/{{DTO_DIR}}/{{DTO}}{{EXT}} | deps: T0XX
-
-**[T] Tests (1-2 tasks):**
-- [ ] T0XX [T] Write {{METHOD}} {{PATH}} integration test • 2 SP → {{TESTS}}/integration/{{Controller}}{{TEST_EXT}} | deps: T0XX
-
-**[D] Documentation (1 task):**
-- [ ] T0XX [D] Document {{METHOD}} {{PATH}} in api.md • 1 SP → docs/api.md | deps: T0XX
-```
-
----
-
-### Step 9.5: Validate Coverage (5 min)
-
-**MANDATORY: Verify matrix is complete before generating document:**
-
-```
-COVERAGE VALIDATION
-┌────────────┬─────┬─────┬─────┬─────┬─────┬─────┐
-│ Component  │ [E] │ [R] │ [S] │ [C] │ [T] │ [D] │
-├────────────┼─────┼─────┼─────┼─────┼─────┼─────┤
-│ User       │ T01 │T03-8│ T09 │ T12 │T15-17│ T18│
-│ Product    │ T20 │T22-27│T28 │ T31 │T34-36│ T37│
-│ POST /auth │  -  │  -  │ T40 │ T41 │ T43 │ T44│
-│ GET /users │  -  │  -  │ T45 │ T46 │ T48 │ T49│
-└────────────┴─────┴─────┴─────┴─────┴─────┴─────┘
-
-✅ All entities have [E], [R], [S], [T], [D]
-✅ All endpoints have [S] or [C], [T], [D]
-✅ No gaps in coverage
-```
-
-**If gaps exist:**
-```
-❌ COVERAGE ERROR: Product missing [T] category
-   → Add: T0XX [T] Write Product unit tests • 2 SP → {{TESTS}}/unit/Product{{TEST_EXT}}
-```
-
----
-
-### Step 9.6: Generate Document (5-10 min)
-
-## Architectural Markers Key
-
-| Marker | Name | Description |
-|--------|------|-------------|
-| **[I]** | Infrastructure | Technical setup, configuration, and core utilities |
-| **[E]** | Entity | Database models and schema definitions |
-| **[R]** | Repository | Data access layer (Prisma ORM) |
-| **[S]** | Service | Business logic and use cases |
-| **[C]** | Controller | API endpoints and request handling |
-| **[T]** | Tests | Unit, integration, and E2E testing |
-| **[D]** | Documentation | Technical and API documentation |
-
----
-
-**Write `planning/roadmap.md` with this structure:**
-
-```markdown
-# Implementation Roadmap: {{PROJECT_NAME}}
-
-> Generated: {{DATE}} | Total: {{SP}} SP | Estimated: {{WEEKS}} weeks
-> Stack: {{LANGUAGE}} / {{FRAMEWORK}} / {{ARCHITECTURE}}
-
-## Project Context
-
-| Variable | Value |
-|----------|-------|
-| Language | {{LANGUAGE}} |
-| Source Dir | {{SRC}} |
-| Tests Dir | {{TESTS}} |
-| Architecture | {{ARCHITECTURE}} |
-
-## Story Points Scale
-
-| SP | Effort    | Time      |
-|----|-----------|-----------|
-| 1  | Trivial   | 1-2h      |
-| 2  | Small     | 2-4h      |
-
-## Coverage Matrix
-
-{{COVERAGE_MATRIX}}
-
-## Epic Overview
-
-| Epic | Name           | SP  | Tasks | Priority |
-|------|----------------|-----|-------|----------|
-| EP-000 | Foundation   | XX  | XX    | P0       |
-| EP-001 | Auth         | XX  | XX    | P0       |
-
-## EP-000: Foundation • XX SP
-
-### Feature 0.1: Base Configuration • X SP
-
-{{TASKS}}
-
-## EP-001: Authentication • XX SP
-
-### Feature 1.1: User Entity • X SP
-
-{{TASKS}}
-
-### Feature 1.2: Login Endpoint • X SP
-
-{{TASKS}}
-
-## Dependency Graph
-
-```mermaid
-graph TD
-    EP000[Foundation] --> EP001[Auth]
-    EP000 --> EP002[Users]
-    EP001 --> EP003[Products]
-```
-
-## Production Checklist
-
-- [ ] All migrations tested
-- [ ] Test coverage >= 80%
-- [ ] API documentation complete
-- [ ] Security requirements verified
-- [ ] CI/CD pipeline working
-```
-
----
-
-## Validation Checklist
-
-Before completing Phase 9:
-
-- [ ] Context variables extracted from ai-instructions.md
-- [ ] All file paths use {{VARIABLE}} format (no hardcoded .ts, .py, etc.)
-- [ ] Every entity has [E], [R], [S], [T], [D] tasks
-- [ ] Every endpoint has [C] or [S], [T], [D] tasks
-- [ ] All tasks use exact format: `TXXX [CAT] Desc • N SP → {{path}} | deps: X`
-- [ ] No task exceeds 2 SP
-- [ ] Coverage matrix shows no gaps
-- [ ] Task IDs are sequential (T001, T002, T003...)
-- [ ] Dependencies form valid DAG (no cycles)
-
-## DO NOT
-
-- ❌ Hardcode file extensions (.ts, .py, .go, .java)
-- ❌ Hardcode directory structures (src/entities/, app/models/)
-- ❌ Assume specific architecture patterns
-- ❌ Use language-specific naming conventions (IRepository, _private)
-- ❌ Create tasks > 2 SP
-- ❌ Skip coverage matrix validation
-- ❌ Leave entities without tests
-
-## Summary
-
-```
-PHASE 9 COMPLETE
-├── Stack: {{LANGUAGE}} / {{FRAMEWORK}}
-├── Epics: X
-├── Features: X
-├── Tasks: X
-├── Story Points: X SP
-├── Coverage: 100% (all components have [E][R][S][C][T][D])
-└── Ready for: /flow-dev-feature
-
-Next: Open planning/roadmap.md and start with EP-000, or continue to Phase 10 for detailed User Stories.
-
-**OFFER PHASE 10:**
-
-```
----
-✅ PHASE 9 COMPLETE: IMPLEMENTATION ROADMAP GENERATED
----
-🎯 Roadmap created in planning/roadmap.md
-📊 Total Story Points: {{SP}}
-🏗️ Epics defined: {{EPICS_COUNT}}
----
-🚀 Optional: Generate Detailed User Stories?
----
-Phase 10 will convert your roadmap features into detailed User Stories with:
-
-✅ Gherkin-style Acceptance Criteria (Given/When/Then)
-✅ Functional, Error, Edge, and Security scenarios
-✅ Technical details inherited from patterns
-✅ Ready-to-use QA Test Cases with data
-✅ Definition of Done (DoD) checklist
-
-⏱️ Estimated time: 30-60 minutes
-
-Would you like to continue to Phase 10?
-
-A) ✅ Yes, generate User Stories now (recommended)
-   → Best for Sprint planning and QA alignment
-   → Will generate {{FEATURES_COUNT}} User Stories
-
-B) ⏭️ Skip for now (you can run Phase 10 later)
-   → You can start coding directly from roadmap
-   → Run Phase 10 anytime: /flow-build fase 10
-
-Your choice (A/B): __
-```
-
----
-
-## 📝 Generated Documents
-
-After Phase 9, generate/update:
-
-- `planning/roadmap.md` - Technical implementation plan
-
----
-
-**Next Phase:** Phase 10 - Agile Planning (User Stories)
-
-Read: `.ai-flow/prompts/backend/flow-build-phase-10.md`
-
----
-
-**Last Updated:** 2025-12-20
-**Version:** 2.1.8
-
+## PHASE 9: Implementation Roadmap (5-10 min)
+
+> **Order for this phase:** OPTIONAL. Executed after Phase 8 or on demand.
+
+> **📌 Scope-based behavior:**
+> - **All Scopes:** Generate a complete Implementation Roadmap with atomic tasks.
+
+### Objective
+Translate all architectural and business specifications into a prioritized, actionable implementation plan (Roadmap) with clear milestones and tasks.
+
+## Context Variables (Extract from docs)
+
+**Before generating tasks, extract these from project documentation:**
+
+```
+From ai-instructions.md:
+├── LANG: {{LANGUAGE}}           # e.g., TypeScript, Python, Go, Java, PHP, Ruby
+├── EXT: {{FILE_EXTENSION}}      # e.g., .ts, .py, .go, .java, .php, .rb
+├── SRC: {{SOURCE_DIR}}          # e.g., src/, app/, lib/, internal/
+├── TESTS: {{TESTS_DIR}}         # e.g., tests/, __tests__/, test/, spec/
+└── ARCH: {{ARCHITECTURE}}       # e.g., Clean, Hexagonal, MVC, Layered
+
+From docs/architecture.md:
+├── ENTITY_DIR: {{ENTITY_PATH}}  # e.g., entities/, models/, domain/
+├── REPO_DIR: {{REPO_PATH}}      # e.g., repositories/, data/, infrastructure/
+├── SERVICE_DIR: {{SERVICE_PATH}}# e.g., services/, usecases/, application/
+├── CTRL_DIR: {{CONTROLLER_PATH}}# e.g., controllers/, handlers/, api/
+└── DTO_DIR: {{DTO_PATH}}        # e.g., dtos/, schemas/, types/
+```
+
+**Use these variables in ALL file paths. Never hardcode language-specific paths.**
+
+---
+
+## Task Format (MANDATORY)
+
+**Every task MUST use this exact format:**
+
+```
+- [ ] TXXX [CAT] Description • 1 SP → {{path}} | deps: TXXX
+```
+
+**Components:**
+- `TXXX` - Sequential ID (T001, T002...)
+- `[CAT]` - Category (see below)
+- `Description` - Specific action (verb + what + where)
+- `1 SP` - Story Points (1 or 2 only)
+- `→ {{path}}` - Target file path using context variables
+- `deps: TXXX` - Dependencies (or `deps: none`)
+
+---
+
+## Categories [CAT]
+
+| Cat | Name       | Description                        | SP Range |
+|-----|------------|------------------------------------|----------|
+| [E] | Entity     | Schema, model, migration           | 1 SP     |
+| [R] | Repository | Data access layer                  | 1 SP     |
+| [S] | Service    | Business logic, use cases          | 1-2 SP   |
+| [C] | Controller | Endpoints, routes, handlers        | 1 SP     |
+| [T] | Test       | Unit, integration, e2e tests       | 1-2 SP   |
+| [D] | Docs       | Documentation updates              | 1 SP     |
+| [I] | Infra      | Config, setup, DevOps              | 1-2 SP   |
+
+---
+
+## Atomic Task Rules
+
+**Maximum 1-2 SP per task. Break down larger tasks:**
+
+**BAD (too large):**
+```
+- [ ] T001 [E] Create User entity with CRUD • 5 SP
+```
+
+**GOOD (atomic, language-agnostic):**
+```
+- [ ] T001 [E] Create User entity schema (id, email, password, role) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/User{{EXT}} | deps: none
+- [ ] T002 [E] Add User validation rules (email format, password min length) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/User{{EXT}} | deps: T001
+- [ ] T003 [R] Create UserRepository interface/contract • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T001
+- [ ] T004 [R] Implement UserRepository.create() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
+- [ ] T005 [R] Implement UserRepository.findById() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
+- [ ] T006 [R] Implement UserRepository.findByEmail() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
+- [ ] T007 [R] Implement UserRepository.update() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
+- [ ] T008 [R] Implement UserRepository.delete() • 1 SP → {{SRC}}/{{REPO_DIR}}/UserRepository{{EXT}} | deps: T003
+```
+
+---
+
+## Workflow: 6 Steps
+
+// turbo
+### Step 9.1: Extract Context & Inventory (10-15 min)
+
+**1. Extract context variables from `ai-instructions.md`:**
+
+```
+CONTEXT EXTRACTED
+├── Language: Python
+├── Extension: .py
+├── Source dir: src/
+├── Tests dir: tests/
+├── Architecture: Clean Architecture
+├── Entity path: domain/entities/
+├── Repository path: infrastructure/repositories/
+├── Service path: application/services/
+├── Controller path: interfaces/api/
+└── DTO path: interfaces/dtos/
+```
+
+**2. Extract inventory from documentation:**
+
+**From `docs/data-model.md`:**
+```
+ENTITIES:
+| Entity   | Fields | Relations | Complexity |
+|----------|--------|-----------|------------|
+| User     | 8      | 3 (1:N)   | Medium     |
+| Product  | 12     | 2 (N:1)   | Medium     |
+
+Complexity: Simple (1-5 fields) | Medium (6-10) | Complex (11+)
+```
+
+**From `docs/api.md`:**
+```
+ENDPOINTS:
+| Method | Path           | Auth | Body | Complexity |
+|--------|----------------|------|------|------------|
+| POST   | /auth/login    | No   | Yes  | Medium     |
+| GET    | /users/:id     | Yes  | No   | Simple     |
+
+Complexity: Simple (no body) | Medium (body+validation) | Complex (transactions)
+```
+
+**From `docs/architecture.md`:**
+```
+INTEGRATIONS:
+| Service  | Type    | Priority |
+|----------|---------|----------|
+| Stripe   | Payment | P0       |
+| SendGrid | Email   | P1       |
+```
+
+**From `specs/security.md`:**
+```
+SECURITY:
+| Requirement       | Category | Priority |
+|-------------------|----------|----------|
+| JWT Auth          | Auth     | P0       |
+| Password Hashing  | Auth     | P0       |
+| Rate Limiting     | Security | P1       |
+```
+
+**Show summary:**
+```
+INVENTORY COMPLETE
+├── Context: {{LANGUAGE}} / {{ARCHITECTURE}}
+├── Entities: X (simple: X, medium: X, complex: X)
+├── Endpoints: X (simple: X, medium: X, complex: X)
+├── Integrations: X
+├── Security: X requirements
+└── Estimated tasks: XXX-XXX
+```
+
+---
+
+### Step 9.2: Coverage Matrix (5-10 min)
+
+**BUILD MANDATORY COVERAGE MATRIX before generating tasks:**
+
+```
+COVERAGE MATRIX
+┌────────────┬─────┬─────┬─────┬─────┬─────┬─────┐
+│ Component  │ [E] │ [R] │ [S] │ [C] │ [T] │ [D] │
+├────────────┼─────┼─────┼─────┼─────┼─────┼─────┤
+│ User       │  ?  │  ?  │  ?  │  ?  │  ?  │  ?  │
+│ Product    │  ?  │  ?  │  ?  │  ?  │  ?  │  ?  │
+│ POST /auth │  -  │  -  │  ?  │  ?  │  ?  │  ?  │
+│ GET /users │  -  │  -  │  ?  │  ?  │  ?  │  ?  │
+└────────────┴─────┴─────┴─────┴─────┴─────┴─────┘
+
+Legend: ? = needs task | ✓ = has task | - = not applicable
+```
+
+**Rules:**
+- Every Entity MUST have: [E], [R], [S], [T], [D]
+- Every Endpoint MUST have: [S] or [C], [T], [D]
+- Every Integration MUST have: [S], [T], [D]
+
+---
+
+### Step 9.3: Epic Definition (5-10 min)
+
+**Standard Epic Structure:**
+
+```
+EP-000: Foundation (ALWAYS FIRST)
+├── Config, error handling, logging
+├── Database connection, base classes
+└── Priority: P0 | Duration: Week 1
+
+EP-001: Authentication (ALWAYS SECOND if auth exists)
+├── Auth mechanism, password hashing, sessions/tokens
+├── Security requirements from specs/security.md
+└── Priority: P0 | Duration: Week 1-2
+
+EP-XXX: Domain Epics (Group by bounded context)
+├── Related entities + endpoints
+└── Priority: P0/P1/P2
+
+EP-ZZZ: Operations (ALWAYS LAST)
+├── CI/CD, monitoring, deployment
+└── Priority: P1 | Duration: Final week
+```
+
+---
+
+### Step 9.4: Task Generation by Component Type (30-45 min)
+
+**For each Entity, generate tasks using context variables:**
+
+```markdown
+### Entity: {{NAME}} ({{COMPLEXITY}})
+
+**[E] Schema (2-3 tasks):**
+- [ ] T0XX [E] Create {{NAME}} entity schema (fields: ...) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/{{NAME}}{{EXT}} | deps: none
+- [ ] T0XX [E] Add {{NAME}} validation rules (field constraints) • 1 SP → {{SRC}}/{{ENTITY_DIR}}/{{NAME}}{{EXT}} | deps: T0XX
+- [ ] T0XX [E] Create {{NAME}} database migration • 1 SP → {{MIGRATIONS_DIR}}/XXX_{{name}}{{MIGRATION_EXT}} | deps: T0XX
+
+**[R] Repository (4-6 tasks):**
+- [ ] T0XX [R] Create {{NAME}}Repository interface/contract • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+- [ ] T0XX [R] Implement {{NAME}}Repository.create() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+- [ ] T0XX [R] Implement {{NAME}}Repository.findById() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+- [ ] T0XX [R] Implement {{NAME}}Repository.findAll() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+- [ ] T0XX [R] Implement {{NAME}}Repository.update() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+- [ ] T0XX [R] Implement {{NAME}}Repository.delete() • 1 SP → {{SRC}}/{{REPO_DIR}}/{{NAME}}Repository{{EXT}} | deps: T0XX
+
+**[S] Service (2-4 tasks based on business logic):**
+- [ ] T0XX [S] Create {{NAME}}Service with dependency injection • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
+- [ ] T0XX [S] Implement {{NAME}}Service.create() with validation • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
+- [ ] T0XX [S] Implement {{NAME}}Service business rules • 1 SP → {{SRC}}/{{SERVICE_DIR}}/{{NAME}}Service{{EXT}} | deps: T0XX
+
+**[T] Tests (3-5 tasks):**
+- [ ] T0XX [T] Write {{NAME}} entity unit tests (5+ cases) • 2 SP → {{TESTS}}/unit/{{NAME}}{{TEST_EXT}} | deps: T0XX
+- [ ] T0XX [T] Write {{NAME}}Repository integration tests • 2 SP → {{TESTS}}/integration/{{NAME}}Repository{{TEST_EXT}} | deps: T0XX
+- [ ] T0XX [T] Write {{NAME}}Service unit tests • 2 SP → {{TESTS}}/unit/{{NAME}}Service{{TEST_EXT}} | deps: T0XX
+
+**[D] Documentation (1 task):**
+- [ ] T0XX [D] Update data-model.md with {{NAME}} schema • 1 SP → docs/data-model.md | deps: T0XX
+```
+
+**For each Endpoint, generate tasks:**
+
+```markdown
+### Endpoint: {{METHOD}} {{PATH}}
+
+**[C] Controller (2-3 tasks):**
+- [ ] T0XX [C] Create {{METHOD}} {{PATH}} handler • 1 SP → {{SRC}}/{{CTRL_DIR}}/{{Controller}}{{EXT}} | deps: T0XX
+- [ ] T0XX [C] Add request validation schema • 1 SP → {{SRC}}/{{DTO_DIR}}/{{DTO}}{{EXT}} | deps: T0XX
+- [ ] T0XX [C] Add response schema • 1 SP → {{SRC}}/{{DTO_DIR}}/{{DTO}}{{EXT}} | deps: T0XX
+
+**[T] Tests (1-2 tasks):**
+- [ ] T0XX [T] Write {{METHOD}} {{PATH}} integration test • 2 SP → {{TESTS}}/integration/{{Controller}}{{TEST_EXT}} | deps: T0XX
+
+**[D] Documentation (1 task):**
+- [ ] T0XX [D] Document {{METHOD}} {{PATH}} in api.md • 1 SP → docs/api.md | deps: T0XX
+```
+
+---
+
+### Step 9.5: Validate Coverage (5 min)
+
+**MANDATORY: Verify matrix is complete before generating document:**
+
+```
+COVERAGE VALIDATION
+┌────────────┬─────┬─────┬─────┬─────┬─────┬─────┐
+│ Component  │ [E] │ [R] │ [S] │ [C] │ [T] │ [D] │
+├────────────┼─────┼─────┼─────┼─────┼─────┼─────┤
+│ User       │ T01 │T03-8│ T09 │ T12 │T15-17│ T18│
+│ Product    │ T20 │T22-27│T28 │ T31 │T34-36│ T37│
+│ POST /auth │  -  │  -  │ T40 │ T41 │ T43 │ T44│
+│ GET /users │  -  │  -  │ T45 │ T46 │ T48 │ T49│
+└────────────┴─────┴─────┴─────┴─────┴─────┴─────┘
+
+✅ All entities have [E], [R], [S], [T], [D]
+✅ All endpoints have [S] or [C], [T], [D]
+✅ No gaps in coverage
+```
+
+**If gaps exist:**
+```
+❌ COVERAGE ERROR: Product missing [T] category
+   → Add: T0XX [T] Write Product unit tests • 2 SP → {{TESTS}}/unit/Product{{TEST_EXT}}
+```
+
+---
+
+### Step 9.6: Generate Document (5-10 min)
+
+## Architectural Markers Key
+
+| Marker | Name | Description |
+|--------|------|-------------|
+| **[I]** | Infrastructure | Technical setup, configuration, and core utilities |
+| **[E]** | Entity | Database models and schema definitions |
+| **[R]** | Repository | Data access layer (Prisma ORM) |
+| **[S]** | Service | Business logic and use cases |
+| **[C]** | Controller | API endpoints and request handling |
+| **[T]** | Tests | Unit, integration, and E2E testing |
+| **[D]** | Documentation | Technical and API documentation |
+
+---
+
+**Write `planning/roadmap.md` with this structure:**
+
+```markdown
+# Implementation Roadmap: {{PROJECT_NAME}}
+
+> Generated: {{DATE}} | Total: {{SP}} SP | Estimated: {{WEEKS}} weeks
+> Stack: {{LANGUAGE}} / {{FRAMEWORK}} / {{ARCHITECTURE}}
+
+## Project Context
+
+| Variable | Value |
+|----------|-------|
+| Language | {{LANGUAGE}} |
+| Source Dir | {{SRC}} |
+| Tests Dir | {{TESTS}} |
+| Architecture | {{ARCHITECTURE}} |
+
+## Story Points Scale
+
+| SP | Effort    | Time      |
+|----|-----------|-----------|
+| 1  | Trivial   | 1-2h      |
+| 2  | Small     | 2-4h      |
+
+## Coverage Matrix
+
+{{COVERAGE_MATRIX}}
+
+## Epic Overview
+
+| Epic | Name           | SP  | Tasks | Priority |
+|------|----------------|-----|-------|----------|
+| EP-000 | Foundation   | XX  | XX    | P0       |
+| EP-001 | Auth         | XX  | XX    | P0       |
+
+## EP-000: Foundation • XX SP
+
+### Feature 0.1: Base Configuration • X SP
+
+{{TASKS}}
+
+## EP-001: Authentication • XX SP
+
+### Feature 1.1: User Entity • X SP
+
+{{TASKS}}
+
+### Feature 1.2: Login Endpoint • X SP
+
+{{TASKS}}
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    EP000[Foundation] --> EP001[Auth]
+    EP000 --> EP002[Users]
+    EP001 --> EP003[Products]
+```
+
+## Production Checklist
+
+- [ ] All migrations tested
+- [ ] Test coverage >= 80%
+- [ ] API documentation complete
+- [ ] Security requirements verified
+- [ ] CI/CD pipeline working
+```
+
+---
+
+## Validation Checklist
+
+Before completing Phase 9:
+
+- [ ] Context variables extracted from ai-instructions.md
+- [ ] All file paths use {{VARIABLE}} format (no hardcoded .ts, .py, etc.)
+- [ ] Every entity has [E], [R], [S], [T], [D] tasks
+- [ ] Every endpoint has [C] or [S], [T], [D] tasks
+- [ ] All tasks use exact format: `TXXX [CAT] Desc • N SP → {{path}} | deps: X`
+- [ ] No task exceeds 2 SP
+- [ ] Coverage matrix shows no gaps
+- [ ] Task IDs are sequential (T001, T002, T003...)
+- [ ] Dependencies form valid DAG (no cycles)
+
+## DO NOT
+
+- ❌ Hardcode file extensions (.ts, .py, .go, .java)
+- ❌ Hardcode directory structures (src/entities/, app/models/)
+- ❌ Assume specific architecture patterns
+- ❌ Use language-specific naming conventions (IRepository, _private)
+- ❌ Create tasks > 2 SP
+- ❌ Skip coverage matrix validation
+- ❌ Leave entities without tests
+
+## Summary
+
+```
+PHASE 9 COMPLETE
+├── Stack: {{LANGUAGE}} / {{FRAMEWORK}}
+├── Epics: X
+├── Features: X
+├── Tasks: X
+├── Story Points: X SP
+├── Coverage: 100% (all components have [E][R][S][C][T][D])
+└── Ready for: /flow-dev-feature
+
+Next: Open planning/roadmap.md and start with EP-000, or continue to Phase 10 for detailed User Stories.
+
+**OFFER PHASE 10:**
+
+```
+---
+✅ PHASE 9 COMPLETE: IMPLEMENTATION ROADMAP GENERATED
+---
+🎯 Roadmap created in planning/roadmap.md
+📊 Total Story Points: {{SP}}
+🏗️ Epics defined: {{EPICS_COUNT}}
+---
+🚀 Optional: Generate Detailed User Stories?
+---
+Phase 10 will convert your roadmap features into detailed User Stories with:
+
+✅ Gherkin-style Acceptance Criteria (Given/When/Then)
+✅ Functional, Error, Edge, and Security scenarios
+✅ Technical details inherited from patterns
+✅ Ready-to-use QA Test Cases with data
+✅ Definition of Done (DoD) checklist
+
+⏱️ Estimated time: 30-60 minutes
+
+Would you like to continue to Phase 10?
+
+A) ✅ Yes, generate User Stories now (recommended)
+   → Best for Sprint planning and QA alignment
+   → Will generate {{FEATURES_COUNT}} User Stories
+
+B) ⏭️ Skip for now (you can run Phase 10 later)
+   → You can start coding directly from roadmap
+   → Run Phase 10 anytime: /flow-build fase 10
+
+Your choice (A/B): __
+```
+
+---
+
+## 📝 Generated Documents
+
+After Phase 9, generate/update:
+
+- `planning/roadmap.md` - Technical implementation plan
+
+---
+
+**Next Phase:** Phase 10 - Agile Planning (User Stories)
+
+Read: `.ai-flow/prompts/backend/flow-build-phase-10.md`
+
+---
+
+**Last Updated:** 2025-12-20
+**Version:** 2.1.8
+