@slamb2k/mad-skills 2.0.6 → 2.0.8

package/skills/manifest.json

@@ -1,12 +1,12 @@
 {
-  "generated": "2026-02-28T05:58:04.217Z",
-  "count": 7,
+  "generated": "2026-03-08T22:06:12.122Z",
+  "count": 8,
   "skills": [
     {
       "name": "brace",
       "directory": "brace",
-      "description": "> Initialize any project directory with the GOTCHA/BRACE framework for agentic AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools, Context, Hard prompts, Args), BRACE build methodology, and a project CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: \"init gotcha\", \"setup brace\", \"brace\", \"initialize framework\", \"bootstrap gotcha\".",
-      "lines": 52,
+      "description": "'Initialize any project directory with the GOTCHA/BRACE framework for agentic AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools, Context, Hard prompts, Args), BRACE build methodology, and a project CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: \"init gotcha\", \"setup brace\", \"brace\", \"initialize framework\", \"bootstrap gotcha\".'",
+      "lines": 278,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -15,8 +15,8 @@
     {
       "name": "build",
       "directory": "build",
-      "description": "> Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.",
-      "lines": 49,
+      "description": "Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.",
+      "lines": 328,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -25,8 +25,8 @@
     {
       "name": "distil",
       "directory": "distil",
-      "description": "> Generate multiple unique web design variations for any website or web application. Accepts site specifications from a file (--spec path) or pasted text block. Creates a Vite + React + TypeScript + Tailwind project with Bun and produces N different creative designs accessible at /1, /2, /3, etc. Use when prototyping or exploring design directions for any web interface.",
-      "lines": 39,
+      "description": "Generate multiple unique web design variations for any website or web application. Accepts site specifications from a file (--spec path) or pasted text block. Creates a Vite + React + TypeScript + Tailwind project with Bun and produces N different creative designs accessible at /1, /2, /3, etc. Use when prototyping or exploring design directions for any web interface.",
+      "lines": 290,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -35,8 +35,8 @@
     {
       "name": "prime",
       "directory": "prime",
-      "description": "> Load project context before implementing features or making architectural decisions. Invoke proactively when starting significant work on DexAI. Supports domain-specific context loading: security (vault, RBAC, audit), routing (OpenRouter, model selection), adhd (design principles, RSD-safe), dashboard (frontend, backend, API), office (OAuth, email, calendar), memory (context capture, commitments), tasks (decomposition, friction-solving), channels (Telegram, Discord, Slack).",
-      "lines": 40,
+      "description": "\"Load project context before implementing features or making architectural decisions. Invoke proactively when starting significant work on DexAI. Supports domain-specific context loading: security (vault, RBAC, audit), routing (OpenRouter, model selection), adhd (design principles, RSD-safe), dashboard (frontend, backend, API), office (OAuth, email, calendar), memory (context capture, commitments), tasks (decomposition, friction-solving), channels (Telegram, Discord, Slack).\"",
+      "lines": 108,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -45,8 +45,8 @@
     {
       "name": "rig",
       "directory": "rig",
-      "description": "> Idempotently bootstrap any repository with standard development tools, hooks, and workflows. Use when starting work on a new repo, onboarding to an existing project, or ensuring a repo has proper CI/CD setup. Configures: git hooks (lefthook), commit message templates, PR templates, and GitHub Actions for lint/format/type-check/build. Prompts for user confirmation before changes. Triggers: \"bootstrap repo\", \"setup hooks\", \"configure CI\", \"rig\", \"standardize repo\".",
-      "lines": 39,
+      "description": "'Idempotently bootstrap any repository with standard development tools, hooks, and workflows. Use when starting work on a new repo, onboarding to an existing project, or ensuring a repo has proper CI/CD setup. Configures: git hooks (lefthook), commit message templates, PR templates, and GitHub Actions for lint/format/type-check/build. Prompts for user confirmation before changes. Triggers: \"bootstrap repo\", \"setup hooks\", \"configure CI\", \"rig\", \"standardize repo\".'",
+      "lines": 197,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -55,8 +55,18 @@
     {
       "name": "ship",
       "directory": "ship",
-      "description": "> Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship.",
-      "lines": 56,
+      "description": "\"Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship.\"",
+      "lines": 227,
+      "hasScripts": false,
+      "hasReferences": true,
+      "hasAssets": false,
+      "hasTests": true
+    },
+    {
+      "name": "speccy",
+      "directory": "speccy",
+      "description": "Deep-dive interview skill for creating comprehensive specifications. Reviews existing code and docs, then interviews the user through multiple rounds of targeted questions covering technical implementation, UI/UX, concerns, and tradeoffs. Produces a structured spec via create-specification. Use when starting a new feature, system, or major change that needs a spec.",
+      "lines": 166,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -65,8 +75,8 @@
     {
       "name": "sync",
       "directory": "sync",
-      "description": "> Sync local repository with origin/main. Use before starting new work, after completing a PR, or when needing latest upstream changes. Safely stashes uncommitted changes, fetches and pulls origin/main, restores stash, and cleans up stale local branches (merged or with deleted remotes). Invoke when switching contexts or preparing for new feature work.",
-      "lines": 55,
+      "description": "Sync local repository with origin/main. Use before starting new work, after completing a PR, or when needing latest upstream changes. Safely stashes uncommitted changes, fetches and pulls origin/main, restores stash, and cleans up stale local branches (merged or with deleted remotes). Invoke when switching contexts or preparing for new feature work.",
+      "lines": 213,
       "hasScripts": false,
       "hasReferences": false,
       "hasAssets": false,

package/skills/prime/SKILL.md

@@ -1,29 +1,25 @@
 ---
 name: prime
-description: >
-  Load project context before implementing features or making architectural decisions.
-  Invoke proactively when starting significant work on DexAI. Supports domain-specific
-  context loading: security (vault, RBAC, audit), routing (OpenRouter, model selection),
-  adhd (design principles, RSD-safe), dashboard (frontend, backend, API), office (OAuth,
-  email, calendar), memory (context capture, commitments), tasks (decomposition,
-  friction-solving), channels (Telegram, Discord, Slack).
+description: "Load project context before implementing features or making architectural decisions. Invoke proactively when starting significant work on DexAI. Supports domain-specific context loading: security (vault, RBAC, audit), routing (OpenRouter, model selection), adhd (design principles, RSD-safe), dashboard (frontend, backend, API), office (OAuth, email, calendar), memory (context capture, commitments), tasks (decomposition, friction-solving), channels (Telegram, Discord, Slack)."
+argument-hint: security, routing, adhd, dashboard, office, memory, tasks, channels (comma-separated)
+allowed-tools: Read, Glob, Grep, LS
 ---
 
 # Prime - Project Context Loader
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
-Pick ONE tagline at random — vary your choice each time:
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
 
 ```
 {tagline}
 
-    ██╗██████╗ ██████╗ ██╗███╗   ███╗███████╗
+⠀   ██╗██████╗ ██████╗ ██╗███╗   ███╗███████╗
    ██╔╝██╔══██╗██╔══██╗██║████╗ ████║██╔════╝
   ██╔╝ ██████╔╝██████╔╝██║██╔████╔██║█████╗
  ██╔╝  ██╔═══╝ ██╔══██╗██║██║╚██╔╝██║██╔══╝
 ██╔╝   ██║     ██║  ██║██║██║ ╚═╝ ██║███████╗
 ╚═╝    ╚═╝     ╚═╝  ╚═╝╚═╝╚═╝     ╚═╝╚══════╝
-
 ```
 
 Taglines:
@@ -36,4 +32,76 @@ Taglines:
 - 📜 Downloading the lore...
 - 🧠 Brain cells: ACTIVATING
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Load project context to inform agent decisions. Raw file contents stay in a
+subagent — the primary thread only sees a structured PRIME_REPORT.
+
+## Step 1: Parse Arguments
+
+Extract domain hints from the request (comma-separated). Valid domains are
+listed in `references/domains.md`. If no domain specified, load core context only.
+
+## Step 2: Load Context via Subagent
+
+Launch a **general-purpose subagent** to read files and build the report:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Load and summarise project context",
+  prompt: <see below>
+)
+```
+
+### Subagent Prompt
+
+```
+Load project context and return a structured summary. Raw file contents must
+NOT appear in the report — summarise only.
+
+Limit PRIME_REPORT to 30 lines maximum.
+
+## Core Files (always load)
+
+1. CLAUDE.md — System handbook, operating procedures
+2. goals/manifest.md — Phase status, available goals, project roadmap
+3. tools/manifest.md — Available tools and their locations
+
+If CLAUDE.md is missing, record as NOT FOUND and continue.
+
+## Domain Files
+
+{For each requested domain, list files from references/domains.md}
+
+For each file:
+- If it exists: read and summarise (2-3 lines max per domain)
+- If it doesn't exist: record as NOT FOUND and continue
+
+## Output Format
+
+PRIME_REPORT:
+- core_files_loaded: {count}/{total}
+- missing_files: {list or "none"}
+- domains_loaded: {list}
+- per_domain_summary:
+  - {domain}: {2-3 line summary}
+- branch: {current branch from git branch --show-current}
+- ready_for: {inferred from loaded context}
+```
+
+## Step 3: Present Summary
+
+Parse PRIME_REPORT and present a clean summary to the user:
+
+```
+Context loaded:
+- Core: {status from core_files_loaded}
+- {Domain}: {summary from per_domain_summary}
+
+Current branch: {branch}
+Ready to assist with: {ready_for}
+```
+
+If CLAUDE.md was missing, warn the user and note that only domain context
+was loaded.

package/skills/rig/SKILL.md

@@ -1,28 +1,25 @@
 ---
 name: rig
-description: >
-  Idempotently bootstrap any repository with standard development tools, hooks, and workflows.
-  Use when starting work on a new repo, onboarding to an existing project, or ensuring a repo
-  has proper CI/CD setup. Configures: git hooks (lefthook), commit message templates, PR templates,
-  and GitHub Actions for lint/format/type-check/build. Prompts for user confirmation before changes.
-  Triggers: "bootstrap repo", "setup hooks", "configure CI", "rig", "standardize repo".
+description: 'Idempotently bootstrap any repository with standard development tools, hooks, and workflows. Use when starting work on a new repo, onboarding to an existing project, or ensuring a repo has proper CI/CD setup. Configures: git hooks (lefthook), commit message templates, PR templates, and GitHub Actions for lint/format/type-check/build. Prompts for user confirmation before changes. Triggers: "bootstrap repo", "setup hooks", "configure CI", "rig", "standardize repo".'
+argument-hint: --skip-system-check (optional)
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 # Rig - Repository Bootstrap
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
-Pick ONE tagline at random — vary your choice each time:
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
 
 ```
 {tagline}
 
-    ██╗██████╗ ██╗ ██████╗
+⠀   ██╗██████╗ ██╗ ██████╗
    ██╔╝██╔══██╗██║██╔════╝
   ██╔╝ ██████╔╝██║██║  ███╗
  ██╔╝  ██╔══██╗██║██║   ██║
 ██╔╝   ██║  ██║██║╚██████╔╝
 ╚═╝    ╚═╝  ╚═╝╚═╝ ╚═════╝
-
 ```
 
 Taglines:
@@ -35,4 +32,165 @@ Taglines:
 - Setting up the drill floor!
 - From blueprint to build-ready!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Idempotently bootstrap repositories with standard development infrastructure.
+Prompts and report schemas are in `references/`. Configuration procedures are
+in `references/configuration-steps.md`.
+
+**Key principle:** Prompt user before making changes. Report findings first,
+get approval, then act.
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+| lefthook | npm | `npx lefthook --help` | yes | install | `npm install -g lefthook` |
+| gh | cli | `gh --version` | yes | url | https://cli.github.com |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+---
+
+## Phase 1: System Requirements Check
+
+Launch **Bash subagent** (haiku — simple checks):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Check system requirements",
+  prompt: <read from references/phase-prompts.md#phase-1>
+)
+```
+
+Parse SYSTEM_REPORT. If any requirement fails, use **AskUserQuestion**:
+
+Options for missing git config:
+- "I'll configure it manually"
+- "Configure for me with: [email] / [name]"
+
+**Stop if user chooses manual. Configure if values provided.**
+
+---
+
+## Phase 2: Repository Analysis
+
+Launch **Bash subagent** (haiku):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Analyze repository",
+  prompt: <read from references/phase-prompts.md#phase-2>
+)
+```
+
+Parse REPO_REPORT.
+
+---
+
+## Phase 3: Present Findings & Get Approval
+
+Present analysis to user with **AskUserQuestion**:
+
+```
+Repository Analysis Complete
+
+Current State:
+  Git initialized: {status}
+  Branch: {branch}
+  Lefthook: {status}
+  Commit template: {status}
+  PR template: {status}
+  CI workflow: {status}
+  {if azdo and unregistered_pipelines:}
+  Azure Pipelines: {N} YAML file(s) found, {M} not yet registered
+
+Detected Stack:
+  Type: {project_type}
+  Components: {detected_components}
+  Available scripts: {available_scripts}
+
+Proposed Changes:
+  {numbered list of what will be added/configured}
+  {if azdo and unregistered_pipelines: "Register Azure Pipelines: {list of YAML paths}"}
+```
+
+Options:
+- "Yes, configure everything"
+- "Let me choose what to configure"
+- "Cancel"
+
+If "Let me choose", present individual options as multi-select.
+
+---
+
+## Phase 4: Execute Configuration
+
+For each approved item, follow the procedures in
+`references/configuration-steps.md`.
+
+---
+
+## Phase 5: Verification
+
+Launch **Bash subagent** (haiku):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Verify configuration",
+  prompt: <read from references/phase-prompts.md#phase-5>
+)
+```
+
+Parse VERIFY_REPORT.
+
+---
+
+## Phase 6: Final Report
+
+Present summary using the template in `references/report-template.md`.
+
+---
+
+## Idempotency Rules
+
+- **Skip** items already correctly configured
+- **Update** items that exist but are outdated (prompt user first)
+- **Add** items that are missing
+- **Never delete** user's existing configuration without explicit approval
+- **Merge** rather than replace when possible (e.g., add missing hooks)
+
+---
+
+## Error Handling
+
+If any step fails:
+1. Report the specific failure
+2. Offer to skip and continue, or abort
+3. Include troubleshooting suggestions
+
+Common issues:
+- No package manager -> suggest installing npm/bun
+- Permission denied -> check file permissions
+- Lefthook install fails -> try global install
+- Git not initialized -> offer to initialize

package/skills/ship/SKILL.md

@@ -1,28 +1,25 @@
 ---
 name: ship
-description: >
-  Ship changes through the full PR lifecycle. Use after completing feature work
-  to commit, push, create PR, wait for checks, and merge. Handles the entire
-  workflow: syncs with main, creates feature branch if needed, groups commits
-  logically with semantic messages, creates detailed PR, monitors CI, fixes
-  issues, squash merges, and cleans up. Invoke when work is ready to ship.
+description: "Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship."
+argument-hint: --pr-only, --no-squash, --keep-branch (optional flags)
+allowed-tools: Bash, Read, Glob, Grep, Skill
 ---
 
 # Ship - Full PR Lifecycle
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
-Pick ONE tagline at random — vary your choice each time:
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
 
 ```
 {tagline}
 
-    ██╗███████╗██╗  ██╗██╗██████╗
+⠀   ██╗███████╗██╗  ██╗██╗██████╗
    ██╔╝██╔════╝██║  ██║██║██╔══██╗
   ██╔╝ ███████╗███████║██║██████╔╝
  ██╔╝  ╚════██║██╔══██║██║██╔═══╝
 ██╔╝   ███████║██║  ██║██║██║
 ╚═╝    ╚══════╝╚═╝  ╚═╝╚═╝╚═╝
-
 ```
 
 Taglines:
@@ -35,21 +32,195 @@ Taglines:
 - 📬 Another one for the merge queue!
 - 🟢 LGTM — Let's Get This Merged!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Ship changes through the complete PR lifecycle. Every stage runs in a subagent
+to isolate context from the primary conversation. Prompts for each stage are
+in `references/stage-prompts.md`.
+
+## Flags
+
+Parse optional flags from the request:
+- `--pr-only`: Stop after creating the PR
+- `--no-squash`: Use regular merge instead of squash
+- `--keep-branch`: Don't delete the source branch after merge
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+| gh | cli | `gh --version` | yes | url | https://cli.github.com |
+| ship-analyzer | agent | `~/.claude/agents/ship-analyzer.md` | no | fallback | Uses general-purpose agent |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+Read `default_branch` and `remote` from Stage 1's SYNC_REPORT. These are
+substituted into all stage prompts as `{REMOTE}` and `{DEFAULT_BRANCH}`.
+
+### Platform Detection
+
+After sync, detect the hosting platform from the remote URL:
+
+```bash
+REMOTE_URL=$(git remote get-url {REMOTE} 2>/dev/null)
+if echo "$REMOTE_URL" | grep -qiE 'dev\.azure\.com|visualstudio\.com'; then
+  PLATFORM="azdo"
+elif echo "$REMOTE_URL" | grep -qi 'github\.com'; then
+  PLATFORM="github"
+else
+  PLATFORM="github"   # default fallback
+fi
+```
+
+Pass `{PLATFORM}` into all stage prompts. Each stage uses the appropriate
+CLI tool: `gh` for GitHub, `az repos`/`az pipelines` for Azure DevOps.
+
+> **Azure DevOps prerequisite:** The `az devops` extension must be installed
+> and configured (`az devops configure --defaults organization=... project=...`).
+> If `az repos` commands fail, report the setup requirement to the user.
+
+---
+
+## Stage 1: Sync
+
+Launch **Bash subagent** (haiku — simple git commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Sync with default branch",
+  prompt: "Follow ~/.claude/skills/sync/SKILL.md subagent prompt. Return SYNC_REPORT."
+)
+```
+
+Parse SYNC_REPORT. Extract `remote` and `default_branch`. Abort if sync failed.
+
+---
+
+## Stage 2: Commit, Push & Create PR
 
-## Subagent Architecture
+This stage needs to **read and understand code** to write good commit messages
+and PR descriptions. Use a code-aware subagent.
 
-All work runs in subagents to keep the primary conversation context clean:
+Launch **ship-analyzer subagent** (reads diffs + source files):
 
-| Stage | Agent Type | Model | Purpose |
-|-------|-----------|-------|---------|
-| Sync | Bash | haiku | Git sync (cheap, fast) |
-| Ship | ship-analyzer | sonnet | Analyze code, commit, push, create PR |
-| CI | Bash (background) | haiku | Poll checks without blocking |
-| Fix CI | general-purpose | default | Read code, fix failures |
-| Land | Bash | haiku | Merge + final sync |
+```
+Task(
+  subagent_type: "ship-analyzer",
+  description: "Analyze, commit, push, and create PR",
+  prompt: <read from references/stage-prompts.md#stage-2>
+)
+```
+
+> **Fallback:** If `ship-analyzer` is not available, use `subagent_type: "general-purpose"`.
+
+Substitute `{USER_INTENT}`, `{FILES_TO_INCLUDE}`, `{FILES_TO_EXCLUDE}`,
+`{REMOTE}`, `{DEFAULT_BRANCH}`, `{PLATFORM}` into the prompt.
+
+Parse SHIP_REPORT. Abort if failed.
+
+**Rollback:** If push succeeds but PR creation fails, report the error and
+suggest the manual PR creation command. Do NOT revert the push.
+- GitHub: `gh pr create --head {branch}`
+- Azure DevOps: `az repos pr create --source-branch {branch} --target-branch {DEFAULT_BRANCH}`
+
+**If `--pr-only` flag: Stop here and report PR URL to user.**
+
+---
 
-The `ship-analyzer` custom agent (`~/.claude/agents/ship-analyzer.md`) reads
-source files to write meaningful commit messages and PR descriptions.
-Falls back to `general-purpose` if not installed.
+## Stage 3: Wait for CI
+
+Launch **Bash subagent** in the **background** (haiku — just polling):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  run_in_background: true,
+  description: "Monitor CI checks",
+  prompt: <read from references/stage-prompts.md#stage-3>
+)
+```
+
+Substitute `{PR_NUMBER}` into the prompt.
+
+While CI runs in the background, briefly inform the user:
+```
+CI running for PR #{pr_number}... waiting for checks.
+```
+
+When the background task completes, read the output file and parse CHECKS_REPORT.
+
+---
+
+## Stage 4: Fix Failing Checks (if needed)
+
+If CHECKS_REPORT shows failures, launch **general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Fix CI failures",
+  prompt: <read from references/stage-prompts.md#stage-4>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{BRANCH}`, `{FAILING_CHECKS}` into the prompt.
+
+If fixed, return to Stage 3 (run CI watch again).
+If unable to fix after 2 attempts, report to user and stop.
+
+---
+
+## Stage 5: Merge & Final Sync
+
+Launch **Bash subagent** (haiku — simple git + platform CLI commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Merge PR and sync",
+  prompt: <read from references/stage-prompts.md#stage-5>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{REMOTE}`, `{DEFAULT_BRANCH}`, merge/branch flags.
+
+Parse LAND_REPORT.
+
+---
+
+## Final Report to User
+
+Compile all stage reports into a summary:
+
+```
+Ship complete
+
+  Branch:  {branch}
+  PR:      {pr_url}
+  Merged:  {merge_commit} ({merge_type})
+
+  Commits:
+  {list of commit messages, indented}
+
+  Files:   {count} files changed ({diff_summary})
+```
 
+If any stage failed, report the failure point and suggested resolution.