skills/convert-to-phased/SKILL.md

name, description

name

description

convert-to-phased

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.