skills/todo-to-phased/SKILL.md

name, description

name

description

todo-to-phased

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.