skills/phase-authoring/SKILL.md

---
name: phase-authoring
description: The required entry point for ANY new work on a .agents/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 .agents/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 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:

- `.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/todo/NN_name.md` — legacy single-file phase (still valid; migrate or split it)
- `.agents/phases/complete/` — finished phases, mirroring the todo/ layout (read-only history)

Legacy flat phases (`todo/NN_name.md`) are still executed as a single unit.
`bash scripts/migrate-phases-to-tasks.sh [project-root]` (resolve `scripts/`
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 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** (`.agents/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 `.agents/` 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.
- **Not phased and no sign of phased intent** → this skill does not apply; do the work normally, and if the work is substantial, suggest the `convert-to-phased` skill.
- Only if the user **explicitly** asks to bypass the phase workflow should code be edited directly — in that case note that the change skips the phase's test and validation gates.

## Scoping from chat context (applies to both protocols)

The conversation that led to the phase-authoring request **is** the primary
source of requirements — the interview is a fallback, not a ritual. Before
asking anything, extract from the chat context:

- what the user asked for, and why (intent)
- explicit decisions, constraints, preferences, and permissions the user stated
- technologies, frameworks, and architecture choices already discussed or agreed
- work already done or in flight during the conversation
- boundaries, non-goals, and "hard" problems the user mentioned

Rules:

- Treat explicit user statements in chat as interview answers. Do not re-ask, and do not pause to re-confirm what the user has already decided.
- If the chat context already settles the scope, **skip the interview entirely** and proceed straight to designing and writing.
- Only interview for the items that are genuinely missing or ambiguous after this extraction — in one message, listing just those items.
- When you proceed without an interview (or a shortened one), state the scope you derived from the chat (intent, dependencies, boundaries, any new technology) in your final summary so the user can correct it.

## Protocol A — Add a phase to an existing project

### Phase 1: Context Acquisition

Before writing anything, you must:

1. Read `.agents/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 the phases and their per-task state, and compute the next free number `NN`.
4. Read the `00_phase.md` files in `.agents/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)

Derive from the chat context (see "Scoping from chat context" above):

1. **Intent:** What capability or fix should this phase deliver?
2. **Dependencies:** Which existing or planned phases does it build on?
3. **Boundaries:** What is explicitly out of scope?
4. **New Technology:** Does it require anything not in the LOCKED DECISIONS?

- 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 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 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

Create **exactly one** new phase directory at `.agents/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. **`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 `.agents/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, 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 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

### Phase 1: Discovery (context first, interview only if needed)

Derive from the chat context (see "Scoping from chat context" above):

1. **Project Identity:** name and high-level intent.
2. **Core Complexity:** data-heavy, real-time, security-focused, etc.
3. **The "Hard" Problems:** primary technical challenges and validation needs.
4. **Tech Stack Preferences:** frameworks, databases, and "Locked" vs "Flexible" components.

- If the chat context already establishes what the user is building, its
  challenges, and the stack (e.g. the project was discussed at length before
  this request), **do not interview** — proceed straight to Phase 2 and
  report the derived identity, complexity, and proposed anchors in the final
  summary.
- If some are missing, ask **only those** — in one message — and **wait**
  for the user's response before scaffolding anything.
- Only when nothing can be derived from the chat should your first response
  be a professional request covering all four items.

### Phase 2: Professional Environment Scaffolding

- Use `uv` for all package management.
- **Mandatory Dependencies:** `python-dotenv` (production); `debugpy`, `ruff`, `pyright`, `pytest`, `pytest-cov` (dev).
- **Web Projects:** add `fastapi`, `alembic`, `pydantic`; prefer `httpx`.
- **Scaffold Files:** a comprehensive `.gitignore` (must include `.agents/phase-sessions/` and `.agents/pipeline.log` — but **never** `.agents/` itself: the planning tree is tracked and committed), a multi-stage `Containerfile` (assuming `podman`/`docker`), and a `README.md` with `uv` and configuration instructions.

### Phase 3: Strategic Architectural Design

Design with high rigor, identifying **Architectural Anchors (LOCKED DECISIONS)**
with the user — adopting them from the chat context when they were already
agreed there. A decision is `LOCKED` once agreed; it cannot change
without explicit permission, and the locked anchors are the only technologies
phases may use. The design must cover:

1. **Assumptions & Design Principles.**
2. **Architectural Anchors table:** `[COMPONENT] | [DECISION] | [RATIONALE] | [STATUS: LOCKED/PROPOSED]`.
3. **High-Level Architecture:** component breakdown and data flow.
4. **Validation/Verification Workflow:** multi-step logic ensuring high-confidence outputs.
5. **Data Model Proposal:** detailed schema and state transitions.
6. Where applicable: **State Machine & Background Jobs** (lifecycle definitions) and **Data Ingestion Strategy** (no hard-coded lists).

### Phase 4: The Hand-Off

Use file tools to create (not just describe):

- **`.agents/PLAN.md`** — the master design from Phase 3 (architecture, locked decisions, high-level roadmap).
- **`AGENTS.md`** — initialized with: always read `.agents/PLAN.md` first; follow the phased protocol in `.agents/phases/`; never modify `.agents/PLAN.md` or anything in `.agents/phases/complete/`; ask the user before editing files in `.agents/phases/todo/`; strictly adhere to the **LOCKED DECISIONS**.
- **`.agents/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.
- **`.agents/phases/complete/`** — create the directory, leave it empty.

Do **not** create `.agents/validate.sh` — the `phased-execution` skill
installs it from its template on first run and it must be adapted to the
project's real checks.

Finish by summarizing the Architectural Anchors established and how to start
execution with `phased-execution` (`auto-phase.sh`).

## Strict Operational Rules

- **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 `.agents/PLAN.md`, `AGENTS.md`, or any file in `.agents/phases/complete/`.
- **Never** modify existing phase directories or their files in `.agents/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.