@slamb2k/mad-skills 2.0.7 → 2.0.8

package/skills/distil/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: 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.
+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.
+argument-hint: <count> --port <port> [--spec <path>] [--favorites <1,2,3>]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion
 ---
 
 # Distil - Design Variation Generator
@@ -35,4 +32,258 @@ Taglines:
 - Distilling N variations of brilliance!
 - From crude concept to pure design!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Generate multiple unique, creative web interface designs for any website or
+web application. The primary agent acts as a thin orchestrator — all heavy
+reading and file creation is delegated to subagents to protect the primary
+context window.
+
+## Arguments
+
+Parse the following from the skill invocation:
+- **count** (required): Number of designs to create (e.g., 5)
+- **--spec** (optional): Path to a file containing site specification
+- **--url** (optional): URL to existing site to review for context
+- **--port** (required): Port for the Vite dev server
+- **--favorites** (optional): Comma-separated list of design numbers for iteration mode
+
+### Examples
+```
+/distil 5 --spec ./site-spec.md --port 5173
+/distil 3 --favorites 2,4 --port 5173
+```
+
+If `--favorites` is provided, follow `references/iteration-mode.md` instead
+of the steps below.
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| npm | cli | `npm --version` | yes | stop | https://bun.sh or use npm |
+| bencium-innovative-ux-designer | skill | `~/.claude/skills/bencium-innovative-ux-designer/SKILL.md` | no | ask | `npx skills add bencium/bencium-claude-code-design-skill@bencium-innovative-ux-designer -g -y` |
+| web-animation-design | skill | `~/.claude/skills/web-animation-design/SKILL.md` | no | ask | `npx skills add connorads/dotfiles@web-animation-design -g -y` |
+| design-system | skill | `~/.claude/skills/design-system/SKILL.md` | no | ask | `npx skills add lobbi-docs/claude@design-system -g -y` |
+
+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
+
+---
+
+## Site Specification
+
+The specification can be provided via:
+
+1. **--spec flag**: Read the file at the provided path
+2. **Pasted text**: Check conversation for a description of the site
+3. **--url flag**: Use WebFetch to analyze an existing site
+
+**If no specification is found, ask the user before proceeding.**
+
+---
+
+## Step 1: Load Site Specification
+
+Parse and store the site context for use when generating each design.
+This is the only file the primary agent reads directly (specs are typically small).
+
+## Step 2: Reconnaissance (launch in parallel)
+
+Launch two subagents **in parallel** to gather context without bloating
+the primary agent.
+
+### 2a: Verify Design Skills
+
+Design skill availability is checked in the Pre-flight section above.
+Use the results from pre-flight to populate SKILL_REPORT:
+- For each design skill: name, installed (yes/no)
+- If any skill was missing and the user declined to install, note it as unavailable
+
+### 2b: Scan Existing Project
+
+```
+Task(
+  subagent_type: "Explore",
+  model: "haiku",
+  description: "Scan existing design project",
+  prompt: "Check if src/designs/ directory exists. If it does:
+    1. List all DesignN.tsx files (glob for src/designs/Design*.tsx)
+    2. For each file, read ONLY the first 10 lines to extract the
+       metadata comment (style name, key traits)
+    3. Determine the highest design number
+    Return PROJECT_REPORT (max 20 lines):
+    - project_exists: true/false
+    - package_manager: detected from lockfile (bun.lockb/pnpm-lock/yarn.lock/package-lock)
+    - design_count: N
+    - highest_number: N
+    - designs: list of (number, style_name) pairs
+    If no src/designs/ directory, return project_exists: false."
+)
+```
+
+### Parse Recon Results
+
+From SKILL_REPORT: Gate on missing skills before proceeding.
+From PROJECT_REPORT:
+- If `project_exists`: set `START_INDEX = highest_number + 1`, skip Step 3
+- If not: set `START_INDEX = 1`, proceed to Step 3
+
+## Step 3: Initialize Project
+
+**Skip this step if an existing project was detected in Step 2b.**
+
+Launch **Bash subagent** (haiku) to set up the project:
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Initialize distil project",
+  prompt: "Follow the project setup instructions:
+    1. Detect package manager (bun -> pnpm -> yarn -> npm)
+    2. Create Vite React-TS project
+    3. Install dependencies: tailwindcss, postcss, autoprefixer,
+       react-router-dom, lucide-react
+    4. Configure Tailwind (content paths, index.css directives)
+    5. Copy {skill_dir}/assets/DesignNav.tsx to src/components/DesignNav.tsx
+    Return SETUP_REPORT (max 10 lines): status, package_manager, errors."
+)
+```
+
+Parse SETUP_REPORT. If setup fails, fall back through the package manager
+chain (bun -> pnpm -> yarn -> npm).
+
+## Step 4: Create Designs via Subagent
+
+Launch a **general-purpose subagent** to create all new designs.
+
+**CRITICAL**: The subagent reads skill files and design guides directly.
+Do NOT read them in the primary agent — pass file paths only.
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Create design variations",
+  prompt: "
+    You are creating {COUNT} new web design variations for a distil project.
+
+    ## Site Specification
+    {SITE_SPEC from Step 1}
+
+    ## Design Knowledge — Read These Files
+    Load design principles and the 50+ style catalog from these skill files:
+    - ~/.claude/skills/bencium-innovative-ux-designer/SKILL.md
+    - ~/.claude/skills/bencium-innovative-ux-designer/MOTION-SPEC.md
+    - ~/.claude/skills/web-animation-design/SKILL.md
+    - ~/.claude/skills/design-system/SKILL.md
+    - ~/.claude/skills/design-system/references/style-guide.md
+
+    Also read the project design guide:
+    - {skill_dir}/references/design-guide.md
+
+    ## Existing Designs (avoid these styles)
+    {Compact list from PROJECT_REPORT: number + style_name pairs,
+     or 'None — fresh project'}
+
+    ## Task
+    Create designs numbered {START_INDEX} through {START_INDEX + COUNT - 1}.
+
+    For each design, create `src/designs/Design{N}.tsx`:
+    - Pick a DISTINCT style from the 50+ style catalog in the design-system skill
+    - Do NOT reuse styles already used by existing designs
+    - Apply the site specification to all content and sections
+    - Follow anti-AI-slop rules strictly (no Inter, no default blue, no cookie-cutter layouts)
+    - Include purposeful animations with proper easing
+    - Each design must be self-contained in a single file
+    - Import and render DesignNav from '../components/DesignNav'
+
+    After creating all designs, update:
+    1. `src/App.tsx` — Add import and route for EVERY design (existing + new)
+    2. Each design file's DesignNav `designs` array — Include ALL designs (existing + new)
+
+    ## Design File Requirements
+    Each design file must have:
+    - A metadata comment at the top: style name, key visual traits, color palette
+    - Import DesignNav from '../components/DesignNav'
+    - A `designs` array listing ALL designs (existing + new) with id and name
+    - ALL sections from the site specification with realistic content
+    - Custom color palette (not default Tailwind)
+    - Animations with proper easing (ease-out for entrances, ease-in-out for movement)
+    - Responsive layout (mobile-first)
+    - Lucide React icons for iconography
+
+    ## App.tsx Requirements
+    The App.tsx must:
+    - Import ALL design components (existing + new)
+    - Have a route for each: <Route path='/{N}' element={<DesignN />} />
+    - Default route redirects to /1
+
+    Return DESIGN_REPORT (max 30 lines):
+    - List each design created: number, style name, key visual traits
+    - Total design count (existing + new)
+    - Files created and modified
+    - Any issues encountered
+  "
+)
+```
+
+Parse DESIGN_REPORT. If any design failed, report the error and offer retry.
+
+## Step 5: Start Dev Server
+
+Launch as a **background Bash** to avoid blocking the primary agent:
+
+```
+Task(
+  subagent_type: "Bash",
+  run_in_background: true,
+  description: "Start Vite dev server",
+  prompt: "{package_manager} run dev --port {PORT}"
+)
+```
+
+If the dev server is already running, HMR should pick up the new files
+automatically — skip this step.
+
+## Step 6: Present Designs
+
+Inform the user:
+- Dev server is running at `http://localhost:{PORT}`
+- Each design is available at `/1`, `/2`, `/3`, etc.
+- Briefly describe each design's unique approach (from DESIGN_REPORT)
+- Note which designs are new vs existing (if appending)
+- Remind they can iterate with `--favorites` to refine preferred designs
+
+## Context Protection Summary
+
+| Step | Agent | Model | Why |
+|---|---|---|---|
+| 1: Load spec | Primary | — | Small file, needed for subagent prompt |
+| 2a: Skill check | Explore | haiku | Avoids reading 2000+ lines of skill content |
+| 2b: Project scan | Explore | haiku | Avoids reading existing design files |
+| 3: Init project | Bash | haiku | Shell commands only |
+| 4: Create designs | general-purpose | default | Heavy lifting: reads skills, writes files |
+| 5: Dev server | Bash (background) | — | Non-blocking, no output in primary |
+| 6: Present | Primary | — | User-facing, uses compact DESIGN_REPORT |
+
+## Troubleshooting
+
+- If package manager commands fail, try the next in the fallback chain
+- If port is in use, suggest killing the process or using a different port
+- If design imports fail, check file naming consistency
+- If no site spec is found, always ask the user before proceeding
+- If a design skill is missing, offer to install it before proceeding
+- If the subagent fails, check error details and retry with adjusted parameters

package/skills/manifest.json

@@ -1,12 +1,12 @@
 {
-  "generated": "2026-03-03T01:58:15.572Z",
-  "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,12 +1,8 @@
 ---
 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
@@ -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,11 +1,8 @@
 ---
 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
@@ -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