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:
+39
-39
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: convert-to-phased
|
||||
description: Converts an existing project to the .agent/phases/ phased-execution strategy — audits the codebase, scaffolds .agent/PLAN.md, AGENTS.md, and .agent/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.
|
||||
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 `.agent/` planning structure, and write a phase
|
||||
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
|
||||
@@ -17,24 +17,24 @@ never add individual phases to an already-converted project — that is the
|
||||
|
||||
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)
|
||||
|
||||
## Choosing the mode
|
||||
|
||||
- **Not phased** (no `.agent/phases/todo/`) → run the conversion protocol below.
|
||||
- **Already phased** (`.agent/phases/todo/` exists) → stop; do not
|
||||
- **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 `.agent/` artifacts exist) → convert only the
|
||||
- **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 `.agent/` artifacts, test tooling, and the next free phase number.
|
||||
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.
|
||||
@@ -46,7 +46,7 @@ Phase state lives in files, not chat:
|
||||
floor is, existing failures.
|
||||
- **Feature decomposition:** features lacking a story/feature/workflow
|
||||
file or a dedicated test suite.
|
||||
- **Existing `.agent/` artifacts:** what exists, what is missing.
|
||||
- **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.
|
||||
|
||||
@@ -69,61 +69,61 @@ matches the project's domain:
|
||||
|
||||
| Domain | Directory | File content |
|
||||
|------------|---------------------------|--------------|
|
||||
| CLI tool | `.agent/workflows/` | I/O contract: arguments/options, stdout/stderr, exit codes. Source of truth for the CliRunner contract tests. |
|
||||
| Library | `.agent/features/` | Public API sketch + exception contracts. Source of truth for the capability test modules. |
|
||||
| Web app | `.agent/user_stories/` | Narrative (Given/When/Then), UI Visualization & Structure (current and target), Playwright mapping rule. |
|
||||
| Anything else | `.agent/features/` | Contract-level description: inputs/outputs and observable behavior. |
|
||||
| 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 `.agent/` structure
|
||||
## Phase 4 — Scaffold the `.agents/` structure
|
||||
|
||||
Create (or merge into what already exists) with file tools:
|
||||
|
||||
- **`.agent/PLAN.md`** — from `assets/plan-template.md`: assumptions & design
|
||||
- **`.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.
|
||||
- **`.agent/phases/todo/`** — the roadmap from Phase 5.
|
||||
- **`.agent/phases/complete/`** — create the directory, leave it empty (it mirrors `todo/` as phases complete).
|
||||
- **`.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.
|
||||
- **`.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 `.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`."
|
||||
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 `.agent/workflows/` file
|
||||
- **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 `.agent/features/` file
|
||||
- **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 `.agent/user_stories/` file
|
||||
- **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 `.agent/PLAN.md` and meets WCAG
|
||||
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 `.agent/validate.sh`** — the `phased-execution` skill
|
||||
**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 `.agent/phases/todo/` — each
|
||||
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
|
||||
@@ -132,7 +132,7 @@ together. Never reuse or collide a number.
|
||||
|
||||
Roadmap shape:
|
||||
|
||||
1. **`01_…` foundation/rectification phase** — adapt `.agent/validate.sh` to
|
||||
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.
|
||||
@@ -149,8 +149,8 @@ Every phase directory must contain:
|
||||
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 (`.agent/workflows/…`, `.agent/features/…`, or
|
||||
`.agent/user_stories/…`).
|
||||
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
|
||||
@@ -189,7 +189,7 @@ final pass is where they are verified end-to-end):
|
||||
## 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 `.agent/`
|
||||
- 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`.
|
||||
@@ -206,13 +206,13 @@ and the phase list (number, name, one-line objective). Then hand off:
|
||||
|
||||
## Strict Operational Rules
|
||||
|
||||
- The conversion writes **planning files only**: `.agent/**`, `AGENTS.md`,
|
||||
- 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 `.agent/` content — merge into it.
|
||||
- Never modify anything in `.agent/phases/complete/`.
|
||||
- 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/`.
|
||||
- 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`.
|
||||
|
||||
Reference in New Issue
Block a user