refactor: consolidate todo storage under .context/compound-engineering/todos/ (#361)

docs/plans/2026-03-24-001-refactor-todo-path-consolidation-plan.md

@@ -0,0 +1,151 @@
+---
+title: "refactor: Consolidate todo storage under .context/compound-engineering/todos/"
+type: refactor
+status: completed
+date: 2026-03-24
+origin: docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md
+---
+
+# Consolidate Todo Storage Under `.context/compound-engineering/todos/`
+
+## Overview
+
+Move the file-based todo system's canonical storage path from `todos/` to `.context/compound-engineering/todos/`, consolidating all compound-engineering workflow artifacts under one namespace. Use a "drain naturally" migration strategy: new todos write to the new path, reads check both paths, legacy files resolve through normal usage.
+
+## Problem Statement / Motivation
+
+The compound-engineering plugin standardized on `.context/compound-engineering/<workflow>/` for workflow artifacts. Multiple skills already use this pattern (`ce-review-beta`, `resolve-todo-parallel`, `feature-video`, `deepen-plan-beta`). The todo system is the last major workflow artifact stored at a different top-level path (`todos/`). Consolidation improves discoverability and organization. PR #345 is adding the `.gitignore` check for `.context/`. (see origin: `docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md`)
+
+## Proposed Solution
+
+Update 7 skills to use `.context/compound-engineering/todos/` as the canonical write path while reading from both locations during the legacy drain period. Consolidate inline todo path references in consumer skills to delegate to the `file-todos` skill as the single authority.
+
+## Technical Considerations
+
+### Multi-Session Lifecycle vs. Per-Run Scratch
+
+Todos are gitignored and transient -- they don't survive clones or branch switches. But unlike per-run scratch directories (e.g., `ce-review-beta/<run-id>/`), a todo's lifecycle spans multiple sessions (pending -> triage -> ready -> work -> complete). The `file-todos` skill should note that `.context/compound-engineering/todos/` should not be cleaned up as part of any skill's post-run scratch cleanup. In practice the risk is low since each skill only cleans up its own namespaced subdirectory, but the note prevents misunderstanding.
+
+### ID Sequencing Across Two Directories
+
+During the drain period, issue ID generation must scan BOTH `todos/` and `.context/compound-engineering/todos/` to avoid collisions. Two todos with the same numeric ID would break the dependency system (`dependencies: ["005"]` becomes ambiguous). The `file-todos` skill's "next ID" logic must take the global max across both paths.
+
+### Directory Creation
+
+The new path is 3 levels deep (`.context/compound-engineering/todos/`). Unlike the old single-level `todos/`, this needs an explicit `mkdir -p` before first write. Add this to the "Creating a New Todo" workflow in `file-todos`.
+
+### Git Tracking
+
+Both `todos/` and `.context/` are gitignored. The `git add todos/` command in `ce-review` (line 448) is dead code -- todos in a gitignored directory were never committed through this path. Remove it.
+
+## Acceptance Criteria
+
+- [ ] New todos created by any skill land in `.context/compound-engineering/todos/`
+- [ ] Existing todos in `todos/` are still found and resolvable by `triage` and `resolve-todo-parallel`
+- [ ] Issue ID generation scans both directories to prevent collisions
+- [ ] Consumer skills (`ce-review`, `ce-review-beta`, `test-browser`, `test-xcode`) delegate to `file-todos` rather than encoding paths inline
+- [ ] `ce-review-beta` report-only prohibition uses path-agnostic language
+- [ ] Stale template paths in `ce-review` (`.claude/skills/...`) fixed to use correct relative path
+- [ ] `bun run release:validate` passes
+
+## Implementation Phases
+
+### Phase 1: Update `file-todos` (Foundation)
+
+**File:** `plugins/compound-engineering/skills/file-todos/SKILL.md`
+
+This is the authoritative skill -- all other changes depend on getting this right first.
+
+Changes:
+1. **YAML frontmatter description** (line 3): Update `todos/ directory` to `.context/compound-engineering/todos/`
+2. **Overview section** (lines 10-11): Update canonical path reference
+3. **Directory Structure section**: Update path references
+4. **Creating a New Todo workflow** (line 76-77):
+   - Add `mkdir -p .context/compound-engineering/todos/` as first step
+   - Update `ls todos/` for next-ID to scan both directories: `ls .context/compound-engineering/todos/ todos/ 2>/dev/null | grep -o '^[0-9]\+' | sort -n | tail -1`
+   - Update template copy target to `.context/compound-engineering/todos/`
+5. **Reading/Listing commands** (line 106+): Update `ls` and `grep` commands to scan both paths. Pattern: `ls .context/compound-engineering/todos/*-pending-*.md todos/*-pending-*.md 2>/dev/null`
+6. **Dependency checking** (lines 131-142): Update `[ -f ]` checks and `grep -l` to scan both directories
+7. **Quick Reference Commands** (lines 197-232): Update all commands to use new canonical path for writes, dual-path for reads
+8. **Key Distinctions** (lines 237-253): Update "Markdown files in `todos/` directory" to new path
+9. **Add a Legacy Support note** near the top: "During the transition period, always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading. Write only to the canonical path. Unlike per-run scratch directories, `.context/compound-engineering/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup."
+
+### Phase 2: Update Consumer Skills (Parallel -- Independent)
+
+These 4 skills only **create** todos. They should delegate to `file-todos` rather than encoding paths inline (R5).
+
+#### 2a. `ce-review` skill
+
+**File:** `plugins/compound-engineering/skills/ce-review/SKILL.md`
+
+Changes:
+1. **Line 244** (`<critical_requirement>`): Replace `todos/ directory` with `the todo directory defined by the file-todos skill`
+2. **Lines 275, 323, 343**: Fix stale template path `.claude/skills/file-todos/assets/todo-template.md` to correct relative reference (or delegate to "load the `file-todos` skill for the template location")
+3. **Line 435** (`ls todos/*-pending-*.md`): Update to reference file-todos conventions
+4. **Line 448** (`git add todos/`): Remove this dead code (both paths are gitignored)
+
+#### 2b. `ce-review-beta` skill
+
+**File:** `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+
+Changes:
+1. **Line 35**: Change `todos/` items to reference file-todos skill conventions
+2. **Line 41** (report-only prohibition): Change `do not create todos/` to `do not create todo files` (path-agnostic -- closes loophole where agent could write to new path thinking old prohibition doesn't apply)
+3. **Line 479**: Update `todos/` reference to delegate to file-todos skill
+
+#### 2c. `test-browser` skill
+
+**File:** `plugins/compound-engineering/skills/test-browser/SKILL.md`
+
+Changes:
+1. **Line 228**: Change `Add to todos/ for later` to `Create a todo using the file-todos skill conventions`
+2. **Line 233**: Update `{id}-pending-p1-browser-test-{description}.md` creation path or delegate to file-todos
+
+#### 2d. `test-xcode` skill
+
+**File:** `plugins/compound-engineering/skills/test-xcode/SKILL.md`
+
+Changes:
+1. **Line 142**: Change `Add to todos/ for later` to `Create a todo using the file-todos skill conventions`
+2. **Line 147**: Update todo creation path or delegate to file-todos
+
+### Phase 3: Update Reader Skills (Sequential after Phase 1)
+
+These skills **read and operate on** existing todos. They need dual-path support.
+
+#### 3a. `triage` skill
+
+**File:** `plugins/compound-engineering/skills/triage/SKILL.md`
+
+Changes:
+1. **Line 9**: Update `todos/ directory` to reference both paths
+2. **Lines 152, 275**: Change "Remove it from todos/ directory" to path-agnostic language ("Remove the todo file from its current location")
+3. **Lines 185-186**: Update summary template from `Removed from todos/` to `Removed`
+4. **Line 193**: Update `Deleted: Todo files for skipped findings removed from todos/ directory`
+5. **Line 200**: Update `ls todos/*-ready-*.md` to scan both directories
+
+#### 3b. `resolve-todo-parallel` skill
+
+**File:** `plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md`
+
+Changes:
+1. **Line 13**: Change `Get all unresolved TODOs from the /todos/*.md directory` to scan both `.context/compound-engineering/todos/*.md` and `todos/*.md`
+
+## Dependencies & Risks
+
+- **Dependency on PR #345**: That PR adds the `.gitignore` check for `.context/`. This change works regardless (`.context/` is already gitignored at repo root), but #345 adds the validation that consuming projects have it gitignored too.
+- **Risk: Agent literal-copying**: Agents often copy shell commands verbatim from skill files. If dual-path commands are unclear, agents may only check one path. Mitigation: Use explicit dual-path examples in the most critical commands (list, create, ID generation) and add a prominent note about legacy path.
+- **Risk: Other branches with in-flight todo work**: The drain strategy avoids this -- no files are moved, no paths break immediately.
+
+## Sources & References
+
+### Origin
+
+- **Origin document:** [docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md](docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md) -- Key decisions: drain naturally (no active migration), delegate to file-todos as authority (R5), update all 7 affected skills.
+
+### Internal References
+
+- `plugins/compound-engineering/skills/file-todos/SKILL.md` -- canonical todo system definition
+- `plugins/compound-engineering/skills/file-todos/assets/todo-template.md` -- todo file template
+- `AGENTS.md:27` -- `.context/compound-engineering/` scratch space convention
+- `.gitignore` -- confirms both `todos/` and `.context/` are already ignored