Implement Phase

You are helping the user implement a build phase for the Orchestra project. This command is designed to work autonomously — read documents yourself rather than asking the user if they have. Follow this process exactly, in order. Do not skip steps.

---

## Step 1: Identify the phase

The user has specified: $ARGUMENTS

- If a phase number or name was given, find and read the matching file in `docs/development/to-be-implemented`
- If nothing was specified, list all phases in `docs/development/to-be-implemented/` with their names and ask which one to implement
- Read `docs/development/prd/PRD-000-product-overview.md` for product context

---

## Step 2: Check for existing implementation and revisions

Before proceeding, check `docs/developement/implemented/` to see if:
- An implementation document already exists for this phase (e.g., `PHASE-X-implementation-*.md`)
- Any revision documents exist (e.g., `PHASE-X-Revision-Y-*.md`)

If an implementation document exists:
- Read it to understand prior decisions
- Read any revision documents to understand amendments
- Show the user a summary of what was planned and what revisions have been made
- Ask the user: "Implementation notes already exist for this phase. Would you like to:
  1. Review and amend the existing implementation (create a revision)
  2. Restart the implementation from scratch (create a new implementation document)"
- If they choose "amend", switch to the revision workflow (see Step 7)

---

## Step 3: Auto-verify document approval status

**Do not ask the user if they have read documents. Read and verify them yourself.**

### 3a. Read and verify all PRDs in scope

Read the phase document to identify all PRD references. Then, for each PRD referenced:

1. Read the file at `docs/development/prd/PRD-XXX-*.md`
2. Extract the `## Status` value from the header

Apply this gate:

| Status | Action |
|--------|--------|
| 🟢 Approved | ✅ Continue |
| ⚫ Complete | ✅ Continue (historical — confirm scope still applies) |
| 🟡 Review | ❌ **STOP** |
| 🔴 Draft | ❌ **STOP** |
| 🔵 Planned | ❌ **STOP** |

If **any PRD is not 🟢 Approved or ⚫ Complete**, stop immediately and report:

⛔ Cannot proceed: the following PRDs are not approved:

• PRD-XXX (Status: 🟡 Review) — needs sign-off before implementation begins
• PRD-YYY (Status: 🔴 Draft) — needs to be completed and approved

Ask the product owner to approve these PRDs, or run /review-prd to complete them.

Do not continue until all referenced PRDs are approved.

### 3b. Read and verify all ADRs in scope

Check CLAUDE.md for the mandatory ADR list for this type of work. Also check if the phase document references specific ADRs. For each ADR:

1. Read the file at `docs/development/adr/ADR-XXX-*.md`
2. Extract the `## Status` value

Apply this gate:

| Status | Action |
|--------|--------|
| Accepted | ✅ Continue |
| Superseded | ⚠️ Warn — note which ADR supersedes it and confirm the right one is in scope |
| Proposed | ❌ **STOP** — ADR is not yet accepted |
| Deprecated | ❌ **STOP** — flag to user, do not build against a deprecated ADR |

If any ADR is Proposed or Deprecated, stop and report the issue before continuing.

### 3c. Version bump check

If the phase includes any new Prisma migrations or new API endpoints:

1. Read `package.json` at the project root and extract the current `version` field
2. Check `git log --oneline -5` to see if a version bump commit already exists for this phase
3. If no bump has been done yet, **stop** and tell the user:

⛔ This phase includes a DB migration / new API endpoint — a MINOR version bump is required before you start.

Run /bump-version now, then return to /implement-phase.

If a bump has been done, note the version number — migration names must include it:

prisma migrate dev --name v{MAJOR}_{MINOR}0{describe_change}

See `docs/guides/managing-versions.md` for full rules.

---

### 3d. Confirmation summary

After reading all documents, print a confirmation block like:

✅ Document verification complete

PRDs verified: ✅ PRD-001: Authentication & OAuth (Approved) ✅ PRD-014: Onboarding (Approved)

ADRs verified: ✅ ADR-001: Hexagonal Architecture (Accepted) ✅ ADR-007: Authentication (Accepted)

All documents approved. Proceeding.

---

## Step 4: Extract and summarise phase content

Read the phase document thoroughly and extract:
- **Phase title and number** (e.g., "Phase 2a: Authentication")
- **Phase goals** — What should be accomplished
- **Deliverables** — What gets shipped
- **PRDs in scope** — List all PRD-XXX references
- **ADRs in scope** — List all ADR references
- **Dependencies** — What prior phases must be complete first
- **Open questions or unknowns** noted in the phase

Also read the key sections of each PRD in scope to understand acceptance criteria and scope boundaries.

Print this summary for the user to confirm before proceeding.

---

## Step 5: Gather implementation context

Ask the user **only** for information you cannot determine from the documents. Keep this to a single message with focused questions. Prefer to infer from the phase and PRD documents where possible.

Ask:

**Q1:** "What is your implementation strategy for this phase? (e.g., 'build all APIs first, then UI', 'do one PRD at a time', 'horizontal slices'). If you have no preference, I'll use the order in the phase document."

**Q2:** "Are there any scope clarifications or amendments — things you plan to do differently from what's written in the phase document?"

**Q3:** "What are the main risks or unknowns you're aware of going in? (Skip if none.)"

If the user has already provided this context in the conversation, do not re-ask — use what they said.

---

## Step 6: Generate and save the implementation document

Using all the information gathered, create an implementation document with this structure:

```markdown
# PHASE-X Implementation: [Phase Title]

## Reference
- **Phase Document:** `docs/development/to-be-implemented/PH