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
|
||||
@@ -0,0 +1,174 @@
|
||||
---
|
||||
name: phase-authoring
|
||||
description: The required entry point for ANY new work on a .agent/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 .agent/phases/ structure, call this skill FIRST to capture the work as a phase file — 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 files; the phased-execution skill runs them.
|
||||
---
|
||||
|
||||
# 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 files; the `phased-execution` skill
|
||||
executes them. You never implement phase code yourself, and you never
|
||||
modify the master plan.
|
||||
|
||||
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)
|
||||
|
||||
## 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 file with this skill; the `phased-execution` skill is the only path from a phase to code (it runs in a fresh subprocess behind the validation gate).
|
||||
|
||||
- **Phased project** (`.agent/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 `.agent/` 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 `.agent/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 `todo/` and `complete/` and compute the next free number `NN`.
|
||||
4. Read every file in `.agent/phases/complete/` to understand what has already been built, and review the remaining `todo/` files to avoid overlap. Read the most recent completed phase file(s) 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 file. 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 file 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 File
|
||||
|
||||
Create **exactly one** new file at `.agent/phases/todo/NN_name.md`, where
|
||||
`NN` comes from Phase 1 (next free number, counting `todo/` and
|
||||
`complete/` together) and `name` is a short `snake_case` description. Use
|
||||
`assets/phase-template.md` as the skeleton. The file must contain:
|
||||
|
||||
1. **Objective** — a 1–3 sentence statement of what the phase delivers.
|
||||
2. **Dependencies** — the phases (by file name) that must be completed first.
|
||||
3. **Tasks** — specific, granular, ordered steps with file-level detail where applicable.
|
||||
4. **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.
|
||||
5. **Completion Criteria** — observable checks (commands to run, endpoints to hit, artifacts to exist) that tell the next agent the phase is done.
|
||||
|
||||
**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 `.agent/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 and this file — no chat history, no follow-ups — must be able to finish the phase. No hidden assumptions.
|
||||
|
||||
### Final Output
|
||||
|
||||
Confirm the path and number of the created file, and summarize its
|
||||
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-phase.sh NN_name.md` for a
|
||||
single 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 `.agent/` and `.agent/phase-sessions/`), 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):
|
||||
|
||||
- **`.agent/PLAN.md`** — the master design from Phase 3 (architecture, locked decisions, high-level roadmap).
|
||||
- **`AGENTS.md`** — initialized with: always read `.agent/PLAN.md` first; follow the phased protocol in `.agent/phases/`; never modify `.agent/PLAN.md` or anything in `.agent/phases/complete/`; ask the user before editing files in `.agent/phases/todo/`; strictly adhere to the **LOCKED DECISIONS**.
|
||||
- **`.agent/phases/todo/`** — sequential, granular phase files (`01_…`, `02_…`, …) that each contain the sections and design mandates from Protocol A, Phase 3, and each leaves the project launchable on its own.
|
||||
- **`.agent/phases/complete/`** — create the directory, leave it empty.
|
||||
|
||||
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.
|
||||
|
||||
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 files.** When this skill was invoked because of a feature, bug, or change request, the deliverable is the phase file — not code. Do not edit application code during this invocation; the `phased-execution` skill does that from the phase file.
|
||||
- **Never** modify `.agent/PLAN.md`, `AGENTS.md`, or any file in `.agent/phases/complete/`.
|
||||
- **Never** modify existing files in `.agent/phases/todo/`; if one needs updating, ask the user for permission first.
|
||||
- Create exactly **one** phase file 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: `NN` is the next free number after the highest existing file, counting `todo/` and `complete/` together. Never reuse or collide a number.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Phase {{NN}} — {{Short Title}}
|
||||
|
||||
**Story:** `{{.agent/user_stories/<story>.md or "n/a"}}`
|
||||
**Context:** `{{PLAN.md sections / files this phase builds on}}`
|
||||
|
||||
## Objective
|
||||
{{1–3 sentences: what this phase delivers}}
|
||||
|
||||
## 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 logic — name the behaviors to cover}}
|
||||
- Coverage: **>90%** on new/modified code
|
||||
{{project additions, e.g. a dedicated Playwright E2E suite run in isolation}}
|
||||
|
||||
## 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}}
|
||||
Executable
+46
@@ -0,0 +1,46 @@
|
||||
#!/usr/bin/env bash
|
||||
# phase-status.sh — phase pipeline state for the Phase Architect.
|
||||
#
|
||||
# Finds the project root (nearest ancestor with .agent/phases/todo), prints
|
||||
# the todo/ and complete/ phase listings, and computes the next free phase
|
||||
# number NN (counting both directories together, zero-padded to 2 digits).
|
||||
#
|
||||
# Usage: bash phase-status.sh # from anywhere in the project tree
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
root="$(pwd)"
|
||||
while :; do
|
||||
if [[ -d "$root/.agent/phases/todo" ]]; then break; fi
|
||||
[[ "$root" == "/" ]] && { echo "✗ ERROR: no .agent/phases/todo found at or above $(pwd)" >&2; exit 1; }
|
||||
root="$(dirname "$root")"
|
||||
done
|
||||
|
||||
list() {
|
||||
local d="$root/.agent/phases/$1" f found=0
|
||||
for f in "$d"/*.md; do
|
||||
[[ -e "$f" ]] || continue
|
||||
found=1
|
||||
printf ' %s\n' "$(basename "$f")"
|
||||
done
|
||||
if (( ! found )); then printf ' (empty)\n'; fi
|
||||
}
|
||||
|
||||
max=0
|
||||
for d in todo complete; do
|
||||
for f in "$root/.agent/phases/$d"/*.md; do
|
||||
[[ -e "$f" ]] || continue
|
||||
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 "project root: $root"
|
||||
echo "todo:"
|
||||
list todo
|
||||
echo "complete:"
|
||||
list complete
|
||||
echo "next number: $(printf '%02d' $((max + 1)))"
|
||||
Reference in New Issue
Block a user