Todos

workflow no always-loaded rules -- loads on demand updated 2026-06-22

File-based review-finding tracker. Review findings, PR nitpicks, and tech debt that does not merit a full GitHub issue go to .claude/todos/NNN-{status}-{priority}-{description}.md with YAML frontmatter. Three skills compose - /todo-create (canonical writer), /todo-triage (interactive pending->ready), /todo-resolve (batch-resolve ready todos via parallel subagents). Fills the gap between review-found-it and cut-an-issue with a lightweight, in-repo third option.

README

Todos

File-based review-finding tracker. Review findings, PR nitpicks, and tech debt that does not warrant a full GitHub issue go to .claude/todos/NNN-{status}-{priority}-{slug}.md in the repo being worked on.

Why

CCGM already has two coordination surfaces:

Surface	Scope	Commit to repo?
GitHub Issues + tracking.csv	cross-session, cross-agent, user-triaged work	no (GitHub + log repo)
`self-improving` / `compound-knowledge`	durable learnings and patterns	yes (per-repo and personal)

Neither fits a p3 nitpick a reviewer leaves on line 42 of a PR. An issue is heavyweight. A learning is the wrong type. The item still deserves to be written down somewhere, or it gets lost between "review found it" and "cut an issue."

todos fills that gap. It is deliberately lightweight - three skills, a filename convention, a small frontmatter schema. No hooks, no hidden state, no external service.

File Layout

.claude/todos/
  README.md                                    # per-repo convention reminder
  001-pending-p2-extract-auth-middleware.md    # freshly captured
  002-ready-p3-rename-foo-to-bar.md            # triaged, scoped, ready to fix
  003-complete-p1-fix-null-pointer.md          # done, kept for history
  .runs/                                       # optional autofix run artifacts
    20260416-1430.md

Filename encodes status and priority so a bare ls gives a visual scan without reading each file. Status changes rename the file in place.

See skills/todo-create/references/schema.yaml for the full frontmatter schema.

What This Module Provides

Files installed globally to ~/.claude/:

Source	Target	Purpose
`skills/todo-create/SKILL.md`	`skills/todo-create/SKILL.md`	`/todo-create` - canonical writer
`skills/todo-create/references/schema.yaml`	`skills/todo-create/references/schema.yaml`	YAML schema for frontmatter
`skills/todo-triage/SKILL.md`	`skills/todo-triage/SKILL.md`	`/todo-triage` - pending -> ready
`skills/todo-resolve/SKILL.md`	`skills/todo-resolve/SKILL.md`	`/todo-resolve` - batch-fix ready todos

Manual Installation

# From the CCGM repo root:

mkdir -p ~/.claude/skills/todo-create/references
mkdir -p ~/.claude/skills/todo-triage
mkdir -p ~/.claude/skills/todo-resolve

cp modules/todos/skills/todo-create/SKILL.md \
   ~/.claude/skills/todo-create/SKILL.md

cp modules/todos/skills/todo-create/references/schema.yaml \
   ~/.claude/skills/todo-create/references/schema.yaml

cp modules/todos/skills/todo-triage/SKILL.md \
   ~/.claude/skills/todo-triage/SKILL.md

cp modules/todos/skills/todo-resolve/SKILL.md \
   ~/.claude/skills/todo-resolve/SKILL.md

Per-Repo Bootstrap

todos writes to the repo being worked on, not CCGM or ~/.claude/. Each consuming repo needs a small one-time setup:

.claude/todos/ - the skill creates this on first use.
.claude/todos/README.md - the skill writes this on first use, explaining the convention.

A pointer block in the repo's AGENTS.md or CLAUDE.md:

## Todos

Review findings and PR nitpicks that do not warrant a GitHub issue live in
`.claude/todos/` as `NNN-{status}-{priority}-{slug}.md` files. Run
`/todo-triage` to promote pending todos to ready; run `/todo-resolve` to
batch-fix ready todos.

The /todo-create skill runs a Discoverability Check on first use and offers to add the pointer and README if missing. Pre-seeding is optional.

Usage

Capture a finding

/todo-create extract the auth middleware out of the request handler, p2
/todo-create

With arguments, writes the todo directly. With no arguments, uses the most recent review finding or PR comment visible in the conversation.

Triage the pending list

/todo-triage
/todo-triage mode:autofix
/todo-triage mode:report-only

