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

docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md

@@ -0,0 +1,58 @@
+---
+date: 2026-03-24
+topic: todo-path-consolidation
+---
+
+# Consolidate Todo Storage Under `.context/compound-engineering/todos/`
+
+## Problem Frame
+
+The file-based todo system currently stores todos in a top-level `todos/` directory. The plugin has standardized on `.context/compound-engineering/` as the consolidated namespace for CE workflow artifacts (scratch space, run artifacts, etc.). Todos should live there too for consistent organization. PR #345 is already adding the `.gitignore` check for `.context/`.
+
+## Requirements
+
+- R1. All skills that **create** todos must write to `.context/compound-engineering/todos/` instead of `todos/`.
+- R2. All skills that **read** todos must check both `.context/compound-engineering/todos/` and legacy `todos/` to support natural drain of existing items.
+- R3. All skills that **modify or delete** todos must operate on files in-place (wherever the file currently lives).
+- R4. No active migration logic -- existing `todos/` files are resolved and cleaned up through normal workflow usage.
+- R5. Skills that create or manage todos should reference the `file-todos` skill as the authority rather than encoding todo paths/conventions inline. This reduces scattered implementations and makes the path change a single-point update.
+
+## Affected Skills
+
+| Skill | Changes needed |
+|-------|---------------|
+| `file-todos` | Update canonical path, template copy target, all example commands. Add legacy read path. |
+| `resolve-todo-parallel` | Read from both paths, resolve/delete in-place. |
+| `triage` | Read from both paths, delete in-place. |
+| `ce-review` | Replace inline `todos/` paths with delegation to `file-todos` skill. |
+| `ce-review-beta` | Replace inline `todos/` paths with delegation to `file-todos` skill. |
+| `test-browser` | Replace inline `todos/` path with delegation to `file-todos` skill. |
+| `test-xcode` | Replace inline `todos/` path with delegation to `file-todos` skill. |
+
+## Scope Boundaries
+
+- No active file migration (move/copy) of existing todos.
+- No changes to todo file format, naming conventions, or template structure.
+- No removal of legacy `todos/` read support in this change -- that can be cleaned up later once confirmed drained.
+
+## Key Decisions
+
+- **Drain naturally over active migration**: Avoids migration logic, dead code, and conflicts with in-flight branches. Old todos resolve through normal usage.
+
+## Success Criteria
+
+- New todos created by any skill land in `.context/compound-engineering/todos/`.
+- Existing todos in `todos/` are still found and resolvable.
+- No skill references only the old `todos/` path for reads.
+- Skills that create todos delegate to `file-todos` rather than encoding paths inline.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R2][Technical] Determine the cleanest way to express dual-path reads in `file-todos` example commands (glob both paths vs. a helper pattern).
+- [Affects R2][Needs research] Decide whether to add a follow-up task to remove legacy `todos/` read support after a grace period.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

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

plugins/compound-engineering/skills/ce-review-beta/SKILL.md

@@ -32,13 +32,13 @@ Check `$ARGUMENTS` for `mode:autonomous` or `mode:report-only`. If either token
 - **Skip all user questions.** Never pause for approval or clarification once scope has been established.
 - **Apply only `safe_auto -> review-fixer` findings.** Leave `gated_auto`, `manual`, `human`, and `release` work unresolved.
 - **Write a run artifact** under `.context/compound-engineering/ce-review-beta/<run-id>/` summarizing findings, applied fixes, residual actionable work, and advisory outputs.
-- **Create durable `todos/` items only for unresolved actionable findings** whose final owner is `downstream-resolver`.
+- **Create durable todo files only for unresolved actionable findings** whose final owner is `downstream-resolver`. Load the `file-todos` skill for the canonical directory path and naming convention.
 - **Never commit, push, or create a PR** from autonomous mode. Parent workflows own those decisions.
 
 ### Report-only mode rules
 
 - **Skip all user questions.** Infer intent conservatively if the diff metadata is thin.
