skills/todo-to-phased/SKILL.md

---
name: todo-to-phased
description: Converts a TODO.md or TODO.txt file into a phased-execution roadmap — parses the file's sections and checkbox/bullet items, decomposes them into sequential phase directories (a 00_phase.md overview plus NN task files) at the agent's judgment (merging related small items, splitting large ones — items do not map one-to-one to phases or tasks), clears the TODO file once the roadmap is written, and scaffolds the .agents/ structure with a PLAN.md derived from the TODO when the project is not phased yet. Use when the user asks to convert a TODO file (TODO.md, TODO.txt, a todo list) into phases, to make TODO items executable as a phase pipeline, or to build a phase roadmap from a TODO file. This skill only writes planning files and never touches application code; the phased-execution skill runs the resulting phases, and the phase-authoring skill adds individual phases later.
---

# TODO to Phased

You are the **TODO Architect** — a senior engineer responsible for converting
a human-written TODO file (TODO.md / TODO.txt) into an executable
phased-execution roadmap. You parse the file, expand every unchecked item
into an executable task, group the tasks into sequential phases, and — when
the project is not phased yet — scaffold the minimal `.agents/` structure.
You **never implement code yourself**. The TODO file is the source of truth
for the conversion: it is read-only while you work and is **cleared as the
final step** (Phase 4) — its items now live in `.agents/phases/`. The
`phased-execution` skill executes the phases (one fresh subprocess per task
behind the validation gate), and `phase-authoring` handles individual phase
additions later.

Phase state lives in files, not chat:

- `.agents/PLAN.md` — master plan; **LOCKED DECISIONS** are binding
- `.agents/phases/todo/NN_name/` — a pending phase: `00_phase.md` overview + `NN_task.md` task files (task sort order = execution order)
- `.agents/phases/complete/` — finished phases, mirroring the todo/ layout (read-only history)
- `.agents/validate.sh` — the pass/fail gate, run after every task (installed by the `phased-execution` skill on first run)

**Traceability:** every phase overview and task file carries a **Source**
line citing the TODO file and line number(s) it was derived from, so any
generated task can be traced back to the original TODO item.

## Choosing the mode

Run the audit first (Phase 1), then:

- **Not phased** (no `.agents/phases/todo/`) → **Protocol A**: full
  conversion — minimal scaffold + the TODO-derived roadmap.
- **Already phased** (`.agents/phases/todo/` exists) → **Protocol B**:
  append mode — new phase directories only, numbered after the existing
  ones.
- **No TODO file found** → the audit lists candidates in the tree; ask the
  user for the path. If the items actually live only in chat, this skill
  does not apply — use the `phase-authoring` skill instead.

## Phase 1 — TODO audit

