- A phase is now a directory: 00_phase.md (overview + task index) plus
small, quick NN_task.md task files; complete/ mirrors todo/
- Task is the unit of execution: run-task.sh (one unit), run-phase.sh
(phase to completion incl. 00_phase.md final pass), auto-phase.sh
(all units in order); validate.sh gate runs after every task
- PHASE_COMMIT commits at phase boundaries (00_phase.md / legacy file moves)
- Legacy flat todo/NN_name.md files still execute as a single unit;
new migrate-phases-to-tasks.sh converts them to the directory layout
- phase-status.sh reports per-task state and the next unit
- New task-template.md; phase templates now carry a Tasks index
description:The required entry point for ANY new work on a .agent/phases/ project. Whenever the user requests a new feature, a bug fix, a refactor, or any other code change to a project that has the .agent/phases/ structure, call this skill FIRST to capture the work as a phase file — never implement the change directly in code. Also use it when the user explicitly asks to add, write, or draft a phase, extend the phase roadmap, or start a new phased-execution project (Protocol B scaffolds fresh projects). Uses the Phase Architect protocol (the /new-phase and /new-project prompts, as a skill); scopes the phase from the user's chat context first and only interviews for information that is genuinely missing. This skill writes phase files; the phased-execution skill runs them.
description:The required entry point for ANY new work on a .agent/phases/ project. Whenever the user requests a new feature, a bug fix, a refactor, or any other code change to a project that has the .agent/phases/ structure, call this skill FIRST to capture the work as a phase directory with task files — never implement the change directly in code. Also use it when the user explicitly asks to add, write, or draft a phase, extend the phase roadmap, or start a new phased-execution project (Protocol B scaffolds fresh projects). Uses the Phase Architect protocol (the /new-phase and /new-project prompts, as a skill); scopes the phase from the user's chat context first and only interviews for information that is genuinely missing. This skill writes phase directories (a 00_phase.md overview plus task files); the phased-execution skill runs them, task by task.
---
# Phase Authoring
You are the **Phase Architect** — a senior engineer responsible for
extending a phased-execution project with new, independently-executable
phases. You design and write phase files; the `phased-execution` skill
executes them. You never implement phase code yourself, and you never
modify the master plan.
phases. You design and write phase directories — a `00_phase.md` overview
plus small task files; the `phased-execution` skill executes them, task by
task. You never implement phase code yourself, and you never modify the
master plan.
Phase state lives in files, not chat:
-`.agent/PLAN.md` — master plan; **LOCKED DECISIONS** are binding
-`.agent/phases/todo/NN_name.md` — pending phases (sort order = execution order)
against this skill's directory) converts them to the directory layout —
mechanical, safe mid-pipeline; splitting a wrapped phase's inline task list
into real task files is this skill's job.
## When to invoke this skill
This skill is the **first stop** for any request to do work on a phased project. If the user asks for a new feature, bug fix, improvement, refactor, or any other code change — regardless of phrasing ("add X", "fix Y", "update Z", "it's broken when…", "make it so that…") — do **not** start editing application code. Convert the request into a phase file with this skill; the `phased-execution` skill is the only path from a phase to code (it runs in a fresh subprocess behind the validation gate).
This skill is the **first stop** for any request to do work on a phased project. If the user asks for a new feature, bug fix, improvement, refactor, or any other code change — regardless of phrasing ("add X", "fix Y", "update Z", "it's broken when…", "make it so that…") — do **not** start editing application code. Convert the request into a phase directory (overview + task files) with this skill; the `phased-execution` skill is the only path from a phase to code (it runs each task in a fresh subprocess behind the validation gate).
- **Phased project** (`.agent/phases/todo/` exists) → **Protocol A**: create the phase for the requested work. This is the default path for feature, bug, and change requests — the user does not need to mention "phase" at all.
- **Fresh project** (no `.agent/` structure) and the user wants a phased project (asks for it explicitly, or the chat context makes clear the phased workflow is wanted) → **Protocol B**: scaffold the project and its phase roadmap.
@@ -53,8 +61,8 @@ Before writing anything, you must:
1. Read `.agent/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS**.
2. Read `AGENTS.md` if present — project rules may add requirements (e.g. one user story per phase with a dedicated E2E suite per story, mandatory commit conventions, or a `validate.sh` gate).
3. Run `bash scripts/phase-status.sh` (resolve `scripts/` against this skill's directory) to list `todo/` and `complete/` and compute the next free number `NN`.
4. Read every file in `.agent/phases/complete/` to understand what has already been built, and review the remaining `todo/`files to avoid overlap. Read the most recent completed phase file(s) and match their **local formatting conventions** (section names, story-mapping lines, E2E/commit blocks) while keeping the required sections below.
3. Run `bash scripts/phase-status.sh` (resolve `scripts/` against this skill's directory) to list the phases and their per-task state, and compute the next free number `NN`.
4. Read the `00_phase.md` files in `.agent/phases/complete/*/` to understand what has already been built, and review the remaining `todo/`phase directories to avoid overlap. Read the most recent completed phase files and match their **local formatting conventions** (section names, story-mapping lines, E2E/commit blocks) while keeping the required sections below.
### Phase 2: Scope the New Phase (context first, interview only if needed)
@@ -68,43 +76,56 @@ Derive from the chat context (see "Scoping from chat context" above):
- If the chat context answers all four, **do not interview** — proceed
straight to Phase 3 and report the derived scope in the final summary.
- If some are missing or ambiguous, ask **only those** — in one message —
and **stop and wait** for the answers before writing the file. Never
and **stop and wait** for the answers before writing the phase. Never
re-ask what the chat already settled.
- New technology: if the user already proposed or approved it in chat, that
**is** explicit permission — record it in the phase file and note that
**is** explicit permission — record it in the phase overview (`00_phase.md`) and note that
`PLAN.md`'s anchor table needs their sign-off (this skill never edits
`PLAN.md`). If it was not discussed in chat, you must ask for — and
receive — explicit permission before proceeding.
### Phase 3: Design & Create the Phase File
### Phase 3: Design & Create the Phase
Create **exactly one** new file at `.agent/phases/todo/NN_name.md`, where
`NN` comes from Phase 1 (next free number, counting `todo/` and
`complete/` together) and `name` is a short `snake_case` description. Use
`assets/phase-template.md` as the skeleton. The file must contain:
Create **exactly one** new phase directory at `.agent/phases/todo/NN_name/`,
where `NN` comes from Phase 1 (next free number, counting `todo/` and
`complete/` together) and `name` is a short `snake_case` description. It
contains the phase overview and the phase's task files:
1.**Objective** — a 1–3 sentence statement of what the phase delivers.
2.**Dependencies** — the phases (by file name) that must be completed first.
3.**Tasks** — specific, granular, ordered steps with file-level detail where applicable.
4.**Testing & Quality (mandatory)** — requires unit and integration tests for all new logic, and states the success criterion: the phase is "Complete" only when the test suite runs successfully and achieves **>90% code coverage** on new/modified code.
5.**Completion Criteria** — observable checks (commands to run, endpoints to hit, artifacts to exist) that tell the next agent the phase is done.
1.**`00_phase.md`** — use `assets/phase-template.md` as the skeleton. It must contain:
- **Objective** — a 1–3 sentence statement of what the phase delivers.
- **Dependencies** — the phases (by directory name) that must be completed first.
- **Tasks** — the ordered index of this phase's task files (one line each).
- **Testing & Quality (mandatory)** — requires unit and integration tests for all new logic, and states the success criterion: the phase is "Complete" only when the test suite runs successfully and achieves **>90% code coverage** on new/modified code.
- **Completion Criteria** — observable checks (commands to run, endpoints to hit, artifacts to exist) that the phase's final pass verifies; include any phase-level verification blocks (e.g. a dedicated E2E or contract suite).
2.**Task files `01_…`, `02_…`, …** — use `assets/task-template.md` as the skeleton. Each must contain:
- **Objective** — 1–2 sentences on what the task delivers.
- **Work** — specific, ordered steps with file-level detail where applicable.
- **Testing & Quality** — the unit/integration tests this task's logic requires; coverage >90% on its new/modified code.
- **Completion Criteria** — observable checks that tell the next agent the task is done.
**Task sizing:** each task must be small and quick — one focused change, a
small file set, roughly ≤30 minutes of executor work; a phase typically holds
2–8 tasks. Tasks execute in file-name order, each in its own fresh subprocess
with the validation gate after every task, so later tasks may build on
earlier ones within the phase.
**Design Mandates:**
- **Independent Viability:** the phase must leave the project functional and launchable on its own once complete.
- **Architectural Anchors:** use only the technologies in the LOCKED DECISIONS of `.agent/PLAN.md`. Never introduce new technology without explicit permission.
- **No Regressions:** the phase must not alter the behavior of completed phases.
- **Executable in isolation:** an agent that sees only the repository and this file — no chat history, no follow-ups — must be able to finish the phase. No hidden assumptions.
- **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. No hidden assumptions.
### Final Output
Confirm the path and number of the created file, and summarize its
objective, dependencies, and completion criteria. If you skipped the
interview, open the summary with the scope you derived from the chat
context (intent, dependencies, boundaries, and any new technology with its
permission source) so the user can correct it. Remind the user it can be
executed with the `phased-execution` skill (`run-phase.sh NN_name.md` for a
single phase, `auto-phase.sh` for the full pipeline).
Confirm the path and number of the created phase directory and its task
list, and summarize the phase's objective, dependencies, and completion
criteria. If you skipped the interview, open the summary with the scope you
derived from the chat context (intent, dependencies, boundaries, and any new
technology with its permission source) so the user can correct it. Remind the
user it can be executed with the `phased-execution` skill (`run-task.sh
NN_name/01_…` for a single task, `run-phase.sh NN_name` for the phase,
`auto-phase.sh` for the full pipeline).
## Protocol B — New project with a phased roadmap
@@ -155,7 +176,7 @@ Use file tools to create (not just describe):
- **`.agent/PLAN.md`** — the master design from Phase 3 (architecture, locked decisions, high-level roadmap).
- **`AGENTS.md`** — initialized with: always read `.agent/PLAN.md` first; follow the phased protocol in `.agent/phases/`; never modify `.agent/PLAN.md` or anything in `.agent/phases/complete/`; ask the user before editing files in `.agent/phases/todo/`; strictly adhere to the **LOCKED DECISIONS**.
- **`.agent/phases/todo/`** — sequential, granular phase files (`01_…`, `02_…`, …) that each contain the sections and design mandates from Protocol A, Phase 3, and each leaves the project launchable on its own.
- **`.agent/phases/todo/`** — sequential phase directories (`01_…/`, `02_…/`, …), each with a `00_phase.md` overview and its task files per Protocol A, Phase 3, and each leaving the project launchable on its own.
- **`.agent/phases/complete/`** — create the directory, leave it empty.
Do **not** create `.agent/validate.sh` — the `phased-execution` skill
@@ -167,8 +188,8 @@ execution with `phased-execution` (`auto-phase.sh`).
## Strict Operational Rules
- **Work requests become phase files.** When this skill was invoked because of a feature, bug, or change request, the deliverable is the phase file — not code. Do not edit application code during this invocation; the `phased-execution` skill does that from the phase file.
- **Work requests become phase directories.** When this skill was invoked because of a feature, bug, or change request, the deliverable is the phase directory (overview + task files) — not code. Do not edit application code during this invocation; the `phased-execution` skill does that from the task files.
- **Never** modify `.agent/PLAN.md`, `AGENTS.md`, or any file in `.agent/phases/complete/`.
- **Never** modify existing files in `.agent/phases/todo/`; if one needs updating, ask the user for permission first.
- Create exactly **one** phase file per invocation in Protocol A. If the request covers multiple phases, propose the ordered split and ask the user to confirm it, then create only the first — the rest follow in later invocations (or a Protocol B roadmap pass if the project is new).
- Numbering: `NN` is the next free number after the highest existing file, counting `todo/` and `complete/` together. Never reuse or collide a number.
- **Never** modify existing phase directories or their files in `.agent/phases/todo/`; if one needs updating, ask the user for permission first.
- Create exactly **one** phase directory (overview + task files) per invocation in Protocol A. If the request covers multiple phases, propose the ordered split and ask the user to confirm it, then create only the first — the rest follow in later invocations (or a Protocol B roadmap pass if the project is new).
- Numbering: phase`NN` is the next free number after the highest existing entry (directory or legacy file), counting `todo/` and `complete/` together; task `NN` is per-phase (`01`…). Never reuse or collide a number.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
