phased-implementation-plan-template.md

1# {{Product Name}} Phased Implementation Plan - {{Version}}
2
3**Last Updated**: {{YYYY-MM-DD}}
4
5> **Transient Document**: Implementation plans created from this template are temporary working documents used to guide specific development increments or phases. Unlike living documents, they have defined lifespans tied to their implementation cycles.
6>
7> **Purpose**: Provides a structured roadmap for implementing the product based on the product specification and technical architecture. Serves as a progress tracker and development guide for AI assistants and development teams during active development.
8>
9> **Lifecycle**: Once an implementation is complete, the plan document can be archived for historical reference or discarded. It is not intended to be continuously maintained beyond the completion of its associated development phase.
10>
11> **Maintenance**: During the implementation of this plan AI assistants should update progress status, mark completed tasks.
12
13## Instructions for AI Assistants
14
15When working with this implementation plan:
16
17**Filename Format**: Save implementation plans using the format `{{product-name}}-implementation-plan-{{version}}.md` (lowercase with hyphens, include version identifier like MVP, v1, v2, etc.)
18
191. **Task & Progress Management**:
20   - Update task status (Not Started → In Progress → Completed → Blocked)
21   - Mark completion dates and add review notes
22   - Update "Last Updated" date when making changes
23   - Update phase completion percentages and overall project status
24   - Add new tasks if scope expands or requirements emerge
25
262. **Technical Requirements**:
27   - Document critical technical requirements, constraints, and build verification criteria
28   - Note mandatory review points with stakeholders
29
303. **Mandatory Reading Requirement**:
31   - **BEFORE ANY IMPLEMENTATION**: Read ALL documents in "MANDATORY Pre-Implementation Reading" section
32   - Verify understanding of patterns, standards, and architectural constraints
33   - Confirm with human before proceeding with implementation work
34   - This reading is required at the START of every conversation involving this implementation
35
364. **UCM Component Integration Strategy**:
37   - **UCM Reference Format**: Use `ucm:` prefix for all UCM artifacts (e.g., `ucm:utaba/main/patterns/micro-block/README.md`)
38   - **Import vs Build**: Tasks must clearly specify if components should be imported from UCM using the `ucm:` prefix
39   - **Discovery Requirement**: Before creating implementation tasks, search UCM for existing components
40   - **Never Recreate**: If a UCM component exists that meets requirements, always import rather than build from scratch
41
425. **Mandatory Pre-Implementation Tasks**:
43   - **EVERY PHASE** must begin with Task X.0: "Pre-Implementation: Mandatory Reading Verification"
44   - **FORBIDDEN**: Starting any implementation tasks (X.1, X.2, etc.) until Task X.0 is completed
45   - Task X.0 forces verification that all mandatory reading has been completed
46
476. **Mandatory Post-Implementation Task**:
48   - **EVERY PHASE** must end with Task X.99: "Post-Implementation: Plan Update & Status Review"
49   - **FORBIDDEN**: Stopping work or asking user to proceed without completing Task X.99
50   - This task forces update of implementation plan status, progress percentages, and completed deliverables
51   - Must update "Current Progress Status" section and mark phase completion
52   - **REQUIRED WHENEVER STOPPING**: Even if stopping mid-phase, must complete Task X.99 to document current state
53
547. **Cross-References**:
55   - Reference product specification features being implemented
56   - Link to technical architecture decisions
57   - Include relevant external documentation
58
598. **Workflow**:
60   - Complete all tasks within a phase before proceeding
61   - Update this document with completed tasks and review notes
62   - **STOP at the end of each phase and ask the user to proceed**
63   - Wait for explicit user approval before starting the next phase
64   - This ensures stakeholder alignment and allows for plan adjustments between phases
65
66## Summary
67
68{{Brief description of the implementation approach and key technical decisions}}
69
70Key capabilities include {{list main features being implemented}}.
71
72## 📊 Current Progress Status
73
74**Overall Progress**: {{X}} out of {{Y}} phases completed ({{Z}}% complete)
75
76- {{Status}} **Phase 1**: {{Phase Name}} - **{{STATUS}}**
77- {{Status}} **Phase 2**: {{Phase Name}} - **{{STATUS}}**
78- {{Status}} **Phase 3**: {{Phase Name}} - **{{STATUS}}**
79
80**Current Status**: {{Summary of current state and next steps}}
81
82## 📚 MANDATORY Pre-Implementation Reading
83
84**⚠️ CRITICAL REQUIREMENT**: The following documents MUST be read by AI assistants at the beginning of ANY conversation involving this implementation plan. This ensures consistency with established patterns, standards, and architectural decisions.
85
86### Required Reading List
87
88| Document Type | Location | Description | Must Read Before |
89|--------------|----------|-------------|-----------------|
90| Pattern Guide | `{{Location/Path}}` | {{Description of pattern/architecture}} | Starting ANY implementation work |
91| Standards | `{{Location/Path}}` | {{Coding standards and practices}} | Writing any code |
92| Implementation Guide | `{{Location/Path}}` | {{Technology-specific guidance}} | Setting up project structure |
93| {{Document Type}} | `{{Location/Path}}` | {{Description}} | {{When to read}} |
94
95### AI Assistant Instructions
96
97**BEFORE implementing ANYTHING in this project:**
98
991. **✅ MANDATORY**: Read ALL documents listed above in the "Required Reading List"
1002. **✅ MANDATORY**: Confirm understanding of patterns, standards, and architectural constraints
1013. **✅ MANDATORY**: Ask the human: "I have reviewed the required documentation. Should I proceed with implementation?"
1024. **❌ FORBIDDEN**: Starting any implementation work without completing the required reading
103
104**Reading Verification**: When starting a new conversation about this implementation, AI assistants must state:
105> "I am reviewing the mandatory pre-implementation reading list: [list document paths]. I will read these before proceeding with any implementation work."
106
107## 🔍 UCM Component Integration Guidelines
108
109### UCM Reference Format
110**All UCM artifacts must use the `ucm:` prefix to distinguish them from file system components:**
111
112**Examples**:
113- `ucm:utaba/main/patterns/micro-block/README.md`
114- `ucm:utaba/main/services/cache/CacheService.ts`
115- `ucm:utaba/main/commands/micro-block/BaseCommand.ts`
116
117### Task Creation Guidelines
118When creating implementation tasks, explicitly specify UCM imports:
119
120**✅ CORRECT Task Format**:
121```
122Task 2.3: Implement User Authentication Service
123Requirements: 
124- Import base service pattern from ucm:utaba/main/patterns/micro-block/BaseService.ts
125- Import authentication utilities from ucm:utaba/main/services/authentication/AuthUtils.ts
126- Build UserAuthService extending BaseService pattern
127- Implement login, logout, and token validation methods
128```
129
130**❌ INCORRECT Task Format**:
131```
132Task 2.3: Implement User Authentication Service
133Requirements: Check if authentication components exist, then build service
134```
135
136### Discovery & Planning Process
1371. **Before creating tasks**: Search UCM for relevant components
1382. **Document UCM components**: List all applicable UCM artifacts using `ucm:` prefix
1393. **Plan imports**: Specify exactly which UCM components will be imported in each task
1404. **Plan builds**: Only plan to build components that don't exist in UCM
141
142## 🚨 Critical Development Requirements 🚨
143
144### {{Requirement Category}}
145**{{Critical requirement description}}**
146
147- ❌ **FORBIDDEN**: {{What must not be done}}
148- ✅ **REQUIRED**: {{What must be done}}
149- **ALL {{scope}}** must {{requirement}}
150
151### {{Another Requirement Category}}
152**{{Another critical requirement}}**
153
154- **NO {{forbidden practice}}** anywhere except {{exception}}
155- **ALL {{components}}** MUST {{requirement}}
156
157### Build Verification Requirement
158**MANDATORY: Every implementation task MUST end with a successful build verification.**
159
160- ✅ **REQUIRED**: Run {{build command}} after completing any implementation work
161- ✅ **REQUIRED**: Ensure {{verification criteria}} succeeds with zero errors
162- ✅ **REQUIRED**: Fix any {{error types}} before marking tasks complete
163- ❌ **FORBIDDEN**: Completing tasks with failing {{verification}}
164
165**Implementation Process**:
1661. Complete implementation work
1672. Run {{verification command}} to verify {{criteria}}
1683. Fix any {{error types}} that arise
1694. Re-run {{verification}} until successful
1705. Only then mark task as complete
171
172## Phased Implementation Plan
173
174### Phase 1: {{Phase Name}}
175
176**Goal**: {{Description of what this phase accomplishes}}
177
178**Status**: {{Overall phase status}} ({{X}}/{{Y}} tasks completed)
179
180**UCM Components Required**:
181- `ucm:{{component-path-1}}` - {{Description of component usage}}
182- `ucm:{{component-path-2}}` - {{Description of component usage}}
183
184**Tasks**:
185
186| Task ID | Task Name | Requirements | Status | Completed Date | Review Notes |
187|---------|-----------|--------------|--------|----------------|--------------|
188| 1.0 | **Pre-Implementation: Mandatory Reading Verification** | **MANDATORY**: Verify all documents in "MANDATORY Pre-Implementation Reading" section have been read. If not completed, read ALL required documents now. Document in Review Notes: "I have read and understood: [list document paths]" | Not Started | | **REQUIRED**: Must complete before proceeding to any other tasks |
189| 1.1 | {{Task Name}} | Import {{ucm:component-path}}, {{Requirement 2, Requirement 3}} | {{STATUS}} | {{Date}} | {{Summary of what was accomplished}} |
190| 1.2 | {{Task Name}} | Build {{ComponentName}} using pattern from {{ucm:pattern-path}}, {{Requirement 2}} | {{STATUS}} | {{Date}} | {{Summary of what was accomplished}} |
191| 1.99 | **Post-Implementation: Plan Update & Status Review** | **MANDATORY**: Update implementation plan status and progress percentages, mark completed tasks and deliverables, update "Current Progress Status" section, document phase completion or current stopping point | Not Started | | **REQUIRED**: Must complete before stopping work or asking user to proceed |
192
193**Deliverables**:
194- {{Deliverable 1}}
195- {{Deliverable 2}}
196- {{Deliverable 3}}
197
198**Completed Deliverables Summary**:
199- {{Summary of what was actually delivered}}
200- {{Key achievements and technical outcomes}}
201- {{Integration points established}}
202
203### Phase 2: {{Phase Name}}
204
205**Goal**: {{Description of what this phase accomplishes}}
206
207**Status**: {{Overall phase status}} ({{X}}/{{Y}} tasks completed)
208
209**UCM Components Required**:
210- `ucm:{{component-path-1}}` - {{Description of component usage}}
211- `ucm:{{component-path-2}}` - {{Description of component usage}}
212
213**Tasks**:
214
215| Task ID | Task Name | Requirements | Status | Completed Date | Review Notes |
216|---------|-----------|--------------|--------|----------------|--------------|
217| 2.0 | **Pre-Implementation: Mandatory Reading Verification** | **MANDATORY**: Verify all documents in "MANDATORY Pre-Implementation Reading" section have been read. If not completed, read ALL required documents now. Document in Review Notes: "I have read and understood: [list document paths]" | Not Started | | **REQUIRED**: Must complete before proceeding to any other tasks |
218| 2.1 | {{Task Name}} | Import {{ucm:component-path}}, {{Requirement 2}} | {{STATUS}} | {{Date}} | {{Summary of what was accomplished}} |
219| 2.99 | **Post-Implementation: Plan Update & Status Review** | **MANDATORY**: Update implementation plan status and progress percentages, mark completed tasks and deliverables, update "Current Progress Status" section, document phase completion or current stopping point | Not Started | | **REQUIRED**: Must complete before stopping work or asking user to proceed |
220
221**Deliverables**:
222- {{Deliverable 1}}
223- {{Deliverable 2}}
224
225## Notes
226
227- {{Important implementation considerations}}
228- {{Technical constraints or limitations}}
229- {{Dependencies on external systems}}
230
231---
232
233*Template created by [Utaba AI](https://utaba.ai)*  
234*Source: [phased-implementation-plan-template.md](https://ucm.utaba.ai/browse/utaba/main/guidance/templates/phased-implementation-plan-template.md)*