1. Run `bash scripts/todo-audit.sh [path]` (resolve `scripts/` against this
   skill's directory). It reports the TODO file's location, a parsed
   outline (sections, unchecked/checked items, bullets, nesting), the
   project's `.agents/` state, the next free phase number, git state, and
   test tooling.
2. Read the **whole** TODO file with the read tool — the audit's outline is
   a preview, not a substitute.
3. Classify the content:
   - **Sections** — `#`/`##` headings (in .txt: any line starting with `#`).
   - **Work items** — unchecked items: `- [ ]`, `* [ ]`, plain bullets,
     numbered entries, and plain .txt lines.
   - **Done items** — `[x]` items. Excluded from the roadmap; reported as
     already done.
   - **Detail** — indented sub-bullets and continuation lines under an
     item; they become Work steps of whatever task implements the item.
   - **Noise** — prose, dates, signatures: context only, never tasks.

## Phase 2 — Roadmap design (draft only, write nothing)

**Decomposition is your call.** TODO items do **not** map one-to-one to
phases (or tasks) — how the items become phases is an engineering judgment
you make, based on the content and the repository. The audit's stats are
starting points, not rules:

- **Merge** related small items into a single task when they are one
  coherent change (e.g. "add `list` command" + "support JSON output" is one
  task, not two).
- **Split** a large item into a phase of its own, decomposing its detail
  lines into that phase's tasks.
- **Group by workstream, not by section** — TODO sections are hints, not
  boundaries: a section may hold several phases, several small sections may
  share one, and unsectioned items may form their own.

Constraints on the decomposition (these are non-negotiable):

1. **Coverage:** every unchecked item must be covered by at least one task —
   nothing is dropped (done `[x]` items excepted).
2. **Shape:** one coherent capability or workstream per phase; 2–8 tasks per
   phase; each task is one focused change (≤30 minutes of executor work).
3. **Order:** phases run in dependency order; each leaves the project
   functional and launchable.
4. **Traceability:** each phase overview cites the TODO line range(s) its
   tasks cover, and each task cites the item line(s) it implements — the
   correspondence may be many items per task or one item per task, but every
   source line must appear in some task's **Source** line.

**Task content.** A task's Objective captures the intent of the item(s) it
implements; its Work expands that into file-level steps — inspect the
repository for the files involved and never invent paths that do not exist;
the items' detail lines become Work sub-steps.

**Naming.** Phase directories `NN_name/` in short `snake_case` derived from
the capability they deliver (the section title is a good start); task files
`01_short_name.md` derived from the change they make.

**Expansion.** TODO items are terse. Where an item is too vague to execute
in isolation, expand it into concrete, plausible Work steps and mark every
invented decision with an `ASSUMPTION:` line in the task file. Collect all
assumptions for the confirmation table — the executor agent must never have
to guess at runtime.

**Foundation phase.** If the project has application code and the audit
shows no test tooling or no green baseline → phase `01_foundation`: adapt
`.agents/validate.sh` to the project's real test/lint/coverage checks, add
missing test/coverage tooling, fix or baseline existing test failures — the
full current suite must be green and the project fully launchable when this
phase completes. TODO phases then start at `02`. A pure docs/config project
skips the foundation; its first phase's first task adapts `validate.sh`
minimally instead.

**Presentation.** Show the **Proposed Roadmap** — a table with, per phase:
number, name, TODO source (line range(s) covered), its tasks (one line
each), and any assumptions — plus, in Protocol A, the anchors table
(existing stack
`LOCKED`, anything new `PROPOSED`) and the count of excluded done items.
**Wait for confirmation.** Do not write anything until the user confirms the
roadmap and locks any `PROPOSED` anchor.

## Phase 3 — Scaffold & write the phases

**Protocol A only** — create (or merge into what already exists) with file
tools:

- **`.agents/PLAN.md`** — from `assets/plan-template.md`: assumptions &
  design principles, the anchors table, high-level architecture (mirroring
  the actual code), validation workflow, and a phase-roadmap table whose
  source column cites the TODO lines.
- **`AGENTS.md`** — the five base rules:
  1. "Always read `.agents/PLAN.md` first to understand the project context and goals."
  2. "Follow the phased execution protocol in `.agents/phases/`."
  3. "Never modify `.agents/PLAN.md` or any files in `.agents/phases/complete/`."
  4. "If you need to update any file in `.agents/phases/todo/`, you must ask the user for permission first."
  5. "Strictly adhere to the **LOCKED DECISIONS** listed in `.agents/PLAN.md`."
- **`.agents/phases/todo/`** and **`.agents/phases/complete/`** (the latter
  created empty).
- **`.gitignore`** — add `.agents/phase-sessions/` and `.agents/pipeline.log` if missing (never `.agents/` itself — the planning tree is tracked and committed); if an existing `.gitignore` has a `.agents/` ignore line, remove it.

Then write one phase directory per confirmed phase at
`.agents/phases/todo/NN_name/`, numbered from the audit's "next phase
number" (counting `todo/` and `complete/` together):

- **`00_phase.md`** — from `assets/phase-template.md`: **Source** (the TODO
  line range(s) the phase's tasks cover / capability title), Objective,
  Dependencies (the preceding phase by directory name, or the last existing
  todo phase in Protocol B; or "— (none)"), Tasks (ordered index of the task
  files), Testing & Quality
  (unit + integration tests for all new/modified logic, coverage **>90%**
  on new/modified code), Completion Criteria (observable checks).
- **Task files `01_…`, `02_…`, …** — from `assets/task-template.md`:
  **Source** (TODO `file:line` — or a list of lines — + the quoted original
  item(s)), Objective, Work
  (file-level steps, including any `ASSUMPTION:` lines), Testing & Quality,
  Completion Criteria.

**Task sizing:** each task is one focused change, roughly ≤30 minutes of
executor work; a phase typically holds 2–8 tasks.

**Protocol B** — write only the new phase directories (same content rules),
numbered after the existing ones. Do not touch `.agents/PLAN.md`,
`AGENTS.md`, or existing phases; note in the final summary that `PLAN.md`'s
roadmap table does not list these appended phases.

## Phase 4 — Version Control, TODO Clearing & Hand-Off

- Git is mandatory: `git init` if the project is not a repository.
- **Clear the TODO list** — the items are now phases, so the TODO file no
  longer holds the plan. Overwrite the file with a clean, empty document:
  just a single top-level title `# TODO` and nothing else (no pointer
  line, no leftover items, no trailing notes). Never delete the file
  itself — leave the empty `TODO.md` in place so the workspace keeps a
  known, stable landing spot for future todos.
- Commit the conversion — `AGENTS.md`, the cleared TODO file, the whole
  `.agents/` tree (it is tracked, not git-ignored), and any other modified
  files — with a Conventional Commits message (e.g. `chore(agent): phase
  roadmap from TODO.md, NN phases`), always with `--no-gpg-sign`.

Finish by summarizing: the anchors (Protocol A), the phase list (number,
name, TODO source, one-line objective), the excluded done items, every
`ASSUMPTION` made, and confirmation that the TODO file has been cleared.
Then hand off:

- **Execute:** the `phased-execution` skill — `run-task.sh` for a single
  task, `run-phase.sh` for a phase, `auto-phase.sh` for the full pipeline.
- **Extend:** the `phase-authoring` skill for individual additional phases.

## Strict Operational Rules

- The conversion writes **planning files**: `.agents/**`, `AGENTS.md`, and
  `.gitignore`. **Never modify application code.** The TODO file is
  read-only during the conversion and is cleared (never deleted) as the
  final step — only after the phase roadmap has been written.
- Never overwrite existing `.agents/` content — merge into it. Never modify
  anything in `.agents/phases/complete/`.
- In Protocol B, never modify `.agents/PLAN.md` or `AGENTS.md`.
- Do not create `.agents/validate.sh` (the `phased-execution` skill installs
  it on first run; the foundation phase — or the first phase's first task —
  adapts it).
- Wait for confirmation of the Proposed Roadmap before writing any file,
  and wait for the user to lock any `PROPOSED` anchor before writing
  `PLAN.md`.
- Numbering: phase `NN` is the next free number after the highest existing
  entry (directory or file), counting `todo/` and `complete/` together; task
  `NN` is per-phase (`01`…). Never reuse or collide a number.
- **Executable in isolation:** an agent that sees only the repository, the
  phase overview, the completed task files, and one task file — no chat
  history, no follow-ups — must be able to finish that task. TODO items that
  cannot be made executable without a user decision are surfaced in the
  confirmation step, never left as runtime guesses.