Walks each pending todo and asks confirm / skip / modify / drop. Confirmed todos get a Proposed Change section and move to ready. mode:autofix only promotes todos with already-concrete bodies; vague ones stay pending.

Batch-resolve ready todos

/todo-resolve
/todo-resolve priority:p3
/todo-resolve only:7,12,19
/todo-resolve mode:autofix
/todo-resolve mode:report-only

Dispatches parallel subagents, one per ready todo, with pass-paths-not-contents. Applies fixes, updates status to complete, posts inline PR replies for PR-sourced todos, and prints a run summary. Skips todos whose dependencies are not complete.

Composition With Other CCGM Skills

todo-create is the canonical writer. Other skills invoke it rather than duplicating the filename and frontmatter rules:

ce-review (future) - for each finding not fixed inline during review, call /todo-create instead of writing its own file.
resolve-pr-feedback (future, CCGM #283) - for each PR comment that cannot be fixed in the same pass, call /todo-create with source: pr-comment.
/xplan - for future-work items surfaced during planning that are not scope for the current plan.

All three resolver-style skills (/todo-resolve, ce-review, /xplan) share the pass-paths-not-contents dispatch and four-state subagent return contract documented in modules/subagent-patterns/rules/subagent-patterns.md.

Dependencies

skill-authoring - all three skills follow the skill-authoring discipline (reference files via backticks, imperative voice, mode token parsing, etc.)
subagent-patterns - /todo-resolve uses the pass-paths-not-contents dispatch pattern and the four-state status protocol

No runtime dependencies beyond the module system.

Non-Goals

This module does not:

Replace GitHub Issues. Issues stay the source of truth for multi-session, cross-agent work.
Replace compound-knowledge. Todos are short-lived work items; docs/solutions/ is durable team knowledge.
Ship a TUI or web UI. ls .claude/todos/ and your editor are the UI.
Install .claude/todos/ in any repo. The skill bootstraps per-repo on first use.

Source

Ported from EveryInc/compound-engineering-plugin (skills/todo-create, skills/todo-triage, skills/todo-resolve). The original ships under .context/compound-engineering/todos/; CCGM adopts the same three-skill structure at .claude/todos/ to match CCGM's directory conventions.

Adaptations from the source:

Directory path: .claude/todos/ instead of .context/compound-engineering/todos/
Mode token names match the CCGM skill-authoring convention (mode:interactive, mode:autofix, mode:report-only, mode:headless)
Frontmatter schema is extracted to skills/todo-create/references/schema.yaml so the skill body does not carry it in every invocation
/todo-resolve dispatch uses the pass-paths-not-contents pattern and the four-state subagent return contract (DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT) from modules/subagent-patterns

Will install

Path	Action	Target	Type
`skills/todo-create/SKILL.md`	→	`skills/todo-create/SKILL.md`	skill
`skills/todo-create/references/schema.yaml`	→	`skills/todo-create/references/schema.yaml`	doc
`skills/todo-triage/SKILL.md`	→	`skills/todo-triage/SKILL.md`	skill
`skills/todo-resolve/SKILL.md`	→	`skills/todo-resolve/SKILL.md`	skill

Dependencies

Required by

No other module depends on this one.

Included in presets

full

Install this module

Agent prompt

Recommended for agent users -- hands the whole install off to your assistant.

Fetch https://cd23a9be.ccgm-site.pages.dev/modules/todos.md and install this module into my Claude Code setup.

Native plugin marketplace

One command via the native plugin marketplace -- additive, does not merge settings.json.

claude plugin install todos@ccgm

The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.

Manual, per file

Full control -- copy exactly the files you want from the sections below.

Files

skill (3)

skills/todo-create/SKILL.md

---
name: todo-create
description: >
  Capture a review finding, PR comment, or tech-debt item as a file under .claude/todos/ in the current repo. Writes NNN-{status}-{priority}-{slug}.md with YAML frontmatter per the schema. Canonical writer - other skills (todo-triage, todo-resolve, ce-review) call this one to avoid duplicating the file-naming and frontmatter rules. Todos start as status:pending by default; promote via /todo-triage.
  Triggers: todo, add todo, capture this as a todo, track this finding, write a todo, note this for later, add to todos.
disable-model-invocation: true
---

# /todo-create - Write a Todo

Capture a reviewable item that is not worth a full GitHub issue but is worth not forgetting. Writes `.claude/todos/NNN-{status}-{priority}-{slug}.md` in the current repo.

## When to Use

Write a todo when:

- A code reviewer flags a nitpick or small concern and the fix does not fit in this PR
- A PR reviewer leaves a comment that needs action later (not immediate)
- While solving problem A you notice problem B and do not want to context-switch
- `/xplan` surfaces a future-work item that is not scope for the current plan
- A debug session uncovers tech debt adjacent to the bug being fixed

Do NOT write a todo when:

- The item belongs in a GitHub issue (multi-session, cross-cutting, needs product input)
- The item belongs in team-shared knowledge (durable learning - use `/compound` instead)
- The item belongs in personal memory (user preference, working style - use self-improving)
- You can fix it right now in two minutes - just fix it

The rule: **agent time is cheap, tech debt is expensive. If an item is valid, capture it - including nitpicks.**

## Directory

Todos live in `.claude/todos/` in the repo being worked on, not in CCGM or `~/.claude/`. This is a per-repo concern, committed with the rest of the code.

If `.claude/todos/` does not exist:

1. Create it.
2. Write `.claude/todos/README.md` with a one-paragraph summary of the convention and a pointer to this skill.
3. Offer to add a short pointer block to the repo's `AGENTS.md` or `CLAUDE.md`:

   ```markdown
   ## Todos

   Review findings and PR nitpicks that do not warrant a GitHub issue live
   in `.claude/todos/` as `NNN-{status}-{priority}-{slug}.md` files. Run
   `/todo-triage` to promote pending todos to ready; run `/todo-resolve` to
   batch-fix ready todos.
   ```

## Inputs

Parse `$ARGUMENTS` for:

- A free-form description (everything else). Example: `/todo-create extract the auth middleware out of the request handler, p2, from ce-review`

If `$ARGUMENTS` is empty, use the most recent discussion context - the last review finding, PR comment, or debug observation visible in the current conversation.

Infer the following from context (ask only when genuinely unclear):

- `priority` - p1 (blocks something), p2 (this cycle), p3 (nitpick). Default p3 if the item came from a nitpick or style comment, p2 otherwise.
- `source` - review, pr-comment, debug, planning, ad-hoc. Default ad-hoc.
- `pr` - if a PR number is visible in context, record it.
- `files` - paths the todo touches, if known.
- `status` - always `pending` at creation. Triage promotes.

## Sequence Number Allocation

Pick the next number by scanning existing files:

```bash
ls .claude/todos/*.md 2>/dev/null \
  | sed -E 's#.*/([0-9]{3})-.*#\1#' \
  | sort -n | tail -1
```

Increment by one, zero-pad to three digits. If no files exist, start at `001`. Never reuse numbers.

## Filename and Frontmatter

Filename: `.claude/todos/NNN-pending-{priority}-{slug}.md`

Slug rules (matches `references/schema.yaml`):

- lowercase, kebab-case
- <= 40 chars
- no trailing punctuation
- truncate at a word boundary, not mid-word

Frontmatter - see `references/schema.yaml` for the full schema. Required fields on every todo:

```yaml
---
title: <one-line imperative>
status: pending
priority: <p1|p2|p3>
created: <YYYY-MM-DD>
source: <review|pr-comment|debug|planning|ad-hoc>
---
```

Include `pr`, `files`, `dependencies`, `tags` when known.

## Body

Write the body in this order:

1. **Context** - one paragraph. Where did this surface? Who flagged it? What were they working on?
2. **Problem** - what is wrong or missing, concretely. If the item came from a review comment, quote the relevant sentence.
3. (Skip **Proposed change** at create time - `/todo-triage` writes this when promoting to ready.)
4. **Notes** - optional. Links to the PR thread, prior docs, or adjacent todos.

Do not speculate about the fix at create time. The triage pass is the place to commit to a direction; capture just enough for triage to have the context it needs.

## Output

After writing the file, print one line:

```
Wrote .claude/todos/NNN-pending-{priority}-{slug}.md (source: {source})
```

If the caller is another skill (headless mode - see `modules/subagent-patterns/rules/subagent-patterns.md`), return the created path in a structured envelope instead of printing.

## When Called From Another Skill

`todo-create` is the canonical writer. `/todo-triage`, `/todo-resolve`, and the review orchestrator (`ce-review`) invoke it to avoid duplicating the filename/frontmatter rules. When called this way:

- Skip the Discoverability Check (the caller has already bootstrapped `.claude/todos/`)
- Accept a structured input object instead of parsing `$ARGUMENTS`
- Return the created path as structured output, no conversational prose

See `references/schema.yaml` for the exact fields.

skills/todo-triage/SKILL.md

---
name: todo-triage
description: >
  Walk every pending todo in .claude/todos/ one at a time. For each, confirm / skip / modify / drop, and on confirm, promote to status:ready with a concrete Proposed Change section. Interactive by default; supports mode:autofix for low-risk promotions and mode:report-only for a dry-run table. Runs before /todo-resolve so the resolver only sees scoped, agreed-upon items.
  Triggers: todo triage, triage todos, review todos, promote todos, walk the todo list, clean up todos.
disable-model-invocation: true
---

# /todo-triage - Promote Pending Todos to Ready

`/todo-create` captures raw findings. `/todo-triage` decides which ones to fix.

The purpose of triage is not to be strict - it is to turn vague captures into scoped, agreed-upon work. A ready todo has a one-paragraph Proposed Change that another agent (or human) can execute without re-reading the review thread.

## When to Run

- Before starting `/todo-resolve` so the resolver only touches scoped items
- After a batch of `/todo-create` calls (e.g., at the end of a review session)
- Weekly, as a standing chore - pending todos drift into irrelevance faster than ready ones
- Before closing out a milestone, to decide which pending items graduate to ready vs. drop

## Mode Selection

Parse `$ARGUMENTS` for a mode token (convention from `modules/subagent-patterns/rules/subagent-patterns.md`):

- `mode:interactive` (default) - For each pending todo, ask the user confirm / skip / modify / drop
- `mode:autofix` - Auto-promote any pending todo where the body is concrete enough to write a Proposed Change without user input; leave everything else as pending
- `mode:report-only` - Strictly read-only. Print a classification table per todo and exit

When composed from another skill (e.g., `ce-review`), prefer `mode:report-only` and let the caller decide per-item.

## Phase 1: Inventory

List every `.claude/todos/NNN-pending-*.md` in the current repo:

```bash
ls .claude/todos/*-pending-*.md 2>/dev/null
```

Sort by priority (p1 > p2 > p3), then by sequence number ascending within each priority band. This surfaces the most urgent items first and preserves capture order as a tiebreaker.

If zero pending todos: print "No pending todos. Nothing to triage." and exit.

## Phase 2: Per-Todo Decision

For each pending todo in the sorted list:

1. Read the file (frontmatter + body).
2. Summarize in two to three lines:
   - `#NNN [{priority}] {title}`
   - Context one-liner (from body Context section)
   - What would Proposed Change look like, in one sentence
3. Prompt the user (interactive mode):

   ```
   [C]onfirm + promote to ready   [S]kip (leave pending)
   [M]odify title / priority      [D]rop (delete file)
   ```

4. Apply the decision:

   - **Confirm** - write the Proposed Change section in the body (one paragraph, imperative voice). Change frontmatter `status: pending` -> `status: ready`. Rename file from `NNN-pending-{priority}-{slug}.md` to `NNN-ready-{priority}-{slug}.md`.
   - **Skip** - no-op. Todo stays pending.
   - **Modify** - ask only for the fields being changed (title, priority). Rewrite frontmatter and rename file if priority changed.
   - **Drop** - delete the file. Print the NNN and title so there is a record in the session.

In `mode:autofix`:

- Confirm automatically if the body already contains explicit direction (e.g., the Context section says "reviewer suggests extracting X into Y")
- Skip (leave pending) if the body is vague or a decision is needed
- Never auto-drop

In `mode:report-only`:

- Print the per-todo summary above, plus a recommended decision (Confirm / Skip / Drop), but take no action

## Phase 3: Proposed Change Template

When promoting to ready, write or append a `## Proposed change` section to the body. Use this template:

```markdown
## Proposed change

<one paragraph in imperative voice describing the fix. Be specific about which file(s) or function(s) to touch. Avoid hedging.>

**Files**: <comma-separated list, or "TBD during implementation">
**Estimated effort**: <S | M | L> (< 30 min / 30-120 min / > 2 hr)
**Acceptance check**: <one sentence describing how to confirm the fix landed>
```

If the Proposed Change is uncertain enough that the user would need to provide it, do not autofix - prompt.

## Phase 4: Summary

After the walk, print a compact summary:

```
Triaged N pending todos:
  promoted -> ready : M
  dropped           : K
  modified          : J
  still pending     : P
```

If any ready todos now exist, suggest the next step:

```
Next: run /todo-resolve to batch-fix M ready todos, or pick specific ones.
```

## File Renaming Notes

Renaming is atomic per todo. If a rename fails (filesystem, permissions), roll back the frontmatter edit so the file and frontmatter stay consistent. Never leave a file where the frontmatter status does not match the filename status - `/todo-resolve` relies on both being in sync.

## Composition

When called from `ce-review` or another orchestrator in headless mode:

- Accept a list of todo paths as structured input instead of walking the whole directory
- Return a structured report: `{ promoted: [...], skipped: [...], dropped: [...] }`
- Do not prompt the user; honor `mode:autofix` or `mode:report-only` strictly

See `modules/subagent-patterns/rules/subagent-patterns.md` for the mode contract.

skills/todo-resolve/SKILL.md

---
name: todo-resolve
description: >
Batch-resolve ready todos in .claude/todos/. Dispatches parallel subagents (one per todo) with pass-paths-not-contents, aggregates their fixes, updates each todo's status to complete, and optionally feeds the pattern back into /compound for team knowledge. Filter by priority, source, or explicit numbers. Skips todos whose dependencies are not complete. Modes - interactive (confirm before each) / autofix / report-only / headless.
Triggers: todo resolve, resolve todos, fix ready todos, batch fix todos, burn down todos, process the todo list.
disable-model-invocation: true
---

# /todo-resolve - Batch-Fix Ready Todos

`/todo-triage` decides which todos are ready. `/todo-resolve` does the work.

This skill exists because small findings accumulate. Ten p3 nits are individually trivial but collectively a drag. Dispatching one subagent per todo lets the orchestrator burn through them in parallel without polluting the main context.

## When to Run

- At the start of a session, before diving into new feature work - clear the backlog first
- After `/todo-triage` promotes a batch of items to ready
- Before cutting a release or merging a long-lived branch - land the nitpicks with the feature
- When a reviewer comes back with cluster of small comments and you would rather batch than ping-pong

Do not run during active feature development on the same files - the parallel fan-out will conflict with in-flight edits.

## Mode Selection

Parse `$ARGUMENTS` for a mode token:

- `mode:interactive` (default) - Plan the batch, show the plan, ask before dispatching
- `mode:autofix` - Plan and dispatch without asking; write a run artifact at `.claude/todos/.runs/YYYYMMDD-HHMM.md` summarizing what landed
- `mode:report-only` - Produce the plan only. Do not dispatch. Safe for concurrent runs
- `mode:headless` - For skill-to-skill composition. Structured output envelope, no prompts, no conversational prose, terminal "Resolve complete" line

## Filtering

Parse `$ARGUMENTS` for optional filters (compose with the mode token):

- `priority:p1` (or `p2`, `p3`) - only this priority band
- `source:review` (or `pr-comment`, `debug`, `planning`, `ad-hoc`) - only this source
- `pr:123` - only todos tied to PR 123
- `only:7,12,19` - only the listed sequence numbers
- no filter - all `status: ready` todos

## Phase 1: Plan

1. List candidates: every `.claude/todos/NNN-ready-*.md` matching the filter.
2. For each candidate, read frontmatter and body.
3. Build a dependency graph from the `dependencies` frontmatter field.
4. Skip any todo whose dependencies are not `status: complete`. Record these as `blocked` in the plan, do not dispatch.
5. Print the plan:

```
Plan: resolve N ready todos in parallel.

dispatching:
#007 [p2] extract-auth-middleware (files: src/auth/*.ts)
#012 [p3] rename-foo-to-bar (files: src/utils/foo.ts)

blocked (dependencies not complete):
#019 [p2] add-rate-limiter (waits on #015)

skipped (out of filter):
#003 [p1] ...
```

6. In `mode:interactive`, ask: `Dispatch N subagents in parallel? [y/n/edit]`. In `mode:autofix` and `mode:headless`, proceed. In `mode:report-only`, stop here.

## Phase 2: Dispatch

Dispatch one subagent per non-blocked todo, in parallel. Each subagent spec:

> **Concurrency — avoid the 429 throttle.** Dispatch resolver subagents at `model: "sonnet"` with medium reasoning effort, and **launch at most 4 at once**. If more than 4 todos are ready, run them in sequential waves of 4 (dispatch 4, wait for them to return, dispatch the next 4) rather than one burst — a batch of 10 ready todos must NOT become 10 simultaneous agents. Bursting too many heavy agents trips a server-side rate limit (`Server is temporarily limiting requests · Rate limited`) that fails the whole batch; if you hit it, wait 30–60s and re-dispatch only the unfinished todos in waves of ≤4. See `~/.claude/rules/concurrency-and-rate-limits.md`.

**Objective** - Implement the Proposed Change section of the todo file.

**Context** (pass paths, not contents - see `modules/subagent-patterns/rules/subagent-patterns.md`):

- Path to the todo file: `.claude/todos/NNN-ready-{priority}-{slug}.md`
- Paths from the todo's `files` frontmatter field (if present)
- Path to the repo's `AGENTS.md` or `CLAUDE.md` for house style

**Constraints**:

- Modify only the files in the todo's `files` field. If a change requires editing a path not listed, STOP and return `BLOCKED` with an explanation.
- No cross-todo edits. If the fix uncovers a second issue, write a new todo via `/todo-create` and keep it out of the current fix.
- One commit per todo if committing inside the subagent; otherwise return the diff for the orchestrator to commit.

**Deliverable** - Either:

- `DONE` + diff + one-paragraph resolution note, or
- `BLOCKED` + reason, or
- `NEEDS_CONTEXT` + the specific missing information, or
- `DONE_WITH_CONCERNS` + diff + concerns section

See `modules/subagent-patterns/rules/subagent-patterns.md` for the four-state completion protocol.

## Phase 3: Two-Stage Review

When subagents return, do not trust self-reports. Two passes (see subagent-patterns):

1. **Spec compliance** - Did each subagent do what was asked? Constraints respected?
2. **Code quality** - Does the diff match project patterns? Any missed edge cases?

Re-dispatch with specific feedback for any subagent that failed either stage. Do not silently patch subagent output.

## Phase 4: Commit and Close

For each `DONE` subagent:

1. Stage the diff if not already committed.
2. Commit with message: `#todo-NNN: {title}` (plural `todos: ...` if batching multiple into one commit).
3. Update the todo file:
- Frontmatter: `status: ready` -> `status: complete`
- Body: append a `## Resolution` section with the resolution note and commit SHA
4. Rename file: `NNN-ready-{priority}-{slug}.md` -> `NNN-complete-{priority}-{slug}.md`

For each `DONE_WITH_CONCERNS`: same as DONE, but preserve the concerns section in the Resolution body for future reference.

For each `BLOCKED` or `NEEDS_CONTEXT`: leave the todo as ready, append a `## Attempt` section noting what was tried and why it stalled.

## Phase 5: Report and Compound

Print a run summary:

```
Resolved N ready todos:
complete : M
blocked : K
needs_context : J
concerns : P

Commits: {shas}
```

If M >= 3 or any concerns were flagged, suggest:

```
Consider running /compound to capture the pattern that surfaced across these fixes.
```

Do not auto-invoke `/compound`. Compound is explicit - the user or the orchestrator decides when a batch of todos represents a durable team learning vs. just cleanup.

## PR Comment Back-Reference

For todos with a `pr:` frontmatter field and source `pr-comment`:

- After the fix commits, post a short inline reply on the GitHub PR thread via `gh api` noting the resolution (commit SHA + one-line summary).
- Do not resolve the thread automatically - the reviewer resolves. Post, do not close.

If `gh` is not authenticated or the PR is merged, skip the comment and note it in the run summary.

## Composition

When called from `ce-review` or a batch orchestrator in `mode:headless`:

- Accept explicit todo paths instead of scanning the directory
- Return a structured envelope: `{ complete: [...], blocked: [...], concerns: [...] }`
- Do not prompt, do not post conversational prose
- End with `Resolve complete` on its own line so the caller can detect termination

See `modules/subagent-patterns/rules/subagent-patterns.md` for the full mode contract.

## Agent Time vs. Tech Debt

The adoption rationale for this whole module: **agent time is cheap, tech debt is expensive**. A p3 nit that sits in a review thread forever costs more in re-review and context-switching than it does to fix in a parallel subagent. Default to resolving, not deferring. The only reason to leave a ready todo unresolved is a real dependency or a legitimate scope concern - not "it is small, I will get to it."

doc (1)

skills/todo-create/references/schema.yaml

# Frontmatter schema for .claude/todos/**/*.md
#
# Every todo file under .claude/todos/ starts with a YAML frontmatter
# block matching this schema. The filename encodes status and priority
# so a bare `ls .claude/todos/` gives a fast visual scan without reading
# each file.

# --- Filename convention ---
#
# .claude/todos/NNN-{status}-{priority}-{slug}.md
#
# - NNN     : zero-padded sequence number (001, 002, ...) allocated at
#             creation time. Never renumbered. Gaps are fine after resolve.
# - status  : pending | ready | complete
#             Matches the frontmatter status field. When the status
#             changes the file is renamed in place.
# - priority: p1 | p2 | p3
#             p1 = must-fix before next PR / blocks something
#             p2 = should-fix this cycle
#             p3 = nice-to-fix, nitpick, style, polish
# - slug    : short-kebab-case-description, <= 40 chars
#
# Example: .claude/todos/007-ready-p2-extract-auth-middleware.md

fields:
  title:
    required: true
    type: string
    description: >
      One-line human-readable title. Imperative voice. Example:
      "Extract auth middleware out of the request handler".

  status:
    required: true
    type: enum
    values:
      - pending
      - ready
      - complete
    description: >
      pending - captured but not yet triaged. /todo-triage decides to
                promote to ready (with concrete scope) or drop.
      ready   - scoped, agreed, ready to be picked up by /todo-resolve
                or a human in the next editing pass.
      complete- resolved. Kept for history; /todo-resolve updates this
                and writes a short resolution note in the body.

  priority:
    required: true
    type: enum
    values:
      - p1
      - p2
      - p3
    description: >
      p1 blocks the current PR or a downstream task. p2 is this-cycle
      work that should not slip to the next release. p3 is polish,
      nitpicks, and low-risk style items.

  created:
    required: true
    type: string
    format: YYYY-MM-DD
    description: Date the todo was first captured.

  source:
    required: true
    type: enum
    values:
      - review
      - pr-comment
      - debug
      - planning
      - ad-hoc
    description: >
      Where the todo came from. review = code review finding; pr-comment
      = GitHub PR review thread; debug = surfaced while debugging an
      unrelated bug; planning = noted during /xplan; ad-hoc = anything
      else. Used by /todo-resolve to route to the right fixer subagent.

  pr:
    required: false
    type: integer
    description: >
      GitHub PR number the todo originated from, if any. Enables
      /todo-resolve to post a resolution comment back on the thread.

  files:
    required: false
    type: array
    description: >
      Paths the todo touches, relative to repo root. Lets /todo-resolve
      dispatch subagents with pass-paths-not-contents.

  dependencies:
    required: false
    type: array
    description: >
      Other todo sequence numbers this one depends on. Example: [3, 7].
      /todo-resolve will not run a todo whose dependencies are not
      status:complete.

  tags:
    required: false
    type: array
    description: >
      Free-form searchable tags. Example - ["refactor", "auth"].

# --- Body convention ---
#
# Body sections in order:
#   1. Context        - one paragraph. What surfaced this? Who flagged it?
#   2. Problem        - what is wrong or missing, concretely.
#   3. Proposed change- what the fix should look like, in imperative voice.
#                       Skip this section until triage promotes to ready.
#   4. Notes          - optional. Links, prior art, discussion snippets.
#   5. Resolution     - written by /todo-resolve when status flips to
#                       complete. One paragraph: what was done, commit
#                       SHA, and any follow-ups spawned.

View source on GitHub

Tags

README

Todos

Why

File Layout

What This Module Provides

Manual Installation

Per-Repo Bootstrap

Usage

Capture a finding

Triage the pending list

Batch-resolve ready todos

Composition With Other CCGM Skills

Dependencies

Non-Goals

Source

Will install

Dependencies

Required by

Included in presets

Install this module

Agent prompt

Native plugin marketplace

Manual, per file

Files

skills/todo-create/SKILL.md

skills/todo-triage/SKILL.md

skills/todo-resolve/SKILL.md

skills/todo-create/references/schema.yaml