@@ -0,0 +1,452 @@
1+# Codebase and Documentation Cleanup Workflow
2+
3+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+**Goal:** Remove dead code, fix outdated tests, reorganize documentation, consolidate known issues, and organize TODO.md using 10 autonomous agents working in parallel.
6+
7+**Architecture:** Split work into 10 independent audit tasks executed by parallel agents, each producing a report with recommended deletions/moves/merges, then execute all changes in a single verification phase.
8+
9+**Tech Stack:** Go 1.22, ripgrep, git, markdown
10+
11+---
12+
13+## Phase 1: Parallel Code Audits (10 Agents)
14+
15+Each agent audits a specific area and produces a report with actionable recommendations.
16+
17+---
18+
19+### Agent 1: Dead Code Detection
20+
21+**Task:** Find unused functions, variables, and imports in production code.
22+
23+**Search for:**
24+- Unexported functions with no references
25+- Unused constants
26+- Commented-out code blocks
27+- Imports marked as unused by LSP
28+
29+**Exclude:**
30+- Test files (*_test.go)
31+- Exported functions (may be used externally)
32+
33+**Output:** `reports/DEAD_CODE_AUDIT_2026-02-07.md` with:
34+- List of dead code with file:line
35+- Reason it's unused (no references found)
36+- Recommended deletion
37+
38+**Verification command:**
39+```bash
40+rg "functionName" --type go
41+```
42+
43+---
44+
45+### Agent 2: Skipped and Disabled Tests
46+
47+**Task:** Find all skipped tests and determine if they should be enabled or removed.
48+
49+**Search for:**
50+- `t.Skip()`
51+- `t.SkipNow()`
52+- `// TODO: test`
53+- `// FIXME: test`
54+- Commented-out test functions
55+
56+**Output:** `reports/SKIPPED_TESTS_AUDIT_2026-02-07.md` with:
57+- List of skipped tests with reason
58+- Recommendation: enable, fix, or remove
59+- Estimated effort to fix
60+
61+**Verification:**
62+```bash
63+rg "t\.Skip|SkipNow" --type go
64+```
65+
66+---
67+
68+### Agent 3: Outdated Test Logic
69+
70+**Task:** Find tests that verify removed or changed functionality.
71+
72+**Search for:**
73+- Tests referencing removed functions (zoea_swarm_status, selectPromptSource, DefaultConfig)
74+- Tests using old architecture (loop-based context vs turn-aware)
75+- Tests with hardcoded provider names that should be dynamic
76+
77+**Cross-reference:**
78+- Recent commits removing features
79+- Architecture changes in reports/
80+
81+**Output:** `reports/OUTDATED_TESTS_AUDIT_2026-02-07.md` with:
82+- Tests that need updating
83+- What changed that invalidates them
84+- Recommended fix or removal
85+
86+**Verification:**
87+```bash
88+git log --oneline --since="2026-02-06" | grep "remove\|delete\|refactor"
89+```
90+
91+---
92+
93+### Agent 4: Hardcoded Config References
94+
95+**Task:** Find remaining hardcoded provider/model references that should use config.
96+
97+**Search for:**
98+- String literals: "ollama", "opencode_zen" in non-provider implementation files
99+- Hardcoded model names in validation
100+- Provider switch statements
101+
102+**Exclude:**
103+- internal/provider/*.go (provider implementations)
104+- Test files (allowed to use hardcoded fixtures)
105+
106+**Output:** `reports/HARDCODED_CONFIG_AUDIT_2026-02-07.md` with:
107+- Hardcoded values with location
108+- Should be dynamic or is acceptable
109+- Recommended fix
110+
111+**Verification:**
112+```bash
113+rg '"ollama"|"opencode_zen"' --type go | grep -v "_test.go" | grep -v "internal/provider"
114+```
115+
116+---
117+
118+### Agent 5: Documentation File Organization
119+
120+**Task:** Audit documentation/ directory for misplaced, duplicate, or outdated files.
121+
122+**Check:**
123+- Files in wrong directories (plans in reports/, reports in investigations/)
124+- Duplicate information across files
125+- Outdated reports superseded by newer implementations
126+- Missing index entries in documentation/README.md
127+
128+**Output:** `reports/DOCUMENTATION_ORGANIZATION_AUDIT_2026-02-07.md` with:
129+- Files to move (source → destination)
130+- Files to merge (list duplicates)
131+- Files to archive
132+- Index updates needed
133+
134+**Verification:**
135+```bash
136+ls -R documentation/
137+```
138+
139+---
140+
141+### Agent 6: Known Issues Consolidation
142+
143+**Task:** Consolidate KNOWN_ISSUES.md, KNOWN_SERVER_ISSUES.md, and issues scattered in other docs.
144+
145+**Check:**
146+- Issues mentioned in multiple places
147+- Fixed issues still listed as known issues
148+- Server issues that should be in KNOWN_SERVER_ISSUES.md
149+- Issues in reports/ that should be in KNOWN_ISSUES.md
150+
151+**Cross-reference:**
152+- Recent commits fixing issues
153+- Git history for "fix:" commits
154+
155+**Output:** `reports/KNOWN_ISSUES_CONSOLIDATION_2026-02-07.md` with:
156+- Issues to remove (fixed)
157+- Issues to add (found in other docs)
158+- Issues to move (wrong file)
159+- Proposed new KNOWN_ISSUES.md structure
160+
161+**Verification:**
162+```bash
163+git log --oneline --grep="fix:" --since="2026-02-05"
164+```
165+
166+---
167+
168+### Agent 7: TODO.md Organization
169+
170+**Task:** Organize TODO.md into categories and remove completed items.
171+
172+**Check:**
173+- Completed items (marked with [x] or mentioned in recent commits)
174+- Duplicate items
175+- Vague items without clear success criteria
176+- Items that should be issues in KNOWN_ISSUES.md instead
177+
178+**Output:** `reports/TODO_ORGANIZATION_2026-02-07.md` with:
179+- Items to remove (completed)
180+- Items to move to KNOWN_ISSUES.md
181+- Items to clarify
182+- Proposed new TODO.md structure with categories
183+
184+**Verification:**
185+```bash
186+git log --oneline --since="2026-02-05" | grep -i "session\|context\|prompt"
187+```
188+
189+---
190+
191+### Agent 8: Test Coverage Gaps
192+
193+**Task:** Find production code without test coverage.
194+
195+**Check:**
196+- Functions in internal/ without corresponding tests
197+- Critical paths (CreateMysis, SendMessage, getContextMemories) test coverage
198+- Error paths not tested
199+
200+**Output:** `reports/TEST_COVERAGE_GAPS_2026-02-07.md` with:
201+- Functions without tests
202+- Critical paths with insufficient coverage
203+- Recommended tests to add (with priority)
204+
205+**Verification:**
206+```bash
207+go test ./... -cover
208+```
209+
210+---
211+
212+### Agent 9: Import Cleanup
213+
214+**Task:** Find unused imports and missing imports across codebase.
215+
216+**Check:**
217+- LSP diagnostics for unused imports
218+- Missing imports causing build failures
219+- Imports that could be stdlib instead of external
220+
221+**Output:** `reports/IMPORT_CLEANUP_2026-02-07.md` with:
222+- Files with unused imports
223+- Recommended removals
224+- Build verification commands
225+
226+**Verification:**
227+```bash
228+go build ./...
229+```
230+
231+---
232+
233+### Agent 10: Documentation Accuracy Audit
234+
235+**Task:** Verify documentation matches current implementation.
236+
237+**Check:**
238+- README.md - keyboard shortcuts, features, providers
239+- AGENTS.md - terminology, architecture, workflow
240+- architecture/*.md - diagrams, state machines, compression strategy
241+- guides/*.md - configuration examples, terminal requirements
242+
243+**Cross-reference:**
244+- Current code (keyboard mappings, features)
245+- Recent architectural changes (turn-aware context)
246+- Provider list (config.toml)
247+
248+**Output:** `reports/DOCUMENTATION_ACCURACY_AUDIT_2026-02-07.md` with:
249+- Inaccurate documentation with corrections
250+- Missing documentation
251+- Outdated examples
252+- Recommended updates
253+
254+**Verification:**
255+```bash
256+diff <(actual_code) <(documented_behavior)
257+```
258+
259+---
260+
261+## Phase 2: Consolidation and Review
262+
263+**Task:** Merge all 10 audit reports into execution plan.
264+
265+**Agent:** Single coordinator agent
266+
267+**Actions:**
268+1. Read all 10 audit reports
269+2. Identify conflicts (same file edited by multiple audits)
270+3. Prioritize changes (critical fixes first)
271+4. Create consolidated change list
272+5. Group by file for efficient editing
273+
274+**Output:** `reports/CLEANUP_EXECUTION_PLAN_2026-02-07.md` with:
275+- Ordered list of all changes
276+- File-by-file change groups
277+- Conflict resolutions
278+- Estimated time per change
279+
280+---
281+
282+## Phase 3: Execution (Batched by File)
283+
284+**Task:** Execute all changes in file-batched order.
285+
286+**Agent:** Single execution agent
287+
288+**Process:**
289+1. For each file with changes:
290+ - Read current state
291+ - Apply all changes to that file
292+ - Run relevant tests
293+ - Commit if tests pass
294+ - Rollback if tests fail
295+
296+**Safety:**
297+- One file at a time
298+- Test after each file change
299+- Commit frequently
300+- Stop on first failure
301+
302+**Commands:**
303+```bash
304+# For each change batch
305+go test ./path/to/affected/package -v
306+git add file.go
307+git commit -m "cleanup: [description]"
308+```
309+
310+---
311+
312+## Phase 4: Documentation Reorganization
313+
314+**Task:** Move/merge/archive documentation files.
315+
316+**Agent:** Documentation agent
317+
318+**Actions:**
319+1. Execute moves (investigation → archive, etc.)
320+2. Merge duplicate content
321+3. Update documentation/README.md index
322+4. Update cross-references
323+5. Verify no broken links
324+
325+**Verification:**
326+```bash
327+rg "]\(.*\.md\)" documentation/ --only-matching | sort | uniq
328+```
329+
330+---
331+
332+## Phase 5: Final Verification
333+
334+**Task:** Verify entire codebase after cleanup.
335+
336+**Agent:** Verification agent
337+
338+**Checks:**
339+1. Full test suite passes
340+2. Build succeeds
341+3. No dead code remains
342+4. No skipped tests (unless documented)
343+5. Documentation accurate
344+6. TODO.md organized
345+7. KNOWN_ISSUES.md complete
346+
347+**Commands:**
348+```bash
349+make test
350+make build
351+go vet ./...
352+```
353+
354+**Output:** `reports/CLEANUP_VERIFICATION_2026-02-07.md` with:
355+- Test results
356+- Build status
357+- Remaining issues (if any)
358+- Cleanup statistics (lines removed, files moved, etc.)
359+
360+---
361+
362+## Success Criteria
363+
364+**Code:**
365+- [ ] No dead code in production files
366+- [ ] No skipped tests without documentation
367+- [ ] No tests for removed functionality
368+- [ ] No hardcoded config outside provider implementations
369+- [ ] All tests passing
370+- [ ] Clean build
371+
372+**Documentation:**
373+- [ ] All files in correct directories
374+- [ ] No duplicate content
375+- [ ] KNOWN_ISSUES.md accurate and complete
376+- [ ] TODO.md organized by category
377+- [ ] Index up to date
378+- [ ] No broken links
379+
380+---
381+
382+## Rollback Plan
383+
384+If Phase 5 verification fails:
385+
386+```bash
387+# List commits from cleanup
388+git log --oneline --since="[start_time]"
389+
390+# Revert all cleanup commits
391+git revert [commit_range]
392+
393+# Or reset to before cleanup
394+git reset --hard [pre_cleanup_commit]
395+```
396+
397+---
398+
399+## Execution Strategy
400+
401+**Parallel Phase (Agents 1-10):**
402+```
403+Agent 1 (dead code) │
404+Agent 2 (skipped tests) │
405+Agent 3 (outdated tests) ├─→ 10 parallel audits → 10 reports
406+Agent 4 (hardcoded config) │
407+Agent 5 (doc organization) │
408+Agent 6 (known issues) │
409+Agent 7 (TODO organization) │
410+Agent 8 (test coverage) │
411+Agent 9 (imports) │
412+Agent 10 (doc accuracy) │
413+```
414+
415+**Sequential Phase (Single agents):**
416+```
417+Consolidation agent → execution plan
418+ ↓
419+Execution agent → apply changes (file-by-file)
420+ ↓
421+Documentation agent → reorganize docs
422+ ↓
423+Verification agent → final checks
424+```
425+
426+**Estimated time:** 30-45 minutes total
427+
428+---
429+
430+## Agent Prompts
431+
432+### Launch Command for All 10 Agents
433+
434+```
435+Launch agents 1-10 in parallel with their respective tasks from Phase 1.
436+Each agent produces a report in documentation/reports/.
437+Wait for all 10 reports before proceeding to Phase 2.
438+```
439+
440+### After Reports Complete
441+
442+```
443+Launch consolidation agent to merge reports into execution plan.
444+Then launch execution agent with the plan.
445+Then launch documentation agent for reorganization.
446+Finally launch verification agent for final checks.
447+```
448+
449+---
450+
451+**Plan Complete**
452+**Ready for autonomous execution with 10 parallel agents**