ai-flow-dev 1.3.0 → 2.0.1

package/prompts/backend/{flow-bootstrap-phase-9.md → flow-build-phase-9.md}

@@ -259,6 +259,89 @@ Story Points | Complexity | Typical Time | Examples
 34 SP        | Epic       | 3 weeks      | Multiple related features
 ```
 
+---
+
+### Story Points to Time Conversion (Hybrid Estimation)
+
+**Use this table to add time estimates to each task:**
+
+| Story Points | Time Estimate (solo dev) | Time Range | Example Task                            |
+| ------------ | ------------------------ | ---------- | --------------------------------------- |
+| **1 SP**     | 1-2 hours                | (~1-2h)    | Add enum value, simple config change    |
+| **2 SP**     | 3-4 hours                | (~3-4h)    | Write 5-8 unit tests, basic validation  |
+| **3 SP**     | 4-8 hours                | (~4-8h)    | Simple CRUD endpoint, basic entity      |
+| **5 SP**     | 1-2 days                 | (~1-2d)    | Complex endpoint with business logic    |
+| **8 SP**     | 2-3 days                 | (~2-3d)    | Auth flow, complex validation           |
+| **13 SP**    | 1 week                   | (~1w)      | Complete module with full test coverage |
+| **21 SP**    | 2 weeks                  | (~2w)      | Major feature with integration          |
+| **34 SP**    | 3 weeks                  | (~3w)      | Multiple related features (Epic-level)  |
+
+> **Note:** Time assumes AI-assisted development (GitHub Copilot, Claude, etc.). Without AI assistance, multiply time estimates by 2-3x.
+>
+> **Velocity Tracking:** After completing 2-3 features, compare actual time vs estimates to calibrate your team's velocity. Adjust remaining estimates accordingly.
+
+**How to use hybrid estimation:**
+
+- Each task shows **both** Story Points and time: `• 2 SP (~3-4h)`
+- Story Points measure **complexity** (stable across teams)
+- Time estimates measure **effort** (varies by team velocity)
+- Track both to improve estimation accuracy over time
+
+---
+
+### Task Format Reference (Spec-Kit Inspired)
+
+**Every task must follow this format:**
+
+```markdown
+- [ ] [TaskID] [Optional:P] [Optional:StoryTag] Description • SP (~time)
+      File: exact/path/to/file.ts
+      Dependencies: T001, T002 (or "None")
+```
+
+**Components explained:**
+
+- **[TaskID]**: Sequential ID in execution order (T001, T002, ..., T099, T100)
+- **[P] marker**: ONLY for parallelizable tasks (different files, no blocking deps)
+- **[StoryTag]**: Links task to user story ([US1], [US2]) - only in story phases
+- **Description**: What to implement (specific, LLM-completable without additional context)
+- **• SP (~time)**: Hybrid estimation - Story Points + time (e.g., "2 SP (~3-4h)", "5 SP (~1-2d)")
+- **File path**: Exact file where work happens (REQUIRED)
+- **Dependencies**: Which tasks must complete first (REQUIRED, even if "None")
+
+**Task Sequencing Rules:**
+
+1. **Tests BEFORE implementation** (TDD approach)
+2. **Models → Services → Controllers → Endpoints** (layer dependency order)
+3. **Core utilities BEFORE features** that use them
+4. **Database migrations BEFORE data access code**
+5. **Interfaces BEFORE implementations**
+
+**Parallelization Rules ([P] marker):**
+
+✅ **Use [P] when:**
+
+- Tasks target different files
+- No shared dependencies between tasks
+- Can run simultaneously (e.g., independent entities, different modules)
+
+❌ **Don't use [P] when:**
+
+- Task depends on another incomplete task
+- Same file is modified by multiple tasks
+- Shared resource (DB migration, config file, shared service)
+
+**Example task with all components:**
+
+```markdown
+- [ ] [T042] [P] Write unit tests for Product entity validation (12 tests) • 2 SP (~3-4h)
+      File: tests/unit/entities/Product.entity.spec.ts
+      Tests: price validation, stock constraints, name required, category FK
+      Dependencies: None (can run parallel with other test tasks)
+```
+
+---
+
 **Feature Breakdown Logic:**
 
 For each Epic:
@@ -275,84 +358,165 @@ For each Epic:
 
 **Feature Template:**
 
-````markdown
-### Feature {{NUMBER}}: {{FEATURE_NAME}} • {{SP}} SP
+```markdown
+### Feature {{NUMBER}}: {{FEATURE_NAME}} • {{SP}} SP (~{{TIME}})
 
