Phase Amend

Phase Amend

This is a maintenance skill for the phase-skills authoring repo itself — not one of the seven workflow skills that ship into other projects. Its job: apply a change to a shared phase-workflow convention consistently everywhere it is expressed.

Why this exists

The conventions are deliberately duplicated. The canonical docs (TERMINOLOGY.md, templates/, phase_project.md) are the source of truth, but every skill also embeds the conventions it needs so it stays self-contained when dropped into a project alone. That duplication is a feature — and a liability: change the phase-number grammar in phase-tracker only, and phase-recap, the charter, CLAUDE.md, and the memory now disagree. Nothing at runtime catches that drift; a human reading one skill months later just gets a wrong rule.

So the value of this skill is not editing — it's knowing the full sync surface for a given convention and hitting all of it in one pass, then proving nothing was missed.

The sync surface

Where each shared convention lives. Grep to confirm before editing (files shift as the suite grows) — treat this as the starting map, not gospel.

Two locations are easy to forget because they aren't plain repo .md files:

• The memory at ~/.claude/projects/-home-aksel-Documents-phase-skills/memory/ (e.g. phases-always-appendable.md + the MEMORY.md pointer). A principle change must update the memory too, or a future session recalls the old rule.
• The installed copies at .claude/skills/<name>/. These are the real skills the harness loads; the root dirs are the working versions. Edits to root do nothing until the installed copy is overridden (final step).

Procedure

1. Pin down the change

State it as from → to, and why. A rule change often implies more than its sentence: changing the numbering grammar ripples into file-naming, branch names, and every worked example. Enumerate the ripples before editing, so the propagation is complete rather than literal.

2. Locate every occurrence

Grep the whole repo for the old form and the concept, not just the exact string — conventions are paraphrased differently per file (the banners appear as a table row in one place, a bullet list in another, a count in a third). Cross-check against the sync-surface table. Include the memory dir.

3. Apply canonical-first

Edit in this order so the source of truth leads and the copies conform to it:

1. Canonical — TERMINOLOGY.md, templates/, phase_project.md.
2. Embedded copies — each affected skill, matching the canonical wording (adapted to that skill's voice; the rule must match, the prose needn't be identical).
3. Assets — the plan/log/index templates under phase-project-init/assets/, and the shipped charter copy phase-project-init/assets/phase_project.md, which must stay byte-identical to the root phase_project.md (re-copy it after any charter edit; validate_repo.py enforces the match).
4. CLAUDE.md — the invariants list, repo contents, architecture notes.
5. Memory — update the relevant memory file and MEMORY.md.

Preserve each file's voice and altitude; this is not a find-and-replace. When a skill explains why a rule holds, update the reasoning too, not just the statement.

4. Verify no drift

Prove the change landed everywhere and the old form is gone:

• grep the repo (and memory dir) for the old form — expect zero hits outside revere_portal_CLAUDE.md (the frozen reference artifact — never edit it).
• Check the cross-file invariants that must agree exactly:
  • Banner set + count identical across response_templates.md, phase_project.md, and CLAUDE.md.
  • Phase-number grammar and examples identical across TERMINOLOGY.md, phase-tracker, phase_project.md, CLAUDE.md.
  • Appendability present in TERMINOLOGY.md, phase-audit, phase-decompose, the memory, CLAUDE.md.
  • Index "bottom = newest" wording consistent across phase-tracker, phase-recap, the phase_index.md asset, phase_project.md, CLAUDE.md.
  • Every SKILL.md carries the same suite version, matching plugin.json, marketplace.json, and the newest CHANGELOG.md heading.
• Run python3 scripts/validate_repo.py — it proves both mirror roots and all four version locations agree.
• If the change added/removed a skill or banner, re-count everywhere a count is stated in prose — e.g. the "…labeled response modes" line and the "…skills" line in CLAUDE.md and the template headers. These spelled-out numbers are the most common drift: they read fine in isolation but silently contradict the list they head.

5. Refresh both mirror roots

The root phase-*/ dirs are the source of truth. Two mirrors must match them byte-for-byte, whole-directory: .agents/skills/<name>/ (the ChatGPT/Codex export) and .claude/skills/<name>/ (what the harness actually loads here — edits to root do nothing until this copy is overridden). Refresh both from the repo root:

for s in <changed-skill-dirs>; do
  rm -rf ".agents/skills/$s" && cp -R "$s" ".agents/skills/$s"
  rm -rf ".claude/skills/$s" && cp -R "$s" ".claude/skills/$s"
done

Then run /reload-skills. (Only the skills you changed need refreshing; canonical docs and the charter aren't loaded as skills.)

5b. Version the change if it moves a convention

If the change alters a convention installed projects depend on, follow VERSIONING.md: record it under CHANGELOG.md's Unreleased heading, and if you are cutting a release, bump plugin.json, marketplace.json, and every SKILL.md frontmatter together. A convention edit with no changelog line is how a release note goes missing.

6. Report

List what changed, grouped by convention, and name every file touched (including memory + installed copies). Flag anything you chose not to change and why — e.g. an intentional wording difference — so the user can spot an accidental omission.

What this skill should not do

• Do not edit revere_portal_CLAUDE.md — it is a frozen reference artifact and its old conventions are intentional.
• Do not treat propagation as literal find-and-replace — follow the concept through each file's own phrasing and reasoning.
• Do not stop at the canonical docs; the embedded skill copies are what make a skill self-contained, so they must match.
• Do not forget the two non-obvious locations: the memory and the installed .claude/skills/ copies.
• Do not run as a phase; amending the suite is repo maintenance, not tracked phase work.