-- **Never edit files or externalize work.** Do not write `.context/compound-engineering/ce-review-beta/<run-id>/`, do not create `todos/`, and do not commit, push, or create a PR.
+- **Never edit files or externalize work.** Do not write `.context/compound-engineering/ce-review-beta/<run-id>/`, do not create todo files, and do not commit, push, or create a PR.
 - **Safe for parallel read-only verification.** `mode:report-only` is the only mode that is safe to run concurrently with browser testing on the same checkout.
 - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`.
 - **Do not overlap mutating review with browser testing on the same checkout.** If a future orchestrator wants fixes, run the mutating review phase after browser testing or in an isolated checkout/worktree.
@@ -476,7 +476,7 @@ After presenting findings and verdict (Stage 6), route the next steps by mode. R
   - applied fixes
   - residual actionable work
   - advisory-only outputs
-- In autonomous mode, create durable `todos/` items only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `file-todos` skill for the naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
+- In autonomous mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `file-todos` skill for the canonical directory path, naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
 - Do not create todos for `advisory` findings, `owner: human`, `owner: release`, or protected-artifact cleanup suggestions.
 - If only advisory outputs remain, create no todos.
 - Interactive mode may offer to externalize residual actionable work after fixes, but it is not required to finish the review.

plugins/compound-engineering/skills/ce-review/SKILL.md

@@ -241,7 +241,7 @@ Run the Task compound-engineering:review:code-simplicity-reviewer() to see if we
 
 ### 5. Findings Synthesis and Todo Creation Using file-todos Skill
 
-<critical_requirement> ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management. </critical_requirement>
+<critical_requirement> ALL findings MUST be stored as todo files using the file-todos skill. Load the `file-todos` skill for the canonical directory path, naming convention, and template. Create todo files immediately after synthesis - do NOT present findings for user approval first. </critical_requirement>
 
 #### Step 1: Synthesize All Findings
 
@@ -272,7 +272,7 @@ Remove duplicates, prioritize by severity and impact.
 
 - Create todo files directly using Write tool
 - All findings in parallel for speed
-- Use standard template from `.claude/skills/file-todos/assets/todo-template.md`
+- Use standard template from the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
 - Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
 
 **Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
@@ -320,7 +320,7 @@ Sub-agents can:
 
    The skill provides:
 
-   - Template location: `.claude/skills/file-todos/assets/todo-template.md`
+   - Template location: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
    - Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
    - YAML frontmatter structure: status, priority, issue_id, tags, dependencies
    - All required sections: Problem Statement, Findings, Solutions, etc.
@@ -340,7 +340,7 @@ Sub-agents can:
    004-pending-p3-unused-parameter.md
    ```
 
-5. Follow template structure from file-todos skill: `.claude/skills/file-todos/assets/todo-template.md`
+5. Follow template structure from file-todos skill: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
 
 **Todo File Structure (from template):**
 
@@ -432,7 +432,7 @@ After creating all todo files, present comprehensive summary:
 
 2. **Triage All Todos**:
    ```bash
-   ls todos/*-pending-*.md  # View all pending todos
+   ls .context/compound-engineering/todos/*-pending-*.md todos/*-pending-*.md 2>/dev/null  # View all pending todos
    /triage                  # Use slash command for interactive triage
    ```
 
@@ -445,7 +445,7 @@ After creating all todo files, present comprehensive summary:
 4. **Track Progress**:
    - Rename file when status changes: pending → ready → complete
    - Update Work Log as you work
-   - Commit todos: `git add todos/ && git commit -m "refactor: add code review findings"`
+   - Commit review findings and status updates
 
 ### Severity Breakdown:
 

plugins/compound-engineering/skills/deepen-plan-beta/SKILL.md

@@ -382,7 +382,7 @@ If the user explicitly requests a separate file, append `-deepened` before `.md`
 - `docs/plans/2026-03-15-001-feat-example-plan-deepened.md`
 
 If artifact-backed mode was used and the user did not ask to inspect the scratch files:
-- clean up the temporary scratch directory after the plan is safely written
+- delete the specific per-run scratch directory (e.g., `.context/compound-engineering/deepen-plan-beta/<run-id>/`) after the plan is safely written. Do not delete any other `.context/` subdirectories.
 - if cleanup is not practical on the current platform, say where the artifacts were left and that they are temporary workflow output
 
 ## Post-Enhancement Options