-⏱️ **Est. Time:** {{TIME_RANGE}}
-🎯 **Priority:** {{PRIORITY}}
-📋 **Dependencies:** {{DEPENDENCIES}}
+**Scope:** {{ENTITY}} entity + {{ENDPOINT_COUNT}} endpoints + {{TEST_COUNT}} tests
 
-**Scope:**
+**Tasks:**
+
+- [ ] T0XX [P] Write {{ENTITY}} entity tests • 2 SP (~3-4h) → tests/unit/{{ENTITY}}.spec.ts
+- [ ] T0YY Create {{ENTITY}} entity • 2 SP (~3-4h) → src/entities/{{ENTITY}}.ts
+- [ ] T0ZZ Create I{{REPOSITORY}} interface • 1 SP (~1-2h) → src/repositories/I{{REPOSITORY}}.ts
+- [ ] T0AA Implement {{REPOSITORY}} • 2 SP (~3-4h) → src/repositories/{{REPOSITORY}}.ts (after T0YY, T0ZZ)
+- [ ] T0BB Implement {{SERVICE}} business logic • 3 SP (~4-8h) → src/services/{{SERVICE}}.ts (after T0AA)
+- [ ] T0CC Create {{CONTROLLER}} endpoints • 2 SP (~3-4h) → src/controllers/{{CONTROLLER}}.ts (after T0BB)
+- [ ] T0DD [P] Write integration tests • 2 SP (~3-4h) → tests/integration/{{CONTROLLER}}.spec.ts
+- [ ] T0EE [P] Update API docs • 1 SP (~1h) → docs/api.md
+
+**Parallel:** T0XX, T0DD, T0EE can run together
+
+**Done when:** All endpoints work + tests pass + coverage ≥ {{COVERAGE}}%
+
+**Start:** `/feature new "{{FEATURE_NAME}}"`
+```
+
+`````
+
+**Example (Real Project):**
 
-- {{ENDPOINT_1}} ({{METHOD}})
-- {{ENDPOINT_2}} ({{METHOD}})
-- Entity: {{ENTITY_NAME}}
-- Tests: {{TEST_COUNT}} ({{TEST_TYPES}})
+````markdown
+### Feature 2.1: User Entity & Repository • 12 SP (~2-3d)
+
+**Scope:** User entity + CRUD endpoints + 12 tests
 
 **Tasks:**
 
-- [ ] Create {{ENTITY}} entity with validation • {{SP}} SP
-- [ ] Create {{REPOSITORY}} repository • {{SP}} SP
-- [ ] Implement {{SERVICE}} service • {{SP}} SP
-- [ ] Create {{CONTROLLER}} controller • {{SP}} SP
-- [ ] Add {{ENDPOINT_1}} endpoint • {{SP}} SP
-- [ ] Add {{ENDPOINT_2}} endpoint • {{SP}} SP
-- [ ] Write unit tests for service ({{COUNT}} tests) • {{SP}} SP
-- [ ] Write integration tests for endpoints ({{COUNT}} tests) • {{SP}} SP
-- [ ] Update API documentation • {{SP}} SP
-- [ ] Update data model documentation • {{SP}} SP
+- [ ] T001 [P] Write User entity validation tests • 2 SP (~3-4h) → tests/unit/User.entity.spec.ts
+- [ ] T002 Create User entity (email, password, role) • 2 SP (~3-4h) → src/entities/User.entity.ts
+- [ ] T003 Create IUserRepository interface • 1 SP (~1-2h) → src/repositories/IUserRepository.ts
+- [ ] T004 Implement UserRepository with Prisma • 2 SP (~3-4h) → src/repositories/UserRepository.ts (after T002, T003)
+- [ ] T005 Implement UserService business logic • 3 SP (~4-8h) → src/services/UserService.ts (after T004)
+- [ ] T006 Create UserController (CRUD endpoints) • 2 SP (~3-4h) → src/controllers/UserController.ts (after T005)
+- [ ] T007 [P] Write integration tests (4 tests) • 2 SP (~3-4h) → tests/integration/UserController.spec.ts
+- [ ] T008 [P] Update API docs • 1 SP (~1h) → docs/api.md
 
