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

title, type, status, date, origin

title	type	status	date	origin
refactor: Consolidate todo storage under .context/compound-engineering/todos/	refactor	completed	2026-03-24	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 -- 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