refactor(skills): use .agents/ instead of .agent/ for phased execution
Standardize on the .agents/ directory across all phased-execution skills (phase state, reports, sessions, validate.sh, PLAN.md, and per-story/feature/workflow trees). Legacy dot-less agent/ fallbacks in migration scripts are untouched.
This commit is contained in:
+27
-27
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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.
|
||||
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
|
||||
@@ -9,20 +9,20 @@ 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.
|
||||
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 `.agent/phases/`. 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:
|
||||
|
||||
- `.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)
|
||||
- `.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
|
||||
@@ -32,9 +32,9 @@ generated task can be traced back to the original TODO item.
|
||||
|
||||
Run the audit first (Phase 1), then:
|
||||
|
||||
- **Not phased** (no `.agent/phases/todo/`) → **Protocol A**: full
|
||||
- **Not phased** (no `.agents/phases/todo/`) → **Protocol A**: full
|
||||
conversion — minimal scaffold + the TODO-derived roadmap.
|
||||
- **Already phased** (`.agent/phases/todo/` exists) → **Protocol B**:
|
||||
- **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
|
||||
@@ -46,7 +46,7 @@ Run the audit first (Phase 1), then:
|
||||
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
|
||||
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.
|
||||
@@ -106,7 +106,7 @@ 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
|
||||
`.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
|
||||
@@ -126,22 +126,22 @@ roadmap and locks any `PROPOSED` anchor.
|
||||
**Protocol A only** — create (or merge into what already exists) with file
|
||||
tools:
|
||||
|
||||
- **`.agent/PLAN.md`** — from `assets/plan-template.md`: assumptions &
|
||||
- **`.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 `.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
|
||||
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 `.agent/phase-sessions/` and `.agent/pipeline.log` if missing (never `.agent/` itself — the planning tree is tracked and committed); if an existing `.gitignore` has a `.agent/` ignore line, remove it.
|
||||
- **`.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
|
||||
`.agent/phases/todo/NN_name/`, numbered from the audit's "next phase
|
||||
`.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
|
||||
@@ -161,7 +161,7 @@ number" (counting `todo/` and `complete/` together):
|
||||
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`,
|
||||
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.
|
||||
|
||||
@@ -175,7 +175,7 @@ roadmap table does not list these appended phases.
|
||||
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
|
||||
`.agent/` tree (it is tracked, not git-ignored), and any other modified
|
||||
`.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`.
|
||||
|
||||
@@ -190,14 +190,14 @@ Then hand off:
|
||||
|
||||
## Strict Operational Rules
|
||||
|
||||
- The conversion writes **planning files**: `.agent/**`, `AGENTS.md`, and
|
||||
- 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 `.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
|
||||
- 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,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Phase {{NN}} — {{Short Title}}
|
||||
|
||||
**Source:** `{{TODO file}} L{{range(s) the phase's tasks cover, e.g. 34–38, 41}} — "{{capability / section title}}"`
|
||||
**Story:** `{{.agent/user_stories/<story>.md or "n/a"}}`
|
||||
**Story:** `{{.agents/user_stories/<story>.md or "n/a"}}`
|
||||
**Context:** `{{PLAN.md sections / files this phase builds on}}`
|
||||
|
||||
## Objective
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Task {{NN}} — {{Short Title}}
|
||||
|
||||
**Phase:** `{{NN_phase}}` · **Source:** `{{TODO file}}:{{line(s), e.g. 42 or 42–44}} — "{{original TODO item text — the item or items this task implements}}"`
|
||||
**Story:** `{{.agent/user_stories/<story>.md or "n/a"}}`
|
||||
**Story:** `{{.agents/user_stories/<story>.md or "n/a"}}`
|
||||
|
||||
## Objective
|
||||
{{1–2 sentences: what this task delivers}}
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
#
|
||||
# Locates a TODO.md / TODO.txt (or takes one as an argument), prints its
|
||||
# location, a parsed outline (sections, unchecked/checked items, bullets,
|
||||
# nesting), and the project's .agent/ state, next free phase number
|
||||
# (counting .agent/phases/todo/ and complete/ together, zero-padded to 2
|
||||
# nesting), and the project's .agents/ state, next free phase number
|
||||
# (counting .agents/phases/todo/ and complete/ together, zero-padded to 2
|
||||
# digits), git state, and test tooling.
|
||||
#
|
||||
# Usage:
|
||||
@@ -140,24 +140,24 @@ else
|
||||
printf '%s\n' ${outline[@]+"${outline[@]}"}
|
||||
fi
|
||||
|
||||
# --- .agent state -----------------------------------------------------------------
|
||||
# --- .agents state -----------------------------------------------------------------
|
||||
echo
|
||||
echo ".agent state:"
|
||||
echo ".agents state:"
|
||||
a=0
|
||||
if [[ -f "$root/.agent/PLAN.md" ]]; then
|
||||
echo " .agent/PLAN.md: present"
|
||||
if [[ -f "$root/.agents/PLAN.md" ]]; then
|
||||
echo " .agents/PLAN.md: present"
|
||||
a=1
|
||||
fi
|
||||
if [[ -f "$root/AGENTS.md" ]]; then
|
||||
echo " AGENTS.md: present"
|
||||
a=1
|
||||
fi
|
||||
if [[ -f "$root/.agent/validate.sh" ]]; then
|
||||
echo " .agent/validate.sh: present"
|
||||
if [[ -f "$root/.agents/validate.sh" ]]; then
|
||||
echo " .agents/validate.sh: present"
|
||||
a=1
|
||||
fi
|
||||
todo_dir="$root/.agent/phases/todo"
|
||||
complete_dir="$root/.agent/phases/complete"
|
||||
todo_dir="$root/.agents/phases/todo"
|
||||
complete_dir="$root/.agents/phases/complete"
|
||||
list_phases() {
|
||||
local dir="$1" entry n t any=0
|
||||
for entry in "$dir"/*; do
|
||||
@@ -176,16 +176,16 @@ list_phases() {
|
||||
if (( ! any )); then echo " (empty)"; fi
|
||||
}
|
||||
if [[ -d "$todo_dir" ]]; then
|
||||
echo " .agent/phases/todo:"
|
||||
echo " .agents/phases/todo:"
|
||||
list_phases "$todo_dir"
|
||||
a=1
|
||||
fi
|
||||
if [[ -d "$complete_dir" ]]; then
|
||||
echo " .agent/phases/complete:"
|
||||
echo " .agents/phases/complete:"
|
||||
list_phases "$complete_dir"
|
||||
a=1
|
||||
fi
|
||||
if (( ! a )); then echo " (no .agent/ artifacts — Protocol A full conversion needed)"; fi
|
||||
if (( ! a )); then echo " (no .agents/ artifacts — Protocol A full conversion needed)"; fi
|
||||
|
||||
max=0
|
||||
for d in "$todo_dir" "$complete_dir"; do
|
||||
|
||||
Reference in New Issue
Block a user