/ui-phase

name: ui-phase
description: "Generate UI-SPEC.md design contracts for frontend-heavy phases."
allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "<phase-number> [--url <dev-server-url>]"

**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 0 immediately.**

Step 0 -- Banner

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► UI PHASE DESIGN                           ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

Step 1 -- Load State

Read the following files:

pbr-tools state load

Also read `.planning/config.json` to check for `ui.enabled` setting.

Step 2 -- Check UI Eligibility

Determine whether the UI pipeline should be active:

**2a.** If `config.ui.enabled` is explicitly `true`, proceed to Step 3.

**2b.** If `config.ui.enabled` is explicitly `false`, display:

UI pipeline is disabled. Enable with: /pbr:config set ui.enabled true

Then **STOP**. Do not proceed further.

**2c.** If `ui.enabled` is not set (undefined), auto-detect frontend project:

1. Check `package.json` for dependencies or devDependencies containing: `react`, `vue`, `angular`, `svelte`, `next`, `nuxt`, `solid-js`, `preact`, `lit`, `@angular/core` 2. Check for `index.html` in the project root or `public/` or `src/` 3. Check for `.css`, `.scss`, `.less`, `.sass` files in `src/` or `styles/`

If frontend indicators are found, proceed to Step 3.

If NO frontend indicators are found, ask the user:

This doesn't appear to be a frontend project. No frontend frameworks
or UI files were detected.

Options:
1. Continue anyway (I know this project has UI components)
2. Cancel (this project doesn't need UI design contracts)
3. Enable permanently: /pbr:config set ui.enabled true

If the user chooses option 1, proceed. If option 2, **STOP**. If option 3, tell them to run the config command and then re-run `/pbr:ui-phase`.

Step 3 -- Parse Arguments

Parse `$ARGUMENTS` for:

• **Phase number** (required): The phase to generate design contracts for
• **--url flag** (optional): Dev server URL for visual inspection (e.g., `http://localhost:3000`)

If no phase number is provided, display usage and **STOP**:

Usage: /pbr:ui-phase <phase-number> [--url <dev-server-url>]

Example: /pbr:ui-phase 3 --url http://localhost:3000

Step 4 -- Load Phase Context

Read the ROADMAP.md to find the phase directory matching the given phase number:

pbr-tools state load

Read the phase directory at `.planning/phases/{NN}-{slug}/` to understand the phase goal and any existing plans. Extract the phase goal from ROADMAP.md for the given phase number.

If the phase directory does not exist, display an error and **STOP**:

Phase {N} not found. Check /pbr:status for available phases.

Step 5 -- Spawn UI Researcher Agent

**CRITICAL: Agent type rule** -- ALWAYS use `subagent_type: "pbr:ui-researcher"`. NEVER use `general-purpose` or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.

Spawn a Task with:

• `subagent_type: "pbr:ui-researcher"`
• Spawn prompt containing:
• Project root path
• Phase number and phase goal
• Dev server URL (if provided via `--url`, otherwise state "not provided")
• Target output path: `.planning/phases/{NN}-{slug}/UI-SPEC.md`
• **Template reference:** `${CLAUDE_PLUGIN_ROOT}/templates/UI-SPEC.md.tmpl` — the agent should read this template for the standard UI-SPEC format (design system, spacing, typography, color, components)
• Instruction to analyze the frontend codebase and generate design contracts

Display before spawning:

Spawning ui-researcher... (est. 2-5 min)

Wait for agent completion.

Step 6 -- Present Results

Read the generated `UI-SPEC.md` from `.planning/phases/{NN}-{slug}/UI-SPEC.md`.

If the file was not created, report the error and **STOP**.

Present a summary to the user showing:

• Number of dimensions covered
• Key design decisions proposed
• Any constraints or patterns identified

Step 7 -- Confirm Design Contracts

Ask the user:

Review the design contracts above. Options:
1. Confirm -- lock UI-SPEC.md and proceed to planning
2. Request changes -- describe what to adjust
3. Cancel -- discard UI-SPEC.md

If the user requests changes, describe what they want adjusted and re-spawn the ui-researcher agent with the feedback. Repeat until confirmed or cancelled.

If cancelled, delete the UI-SPEC.md file and **STOP**.

Step 8 -- Success

Display:

UI-SPEC.md locked for phase {N}.

Next step: Run /pbr:plan-phase {N} to plan with these design contracts.
The planner will reference UI-SPEC.md as a constraint alongside CONTEXT.md.

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• Delegate ALL analysis to the ui-researcher subagent -- do not analyze frontend code yourself
• Read UI-SPEC.md output only for summary presentation, not deep inspection
• If user requests multiple rounds of changes, warn about context budget after 3 iterations

Reference: `skills/shared/commit-planning-docs.md` -- if `planning.commit_docs` is true, commit UI-SPEC.md.

Anti-Patterns

1. DO NOT analyze the frontend codebase yourself -- the ui-researcher agent does this 2. DO NOT read agent .md files -- auto-loaded via subagent_type 3. DO NOT modify UI-SPEC.md directly -- the agent handles writes 4. DO NOT skip the UI eligibility check (Step 2) 5. DO NOT proceed without user confirmation of design contracts 6. DO NOT use general-purpose agents -- always use `pbr:ui-researcher`