plugins/compound-engineering/skills/file-todos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-todos
-description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
+description: This skill should be used when managing the file-based todo tracking system in the .context/compound-engineering/todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with code review processes.
 disable-model-invocation: true
 ---
 
@@ -8,26 +8,35 @@ disable-model-invocation: true
 
 ## Overview
 
-The `todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
+The `.context/compound-engineering/todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
+
+> **Legacy support:** During the transition period, always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading or searching for todos. Write new todos 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.
 
 This skill should be used when:
 - Creating new todos from findings or feedback
-- Managing todo lifecycle (pending → ready → complete)
+- Managing todo lifecycle (pending -> ready -> complete)
 - Triaging pending items for approval
 - Checking or managing dependencies
 - Converting PR comments or code findings into tracked work
 - Updating work logs during todo execution
 
-## File Naming Convention
+## Directory Paths
 
-Todo files follow this naming pattern:
+| Purpose | Path |
+|---------|------|
+| **Canonical (write here)** | `.context/compound-engineering/todos/` |
+| **Legacy (read-only)** | `todos/` |
+
+When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.
+
+## File Naming Convention
 
 ```
 {issue_id}-{status}-{priority}-{description}.md
 ```
 
 **Components:**
-- **issue_id**: Sequential number (001, 002, 003...) - never reused
+- **issue_id**: Sequential number (001, 002, 003...) -- never reused
 - **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
 - **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
 - **description**: kebab-case, brief description
@@ -44,17 +53,17 @@ Todo files follow this naming pattern:
 Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
 
 **Required sections:**
-- **Problem Statement** - What is broken, missing, or needs improvement?
+- **Problem Statement** -- What is broken, missing, or needs improvement?
-- **Findings** - Investigation results, root cause, key discoveries
+- **Findings** -- Investigation results, root cause, key discoveries
-- **Proposed Solutions** - Multiple options with pros/cons, effort, risk
+- **Proposed Solutions** -- Multiple options with pros/cons, effort, risk
-- **Recommended Action** - Clear plan (filled during triage)
+- **Recommended Action** -- Clear plan (filled during triage)
-- **Acceptance Criteria** - Testable checklist items
+- **Acceptance Criteria** -- Testable checklist items
-- **Work Log** - Chronological record with date, actions, learnings
+- **Work Log** -- Chronological record with date, actions, learnings
 
 **Optional sections:**
-- **Technical Details** - Affected files, related components, DB changes
+- **Technical Details** -- Affected files, related components, DB changes
-- **Resources** - Links to errors, tests, PRs, documentation
+- **Resources** -- Links to errors, tests, PRs, documentation
-- **Notes** - Additional context or decisions
+- **Notes** -- Additional context or decisions
 
 **YAML frontmatter fields:**
 ```yaml
@@ -69,20 +78,21 @@ dependencies: ["001"]     # Issue IDs this is blocked by
 
 ## Common Workflows
 
+> **Tool preference:** Use native file-search (e.g., Glob in Claude Code) and content-search (e.g., Grep in Claude Code) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., `mv` for renames, `mkdir -p` for directory creation).
+
 ### Creating a New Todo
 
-**To create a new todo from findings or feedback:**
+1. Ensure directory exists: `mkdir -p .context/compound-engineering/todos/`
-
+2. Determine next issue ID by searching both canonical and legacy paths for files matching `[0-9]*-*.md` using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., `007`).
-1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1`
+3. Read the template at [todo-template.md](./assets/todo-template.md), then write it to `.context/compound-engineering/todos/{NEXT_ID}-pending-{priority}-{description}.md` using the native file-write tool.
-2. Copy template: `cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md`
+4. Edit and fill required sections:
-3. Edit and fill required sections:
    - Problem Statement
    - Findings (if from investigation)
    - Proposed Solutions (multiple options)
    - Acceptance Criteria
    - Add initial Work Log entry
-4. Determine status: `pending` (needs triage) or `ready` (pre-approved)
+5. Determine status: `pending` (needs triage) or `ready` (pre-approved)
-5. Add relevant tags for filtering
+6. Add relevant tags for filtering
 
 **When to create a todo:**
 - Requires more than 15-20 minutes of work
