ralph-teams-codex 1.5.1

package/skills/debug/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: teams-debug
+description: "Fix any bug related to an active Teams plan. Can be triggered by the user at any time or automatically from teams-verify on failure. Reads PLAN.md, VERIFY.md, and REVIEW.md for context, then spawns a targeted builder to fix the issue."
+user-invocable: true
+---
+
+# Teams: Debug
+
+Fix a bug related to the current Teams plan. This skill can be triggered:
+- **By the user at any time** — e.g. "something's broken, use `teams-debug`"
+- **Automatically from `teams-verify`** — when a scenario fails during manual verification
+
+It reads the existing plan and any available verification/review reports to understand context before fixing.
+
+**Prerequisite:** `.ralph-teams/PLAN.md` must exist. If not found, stop and tell the user to run `teams-plan` first.
+
+---
+
+## Step 1: Load Context
+
+Check that `.ralph-teams/PLAN.md` exists. If not:
+> `.ralph-teams/PLAN.md` not found. This skill requires an active Teams plan. Run `teams-plan` first.
+
+Read all available context files:
+- `.ralph-teams/PLAN.md` — the feature plan (note its `Plan ID:` field)
+- `.ralph-teams/VERIFY.md` — if it exists, the manual verification report with failed scenarios
+- `.ralph-teams/REVIEW.md` — if it exists, the automated review findings
+
+---
+
+## Step 2: Identify the Bug
+
+If the user described the bug when invoking this skill, use that description.
+
+Otherwise, ask:
+
+> **What's the bug?**
+>
+> Describe what went wrong, what you expected, and what you saw. Include the scenario name if it came from `teams-verify`.
+
+Wait for their response.
+
+---
+
+## Step 3: Confirm Scope
+
+Summarize your understanding back to the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Bug report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Feature:   [feature name from PLAN.md]
+  Bug:       [one-line summary]
+  Related:   [phase(s)/task(s) or scenario(s) from the plan]
+  Criteria:  [affected acceptance criteria, if any]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ask:
+> **Correct? Reply `yes` to fix, or clarify what I got wrong.**
+
+---
+
+## Step 4: Spawn a Fix Builder
+
+When confirmed, spawn a builder subagent:
+
+```
+spawn_agent(
+  agent_type: "worker",
+  model: "gpt-5.4-mini",
+  message: "You are fixing a bug found during manual verification of a completed feature.
+
+    Bug report:
+    [user's bug description]
+
+    Feature plan (.ralph-teams/PLAN.md):
+    [paste full PLAN.md content]
+
+    [If VERIFY.md exists:]
+    Verification report (.ralph-teams/VERIFY.md):
+    [paste VERIFY.md content]
+
+    [If REVIEW.md exists:]
+    Review findings (.ralph-teams/REVIEW.md):
+    [paste REVIEW.md content]
+
+    Instructions:
+    - Investigate the root cause of the bug before making changes
+    - Fix only what is broken — do not refactor unrelated code
+    - Platform: [web|mobile from PLAN.md]
+    - Verify the fix using [Playwright|Maestro] after applying it
+    - If verification tools are not available, run tests/lint instead
+    - Commit with message: 'fix: [short description of the bug fixed]'"
+)
+```
+
+Print while the builder runs:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Fixing bug...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Wait for the builder with `wait_agent`. After you have handled the result, call `close_agent`.
+
+---
+
+## Step 5: Update Verification Report
+
+After the builder completes, if `.ralph-teams/VERIFY.md` exists, update the relevant scenario's status from `FAIL` to `FIXED`:
+
+```markdown
+### ✓ Scenario N: [Name]
+Status: FIXED
+Fix applied: [commit message or brief description]
+```
+
+---
+
+## Step 5b: Update Review Report
+
+If `.ralph-teams/REVIEW.md` exists, append a fix summary section at the bottom:
+
+```markdown
+---
+
+## Fix Applied
+
+**Bug:** [one-line bug summary]
+**Fix:** [brief description of what was changed]
+**Commit:** [commit message]
+**Status:** Resolved
+```
+
+If the REVIEW.md already has findings related to this bug, update the relevant finding's status to `Resolved` inline as well.
+
+---
+
+## Step 6: Done
+
+Print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Fix applied
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Bug:    [summary]
+  Status: Fixed + committed
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then ask:
+> **Want to re-verify this scenario? Run `teams-verify` to continue from where you left off.**

