1# Implementation Plan: Project Initialization with Dependencies
2
3**Branch**: `001-init-project` | **Date**: 2025-01-09 | **Spec**: [spec.md](./spec.md)
4**Input**: Feature specification from `/home/brice/dev/projects/dumber/specs/001-init-project/spec.md`
5
6## Execution Flow (/plan command scope)
7```
81. Load feature spec from Input path
9   → If not found: ERROR "No feature spec at {path}"
102. Fill Technical Context (scan for NEEDS CLARIFICATION)
11   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
12   → Set Structure Decision based on project type
133. Evaluate Constitution Check section below
14   → If violations exist: Document in Complexity Tracking
15   → If no justification possible: ERROR "Simplify approach first"
16   → Update Progress Tracking: Initial Constitution Check
174. Execute Phase 0 → research.md
18   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
195. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
206. Re-evaluate Constitution Check section
21   → If new violations: Refactor design, return to Phase 1
22   → Update Progress Tracking: Post-Design Constitution Check
237. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
248. STOP - Ready for /tasks command
25```
26
27**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
28- Phase 2: /tasks command creates tasks.md
29- Phase 3-4: Implementation execution (manual or via tools)
30
31## Summary
32Initialize a Go project with all required dependencies for the dumber application, following the constitution's technical stack: Go + Wails v3-alpha + WebKit2GTK + SQLite with CLI (Cobra + Viper), database (SQLC), and validation (go-playground/validator) components. Use `go get @latest` for all dependencies.
33
34## Technical Context
35**User Details**: We need to add all deps using go get @latest
36**Language/Version**: Go (latest compatible with Wails v3-alpha)
37**Primary Dependencies**: Wails v3-alpha, Cobra, Viper, SQLC, go-playground/validator, SQLite driver
38**Storage**: SQLite (local embedded database)
39**Testing**: Go standard testing + testify for enhanced assertions
40**Target Platform**: Linux Wayland (sway, hyprland) - primary focus
41**Project Type**: single (desktop application with CLI + GUI components)
42**Performance Goals**: < 500ms startup time, < 100MB baseline memory
43**Constraints**: Single binary, WebKit2GTK system dependency only
44**Scale/Scope**: Personal productivity tool, local history management (1000+ entries)
45
46## Constitution Check
47*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
48
49**Simplicity**:
50- Projects: 1 (single desktop app - dumber)
51- Using framework directly? YES (Wails, Cobra, Viper directly)
52- Single data model? YES (SQLite schema matches Go structs via SQLC)
53- Avoiding patterns? YES (no unnecessary abstractions for initialization)
54
55**Architecture**:
56- EVERY feature as library? YES (CLI, parser, database, browser as separate packages)
57- Libraries planned: cli (cobra commands), db (sqlc queries), parser (URL handling), browser (Wails integration)
58- CLI per library: main CLI with subcommands (--dmenu, history, config)
59- Library docs: llms.txt format will be generated post-implementation
60
61**Testing (NON-NEGOTIABLE)**:
62- RED-GREEN-Refactor cycle enforced? YES (tests for module initialization first)
63- Git commits show tests before implementation? YES (test dependency resolution before implementation)
64- Order: Contract→Integration→E2E→Unit strictly followed? YES
65- Real dependencies used? YES (actual Go modules, SQLite DB)
66- Integration tests for: module loading, dependency compatibility, build success
67- FORBIDDEN: Implementation before test, skipping RED phase
68
69**Observability**:
70- Structured logging included? YES (slog for debugging initialization)
71- Frontend logs → backend? N/A for initialization phase
72- Error context sufficient? YES (proper error chains for dependency failures)
73
74**Versioning**:
75- Version number assigned? YES (v0.1.0 - initial development)
76- BUILD increments on every change? YES (following semantic versioning)
77- Breaking changes handled? N/A for initial setup
78
79## Project Structure
80
81### Documentation (this feature)
82```
83specs/[###-feature]/
84├── plan.md              # This file (/plan command output)
85├── research.md          # Phase 0 output (/plan command)
86├── data-model.md        # Phase 1 output (/plan command)
87├── quickstart.md        # Phase 1 output (/plan command)
88├── contracts/           # Phase 1 output (/plan command)
89└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
90```
91
92### Source Code (repository root)
93```
94# Option 1: Single project (DEFAULT)
95src/
96├── models/
97├── services/
98├── cli/
99└── lib/
100
101tests/
102├── contract/
103├── integration/
104└── unit/
105
106# Option 2: Web application (when "frontend" + "backend" detected)
107backend/
108├── src/
109│   ├── models/
110│   ├── services/
111│   └── api/
112└── tests/
113
114frontend/
115├── src/
116│   ├── components/
117│   ├── pages/
118│   └── services/
119└── tests/
120
121# Option 3: Mobile + API (when "iOS/Android" detected)
122api/
123└── [same as backend above]
124
125ios/ or android/
126└── [platform-specific structure]
127```
128
129**Structure Decision**: Option 1 - Single project (desktop application with CLI and GUI components)
130
131## Phase 0: Outline & Research
1321. **Extract unknowns from Technical Context** above:
133   - For each NEEDS CLARIFICATION → research task
134   - For each dependency → best practices task
135   - For each integration → patterns task
136
1372. **Generate and dispatch research agents**:
138   ```
139   For each unknown in Technical Context:
140     Task: "Research {unknown} for {feature context}"
141   For each technology choice:
142     Task: "Find best practices for {tech} in {domain}"
143   ```
144
1453. **Consolidate findings** in `research.md` using format:
146   - Decision: [what was chosen]
147   - Rationale: [why chosen]
148   - Alternatives considered: [what else evaluated]
149
150**Output**: research.md with all NEEDS CLARIFICATION resolved
151
152## Phase 1: Design & Contracts
153*Prerequisites: research.md complete*
154
1551. **Extract entities from feature spec** → `data-model.md`:
156   - Entity name, fields, relationships
157   - Validation rules from requirements
158   - State transitions if applicable
159
1602. **Generate API contracts** from functional requirements:
161   - For each user action → endpoint
162   - Use standard REST/GraphQL patterns
163   - Output OpenAPI/GraphQL schema to `/contracts/`
164
1653. **Generate contract tests** from contracts:
166   - One test file per endpoint
167   - Assert request/response schemas
168   - Tests must fail (no implementation yet)
169
1704. **Extract test scenarios** from user stories:
171   - Each story → integration test scenario
172   - Quickstart test = story validation steps
173
1745. **Update agent file incrementally** (O(1) operation):
175   - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
176   - If exists: Add only NEW tech from current plan
177   - Preserve manual additions between markers
178   - Update recent changes (keep last 3)
179   - Keep under 150 lines for token efficiency
180   - Output to repository root
181
182**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
183
184## Phase 2: Task Planning Approach
185*This section describes what the /tasks command will do - DO NOT execute during /plan*
186
187**Task Generation Strategy**:
188- Load `/templates/tasks-template.md` as base
189- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
190- Prioritize CGO-free components first (faster development cycle)
191- Each CLI command contract → contract test + implementation task
192- Module initialization → dependency installation tasks
193- Project structure → directory creation + config generation tasks
194- Integration tests for each success criterion in quickstart
195
196**Ordering Strategy**:
197- TDD order: Tests before implementation 
198- CGO-free first: CLI, parser, database (can develop with CGO_ENABLED=0)
199- Wails integration last: Full application build (requires CGO_ENABLED=1)
200- Dependency order: Go module → dependencies → structure → config → verification
201- Mark [P] for parallel execution (independent dependency installations)
202
203**Key Task Categories**:
2041. **Module Setup Tasks**: go mod init, dependency installation
2052. **Structure Tasks**: Directory creation, config file generation  
2063. **Verification Tasks**: Build tests, tool availability checks
2074. **Integration Tasks**: Full quickstart validation
208
209**CGO Optimization**:
210- Most tasks can run with CGO_ENABLED=0 for faster iteration
211- Only final integration tests require CGO_ENABLED=1
212- Clear separation allows parallel development of CGO-free components
213
214**Estimated Output**: 15-20 numbered, ordered tasks in tasks.md (streamlined for initialization focus)
215
216**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
217
218## Phase 3+: Future Implementation
219*These phases are beyond the scope of the /plan command*
220
221**Phase 3**: Task execution (/tasks command creates tasks.md)  
222**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
223**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
224
225## Complexity Tracking
226*Fill ONLY if Constitution Check has violations that must be justified*
227
228| Violation | Why Needed | Simpler Alternative Rejected Because |
229|-----------|------------|-------------------------------------|
230| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
231| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
232
233
234## Progress Tracking
235*This checklist is updated during execution flow*
236
237**Phase Status**:
238- [x] Phase 0: Research complete (/plan command)
239- [x] Phase 1: Design complete (/plan command)  
240- [x] Phase 2: Task planning complete (/plan command - describe approach only)
241- [ ] Phase 3: Tasks generated (/tasks command)
242- [ ] Phase 4: Implementation complete
243- [ ] Phase 5: Validation passed
244
245**Gate Status**:
246- [x] Initial Constitution Check: PASS
247- [x] Post-Design Constitution Check: PASS  
248- [x] All NEEDS CLARIFICATION resolved
249- [x] Complexity deviations documented (none - simplicity maintained)
250
251---
252*Based on Constitution v2.1.1 - See `/memory/constitution.md`*