@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/ui-phase/SKILL.md

@@ -0,0 +1,177 @@
+---
+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:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js 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:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js 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`
+  - 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
+
+## 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`

package/plan-build-run/skills/ui-review/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: ui-review
+description: "Retroactive visual audit of UI implementation with 1-4 scoring per dimension."
+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 REVIEW                                 ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Load State
+
+Read the following files:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js 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-review`.
+
+## Step 3 -- Parse Arguments
+
+Parse `$ARGUMENTS` for:
+
+- **Phase number** (required): The phase to audit
+- **--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-review <phase-number> [--url <dev-server-url>]
+
+Example: /pbr:ui-review 3 --url http://localhost:3000
+```
+
+## Step 4 -- Load UI-SPEC.md
+
+Look for the UI-SPEC.md in the phase directory:
+
+```
+.planning/phases/{NN}-{slug}/UI-SPEC.md
+```
+
+If the file does not exist, display:
+
+```
+No UI-SPEC.md found for phase {N}.
+
+Run /pbr:ui-phase {N} first to generate design contracts,
+then re-run /pbr:ui-review {N} to audit against them.
+```
+
+Then **STOP**. The review requires a baseline specification to score against.
+
+## Step 5 -- Spawn UI Checker Agent
+
+**CRITICAL: Agent type rule** -- ALWAYS use `subagent_type: "pbr:ui-checker"`. 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-checker"`
+- Spawn prompt containing:
+  - Project root path
+  - Phase number
+  - Path to UI-SPEC.md: `.planning/phases/{NN}-{slug}/UI-SPEC.md`
+  - Dev server URL (if provided via `--url`, otherwise state "not provided")
+  - Target output path: `.planning/phases/{NN}-{slug}/UI-REVIEW.md`
+  - Instruction to review UI implementation against the spec and score each dimension
+
+Display before spawning:
+
+```
+Spawning ui-checker... (est. 2-5 min)
+```
+
+Wait for agent completion.
+
+## Step 6 -- Read Results
+
+Read the generated `UI-REVIEW.md` from `.planning/phases/{NN}-{slug}/UI-REVIEW.md`.
+
+If the file was not created, report the error and **STOP**.
+
+## Step 7 -- Present Scores
+
+Display the audit results in a formatted table:
+
+```
+UI Visual Audit -- Phase {N}
+============================
+
+Dimension    | Score | Notes
+-------------|-------|------
+Copywriting  | X/4   | {summary}
+Visuals      | X/4   | {summary}
+Color        | X/4   | {summary}
+Typography   | X/4   | {summary}
+Spacing      | X/4   | {summary}
+Experience   | X/4   | {summary}
+-------------|-------|------
+Overall      | X.X/4 | Visual verification: Yes/No
+
+Legend: 1 = Poor, 2 = Below Average, 3 = Good, 4 = Excellent
+```
+
+If the overall score is below 2.5, highlight areas needing attention:
+
+```
+Dimensions below threshold (< 3):
+- {dimension}: {specific issue and suggested fix}
+```
+
+## Step 8 -- Offer Next Steps
+
+Ask the user:
+
+```
+Would you like to address any of these findings?
+
+Options:
+1. Fix specific dimensions -- I'll suggest /pbr:do tasks for improvements
+2. Re-run audit -- after making manual changes
+3. Accept results -- no changes needed
+```
+
+## Step 9 -- Suggest Fixes
+
+If the user wants to fix specific dimensions, for each dimension they want to address, suggest a `/pbr:do` task:
+
+```
+Suggested tasks:
+
+/pbr:do "Improve {dimension} for phase {N}: {specific improvement from review}"
+```
+
+List each dimension the user selected with a concrete, actionable task description derived from the ui-checker's feedback.
+
+## 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-checker subagent -- do not analyze UI implementation yourself
+- Read UI-REVIEW.md output for score presentation, extract only the scoring table and key findings
+- Keep follow-up suggestions concise -- one `/pbr:do` command per dimension
+
+## Anti-Patterns
+
+1. DO NOT analyze the UI implementation yourself -- the ui-checker agent does this
+2. DO NOT read agent .md files -- auto-loaded via subagent_type
+3. DO NOT modify UI-REVIEW.md directly -- the agent handles writes
+4. DO NOT skip the UI eligibility check (Step 2)
+5. DO NOT skip the UI-SPEC.md existence check (Step 4) -- review requires a baseline
+6. DO NOT use general-purpose agents -- always use `pbr:ui-checker`
+7. DO NOT implement fixes yourself -- suggest `/pbr:do` tasks for the user

