add todo to phased
This commit is contained in:
@@ -0,0 +1,211 @@
|
||||
---
|
||||
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 .agent/ 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 `.agent/` 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 `.agent/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:
|
||||
|
||||
- `.agent/PLAN.md` — master plan; **LOCKED DECISIONS** are binding
|
||||
- `.agent/phases/todo/NN_name/` — a pending phase: `00_phase.md` overview + `NN_task.md` task files (task sort order = execution order)
|
||||
- `.agent/phases/complete/` — finished phases, mirroring the todo/ layout (read-only history)
|
||||
- `.agent/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 `.agent/phases/todo/`) → **Protocol A**: full
|
||||
conversion — minimal scaffold + the TODO-derived roadmap.
|
||||
- **Already phased** (`.agent/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 `.agent/` 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
|
||||
`.agent/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:
|
||||
|
||||
- **`.agent/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 `.agent/PLAN.md` first to understand the project context and goals."
|
||||
2. "Follow the phased execution protocol in `.agent/phases/`."
|
||||
3. "Never modify `.agent/PLAN.md` or any files in `.agent/phases/complete/`."
|
||||
4. "If you need to update any file in `.agent/phases/todo/`, you must ask the user for permission first."
|
||||
5. "Strictly adhere to the **LOCKED DECISIONS** listed in `.agent/PLAN.md`."
|
||||
- **`.agent/phases/todo/`** and **`.agent/phases/complete/`** (the latter
|
||||
created empty).
|
||||
- **`.gitignore`** — add `.agent/` and `.agent/phase-sessions/` if missing.
|
||||
|
||||
Then write one phase directory per confirmed phase at
|
||||
`.agent/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 `.agent/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. Replace its entire item list with a one-line
|
||||
pointer (e.g. `Phased on YYYY-MM-DD — items now live in
|
||||
.agent/phases/todo/`); never delete the file itself.
|
||||
- Commit the conversion — `AGENTS.md`, the cleared TODO file, and any other
|
||||
modified non-`.agent/` files (the `.agent/` tree itself is git-ignored by
|
||||
protocol) — 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**: `.agent/**`, `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 `.agent/` content — merge into it. Never modify
|
||||
anything in `.agent/phases/complete/`.
|
||||
- In Protocol B, never modify `.agent/PLAN.md` or `AGENTS.md`.
|
||||
- Do not create `.agent/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.
|
||||
Reference in New Issue
Block a user