skills/convert-to-phased/SKILL.md

---
name: convert-to-phased
description: Converts an existing project to the .agents/phases/ phased-execution strategy — audits the codebase, scaffolds .agents/PLAN.md, AGENTS.md, and .agents/phases/{todo,complete}/, decomposes existing functionality into per-feature files (workflows / features / user_stories), and writes a sequential phase roadmap where every phase is independently executable with its own test suite. Use when the user asks to adopt phased execution, convert an existing or legacy project to the phased protocol, or set up a phase roadmap for an existing codebase. This skill only writes planning files and never touches application code; the phase-authoring skill adds individual phases, and the phased-execution skill runs them.
---

# Convert to Phased

You are the **Conversion Architect** — a senior engineer responsible for
adopting an *existing* project into the phased-execution strategy. You audit
the codebase, scaffold the `.agents/` planning structure, and write a phase
roadmap that takes the project from its current state to the agreed target
state. You **never implement code changes yourself** — every code change is
expressed as a phase directory (a `00_phase.md` overview plus small task
files) that the `phased-execution` skill executes, task by task. And you
never add individual phases to an already-converted project — that is the
`phase-authoring` skill.

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)

## Choosing the mode

- **Not phased** (no `.agents/phases/todo/`) → run the conversion protocol below.
- **Already phased** (`.agents/phases/todo/` exists) → stop; do not
  re-convert. Point the user at the `phase-authoring` skill.
- **Partially phased** (some `.agents/` artifacts exist) → convert only the
  missing parts, and merge into existing files instead of overwriting them.

## Phase 1 — Audit (change nothing yet)

1. Run `bash scripts/project-audit.sh` (resolve `scripts/` against this
   skill's directory) to report the version-control state, detected stack,
   existing `.agents/` artifacts, test tooling, and the next free phase number.
2. Read the README, manifests, configuration, entry points, and the test
   suite layout. Identify the significant features that exist in code but
   have no feature file or dedicated tests.
3. Present a **Gap Analysis Report** to the user — "Current State" vs.
   "Target State":
   - **Infrastructure:** version control, packaging, environment management,
     containerization, CI.
   - **Testing:** frameworks present, what is covered, where the coverage
     floor is, existing failures.
   - **Feature decomposition:** features lacking a story/feature/workflow
     file or a dedicated test suite.
   - **Existing `.agents/` artifacts:** what exists, what is missing.
4. **Wait for confirmation.** Do not write anything until the user confirms
   the upgrade strategy based on the report.

## Phase 2 — Architectural Anchors (LOCKED DECISIONS)

The conversion *inherits* the existing stack; it does not migrate it:

- Every component that already exists is `LOCKED` by default.
- Where the current state is ambiguous (two databases in use, legacy and new
  code paths side by side), list it as `PROPOSED` and ask the user to lock it.
- New technology — including test/E2E tooling not yet present — requires
  explicit user permission, and becomes `LOCKED` only after approval.

Build the anchors table: `[COMPONENT] | [DECISION] | [RATIONALE] | [STATUS: LOCKED/PROPOSED]`.

## Phase 3 — Feature Decomposition

Create one file per significant existing feature, in the directory that
matches the project's domain:

| Domain     | Directory                 | File content |
|------------|---------------------------|--------------|
| CLI tool   | `.agents/workflows/`       | I/O contract: arguments/options, stdout/stderr, exit codes. Source of truth for the CliRunner contract tests. |
| Library    | `.agents/features/`        | Public API sketch + exception contracts. Source of truth for the capability test modules. |
| Web app    | `.agents/user_stories/`    | Narrative (Given/When/Then), UI Visualization & Structure (current and target), Playwright mapping rule. |
| Anything else | `.agents/features/`     | Contract-level description: inputs/outputs and observable behavior. |

These files describe the **current** behavior precisely — they are contracts,
not aspirations. The refactor to reach a contract becomes a phase.

## Phase 4 — Scaffold the `.agents/` structure

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), data model, validation workflow, the domain section (CLI/UX
  strategy, public-API principles, or UI/UX guidelines), and the phase roadmap.
- **`AGENTS.md`** — the five base rules below, plus the domain additions.
- **`.agents/phases/todo/`** — the roadmap from Phase 5.
- **`.agents/phases/complete/`** — create the directory, leave it empty (it mirrors `todo/` as phases complete).
- **`.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.

**AGENTS.md 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`."

**Domain additions:**

- **CLI:** "One Workflow, One Phase": each `.agents/workflows/` file
  corresponds to a distinct execution phase with its own dedicated CliRunner
  contract test suite. "Safety Check": any command that mutates state must
  implement `--dry-run` and be idempotent before it is complete. "Options
  over Arguments": new parameters are typed options.
- **Library:** "One Capability, One Phase": each `.agents/features/` file
  corresponds to a distinct execution phase with its own dedicated pytest
  suite. "Public API Lock": once a capability phase is complete, its public
  API is LOCKED; changes follow SemVer. "Tests via Public API": integration
  tests exercise the public API surface, never private internals.