-**Acceptance Criteria:**
+**Parallel tasks:** T001, T007, T008 (different files)
 
-- [ ] All endpoints return correct responses
-- [ ] {{VALIDATION_RULES}} are enforced
-- [ ] Test coverage ≥ {{COVERAGE_TARGET}}%
-- [ ] API documentation is updated
-- [ ] Code passes linting and type-check
+**Done when:** GET/POST/PUT/DELETE /users working + 12 tests pass + coverage ≥ 80%
+`````
 
-**Ready-to-execute command:**
+---
 
-```bash
-/feature new "{{FEATURE_NAME}}"
+**Example (Simplified Format):**
+
+```markdown
+### Feature 2.1: User Entity & Repository • 12 SP (~2-3d)
+
+**Scope:** User entity + CRUD endpoints + 12 tests
+
+**Tasks:**
+
+- [ ] T001 [P] Write User entity validation tests • 2 SP (~3-4h) → tests/unit/User.entity.spec.ts
+- [ ] T002 Create User entity (email, password, role) • 2 SP (~3-4h) → src/entities/User.entity.ts
+- [ ] T003 Create IUserRepository interface • 1 SP (~1-2h) → src/repositories/IUserRepository.ts
+- [ ] T004 Implement UserRepository with Prisma • 2 SP (~3-4h) → src/repositories/UserRepository.ts (after T002, T003)
+- [ ] T005 Implement UserService business logic • 3 SP (~4-8h) → src/services/UserService.ts (after T004)
+- [ ] T006 Create UserController (CRUD endpoints) • 2 SP (~3-4h) → src/controllers/UserController.ts (after T005)
+- [ ] T007 [P] Write integration tests (4 tests) • 2 SP (~3-4h) → tests/integration/UserController.spec.ts
+- [ ] T008 [P] Update API docs • 1 SP (~1h) → docs/api.md
+
+**Parallel tasks:** T001, T007, T008 (different files)
+
+**Done when:** GET/POST/PUT/DELETE /users working + 12 tests pass + coverage ≥ 80%
+
+**Start:** `/feature new "User Entity & Repository"`
 ```
-````
 
-````
+---
 