package/skills/teams-document/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: teams-document
+description: "Update existing project docs (README.md, ARCHITECTURE.md, etc.) and the active plan file to reflect the latest build. Spawns a lightweight scribe agent to find and update relevant documentation files and ensure the plan is accurate."
+user-invocable: true
+---
+
+# Teams: Document
+
+Update existing project documentation to reflect what was built in the current plan. Spawns a scribe agent that finds relevant docs and updates them — no new files created unless explicitly needed.
+
+**Prerequisite:** `.ralph-teams/PLAN.md` must exist. If not found, stop:
+> `.ralph-teams/PLAN.md` not found. Run `teams-plan` first.
+
+---
+
+## Step 1: Load Context
+
+Read:
+- `.ralph-teams/PLAN.md` — plan ID, feature name, tasks completed, acceptance criteria
+- `.ralph-teams/REVIEW.md` — if it exists, for additional context on what was changed
+- Run `git log --oneline` to identify recent commits from the build
+
+---
+
+## Step 2: Confirm Scope
+
+Show the user what will be updated:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — [Feature Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Scribe will scan for and update:
+  • .ralph-teams/PLAN.md (verify phase statuses + overall status)
+  • README.md
+  • ARCHITECTURE.md
+  • docs/**
+  • Any other relevant docs found
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ask:
+> **Anything to skip or add? Reply `go` to start, or tell me what to adjust.**
+
+---
+
+## Step 3: Spawn the Scribe
+
+When confirmed, spawn a scribe agent:
+
+```
+spawn_agent(
+  agent_type: "worker",
+  model: "gpt-5.4-mini",
+  message: "You are a documentation scribe. Your job is to update existing project documentation to reflect recent changes — not to create new files.
+
+    Plan ID: #[N]
+    Feature: [feature name]
+
+    Phases completed:
+    [paste phase list from .ralph-teams/PLAN.md]
+
+    Acceptance criteria:
+    [paste acceptance criteria from .ralph-teams/PLAN.md]
+
+    Instructions:
+    1. Update `.ralph-teams/PLAN.md` first:
+       - Run `git log --oneline` to verify which phases were actually committed.
+       - Ensure each phase checkbox matches reality: `[x]` if committed, `[!]` if it failed, `[ ]` if not started.
+       - Update the top-level `Status:` field to reflect the current state (e.g., `complete`, `in-progress`).
+    2. Find all existing documentation files: README.md, ARCHITECTURE.md, docs/**, CHANGELOG.md, or any other .md files that describe the project.
+    3. For each relevant file, update only the sections affected by the completed phases — do not rewrite unrelated content.
+    4. Keep changes minimal and accurate. Only document what was actually built.
+    5. Do NOT create new documentation files unless one is completely missing and clearly expected (e.g., no README.md at all).
+    6. After updating, commit all changes with message: 'docs: update docs for Plan #[N] — [feature name]'
+
+    What to update (examples):
+    - README: feature descriptions, usage instructions, setup steps
+    - ARCHITECTURE.md: new components, changed data flows, updated diagrams descriptions
+    - CHANGELOG.md: add an entry for this feature
+    - API docs: new or changed endpoints"
+)
+```
+
+Print while running:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Updating docs...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Wait for the scribe with `wait_agent`. After you have captured the list of updated files and any commit details you need, call `close_agent`.
+
+---
+
+## Step 4: Done
+
+After the scribe completes, print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Docs updated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  [list of files updated by the scribe]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/skills/teams-plan/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: teams-plan
+description: "Plan and build a feature. Orchestrate a plan, spawn sequential builder subagents per phase with Playwright or Maestro verification, then run a reviewer and a fix pass if needed."
+user-invocable: true
+---
+
+# Teams: Plan + Build
+
+You are the planner and orchestrator. Your job: discuss the feature, create a plan, execute it with sequential builder subagents, review the result with a reviewer, and apply fixes.
+
+---
+
+## Step 1: Discuss + Plan
+
+Ask: **"What do you want to build?"**
+
+Discuss with the user. Identify the target platform: **web** or **mobile** (this determines whether the builder uses Playwright or Maestro for verification).
+
+**Phase sizing:** Each phase runs in its own builder agent with a 200k token context window. A well-sized phase should fill **50–60% of that context** — meaning the builder will read, write, and reason about enough code that it uses roughly half its available context doing the work. Phases contain tasks (concrete steps the builder follows).
+- **Too small:** a phase that takes only a few minutes or touches one file — merge it into a related phase or make it a task within a larger phase.
+- **Too big:** a phase whose tasks collectively require more code than fits in one builder session — split it into two phases.
+- **Right size:** "Implement full auth system" (tasks: user model + DB migration, signup/login endpoints, JWT middleware + refresh tokens, password reset flow, email verification, auth guards on all protected routes, unit + integration tests), "Build product catalog" (tasks: product model + seed data, list page with filters + pagination, detail page, search endpoint, cart integration, component tests).
+
+> **Rule of thumb:** a phase = one meaningful feature area with enough depth to keep a builder busy for a substantial session. Tasks = the concrete steps the builder takes to complete it. Aim for 4–8 tasks per phase. When in doubt, make phases larger rather than smaller.
+
+**Phase complexity:** For each phase, assign a complexity level — this determines which model the builder uses:
+- `simple` → `gpt-5.4-mini`: truly trivial phases only — renaming, copy changes, config tweaks, adding a single field
+- `standard` → `gpt-5.4`: everything else — the default for any phase with real logic, UI, CRUD, auth, migrations, architecture, etc.
+
+**Prepare the build directory:**
+
+```bash
+mkdir -p ralph-teams
+```
+
+**Determine the plan number:**
+- Check for existing plan files: `.ralph-teams/PLAN-*.md`
+- Count existing files to determine N (next plan number = count + 1)
+- If plans exist, inform the user:
+  > **Found [N-1] existing plan(s). Creating Plan #[N]. Use `teams-run` to resume an existing plan.**
+- If no existing plans: plan number = 1
+
+Write `.ralph-teams/PLAN-[N].md`:
+
+```markdown
+# Plan #[N]: [Feature Name]
+
+Plan ID: #[N]
+Generated: [date]
+Platform: web | mobile
+Status: draft
+
+## Phases
+1. [ ] Phase 1: [Description] — complexity: simple
+   - [Task 1 description]
+   - [Task 2 description]
+2. [ ] Phase 2: [Description] — complexity: standard
+   - [Task 1 description]
+   - [Task 2 description]
+   - [Task 3 description]
+3. [ ] Phase 3: [Description] — complexity: standard
+   - [Task 1 description]
+   - [Task 2 description]
+
+## Acceptance Criteria
+- [Criterion 1]
+- [Criterion 2]
+
+## Verification
+Tool: Playwright | Maestro
+Scenarios:
+- [Scenario 1: name — steps — expected result]
+- [Scenario 2: name — steps — expected result]
+```
+
+---
+
+## Step 2: Optional Plan Review
+
+After writing the draft plan, ask the user:
+
+> **"Would you like another AI agent to review this plan for completeness and edge cases? (Recommended: Yes)"**
+
+If **yes**:
+1. **Check for a second-opinion coding CLI:** Look for an available tool such as `mcp__Multi_CLI__Ask_Claude`, `mcp__Multi_CLI__Ask_Gemini`, or `mcp__Multi_CLI__Ask_OpenCode`.
+   - If available: read `.ralph-teams/PLAN-[N].md` and call that tool with the prompt: *"Review this implementation plan. Identify missing phases, edge cases, or architectural gaps. Be concise."*
+   - If not available: use `spawn_agent` to start a reviewer subagent and prompt it to review `.ralph-teams/PLAN-[N].md` for completeness, edge cases, and architectural gaps. After `wait_agent` returns and you have incorporated the feedback, call `close_agent`.
+2. Evaluate the feedback. Incorporate valid findings into `.ralph-teams/PLAN-[N].md`.
+3. Briefly tell the user what changed.
+
+If **no**: skip to Step 3.
+
+---
+
+## Step 3: Get Approval
+
+Display `.ralph-teams/PLAN-[N].md` and ask:
+
+> **"Plan looks good? Reply `yes` to start, or tell me what to change."**
+
+---
+
+## Step 4: Execute — Sequential Builder Subagents
+
+When approved:
+
+1. Update `.ralph-teams/PLAN-[N].md` status to `approved`.
+2. Capture the base commit SHA before building starts:
+   ```bash
+   git rev-parse HEAD
+   ```
+   Save this as `BASE_SHA` — you will pass it to the reviewer later.
+3. Print:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     RALPH-TEAMS  Plan #[N] — Starting build...
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+For **each phase in order**, use `spawn_agent` to start a builder subagent. Pick the model from the phase's complexity annotation:
+- `complexity: simple` → `model: "gpt-5.4-mini"`
+- `complexity: standard` → `model: "gpt-5.4"`
+
+```
+spawn_agent(
+  agent_type: "worker",
+  model: "[gpt-5.4-mini | gpt-5.4 based on phase complexity]",
+  message: "You are implementing Phase [N] of [M]: [phase description].
+
+    Tasks to complete:
+    [list tasks from the phase]
+
+    Platform: [web|mobile]
+
+    Full plan:
+    [paste .ralph-teams/PLAN-[N].md content]
+
+    Your assignment: implement Phase [N] only, completing all its tasks. Verify it works using [Playwright|Maestro], then commit.
+    If [Playwright|Maestro] tools are not available, run tests/lint instead and note that E2E verification was skipped."
+)
+```
+
+Wait for the subagent with `wait_agent` before starting the next. As soon as you have recorded the result, call `close_agent` for that finished builder. After each phase, update `.ralph-teams/PLAN-[N].md` (change `[ ]` to `[x]` on success, `[!]` on failure) and print the phase board:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  [N of M phases complete]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓  Phase 1: Project Setup          [done]        (mini)
+  ►  Phase 2: Auth System            [building...]  (5.4)
+  ○  Phase 3: API Routes             [pending]      (mini)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status symbols:
+- `✓` — completed
+- `►` — in progress
+- `✗` — failed
+- `○` — pending
+
+If a builder subagent fails, log it as failed and continue with the next phase.
+
+---
+
+## Step 5: Review
+
+After all phases complete, print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Reviewing implementation...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Spawn the reviewer with `spawn_agent`:
+
+```
+spawn_agent(
+  agent_type: "default",
+  model: "gpt-5.4",
+  message: "Review the implementation for: [feature name].
+
+    Base commit (before build started): [BASE_SHA]
+    Use `git diff [BASE_SHA]..HEAD` to see all changes.
+
+    Full plan:
+    [paste .ralph-teams/PLAN-[N].md content]
+
+    Write your review to .ralph-teams/REVIEW.md.
+    If a second-opinion coding CLI is available, use it for a second opinion."
+)
+```
+
+Wait for the reviewer with `wait_agent`. After you have read `.ralph-teams/REVIEW.md` and captured anything you need from the result, call `close_agent`.
+
+---
+
+## Step 6: Apply Fixes
+
+After the reviewer completes, read `.ralph-teams/REVIEW.md`.
+
+If there are blocking findings:
+1. Print a summary of the review findings.
+2. Spawn a fix-pass builder:
+   ```
+   spawn_agent(
+     agent_type: "worker",
+     model: "gpt-5.4-mini",
+     message: "You are applying review fixes (not implementing a new phase).
+
+       Review findings to fix:
+       [paste blocking findings from .ralph-teams/REVIEW.md]
+
+       Platform: [web|mobile]
+
+       Fix each blocking issue. Verify the fixes work using [Playwright|Maestro].
+       If verification tools are not available, run tests/lint instead.
+       Commit all fixes together with message: 'fix: address review findings'."
+   )
+   ```
+3. Wait for the fix-pass builder with `wait_agent`, then call `close_agent` once its result has been handled.
+4. Print final summary when done.
+
+If no blocking findings, print final summary directly.
+
+Final summary format:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Build complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓  Phase 1: ...
+  ✓  Phase 2: ...
+  ✓  Review: [passed | N fixes applied]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then suggest:
+> **Build done. Run `teams-verify` to walk through manual E2E verification.**
+
+---
+
+## Step 7: Optional — Update Docs
+
+Ask the user:
+
+> **"Would you like to update your documentation? Run `teams-document` to have the scribe update your README, ARCHITECTURE.md, and other docs."**
+
+If yes, invoke the `teams-document` skill.
+
+If **no**, skip.

package/skills/teams-run/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: teams-run
+description: "Resume building a single Teams plan. Orchestrate sequential builder subagents for incomplete phases, then run a reviewer and apply fixes."
+user-invocable: true
+---
+
+# Teams: Run (Resume Build)
+
+You are the orchestrator. Resume an existing build by running all incomplete phases, then reviewing and applying fixes.
+
+---
+
+## Step 1: Find the Plan
+
+Read `.ralph-teams/PLAN.md`. If not found:
+> `.ralph-teams/PLAN.md` not found. Use `teams-plan` to create a plan first.
+
+Identify:
+- Plan ID (the `Plan ID:` field — e.g. `#2`)
+- All phases, their status (`[x]` = done, `[!]` = failed, `[ ]` = incomplete), and their complexity annotation (`complexity: simple` or `complexity: standard`)
+- Platform (web or mobile)
+- Verification scenarios
+
+Print the current state:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Resuming — [N of M phases already done]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓  Phase 1: Project Setup          [done]
+  ✓  Phase 2: Auth System            [done]
+  ○  Phase 3: API Routes             [pending]
+  ○  Phase 4: Frontend               [pending]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Step 2: Execute — Sequential Builder Subagents
+
+Capture the base commit SHA before building starts:
+```bash
+git rev-parse HEAD
+```
+Save this as `BASE_SHA`.
+
+For **each incomplete phase** (`[ ]` or `[!]`) **in order**, use `spawn_agent`. Pick the model from the phase's complexity annotation:
+- `complexity: simple` → `model: "gpt-5.4-mini"`
+- `complexity: standard` → `model: "gpt-5.4"`
+
+```
+spawn_agent(
+  agent_type: "worker",
+  model: "[gpt-5.4-mini | gpt-5.4 based on phase complexity]",
+  message: "You are implementing Phase [N] of [M]: [phase description].
+
+    Tasks to complete:
+    [list tasks from the phase]
+
+    Platform: [web|mobile]
+
+    Full plan:
+    [paste .ralph-teams/PLAN.md content]
+
+    Your assignment: implement Phase [N] only, completing all its tasks. Verify it works using [Playwright|Maestro], then commit.
+    If [Playwright|Maestro] tools are not available, run tests/lint instead and note that E2E verification was skipped."
+)
+```
+
+Wait for each subagent with `wait_agent` before starting the next. As soon as you have recorded the result, call `close_agent` for that finished builder. After each phase, update `.ralph-teams/PLAN.md` (change `[ ]` to `[x]` on success, `[!]` on failure) and reprint the phase board.
+
+If a builder subagent fails, log it as failed and continue.
+
+---
+
+## Step 3: Review
+
+After all phases complete, print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Reviewing implementation...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Spawn the reviewer with `spawn_agent`:
+
+```
+spawn_agent(
+  agent_type: "default",
+  model: "gpt-5.4",
+  message: "Review the implementation for: [feature name].
+
+    Base commit (before build started): [BASE_SHA]
+    Use `git diff [BASE_SHA]..HEAD` to see all changes.
+
+    Full plan:
+    [paste .ralph-teams/PLAN.md content]
+
+    Write your review to .ralph-teams/REVIEW.md.
+    If a second-opinion coding CLI is available, use it for a second opinion."
+)
+```
+
+Wait for the reviewer with `wait_agent`. After you have read `.ralph-teams/REVIEW.md` and captured anything you need from the result, call `close_agent`.
+
+---
+
+## Step 4: Apply Fixes
+
+Read `.ralph-teams/REVIEW.md`. If there are blocking findings:
+1. Print a summary of the findings.
+2. Spawn a fix-pass builder:
+   ```
+   spawn_agent(
+     agent_type: "worker",
+     model: "gpt-5.4-mini",
+     message: "You are applying review fixes (not implementing a new phase).
+
+       Review findings to fix:
+       [paste blocking findings from .ralph-teams/REVIEW.md]
+
+       Platform: [web|mobile]
+
+       Fix each blocking issue. Verify the fixes work using [Playwright|Maestro].
+       If verification tools are not available, run tests/lint instead.
+       Commit all fixes together with message: 'fix: address review findings'."
+   )
+   ```
+3. Wait for the fix-pass builder with `wait_agent`, then call `close_agent` once its result has been handled.
+4. After the fix-pass builder completes, update `.ralph-teams/REVIEW.md` — append a fix summary section at the bottom:
+   ```markdown
+   ---
+
+   ## Fixes Applied
+
+   **Fixes:** [brief description of what was changed]
+   **Commit:** fix: address review findings
+   **Status:** All blocking findings resolved
+   ```
+   Also mark any blocking findings in the REVIEW.md body as `Resolved` inline.
+
+Final summary:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #[N] — Build complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓  Phase 1: ...
+  ✓  Phase 2: ...
+  ✓  Review: [passed | N fixes applied]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then suggest:
+> **Build done. Run `teams-verify` to walk through manual E2E verification.**
+
+---
+
+## Step 5: Optional — Update Docs
+
+Ask the user:
+
+> **"Would you like to update your documentation? Run `teams-document` to have the scribe update your README, ARCHITECTURE.md, and other docs."**
+
+If yes, invoke the `teams-document` skill.
+
+If **no**, skip.