@@ -101,21 +111,19 @@ dependencies: ["001"]     # Issue IDs this is blocked by
 
 ### Triaging Pending Items
 
-**To triage pending todos:**
+1. Find pending items using the native file-search/glob tool with pattern `*-pending-*.md` in both directory paths.
-
-1. List pending items: `ls todos/*-pending-*.md`
 2. For each todo:
    - Read Problem Statement and Findings
    - Review Proposed Solutions
    - Make decision: approve, defer, or modify priority
 3. Update approved todos:
    - Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
-   - Update frontmatter: `status: pending` → `status: ready`
+   - Update frontmatter: `status: pending` -> `status: ready`
    - Fill "Recommended Action" section with clear plan
    - Adjust priority if different from initial assessment
 4. Deferred todos stay in `pending` status
 
-**Use slash command:** `/triage` for interactive approval workflow
+Load the `triage` skill for an interactive approval workflow.
 
 ### Managing Dependencies
 
@@ -126,31 +134,20 @@ dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
 dependencies: []               # No blockers - can work immediately
 ```
 
-**To check what blocks a todo:**
+**To check what blocks a todo:** Use the native content-search tool (e.g., Grep in Claude Code) to search for `^dependencies:` in the todo file.
-```bash
-grep "^dependencies:" todos/003-*.md
-```
 
-**To find what a todo blocks:**
+**To find what a todo blocks:** Search both directory paths for files containing `dependencies:.*"002"` using the native content-search tool.
-```bash
-grep -l 'dependencies:.*"002"' todos/*.md
-```
 
-**To verify blockers are complete before starting:**
+**To verify blockers are complete before starting:** For each dependency ID, use the native file-search/glob tool to look for `{dep_id}-complete-*.md` in both directory paths. Any missing matches indicate incomplete blockers.
-```bash
-for dep in 001 002 003; do
-  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
-done
-```
 
 ### Updating Work Logs
 
-**When working on a todo, always add a work log entry:**
+When working on a todo, always add a work log entry:
 
 ```markdown
 ### YYYY-MM-DD - Session Title
 
-**By:** Claude Code / Developer Name
+**By:** Agent name / Developer Name
 
 **Actions:**
 - Specific changes made (include file:line references)
@@ -172,82 +169,62 @@ Work logs serve as:
 
 ### Completing a Todo
 
-**To mark a todo as complete:**
-
 1. Verify all acceptance criteria checked off
 2. Update Work Log with final session and results
 3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
-4. Update frontmatter: `status: ready` → `status: complete`
+4. Update frontmatter: `status: ready` -> `status: complete`
-5. Check for unblocked work: `grep -l 'dependencies:.*"002"' todos/*-ready-*.md`
+5. Check for unblocked work: search both directory paths for `*-ready-*.md` files containing `dependencies:.*"{issue_id}"` using the native content-search tool
 6. Commit with issue reference: `feat: resolve issue 002`
 
 ## Integration with Development Workflows
 
 | Trigger | Flow | Tool |
 |---------|------|------|
-| Code review | `/ce:review` → Findings → `/triage` → Todos | Review agent + skill |
+| Code review | `/ce:review` -> Findings -> `/triage` -> Todos | Review agent + skill |
-| Beta autonomous review | `/ce:review-beta mode:autonomous` → Downstream-resolver residual todos → `/resolve-todo-parallel` | Review skill + todos |
+| Beta autonomous review | `/ce:review-beta mode:autonomous` -> Downstream-resolver residual todos -> `/resolve-todo-parallel` | Review skill + todos |
-| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill |
+| PR comments | `/resolve_pr_parallel` -> Individual fixes -> Todos | gh CLI + skill |
-| Code TODOs | `/resolve-todo-parallel` → Fixes + Complex todos | Agent + skill |
+| Code TODOs | `/resolve-todo-parallel` -> Fixes + Complex todos | Agent + skill |
-| Planning | Brainstorm → Create todo → Work → Complete | Skill |
+| Planning | Brainstorm -> Create todo -> Work -> Complete | Skill |
-| Feedback | Discussion → Create todo → Triage → Work | Skill + slash |
+| Feedback | Discussion -> Create todo -> Triage -> Work | Skill |
 
-## Quick Reference Commands
+## Quick Reference Patterns
+
+Use the native file-search/glob tool (e.g., Glob in Claude Code) and content-search tool (e.g., Grep in Claude Code) for these operations. Search both canonical and legacy directory paths.
 
 **Finding work:**
-```bash
-# List highest priority unblocked work
-grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md
 
-# List all pending items needing triage
+| Goal | Tool | Pattern |
-ls todos/*-pending-*.md
+|------|------|---------|
-
+| List highest priority unblocked work | Content-search | `dependencies: \[\]` in `*-ready-p1-*.md` |
-# Find next issue ID
+| List all pending items needing triage | File-search | `*-pending-*.md` |
-ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'
+| Find next issue ID | File-search | `[0-9]*-*.md`, extract highest numeric prefix |
-
+| Count by status | File-search | `*-pending-*.md`, `*-ready-*.md`, `*-complete-*.md` |
-# Count by status
-for status in pending ready complete; do
-  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
-done
-```
 
 **Dependency management:**
-```bash
-# What blocks this todo?
-grep "^dependencies:" todos/003-*.md
 
-# What does this todo block?
+| Goal | Tool | Pattern |
-grep -l 'dependencies:.*"002"' todos/*.md
+|------|------|---------|
-```
+| What blocks this todo? | Content-search | `^dependencies:` in the specific todo file |
+| What does this todo block? | Content-search | `dependencies:.*"{id}"` across all todo files |
 
 **Searching:**
-```bash
-# Search by tag
-grep -l "tags:.*rails" todos/*.md
 
-# Search by priority
+| Goal | Tool | Pattern |
-ls todos/*-p1-*.md
+|------|------|---------|
-
+| Search by tag | Content-search | `tags:.*{tag}` across all todo files |
-# Full-text search
+| Search by priority | File-search | `*-p1-*.md` (or p2, p3) |
-grep -r "payment" todos/
+| Full-text search | Content-search | `{keyword}` across both directory paths |
-```
 
 ## Key Distinctions
 
 **File-todos system (this skill):**
-- Markdown files in `todos/` directory
+- Markdown files in `.context/compound-engineering/todos/` (legacy: `todos/`)
-- Development/project tracking
+- Development/project tracking across sessions and agents
 - Standalone markdown files with YAML frontmatter
-- Used by humans and agents
+- Persisted to disk, cross-agent accessible
 
-**Rails Todo model:**
+**In-session task tracking (e.g., TaskCreate/TaskUpdate in Claude Code, update_plan in Codex):**
-- Database model in `app/models/todo.rb`
-- User-facing feature in the application
-- Active Record CRUD operations
-- Different from this file-based system
-
-**TodoWrite tool:**
 - In-memory task tracking during agent sessions
 - Temporary tracking for single conversation
-- Not persisted to disk
+- Not persisted to disk after session ends
-- Different from both systems above
+- Different purpose: use for tracking steps within a session, not for durable cross-session work items

plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md

@@ -10,7 +10,7 @@ Resolve all TODO comments using parallel processing, document lessons learned, t
 
 ### 1. Analyze
 
-Get all unresolved TODOs from the /todos/*.md directory
+Get all unresolved TODOs from `.context/compound-engineering/todos/*.md` and legacy `todos/*.md`
 
 Residual actionable work may come from `ce:review-beta mode:autonomous` after its in-skill `safe_auto` pass. Treat those todos as normal unresolved work items; the review skill has already decided they should not be auto-fixed inline.
 
@@ -54,9 +54,9 @@ GATE: STOP. Verify that the compound skill produced a solution document in `docs
 
 ### 6. Clean Up Completed Todos
 
-List all todos and identify those with `done` or `resolved` status, then delete them to keep the todo list clean and actionable.
+Search both `.context/compound-engineering/todos/` and legacy `todos/` for files with `done`, `resolved`, or `complete` status, then delete them to keep the todo list clean and actionable.
 
-If a scratch directory was used and the user did not ask to inspect it, clean it up after todo cleanup succeeds.
+If a per-run scratch directory was created at `.context/compound-engineering/resolve-todo-parallel/<run-id>/`, and the user did not ask to inspect it, delete that specific `<run-id>/` directory after todo cleanup succeeds. Do not delete any other `.context/` subdirectories.
 
 After cleanup, output a summary:
 

plugins/compound-engineering/skills/test-browser/SKILL.md

@@ -225,12 +225,12 @@ When a test fails:
 
    How to proceed?
    1. Fix now - I'll help debug and fix
-   2. Create todo - Add to todos/ for later
+   2. Create todo - Add a todo for later (using the file-todos skill)
    3. Skip - Continue testing other pages
    ```
 
 3. **If "Fix now":** investigate, propose a fix, apply, re-run the failing test
-4. **If "Create todo":** create `{id}-pending-p1-browser-test-{description}.md`, continue
+4. **If "Create todo":** load the `file-todos` skill and create a todo with priority p1 and description `browser-test-{description}`, continue
 5. **If "Skip":** log as skipped, continue
 
 ### 10. Test Summary

plugins/compound-engineering/skills/test-xcode/SKILL.md

@@ -139,12 +139,12 @@ When a test fails:
 
    How to proceed?
    1. Fix now - I'll help debug and fix
-   2. Create todo - Add to todos/ for later
+   2. Create todo - Add a todo for later (using the file-todos skill)
    3. Skip - Continue testing other screens
    ```
 
 3. **If "Fix now":** investigate, propose a fix, rebuild and retest
-4. **If "Create todo":** create `{id}-pending-p1-xcode-{description}.md`, continue
+4. **If "Create todo":** load the `file-todos` skill and create a todo with priority p1 and description `xcode-{description}`, continue
 5. **If "Skip":** log as skipped, continue
 
 ### 8. Test Summary

plugins/compound-engineering/skills/triage/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 ---
 
 - First set the /model to Haiku
-- Then read all pending todos in the todos/ directory
+- Then read all pending todos from `.context/compound-engineering/todos/` and legacy `todos/` directories
 
 Present all findings, decisions, or issues here one by one for triage. The goal is to go through each item and decide whether to add it to the CLI todo system.
 
@@ -149,7 +149,7 @@ Do you want to add this to the todo list?
 
 **When user says "next":**
 
-- **Delete the todo file** - Remove it from todos/ directory since it's not relevant
+- **Delete the todo file** - Remove it from its current location since it's not relevant
 - Skip to the next item
 - Track skipped items for summary
 
@@ -182,22 +182,22 @@ After all items processed:
 
 ### Skipped Items (Deleted):
 
-- Item #5: [reason] - Removed from todos/
+- Item #5: [reason] - Removed
-- Item #12: [reason] - Removed from todos/
+- Item #12: [reason] - Removed
 
 ### Summary of Changes Made:
 
 During triage, the following status updates occurred:
 
 - **Pending → Ready:** Filenames and frontmatter updated to reflect approved status
-- **Deleted:** Todo files for skipped findings removed from todos/ directory
+- **Deleted:** Todo files for skipped findings removed
 - Each approved file now has `status: ready` in YAML frontmatter
 
 ### Next Steps:
 
 1. View approved todos ready for work:
    ```bash
-   ls todos/*-ready-*.md
+   ls .context/compound-engineering/todos/*-ready-*.md todos/*-ready-*.md 2>/dev/null
    ```
 ````
 
@@ -272,7 +272,7 @@ Do you want to add this to the todo list?
 4. Confirm: "✅ Approved: `{filename}` (Issue #{issue_id}) - Status: **ready**"
 
 **When "next" is selected:**
-1. Delete the todo file from todos/ directory
+1. Delete the todo file from its current location
 2. Skip to next item
 3. No file remains in the system
 

tests/review-skill-contract.test.ts

@@ -36,7 +36,7 @@ describe("ce-review-beta contract", () => {
       'If the fixer queue is empty, do not offer "Apply safe_auto fixes" options.',
     )
     expect(content).toContain(
-      "In autonomous mode, create durable `todos/` items only for unresolved actionable findings whose final owner is `downstream-resolver`.",
+      "In autonomous mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`.",
     )
     expect(content).toContain("If only advisory outputs remain, create no todos.")
     expect(content).toContain("**On the resolved review base/default branch:**")