-**Example Feature Breakdown:**
+**Original Feature Breakdown Example:**
 
 ```markdown
 ## 💾 Epic 2: Data Layer • 34 SP
 
-### Feature 2.1: User Entity & Repository • 5 SP
+### Feature 2.1: User Entity & Repository (Detailed Version) • 5 SP
 
-⏱️ **Est. Time:** 1-2 days
+⏱️ **Est. Time:** 1-2 days (~12-16h total)
 🎯 **Priority:** P0
-📋 **Dependencies:** None
+📋 **Dependencies:** None (foundational entity)
+🏷️ **User Story:** [US1] As a system, I need to store user data securely
 
 **Scope:**
+
 - Entity: User (id, email, username, passwordHash, role, createdAt, updatedAt)
 - Repository: IUserRepository with CRUD operations
 - Validation: Email format, username constraints, password strength
 - Tests: 8 unit tests, 4 integration tests
 
-**Tasks:**
-- [ ] Create User entity with field validation • 2 SP
-- [ ] Create IUserRepository interface • 1 SP
-- [ ] Implement UserRepository (Prisma/TypeORM) • 1 SP
-- [ ] Add database migration for users table • 1 SP
-- [ ] Add indexes (email unique, username unique) • 1 SP
-- [ ] Write unit tests for User entity validation (8 tests) • 2 SP
-- [ ] Write integration tests for UserRepository (4 tests) • 2 SP
-- [ ] Update docs/data-model.md • 1 SP
+**Tasks:** (Test-First, execution order, hybrid estimation)
+
+- [ ] [T001] [P] Write unit tests for User entity validation (8 tests) • 2 SP (~3-4h)
+      File: tests/unit/entities/User.entity.spec.ts
+      Tests: email format, username constraints, password hashing, role enum, timestamps
+      Dependencies: None (can run parallel with other test tasks)
+
+- [ ] [T002] Create User entity with field validation • 2 SP (~3-4h)
+      File: src/entities/User.entity.ts
+      Implements: Email validation regex, username 3-20 chars, password bcrypt hashing
+      Dependencies: None
+
+- [ ] [T003] [P] Create IUserRepository interface • 1 SP (~1-2h)
+      File: src/repositories/interfaces/IUserRepository.ts
+      Methods: create, findById, findByEmail, findAll, update, delete
+      Dependencies: T002 (needs User entity type)
+
+- [ ] [T004] Implement UserRepository with Prisma/TypeORM • 1 SP (~1-2h)
+      File: src/repositories/UserRepository.ts
+      Implements: All CRUD methods from IUserRepository interface
+      Dependencies: T002 (User entity), T003 (interface)
+
+- [ ] [T005] Add database migration for users table • 1 SP (~1-2h)
+      File: migrations/001_create_users_table.ts (Prisma) or similar
+      Schema: All User fields + indexes (email unique, username unique)
+      Dependencies: T002 (User entity schema)
+
+- [ ] [T006] Write integration tests for UserRepository (4 tests) • 2 SP (~3-4h)
+      File: tests/integration/repositories/UserRepository.spec.ts
+      Tests: CRUD operations, unique constraints, transactions, error handling
+      Dependencies: T004 (UserRepository), T005 (migration)
+
+- [ ] [T007] Update data model documentation • 1 SP (~1h)
+      File: docs/data-model.md
+      Add: User entity schema, relationships, validation rules
+      Dependencies: T002 (User entity complete)
 
 **Acceptance Criteria:**
-- [ ] User entity validates email format
-- [ ] Password is hashed before storage
-- [ ] Repository handles all CRUD operations
-- [ ] Migration creates table with correct schema
-- [ ] Test coverage ≥ 80%
-- [ ] No TypeScript errors
+
+- [ ] User entity validates email format (regex: RFC 5322)
+- [ ] Password is hashed with bcrypt (cost factor 10) before storage
+- [ ] Repository handles all CRUD operations correctly
+- [ ] Migration creates table with correct schema + indexes
+- [ ] Test coverage ≥ 80% (measured by Jest/Vitest)
+- [ ] No TypeScript errors (strict mode)
+- [ ] All 12 tests passing (8 unit + 4 integration)
+
+**Task Execution Graph:**
+```
+
+T001 [P] ──┐
+├──> T002 ──┬──> T003 ──> T004 ──┬──> T006
+│ │ │
+│ └──> T005 ────────────┘
+│ │
+└─────────────────────────────────┴──> T007
+
+````
+
+**Parallelization Notes:**
+- T001 can run parallel to other test tasks (different file)
+- T005 can start as soon as T002 completes (don't need to wait for T004)
+- T007 (docs) can run while T006 (tests) runs
 
 **Ready-to-execute command:**
 ```bash
@@ -363,40 +527,96 @@ For each Epic:
 
 ### Feature 2.2: Product Entity & Repository • 8 SP
 
-⏱️ **Est. Time:** 2-3 days
+⏱️ **Est. Time:** 2-3 days (~16-24h total)
 🎯 **Priority:** P0
-📋 **Dependencies:** Feature 2.4 (Category entity)
+📋 **Dependencies:** Feature 2.4 (Category entity - needs Category FK)
+🏷️ **User Story:** [US2] As a store owner, I need to manage product catalog with search
 
 **Scope:**
 
 - Entity: Product (id, name, description, price, stock, categoryId, images, createdAt, updatedAt)
-- Repository: IProductRepository with CRUD + search
+- Repository: IProductRepository with CRUD + search/filter
 - Validation: Price > 0, stock ≥ 0, name required
 - Relationships: belongsTo Category
 - Tests: 12 unit tests, 6 integration tests
 
-**Tasks:**
-
-- [ ] Create Product entity with validation • 3 SP
-- [ ] Add relationship to Category (FK constraint) • 1 SP
-- [ ] Create IProductRepository interface • 1 SP
-- [ ] Implement ProductRepository with search/filter methods • 2 SP
-- [ ] Add database migration for products table • 1 SP
-- [ ] Add indexes (categoryId, name for search) • 1 SP
-- [ ] Implement inventory tracking logic • 2 SP
-- [ ] Write unit tests for Product entity (12 tests) • 3 SP
-- [ ] Write integration tests for ProductRepository (6 tests) • 2 SP
-- [ ] Write tests for search/filter functionality (4 tests) • 2 SP
-- [ ] Update docs/data-model.md • 1 SP
+**Tasks:** (Test-First, execution order, hybrid estimation)
+
+- [ ] [T008] [P] Write unit tests for Product entity validation (12 tests) • 3 SP (~4-8h)
+      File: tests/unit/entities/Product.entity.spec.ts
+      Tests: price validation, stock constraints, name required, category FK, images array
+      Dependencies: T007 (Category entity exists for FK testing)
+
+- [ ] [T009] Create Product entity with validation + Category FK • 3 SP (~4-8h)
+      File: src/entities/Product.entity.ts
+      Implements: Price > 0, stock ≥ 0, name required, belongs to Category relationship
+      Dependencies: T007 (Category entity), T008 (tests)
+
+- [ ] [T010] Create IProductRepository interface • 1 SP (~1-2h)
+      File: src/repositories/interfaces/IProductRepository.ts
+      Methods: CRUD + search(query), filterByCategory(categoryId), updateStock(id, quantity)
+      Dependencies: T009 (Product entity)
+
+- [ ] [T011] Implement ProductRepository with search/filter methods • 2 SP (~3-4h)
+      File: src/repositories/ProductRepository.ts
+      Implements: All CRUD + search (case-insensitive name), filter by category
+      Dependencies: T009 (entity), T010 (interface)
+
+- [ ] [T012] Add database migration for products table • 1 SP (~1-2h)
+      File: migrations/002_create_products_table.ts
+      Schema: All Product fields + FK to categories + indexes (categoryId, name)
+      Dependencies: T009 (Product entity schema)
+
+- [ ] [T013] Implement inventory tracking logic • 2 SP (~3-4h)
+      File: src/repositories/ProductRepository.ts (extend)
+      Logic: Atomic stock decrements, prevent negative stock, transaction support
+      Dependencies: T011 (ProductRepository base)
+
+- [ ] [T014] Write integration tests for ProductRepository (6 tests) • 2 SP (~3-4h)
+      File: tests/integration/repositories/ProductRepository.spec.ts
+      Tests: CRUD, search, filter by category, stock updates, FK constraints
+      Dependencies: T011, T012, T013
+
+- [ ] [T015] Write tests for search/filter functionality (4 tests) • 2 SP (~3-4h)
+      File: tests/integration/repositories/ProductRepository.search.spec.ts
+      Tests: Case-insensitive search, partial match, filter by category, pagination
+      Dependencies: T011 (search implementation)
+
+- [ ] [T016] Update data model documentation • 1 SP (~1h)
+      File: docs/data-model.md
+      Add: Product entity schema, Category relationship, search indexes
+      Dependencies: T009 (Product entity complete)
 
 **Acceptance Criteria:**
 
-- [ ] Product validates price and stock constraints
-- [ ] Search by name works (case-insensitive)
-- [ ] Filter by category works
-- [ ] Inventory decrements correctly
-- [ ] Migration includes FK constraint to categories
+- [ ] Product validates price > 0 and stock ≥ 0
+- [ ] Search by name works (case-insensitive, partial match)
+- [ ] Filter by category returns only products in that category
+- [ ] Inventory decrements correctly with atomic operations
+- [ ] Stock cannot go negative (validation error)
+- [ ] Migration includes FK constraint to categories + indexes
 - [ ] Test coverage ≥ 80%
+- [ ] All 22 tests passing (12 unit + 6 integration + 4 search)
+
+**Task Execution Graph:**
+
+```
+T007 (Category) ──> T008 [P] (tests) ──> T009 (entity) ──┬──> T010 (interface) ──> T011 (repo) ──> T013 (inventory)
+                                                          │                                            │
+                                                          └──> T012 (migration) ─────────────────────┬─┤
+                                                                                                     │ │
+                                                T014 <──────────────────────────────────────────────┤ │
+                                                T015 <────────────────────────────────────────────────┘
+                                                T016 <── T009
+
+[P] = Can run parallel with other test tasks
+```
+
+**Parallelization Notes:**
+
+- T008 (tests) can run parallel to other entity test tasks
+- T014 (integration tests) and T015 (search tests) can run in parallel (different test files)
+- T016 (docs) can run while tests are executing
 
 **Ready-to-execute command:**
 
@@ -437,6 +657,58 @@ For each Epic:
    - Independent entities can be built in parallel
    - Independent epics (after foundation) can be worked simultaneously
 
+4. **Task-Level Dependencies** (Spec-Kit Inspired):
+   - For each Feature, analyze task dependencies at granular level
+   - Identify parallelization opportunities **within** Features (not just between)
+   - Generate task execution graph per Epic showing exact task order
+
+**Task Dependency Matrix Example:**
+
+```
+Epic 2: Data Layer
+
+Feature 2.1: User Entity (5 SP)
+├─ T001 [P] Write User entity tests → No deps (can run parallel)
+├─ T002 Create User entity → Depends on: None
+├─ T003 [P] Create IUserRepository interface → Depends on: T002
+├─ T004 Implement UserRepository → Depends on: T002, T003
+├─ T005 Add users table migration → Depends on: T002
+├─ T006 Write UserRepository integration tests → Depends on: T004, T005
+└─ T007 Update data model docs → Depends on: T002
+
+Feature 2.2: Category Entity (3 SP) [Can run PARALLEL to Feature 2.1]
+├─ T008 [P] Write Category entity tests → No deps
+├─ T009 Create Category entity → Depends on: None
+├─ T010 Create CategoryRepository → Depends on: T009
+└─ T011 Update data model docs → Depends on: T009
+
+Feature 2.3: Product Entity (8 SP) [BLOCKS on Feature 2.2 - needs Category FK]
+├─ T012 Write Product entity tests → Depends on: T009 (Category entity)
+├─ T013 Create Product entity with Category FK → Depends on: T009, T012
+├─ T014 Create IProductRepository → Depends on: T013
+├─ T015 Implement ProductRepository with search → Depends on: T013, T014
+├─ T016 Write ProductRepository tests → Depends on: T015
+└─ T017 Update data model docs → Depends on: T013
+```
+
+**Parallelization Analysis:**
+
+✅ **Feature-Level Parallelization:**
+- Feature 2.1 (User) and Feature 2.2 (Category) can run in PARALLEL → 40% time save
+- Feature 2.3 (Product) BLOCKS on Feature 2.2 → must wait for Category entity
+
+✅ **Task-Level Parallelization (within Feature 2.1):**
+- T001 (tests) can run parallel to T002 (entity) if desired (TDD: run tests first recommended)
+- T003 (interface) and T005 (migration) can run in parallel (both depend only on T002)
+- T006 (integration tests) and T007 (docs) can run in parallel
+
+⚡ **Team Scaling:**
+- With 1 dev: Features run sequentially → ~16 hours (Feature 2.1) + ~8 hours (Feature 2.2) + ~16 hours (Feature 2.3) = 40 hours total
+- With 2 devs: Feature 2.1 + 2.2 parallel → ~16 hours + ~16 hours (Product) = 32 hours total (20% save)
+- With 3 devs: Task-level parallelization within features → ~28 hours total (30% save)
+
+---
+
 **Generate Mermaid Dependency Graph:**
 
 ```mermaid
@@ -524,14 +796,14 @@ With 3 developers: ~9 weeks (47% time savings)
 
 ### Step 9.5: Generate Roadmap Document (2-5 minutes - automatic)
 
-**Generate `.ai-flow/roadmap.md` with complete implementation plan:**
+**Generate `roadmap.md` with complete implementation plan:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 Step 9.5/6: Generating Roadmap Document
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Writing to .ai-flow/roadmap.md...
+Writing to roadmap.md...
 ```
 
 **Roadmap Document Structure:**
@@ -595,6 +867,91 @@ Use this table to translate Story Points to time estimates:
 
 ---
 
+## 🔄 5-Phase Execution Model (Spec-Kit Inspired)
+
+Our roadmap follows a battle-tested 5-phase approach for predictable, incremental delivery:
+
+### Phase 0: Setup (Pre-Foundation)
+
+**Goal:** Project initialization
+**Duration:** 1-2 days (already done by `/project-scaffold`)
+
+- Repository setup, CI/CD baseline, Docker configuration
+- Development environment setup
+- Base dependencies installed
+
+### Phase 1: Foundational (Blocking Prerequisites)
+
+**Goal:** Core infrastructure that everything depends on
+**Duration:** 2-3 weeks
+**Epics:** Foundation, Data Layer (base models only)
+
+**Characteristics:**
+
+- ❌ NO parallelization (everything blocks on these)
+- ✅ Must complete BEFORE user story implementation
+- 🎯 Establish patterns for entire project
+
+**Example Tasks:**
+
+- [T001-T020] Database connection, ORM setup, migrations
+- [T021-T040] Logging, error handling, config management
+- [T041-T060] Base entity models (User, Session)
+
+### Phase 2-N: User Stories (Priority-Ordered)
+
+**Goal:** Deliver business value incrementally
+**Duration:** Varies per story (1-3 weeks each)
+**Epics:** All business features
+
+**Characteristics:**
+
+- ✅ Each story is INDEPENDENTLY deployable
+- ✅ High parallelization potential (2-3 devs)
+- 🎯 Delivers working software each iteration
+
+**Story Execution Order:**
+
+1. P0 stories (MVP-critical) → [US1], [US2], [US3]
+2. P1 stories (high value) → [US4], [US5]
+3. P2 stories (nice-to-have) → [US6], [US7]
+
+**Example Story Tasks:**
+
+- [T061] [US1] Write authentication tests
+- [T062] [US1] Implement JWT service
+- [T063] [US1] Create login endpoint
+- [T064] [P] [US2] Write product catalog tests (parallel to US1)
+
+### Phase N: Polish & Cross-Cutting
+
+**Goal:** Production readiness
+**Duration:** 1-2 weeks
+**Epics:** Operations, Testing, Performance
+
+**Characteristics:**
+
+- ✅ Can run after all critical stories complete
+- ✅ Some parallelization (different concerns)
+- 🎯 Ensures quality and operability
+
+**Example Tasks:**
+
+- [T200-T210] Performance optimization, caching
+- [T211-T220] Security hardening, penetration testing
+- [T221-T230] Monitoring, alerting, logging
+- [T231-T240] Documentation finalization
+
+### Phase Benefits:
+
+1. **Incremental Delivery**: Ship user stories as they complete
+2. **Risk Mitigation**: Foundation issues caught early
+3. **Team Scaling**: Multiple stories run in parallel
+4. **Predictable Velocity**: Story points per sprint stabilize
+5. **Quality Gates**: Each phase has clear exit criteria
+
+---
+
 ## 🔗 Dependency Graph
 
 ```mermaid
@@ -625,16 +982,40 @@ Use this table to translate Story Points to time estimates:
 
 ##### Feature 1.1: Base Application Configuration • 5 SP
 
-⏱️ **Est. Time:** 1-2 days • 🎯 **Priority:** P0 • 📋 **Dependencies:** None
+⏱️ **Est. Time:** 1-2 days (~8-12h total) • 🎯 **Priority:** P0 • 📋 **Dependencies:** None
+🏷️ **User Story:** [US0] As a developer, I need a robust configuration system
 
-**Tasks:**
+**Tasks:** (Test-First, execution order, hybrid estimation)
+
+- [ ] [T001] [P] Write unit tests for configuration service (5 tests) • 2 SP (~3-4h)
+      File: tests/unit/config/ConfigService.spec.ts
+      Tests: env var loading, validation, defaults, type conversion, missing var errors
+      Dependencies: None (can run parallel with other foundational tests)
+
+- [ ] [T002] Setup configuration service/module • 2 SP (~3-4h)
+      File: src/config/ConfigService.ts
+      Implements: Load env vars, validate required fields, type-safe access
+      Dependencies: None
+
+- [ ] [T003] Configure environment variables (`.env` structure) • 1 SP (~1-2h)
+      File: .env.example
+      Structure: All required env vars with descriptions and example values
+      Dependencies: T002 (know which vars are needed)
+
+- [ ] [T004] Add validation for required env vars • 1 SP (~1-2h)
+      File: src/config/ConfigService.ts (extend)
+      Logic: Fail-fast on missing vars, clear error messages
+      Dependencies: T002 (base service exists)
+
+- [ ] [T005] [P] Create constants file for app-wide values • 1 SP (~1h)
+      File: src/constants/index.ts
+      Constants: App name, version, default values, enums
+      Dependencies: None (can run parallel with other tasks)
 
-- [ ] Configure environment variables (`.env` structure) • 1 SP
-- [ ] Setup configuration service/module • 2 SP
-- [ ] Add validation for required env vars • 1 SP
-- [ ] Create constants file for app-wide values • 1 SP
-- [ ] Write unit tests for configuration service (5 tests) • 2 SP
-- [ ] Document configuration in `specs/configuration.md` • 1 SP
+- [ ] [T006] Document configuration in specs/configuration.md • 1 SP (~1h)
+      File: specs/configuration.md
+      Add: All env vars, types, defaults, validation rules
+      Dependencies: T002, T003, T004 (config system complete)
 
 **Acceptance Criteria:**
 
@@ -773,7 +1154,7 @@ Update this roadmap as you complete features:
 
 **Need to modify the roadmap?**
 
-- Update documentation first (`/flow-bootstrap` or `/flow-docs-sync`)
+- Update documentation first (`/flow-build` or `/flow-docs-sync`)
 - Re-run Phase 9 to regenerate roadmap
 
 ---
@@ -786,7 +1167,7 @@ Update this roadmap as you complete features:
 
 ```
 ✅ Roadmap document generated
-✅ Location: .ai-flow/roadmap.md
+✅ Location: roadmap.md
 ✅ Total: {{TOTAL_EPICS}} Epics, {{TOTAL_FEATURES}} Features, {{TOTAL_TASKS}} Tasks
 ✅ Estimated: {{TOTAL_SP}} Story Points (~{{TOTAL_WEEKS}} weeks)
 ```
@@ -811,7 +1192,7 @@ Update this roadmap as you complete features:
 ✅ Estimated time: {{SOLO_WEEKS}} weeks (1 dev) | {{TWO_DEV_WEEKS}} weeks (2 devs)
 ✅ Dependency graph: Generated
 ✅ Execution order: Optimized for parallelization
-✅ Roadmap document: .ai-flow/roadmap.md
+✅ Roadmap document: roadmap.md
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🎯 What This Roadmap Guarantees
@@ -840,14 +1221,14 @@ Update this roadmap as you complete features:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 1. **Open the roadmap**
-   └─ Open .ai-flow/roadmap.md in your editor
+   └─ Open roadmap.md in your editor
 
 2. **Review and adjust priorities**
    └─ Decide which features are MVP vs future phases
    └─ Adjust P0/P1/P2/P3 priorities if needed
 
 3. **Commit the roadmap**
-   └─ git add .ai-flow/roadmap.md
+   └─ git add roadmap.md
    └─ git commit -m "docs: add implementation roadmap with Story Points"
 
 4. **Start implementation**
@@ -879,13 +1260,13 @@ Update this roadmap as you complete features:
   time-to-market.
 
 • **Re-generate:** If documentation changes significantly, run
-  /flow-bootstrap again (Phases 0-9) to update everything.
+  /flow-build again (Phases 0-9) to update everything.
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Ready to start building? 🚀
 
-Open .ai-flow/roadmap.md and let's ship this! 💪
+Open roadmap.md and let's ship this! 💪
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -899,10 +1280,10 @@ A) ✅ Start implementing first feature now (recommended)
    → Will execute: /feature new "{{FIRST_FEATURE_NAME}}"
 
 B) 📋 Review roadmap first
-   → Will open .ai-flow/roadmap.md
+   → Will open roadmap.md
 
 C) ✏️ Customize roadmap
-   → Will open .ai-flow/roadmap.md for editing
+   → Will open roadmap.md for editing
 
 Your choice (A/B/C): __
 ```
@@ -1021,7 +1402,7 @@ Please fix documentation and re-run Phase 9
 
 **9.5 Generate Roadmap Document:**
 
-- [ ] Create `.ai-flow/roadmap.md`
+- [ ] Create `roadmap.md`
 - [ ] Include project overview
 - [ ] Include Story Points reference table
 - [ ] Include Epic overview table