---
name: phase-transition
description: Handle a full phase transition — update the phase number, status, and documentation across all project files atomically.
disable-model-invocation: true
argument-hint: "[new-phase-number]"
---

# Phase Transition

Update all project documentation when moving to a new development phase.

## Steps

1. Read `RULES.md` section 6.2 to determine the current phase
2. Confirm the target phase with the user: $ARGUMENTS
3. Read `.claude/status-update-checklist.md` and follow the **Phase Transition Checklist** section
4. Update ALL files listed in the checklist — this must be atomic (all or nothing):

   **Required updates:**
   - `RULES.md` section 6.2 — change `Current phase: Phase N`
   - `README.md` — update status block (phase badge and status line) and footer
   - `DOCS.md` — update footer `**Last Updated:** Phase N (Description)`
   - `RECOMMENDATIONS.md` — update `Current phase` in section 1, add Change Log entry in section 6
   - `docs/phases-plan.md` — update header Phase/Status, mark completed phase tasks

   **Conditional updates (check if relevant):**
   - `docs/frontend/architecture.md` — lock decisions after Phase 1
   - `docs/backend/architecture.md` — lock decisions after Phase 1
   - `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` — archive after Phase 1

5. Run the verification commands:
   ```bash
   grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases-plan.md
   ```
6. Confirm all files show the same phase number
7. Show the user a summary of all changes made