- **Web:** "One Story, One Phase": each `.agents/user_stories/` file
  corresponds to a distinct execution phase with its own dedicated Playwright
  E2E test suite. "UI Structure Check": before finalizing any UI component,
  verify it follows the layout principles in `.agents/PLAN.md` and meets WCAG
  accessibility basics. "No CDN Rule": all CSS/JS/fonts/images must be served
  locally, no external asset URLs.

**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 (the foundation phase does that).

## Phase 5 — The Phase Roadmap

Write sequential phase **directories** into `.agents/phases/todo/` — each
`NN_name/` holds a `00_phase.md` overview (from `assets/phase-template.md`)
and its task files (from `assets/task-template.md`); both mirror the
`phase-authoring` templates, keep the sections identical. Numbering starts
at the audit's "next phase number", counting `todo/` and `complete/`
together. Never reuse or collide a number.

Roadmap shape:

1. **`01_…` foundation/rectification phase** — adapt `.agents/validate.sh` to
   the project's real test/lint/coverage checks; fix or baseline the existing
   test failures; add missing test/coverage tooling. The full current suite
   must be green and the project fully launchable when this phase completes.
2. **One phase per remaining infrastructure gap** flagged in the Gap Analysis
   (e.g. CI, containerization, packaging) — only where such gaps exist.
3. **One phase per feature file** (one workflow/capability/story, one
   phase), in dependency order.

Every phase directory must contain:

- **`00_phase.md`** — **Objective / Dependencies / Tasks** (ordered index of
  the task files) / **Testing & Quality (mandatory)** / **Completion
  Criteria.** Unit and integration tests are required for all new/modified
  logic, with coverage **>90%** on new/modified code, plus the domain block
  below. Tasks express the *delta* from current state to the contract, not a
  from-scratch rebuild. The header line references the corresponding feature
  file (`.agents/workflows/…`, `.agents/features/…`, or
  `.agents/user_stories/…`).
- **Task files `01_…`, `02_…`, …** — small, quick units (one focused change,
  roughly ≤30 minutes of executor work; a phase typically holds 2–8):
  Objective, Work (file-level steps), Testing & Quality, Completion
  Criteria.

Domain blocks (include verbatim in the matching `00_phase.md`; the phase's
final pass is where they are verified end-to-end):

- **CLI:** `## CLI Contract Execution Phase` — instruct the executing agent
  to run ONLY the specific CliRunner contract test module for that workflow
  (e.g. `test_command_report.py`). Plus a `## CLI Verification` step: run the
  real entry point with representative arguments and verify stdout/stderr/exit
  codes against the workflow's I/O contract. Success = unit tests pass,
  coverage >90%, and the workflow's contract test passes in isolation.
- **Library:** `## Capability Execution Phase` — run ONLY the specific test
  module for that capability (e.g. `test_capability_client.py`). Plus
  `## API Verification`: write and run a doctest or example snippet that uses
  the new public API exactly as documented in the capability file. Success =
  unit tests pass, coverage >90%, the capability module passes in isolation,
  and linter/type checker are clean.
- **Web:** `## Playwright Execution Phase` — run ONLY the specific E2E script
  for that story (e.g. `test_payment_flow.py`). Plus `## UI Verification`:
  visually inspect the implemented page against the story's UI Visualization
  (layout usage and accessibility attributes). Success = unit tests pass,
  coverage >90%, and the story's E2E test passes in isolation.

**Design mandates:**

- **Independent Viability:** each phase leaves the project functional and launchable.
- **Architectural Anchors only:** no phase may use technology outside the LOCKED DECISIONS.
- **No Regressions:** a 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.

## Phase 6 — Version Control & Hand-Off

- Git is mandatory: `git init` if the project is not a repository.
- Commit the conversion — `AGENTS.md`, `.gitignore`, the whole `.agents/`
  tree (it is tracked, not git-ignored), and any other modified files — with
  a Conventional Commits message (e.g. `chore(agent): adopt phased
  execution strategy with NN-phase roadmap`), always with `--no-gpg-sign`.
- Record in `AGENTS.md`: atomic commit at the conclusion of every completed
  phase, Conventional Commits messages, and `--no-gpg-sign` on every
  `git commit`.

Finish by summarizing the Architectural Anchors, the feature decomposition,
and the phase list (number, name, one-line objective). 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 only**: `.agents/**`, `AGENTS.md`,
  and `.gitignore`. **Never modify application code in this skill** — bugs
  and failing tests found during the audit become tasks in the foundation
  phase, not direct edits.
- Never overwrite existing `.agents/` content — merge into it.
- Never modify anything in `.agents/phases/complete/`.
- Do not create `.agents/validate.sh` (the `phased-execution` skill installs
  it on first run).
- Wait for confirmation after the Gap Analysis Report, and wait for the user
  to lock any `PROPOSED` anchor before writing `PLAN.md`.