package/plan-build-run/skills/undo/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: undo
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--last N] [--phase NN] [--plan NN-MM] [--range HASH..HASH]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 0 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► UNDO                                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:undo — Safe Commit Reversal
+
+You are running the **undo** skill. Your job is to help the user safely revert recent PBR-generated commits using `git revert` (history-preserving), not `git reset` (destructive).
+
+This skill runs **inline** (no Task delegation).
+
+---
+
+## Step 1 — Gather PBR Commits
+
+Run:
+
+```bash
+git log --oneline --no-merges -50
+```
+
+Filter lines matching the PBR commit pattern:
+`^[0-9a-f]+ (feat|fix|refactor|test|docs|chore|wip|revert)(\([a-zA-Z0-9._-]+\))?:`
+
+If no PBR commits found, display:
+
+```
+No PBR commits found in the last 50 commits.
+```
+
+Then exit.
+
+**Parse $ARGUMENTS for flags**:
+- `--last N`: limit to N most recent PBR commits (default 20)
+- `--phase NN`: filter to commits for a specific phase number (e.g. `--phase 55`)
+- `--plan NN-MM`: filter to commits for a specific plan (e.g. `--plan 55-02`)
+- `--range HASH..HASH`: preselect a hash range for revert — if provided, skip to Step 5 with that range pre-filled
+
+**Phase manifest mode (`--phase NN`):**
+
+When `--phase NN` is specified, first check for a `.phase-manifest.json` in the phase directory:
+
+1. Resolve the phase directory: `.planning/phases/{NN}-*/`
+2. Check for `.phase-manifest.json` in that directory
+3. If manifest exists: use `manifest.commits` as the commit list (skip git log scan)
+4. If manifest missing (phases completed before manifest support): fall back to git log scan and filter by scope pattern
+
+Phase manifests are written by `completePhase()`. Older phases may not have manifests.
+
+Apply filters to the collected PBR commits before proceeding.
+
+---
+
+## Step 2 — Group Commits by Scope
+
+Parse the scope from each commit message (e.g., `55-02`, `quick-003`, `planning`). If no scope is present, use `(no scope)`.
+
+Present grouped output:
+
+```
+Recent PBR commits (grouped by scope):
+
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
+
+[quick-003]
+  ghi9012  fix(quick-003): fix hook path resolution
+
+[planning]
+  jkl3456  docs(planning): update roadmap phase 55
+```
+
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
+
+---
+
+## Step 3 — Prompt for Selection
+
+Use AskUserQuestion with the **select-action** pattern:
+
+- **question**: "Which commit(s) do you want to undo? Select a scope to revert all commits in that scope, or choose a custom option."
+- **header**: "Select commits to undo"
+- **options**: (dynamic — top 8 scope labels from grouped list, each formatted as `[{scope}] {N} commit(s)`, plus "Enter custom hash or range" and "Cancel")
+- **multiSelect**: false
+
+If user selects a scope label: collect all commits with that scope as the revert set.
+If user selects "Enter custom hash or range": use AskUserQuestion (freeform) to ask:
+  - "Enter a commit hash or range (e.g. abc1234 or abc..def):"
+  - Parse the response as a hash or HASH1..HASH2 range
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+---
+
+## Step 3.5 — Pre-Revert Safety Gates (for `--phase NN` mode)
+
+When reverting an entire phase (`--phase NN`), run these 3 safety checks before proceeding to confirmation:
+
+**Gate 1: Downstream dependency check**
+Parse `.planning/ROADMAP.md` to find phases that list the target phase in their "Depends on" field. If any dependent phase has been started (has PLAN files or SUMMARY files), block with:
+```
+Phase {M} ({name}) depends on phase {N} and has already begun. Undo would break downstream work.
+To proceed anyway, use --force.
+```
+
+**Gate 2: Commit preview**
+Display all commits that will be reverted as a numbered list:
+```
+Commits to revert ({count}):
+  1. abc1234  feat(auth): implement discord oauth
+  2. def5678  fix(auth): handle null profile
+  3. ghi9012  docs(planning): add phase 3 summaries
+```
+
+**Gate 3: Explicit confirmation**
+Use AskUserQuestion with the **yes-no** pattern:
+- **question**: "Revert {count} commits from phase {N}? This uses git revert (history-preserving)."
+- **options**: ["Proceed with revert", "Cancel"]
+
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+For non-phase mode (single commits, custom ranges), skip Gate 1 and proceed to Step 4.
+
+---
+
+## Step 4 — Confirm Selection
+
+Display the commits that will be reverted:
+
+```
+The following commits will be reverted (using git revert, NOT git reset):
+
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
+
+This creates new revert commits — your history is preserved.
+```
+
+Use AskUserQuestion with the **yes-no** pattern:
+- **question**: "Proceed with reverting these commits?"
+- **options**: ["Proceed with revert", "Cancel"]
+
+If user selects "Cancel": print "Undo cancelled." and exit.
+
+---
+
+## Step 5 — Execute git revert
+
+For each commit hash in **reverse chronological order** (newest first):
+
+```bash
+git revert --no-commit {hash}
+```
+
+After all reverts are staged, determine the commit message:
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
+- If reverting a **single commit**: `revert({scope}): undo {original description}`
+- If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`
+
+Commit with:
+
+```bash
+git commit -m "revert({scope}): undo {description}"
+```
+
+**Conflict handling**: If `git revert --no-commit` exits non-zero or produces conflict markers:
+1. Run `git revert --abort` to clean up
+2. Display:
+   ```
+   Revert failed due to merge conflicts. Manual resolution required.
+   Run: git revert {hashes} and resolve conflicts.
+   ```
+3. Exit without committing.
+
+---
+
+## Step 6 — Report Result
+
+Display completion banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► UNDO COMPLETE                              ║
+╚══════════════════════════════════════════════════════════════╝
+
+Reverted: {N} commit(s) from scope {scope}
+New revert commit: {hash} — revert({scope}): undo {description}
+
+/pbr:progress — check current state
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** use `git reset` — always use `git revert` to preserve history
+2. **DO NOT** revert commits from other users without confirmation
+3. **DO NOT** revert merge commits without warning the user about potential complexity
+4. **DO NOT** skip the confirmation step (Step 4)
+5. **DO NOT** commit if `git revert` reports conflicts — abort and report instead