update convert to phased and phase authoring
This commit is contained in:
@@ -0,0 +1,210 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# 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
|
||||
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 file that the `phased-execution` skill executes. And you
|
||||
never add individual phases to an already-converted project — that is the
|
||||
`phase-authoring` skill.
|
||||
|
||||
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)
|
||||
- `.agent/phases/complete/` — finished phases (read-only history)
|
||||
- `.agent/validate.sh` — the pass/fail gate for every phase (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
|
||||
re-convert. Point the user at the `phase-authoring` skill.
|
||||
- **Partially phased** (some `.agent/` 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.
|
||||
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 `.agent/` 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 | `.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. |
|
||||
|
||||
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
|
||||
|
||||
Create (or merge into what already exists) with file tools:
|
||||
|
||||
- **`.agent/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.
|
||||
- **`.gitignore`** — add `.agent/` and `.agent/phase-sessions/` if missing.
|
||||
|
||||
**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`."
|
||||
|
||||
**Domain additions:**
|
||||
|
||||
- **CLI:** "One Workflow, One Phase": each `.agent/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
|
||||
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
|
||||
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
|
||||
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
|
||||
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 files into `.agent/phases/todo/` using
|
||||
`assets/phase-template.md` (mirrors the `phase-authoring` template; 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 `.agent/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 file must contain:
|
||||
|
||||
- **Objective / Dependencies / Tasks** — file-level detail; tasks express the
|
||||
*delta* from current state to the contract, not a from-scratch rebuild.
|
||||
- **Testing & Quality (mandatory)** — unit and integration tests for all
|
||||
new/modified logic; coverage **>90%** on new/modified code; plus the domain
|
||||
block below.
|
||||
- **Completion Criteria** — observable checks (commands to run, endpoints to
|
||||
hit, artifacts to exist).
|
||||
- **Feature linkage** — the header line references the corresponding feature
|
||||
file (`.agent/workflows/…`, `.agent/features/…`, or `.agent/user_stories/…`).
|
||||
|
||||
Domain blocks (include verbatim in the matching phase files):
|
||||
|
||||
- **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 and this
|
||||
phase file — no chat history, no follow-ups — must be able to finish it.
|
||||
|
||||
## Phase 6 — Version Control & Hand-Off
|
||||
|
||||
- Git is mandatory: `git init` if the project is not a repository.
|
||||
- Commit the conversion — `AGENTS.md`, `.gitignore`, and any other modified
|
||||
non-`.agent/` files (the `.agent/` tree itself is git-ignored by protocol) —
|
||||
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-phase.sh` for a single
|
||||
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**: `.agent/**`, `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
|
||||
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`.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Phase {{NN}} — {{Short Title}}
|
||||
|
||||
**Feature:** `{{.agent/workflows/<name>.md | .agent/features/<name>.md | .agent/user_stories/<name>.md | "n/a"}}`
|
||||
**Context:** `{{PLAN.md sections / files this phase builds on}}`
|
||||
|
||||
## Objective
|
||||
{{1–3 sentences: what this phase delivers (the delta from current state to the contract)}}
|
||||
|
||||
## Dependencies
|
||||
- `{{NN_name}}` ({{complete|todo}}) — {{what is needed from it}}
|
||||
{{or "— (none)"}}
|
||||
|
||||
## Tasks
|
||||
1. `{{path/to/file}}` — {{specific change, file-level detail}}
|
||||
2. `{{path/to/file}}` — {{specific change}}
|
||||
|
||||
## Testing & Quality
|
||||
- Unit/integration: {{tests required for all new/modified logic — name the behaviors to cover}}
|
||||
- Coverage: **>90%** on new/modified code
|
||||
{{project additions, e.g. the CLI Contract Execution Phase / Capability Execution Phase / Playwright Execution Phase block}}
|
||||
|
||||
## Completion Criteria
|
||||
- [ ] {{observable check: command to run / endpoint to hit / artifact to exist}}
|
||||
- [ ] test suite green, coverage >90%
|
||||
- [ ] no behavior change in completed phases
|
||||
{{project additions, e.g. a commit command per AGENTS.md conventions}}
|
||||
@@ -0,0 +1,34 @@
|
||||
# {{Project Name}} — Master Plan
|
||||
|
||||
> Master design document for a phased-execution project. The **LOCKED
|
||||
> DECISIONS** below are binding: no phase may introduce technology outside
|
||||
> them without explicit user permission.
|
||||
|
||||
## Assumptions & Design Principles
|
||||
- {{...}}
|
||||
|
||||
## Architectural Anchors
|
||||
| COMPONENT | DECISION | RATIONALE | STATUS |
|
||||
|-----------|----------|-----------|--------|
|
||||
| {{component}} | {{decision — inherited from the existing codebase}} | {{why}} | LOCKED |
|
||||
| {{component}} | {{decision awaiting ratification}} | {{why}} | PROPOSED |
|
||||
|
||||
## High-Level Architecture
|
||||
{{Component breakdown and data flow, mirroring the actual code.}}
|
||||
|
||||
## Data Model
|
||||
{{Existing schemas, state transitions, and persistence details.}}
|
||||
|
||||
## Validation / Verification Workflow
|
||||
{{Multi-step logic ensuring high-confidence outputs (unit → integration →
|
||||
contract/E2E → coverage floor).}}
|
||||
|
||||
## {{Domain Section}}
|
||||
{{CLI/UX Strategy | Public API design principles | UI/UX guidelines (layout,
|
||||
accessibility, asset policy) — whichever matches the project's domain.}}
|
||||
|
||||
## Phase Roadmap
|
||||
| # | Phase | Feature file | Objective (one line) |
|
||||
|---|-------|--------------|----------------------|
|
||||
| 01 | {{NN_name}} | — | foundation: adapt validate.sh, green test baseline |
|
||||
| 02 | {{NN_name}} | `.agent/{{workflows\|features\|user_stories}}/{{name}}.md` | {{...}} |
|
||||
Executable
+166
@@ -0,0 +1,166 @@
|
||||
#!/usr/bin/env bash
|
||||
# project-audit.sh — stack & phased-readiness probe for the Conversion Architect.
|
||||
#
|
||||
# Prints: project root, version-control state, detected manifests, domain
|
||||
# hints, existing .agent/ artifacts, test tooling, and the next free phase
|
||||
# number NN (counting .agent/phases/todo/ and complete/ together,
|
||||
# zero-padded to 2 digits).
|
||||
#
|
||||
# Usage: bash project-audit.sh # from anywhere in the project tree
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
root="$(pwd)"
|
||||
if git rev-parse --show-toplevel >/dev/null 2>&1; then
|
||||
root="$(git rev-parse --show-toplevel)"
|
||||
fi
|
||||
|
||||
echo "project root: $root"
|
||||
|
||||
echo
|
||||
echo "version control:"
|
||||
if [[ -d "$root/.git" ]]; then
|
||||
branch="$(git -C "$root" branch --show-current 2>/dev/null || echo unknown)"
|
||||
dirty="$(git -C "$root" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
|
||||
echo " git repository (branch: ${branch:-detached}, uncommitted changes: ${dirty})"
|
||||
else
|
||||
echo " (not a git repository — the conversion must git init)"
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "manifests:"
|
||||
found=0
|
||||
for m in pyproject.toml uv.lock package.json pnpm-lock.yaml go.mod Cargo.toml requirements.txt setup.py setup.cfg pom.xml build.gradle; do
|
||||
if [[ -f "$root/$m" ]]; then
|
||||
echo " $m"
|
||||
found=1
|
||||
fi
|
||||
done
|
||||
for c in compose.yaml docker-compose.yml Containerfile Dockerfile; do
|
||||
if [[ -f "$root/$c" ]]; then
|
||||
echo " $c"
|
||||
found=1
|
||||
fi
|
||||
done
|
||||
if (( ! found )); then echo " (none detected)"; fi
|
||||
|
||||
echo
|
||||
echo "domain hints:"
|
||||
hint=0
|
||||
if [[ -f "$root/pyproject.toml" ]]; then
|
||||
if grep -q '^\[project\.scripts\]' "$root/pyproject.toml"; then
|
||||
echo " cli ([project.scripts] entry points)"
|
||||
hint=1
|
||||
fi
|
||||
if grep -qiE 'fastapi|flask|django|starlette|aiohttp' "$root/pyproject.toml"; then
|
||||
echo " web (web framework dependency)"
|
||||
hint=1
|
||||
fi
|
||||
fi
|
||||
if [[ -f "$root/py.typed" ]]; then
|
||||
echo " library (py.typed marker)"
|
||||
hint=1
|
||||
fi
|
||||
if [[ -d "$root/templates" ]]; then
|
||||
echo " web (templates/ directory)"
|
||||
hint=1
|
||||
fi
|
||||
if [[ -f "$root/package.json" ]] && grep -q '"bin"' "$root/package.json"; then
|
||||
echo " cli (package.json \"bin\")"
|
||||
hint=1
|
||||
fi
|
||||
if (( ! hint )); then echo " (none — classify from the manifests above)"; fi
|
||||
|
||||
echo
|
||||
echo ".agent state:"
|
||||
a=0
|
||||
if [[ -f "$root/.agent/PLAN.md" ]]; then
|
||||
echo " .agent/PLAN.md: present"
|
||||
a=1
|
||||
fi
|
||||
if [[ -f "$root/AGENTS.md" ]]; then
|
||||
echo " AGENTS.md: present"
|
||||
a=1
|
||||
fi
|
||||
if [[ -f "$root/.agent/validate.sh" ]]; then
|
||||
echo " .agent/validate.sh: present"
|
||||
a=1
|
||||
fi
|
||||
for d in workflows features user_stories; do
|
||||
if [[ -d "$root/.agent/$d" ]]; then
|
||||
n="$(find "$root/.agent/$d" -maxdepth 1 -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
|
||||
echo " .agent/$d/: present ($n file(s))"
|
||||
a=1
|
||||
fi
|
||||
done
|
||||
todo_dir="$root/.agent/phases/todo"
|
||||
complete_dir="$root/.agent/phases/complete"
|
||||
if [[ -d "$todo_dir" ]]; then
|
||||
echo " .agent/phases/todo:"
|
||||
any=0
|
||||
for f in "$todo_dir"/*.md; do
|
||||
if [[ -e "$f" ]]; then
|
||||
echo " $(basename "$f")"
|
||||
any=1
|
||||
fi
|
||||
done
|
||||
if (( ! any )); then echo " (empty)"; fi
|
||||
a=1
|
||||
fi
|
||||
if [[ -d "$complete_dir" ]]; then
|
||||
echo " .agent/phases/complete:"
|
||||
any=0
|
||||
for f in "$complete_dir"/*.md; do
|
||||
if [[ -e "$f" ]]; then
|
||||
echo " $(basename "$f")"
|
||||
any=1
|
||||
fi
|
||||
done
|
||||
if (( ! any )); then echo " (empty)"; fi
|
||||
a=1
|
||||
fi
|
||||
if (( ! a )); then echo " (no .agent/ artifacts — full conversion needed)"; fi
|
||||
|
||||
max=0
|
||||
for d in "$todo_dir" "$complete_dir"; do
|
||||
for f in "$d"/*.md; do
|
||||
if [[ ! -e "$f" ]]; then continue; fi
|
||||
n="$(basename "$f" .md)"
|
||||
if [[ "$n" =~ ^([0-9]+) ]]; then
|
||||
n=$((10#${BASH_REMATCH[1]}))
|
||||
if (( n > max )); then max=$n; fi
|
||||
fi
|
||||
done
|
||||
done
|
||||
echo " next phase number: $(printf '%02d' $((max + 1)))"
|
||||
|
||||
echo
|
||||
echo "test tooling:"
|
||||
t=0
|
||||
if [[ -f "$root/pytest.ini" ]] || { [[ -f "$root/pyproject.toml" ]] && grep -q '\[tool\.pytest' "$root/pyproject.toml"; }; then
|
||||
echo " pytest configured"
|
||||
t=1
|
||||
fi
|
||||
if [[ -f "$root/conftest.py" ]] || [[ -d "$root/tests" ]]; then
|
||||
echo " tests/ or conftest.py present"
|
||||
t=1
|
||||
fi
|
||||
n_py="$(find "$root" \( -name 'test_*.py' -o -name '*_test.py' \) -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/venv/*' 2>/dev/null | wc -l | tr -d ' ')"
|
||||
if (( n_py > 0 )); then echo " $n_py python test file(s)"; t=1; fi
|
||||
if [[ -f "$root/package.json" ]] && grep -q '"test"' "$root/package.json"; then
|
||||
echo " npm test script"
|
||||
t=1
|
||||
fi
|
||||
if [[ -f "$root/ruff.toml" ]] || { [[ -f "$root/pyproject.toml" ]] && grep -q '\[tool\.ruff\]' "$root/pyproject.toml"; }; then
|
||||
echo " ruff configured"
|
||||
t=1
|
||||
fi
|
||||
if [[ -f "$root/pyrightconfig.json" ]] || { [[ -f "$root/pyproject.toml" ]] && grep -q '\[tool\.pyright\]' "$root/pyproject.toml"; }; then
|
||||
echo " pyright configured"
|
||||
t=1
|
||||
fi
|
||||
if [[ -f "$root/.coveragerc" ]] || { [[ -f "$root/pyproject.toml" ]] && grep -qE '\[tool\.(coverage|pytest-cov)\]' "$root/pyproject.toml"; }; then
|
||||
echo " coverage configured"
|
||||
t=1
|
||||
fi
|
||||
if (( ! t )); then echo " (none detected — the foundation phase must establish a test baseline)"; fi
|
||||
Reference in New Issue
Block a user