@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/references/questioning.md

@@ -1,7 +1,41 @@
-<!-- canonical: ../../pbr/references/questioning.md -->
 # Deep Questioning Guide
 
-Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+Techniques for understanding a user's project vision during `/pbr:new-project`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+
+> Skills are being migrated to these patterns. See Phase 5 for skill-level updates.
+
+---
+
+## Philosophy
+
+**You are a thinking partner, not an interviewer.**
+
+Project initialization is dream extraction, not requirements gathering. The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan** needs: specific requirements to break into tasks, context for implementation choices
+- **build** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+---
+
+## Background Context Checklist
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally into the conversation.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. When you have all four, you can offer to proceed. If they volunteer more, capture it.
 
 ---
 
@@ -92,44 +126,6 @@ This produces better answers than binary choices because users reveal their actu
 
 ---
 
-## Required Context Checklist
-
-By the end of questioning, you should have clear answers for ALL of these:
-
-### The Problem
-- [ ] What problem is being solved?
-- [ ] Who has this problem? (specific users/personas)
-- [ ] How are they solving it today? (current state)
-- [ ] Why is the current solution inadequate?
-
-### The Solution
-- [ ] What is being built? (concrete description)
-- [ ] What does "done" look like? (at least 3 success criteria)
-- [ ] What are the core features? (prioritized)
-- [ ] What is explicitly NOT being built? (scope boundaries)
-
-### Constraints
-- [ ] Technology choices already made (language, framework, hosting)
-- [ ] Budget constraints (money, time, resources)
-- [ ] Team constraints (size, skill level, availability)
-- [ ] Integration constraints (existing systems, APIs, databases)
-- [ ] Timeline expectations (deadlines, milestones)
-
-### Decisions Already Made
-- [ ] Architecture preferences or requirements
-- [ ] Deployment environment (cloud, self-hosted, serverless)
-- [ ] Authentication approach
-- [ ] Data storage approach
-- [ ] Third-party services to use
-
-### Edge Cases and Concerns
-- [ ] What keeps them up at night about this project?
-- [ ] What's the hardest part?
-- [ ] What might go wrong?
-- [ ] What are they unsure about?
-
----
-
 ## Progressive Depth Layers
 
 Structure the conversation as deepening layers. Each layer builds on the previous one. You do not need to complete every layer in every project, but the order matters — do not jump to Layer 3 before Layer 1 is solid.
@@ -139,24 +135,32 @@ Establish the broad outline. What is it, who is it for, what does it do?
 - Core purpose and user personas
 - Primary features and workflows
 - Technology preferences or constraints
+- What is being built (concrete deliverable)
+- What is NOT being built (scope boundaries)
+- Technology choices already made (language, framework, hosting)
 
 ### Layer 2: Feel — "How should users experience this?"
 Move from structure to experience. How does it feel to use?
 - UI expectations, interaction patterns, responsiveness
 - Tone, branding, visual direction
 - Performance expectations from the user's perspective
+- Timeline expectations and budget constraints
 
 ### Layer 3: Edges — "What happens when things go wrong?"
 Probe failure modes, edge cases, and the unexpected.
 - Error handling, empty states, data conflicts
 - Permission boundaries, rate limits, abuse scenarios
 - What the user has NOT thought about yet
+- What keeps them up at night about this project
+- What might go wrong, what's the hardest part
 
 ### Layer 4: System — "How does this fit into the bigger picture?"
 Zoom out to the surrounding ecosystem.
 - Integrations, data flows, deployment environment
 - Operational concerns — monitoring, backups, migrations
 - Future evolution and extensibility
+- Integration constraints (existing systems, APIs, databases)
+- Architecture preferences and deployment targets
 
 ---
 
@@ -200,16 +204,100 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 
 ---
 
+## Using AskUserQuestion
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+### Concrete Interpretations
+
+Options should be specific and reactable, not abstract categories.
+
+**Bad options:**
+- "Simple", "Medium", "Complex"
+- "Technical", "Business", "Other"
+- Leading options that presume an answer
+
+**Good options:**
+- "Landing page with contact form", "Multi-page site with blog", "Full web app with auth and dashboard"
+- "Sub-second response", "Handles large datasets", "Quick to build"
+- Specific examples that reveal priorities
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+### Modifying Options
+
+Users can modify a presented option without selecting "Other":
+- Select by number and modify: "#1 but with X"
+- Reference and adjust: "#2 with pagination disabled"
+
+When a user modifies an option, accept the modification as their decision. Do not re-present options or ask them to pick from the original list.
+
+For AskUserQuestion structural rules (max 4 options, 12-char header, multiSelect), see `references/ui-brand.md`.
+
+---
+
+## Freeform Rule
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" or "Let me explain" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** -- NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+**Wrong:** User says "let me describe it" -> AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" -> "Go ahead -- what are you thinking?"
+
+The freeform rule prevents AskUserQuestion from becoming an interrogation tool. When someone wants to talk, let them talk.
+
+---
+
+## Decision Gate
+
+When you have enough clarity to write the target document (PROJECT.md, CONTEXT.md, etc.), offer to proceed:
+
+```
+AskUserQuestion:
+  question: "I think I understand what you're after. Ready to proceed?"
+  header: "Ready?"
+  options:
+    - label: "Yes, proceed"    description: "Move forward with document creation"
+    - label: "Keep exploring"  description: "I want to share more or ask me more"
+```
+
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally. Loop until "Yes, proceed" is selected.
+
+This gate is **mandatory** in all skills that transition from questioning to document creation (begin, discuss, explore).
+
+---
+
 ## Anti-Patterns
 
 1. **DO NOT** present a form and ask users to fill it in
-2. **DO NOT** ask all questions at once — have a conversation
-3. **DO NOT** assume you know what they want — ask
-4. **DO NOT** suggest technologies before understanding the problem
-5. **DO NOT** skip edge case exploration
-6. **DO NOT** accept vague answers — push for specifics
-7. **DO NOT** rush through questioning to get to planning
-8. **DO NOT** ignore concerns or hand-wave them away
-9. **DO NOT** lead the user toward a particular solution
-10. **DO NOT** forget to summarize and confirm understanding
-11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+2. **DO NOT** walk through a checklist -- the background checklist is for your mental tracking, never for the user
+3. **DO NOT** ask all questions at once — have a conversation
+4. **DO NOT** assume you know what they want — ask
+5. **DO NOT** suggest technologies before understanding the problem
+6. **DO NOT** impose premature constraints before understanding what the user actually wants to build
+7. **DO NOT** skip edge case exploration
+8. **DO NOT** accept vague answers — push for specifics
+9. **DO NOT** rush through questioning to get to planning
+10. **DO NOT** ignore concerns or hand-wave them away
+11. **DO NOT** lead the user toward a particular solution
+12. **DO NOT** forget to summarize and confirm understanding
+13. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+14. **DO NOT** use corporate speak or jargon — "What are your success criteria?" and "Who are your stakeholders?" sound like a consultant, not a thinking partner
+15. **DO NOT** ask about the user's technical experience — it's irrelevant and condescending. You build what they describe regardless of their background.

package/plugins/cursor-pbr/references/reading-verification.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/reading-verification.md -->
 # Reading Verification Reports
 
 A user-friendly guide to understanding verification results. For agent-facing patterns, see `verification-patterns.md`.
@@ -96,20 +95,20 @@ You have several options:
 
 ### Option 1: Re-run the build (most common)
 ```
-/pbr:build <N>
+/pbr:execute-phase <N>
 ```
 The executor will detect what's already complete and only fix what's missing.
 
 ### Option 2: Create a gap-closure plan
 ```
-/pbr:plan <N> --gaps
+/pbr:plan-phase <N> --gaps
 ```
 This creates a focused plan that targets only the specific gaps found during verification.
 
 ### Option 3: Manual fix
 For small gaps (like a missing import), you can fix the code yourself and then re-run verification:
 ```
-/pbr:review <N>
+/pbr:verify-work <N>
 ```
 
 ### Option 4: Override (for false positives)

package/plugins/cursor-pbr/references/signal-files.md

@@ -0,0 +1,41 @@
+# Signal Files Reference
+
+Signal files are ephemeral files in `.planning/` that coordinate state between hook scripts
+and skills. They are scoped to either the current session or the current phase/plan.
+
+## Session-Scoped Files
+
+All 5 session signals are consolidated in `.planning/.session.json`. Scripts must read and write
+`.session.json` via `pbr-tools session get|set|clear` — never read the raw `.session.json` file directly.
+The `.session.json` schema is an object with the keys documented below.
+
+| JSON Key | Former File | Written By | Read By | Semantics |
+|----------|-------------|------------|---------|-----------|
+| `activeSkill` | `.active-skill` | Skills (Write tool) | check-skill-workflow, enforce-pbr-workflow, check-subagent-output, log-subagent, block-skill-self-read | Which skill is active. Written at skill start, cleared at skill end (session-cleanup). |
+| `compactCounter` | `.compact-counter` | suggest-compact.js | suggest-compact.js | Write count since last /compact. Resets on SessionStart. |
+| `sessionStart` | `.session-start` | progress-tracker.js | local-llm metrics | ISO timestamp of session start. Used for LLM metrics correlation. |
+| `activeOperation` | `.active-operation` | context-budget-check.js | context-budget-check.js | Current named operation for budget display. |
+| `activePlan` | `.active-plan` | context-budget-check.js | context-budget-check.js | Current plan ID for budget display. |
+
+**Atomic access**: Use `pbr-tools session get|set|clear` for safe reads/writes from hook scripts.
+
+**Lifecycle**: Written during SessionStart (progress-tracker), cleared during SessionEnd (session-cleanup).
+Stale sessions (> 60 min) are auto-cleaned by progress-tracker.js on next SessionStart.
+
+## One-Shot Files
+
+These files are NOT consolidated — they use write-once, delete-on-read semantics.
+
+| File | Written By | Read By | Semantics |
+|------|------------|---------|-----------|
+| `.planning/.auto-next` | auto-continue.js | auto-continue.js (Stop hook) | Next command to run after session stops. Deleted after read. |
+| `.planning/.auto-verify` | event-handler.js | event-handler.js (SubagentStop hook) | Trigger auto-verification after agent completes. Deleted after read. |
+
+## Phase-Scoped Files
+
+These files persist across sessions, scoped to a specific phase or plan.
+
+| File Pattern | Written By | Read By | Semantics |
+|-------------|------------|---------|-----------|
+| `.planning/phases/{id}/.checkpoint-manifest.json` | build skill | validate-task.js, session-cleanup.js | Checkpoint state for a plan in progress. Cleaned up after 24h. |
+| `.planning/phases/{id}/.PROGRESS-{taskId}` | executor agent | validate-task.js | Task progress marker for crash recovery. Orphaned files warn on SessionStart. |

package/plugins/cursor-pbr/references/stub-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/stub-patterns.md -->
 # Stub Detection Patterns
 
 Technology-aware patterns for detecting incomplete implementations. Used by the verifier during Layer 2 (Substantiveness) checks.

package/plugins/cursor-pbr/references/tmux-setup.md

@@ -0,0 +1,286 @@
+# TMUX Setup for Claude Code (Windows 11 + WSL2)
+
+Complete guide to running Claude Code inside TMUX on Windows 11. Claude Code stays
+installed on Windows; TMUX in WSL2 wraps it via `cmd.exe /c claude`. Projects remain
+on Windows drives (e.g., `D:\Repos\`), accessed through WSL2's `/mnt/` mount.
+
+## Prerequisites
+
+- Windows 11 with WSL2 enabled (`wsl --install` if not already set up)
+- A WSL2 distro installed (Ubuntu recommended: `wsl --install -d Ubuntu`)
+- Claude Code installed on Windows (`npm install -g @anthropic-ai/claude-code`)
+- Windows Terminal (recommended, available from Microsoft Store)
+
+## Step 1: Install TMUX in WSL2
+
+```bash
+sudo apt update && sudo apt install -y tmux
+tmux -V  # Should print tmux 3.x+
+```
+
+## Step 2: Install gum (optional but recommended)
+
+gum provides polished interactive menus for `pbr-tmux`. Without it, `pbr-tmux` falls
+back to plain bash `select` menus -- fully functional, just less pretty.
+
+**Method A -- Charm apt repository (Ubuntu/Debian):**
+
+```bash
+sudo mkdir -p /etc/apt/keyrings
+curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
+echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" \
+  | sudo tee /etc/apt/sources.list.d/charm.list
+sudo apt update && sudo apt install gum
+```
+
+**Method B -- Direct binary download (any Linux distro):**
+
+```bash
+GUM_VERSION=$(curl -s https://api.github.com/repos/charmbracelet/gum/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)
+curl -fsSL "https://github.com/charmbracelet/gum/releases/download/v${GUM_VERSION}/gum_${GUM_VERSION}_Linux_x86_64.tar.gz" \
+  | sudo tar xz -C /usr/local/bin gum
+```
+
+**Verify:** `gum --version`
+
+## Step 3: Install .tmux.conf
+
+Copy the PBR-optimized tmux configuration:
+
+```bash
+# From the plan-build-run repository root (WSL2 path):
+cp /mnt/d/Repos/plan-build-run/.tmux.conf ~/.tmux.conf
+```
+
+**CRITICAL:** The config sets `default-terminal "tmux-256color"`. Do NOT change this to
+`screen-256color` -- that causes Windows `.exe` processes (including `cmd.exe /c claude`)
+to hang indefinitely in WSL2 tmux panes.
+
+Key features provided by `.tmux.conf`:
+
+- Mouse support (click panes, scroll, resize)
+- 50,000-line scrollback history
+- Vi copy-mode with clipboard integration (xclip or clip.exe)
+- Vim-style pane navigation (`Ctrl-b h/j/k/l`)
+- Intuitive splits (`Ctrl-b |` horizontal, `Ctrl-b -` vertical)
+- PBR-aware status bar (shows current phase and status)
+
+## Step 4: Set up PBR status bar
+
+The status bar reads `.planning/STATE.md` every 10 seconds and displays the current
+phase and workflow status in the bottom-right corner.
+
+```bash
+mkdir -p ~/.tmux
+ln -sf /mnt/d/Repos/plan-build-run/tools/pbr-tmux/lib/pbr-state.sh ~/.tmux/pbr-status.sh
+```
+
+Point it at your project:
+
+```bash
+# Option A: Breadcrumb file (persists across sessions)
+echo "/mnt/d/Repos/your-project" > ~/.pbr-project-path
+
+# Option B: Environment variable (set in ~/.bashrc)
+export PBR_PROJECT_DIR="/mnt/d/Repos/your-project"
+```
+
+The status bar shows `P{phase}:{status}` when a project is active, or `no-pbr` when
+no `.planning/STATE.md` is found.
+
+## Step 5: Set up pbr-tmux
+
+`pbr-tmux` is the interactive CLI for common tmux operations in a PBR workflow.
+
+```bash
+# Option A: Symlink to PATH (recommended)
+sudo ln -sf /mnt/d/Repos/plan-build-run/tools/pbr-tmux/pbr-tmux /usr/local/bin/pbr-tmux
+
+# Option B: Add directory to PATH in ~/.bashrc
+echo 'export PATH="/mnt/d/Repos/plan-build-run/tools/pbr-tmux:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Usage:
+
+- `pbr-tmux` -- Interactive menu (uses gum if available, bash select otherwise)
+- `pbr-tmux launch` -- Launch a Claude Code session in a new pane
+- `pbr-tmux cycle` -- Send `/clear` + `/pbr:resume-work` to the Claude pane
+- `pbr-tmux status` -- Show PBR project status
+- `pbr-tmux list` -- List active tmux sessions
+- `pbr-tmux --help` -- Full list of operations
+
+Non-interactive mode for scripting: `pbr-tmux cycle --non-interactive`
+
+## Step 6: Windows Terminal integration
+
+Add a dedicated "PBR TMUX" profile to Windows Terminal:
+
+1. Open Windows Terminal Settings (`Ctrl+,`) and click "Open JSON file"
+2. Add the contents of `tools/pbr-tmux/windows-terminal-profile.json` to `profiles.list[]`:
+
+```json
+{
+  "name": "PBR TMUX",
+  "commandline": "wsl.exe -d Ubuntu -- bash -lc 'tmux new-session -A -s pbr'",
+  "font": { "face": "JetBrainsMono Nerd Font", "size": 11 },
+  "colorScheme": "One Half Dark",
+  "padding": "4",
+  "scrollbarState": "hidden"
+}
+```
+
+**Notes:**
+
+- Change `Ubuntu` in the commandline to match your WSL2 distro (`wsl -l -v` to check)
+- Install JetBrainsMono Nerd Font from <https://www.nerdfonts.com/> for proper glyph
+  rendering in the status bar and gum menus
+- The `-A` flag in `tmux new-session -A -s pbr` attaches to an existing `pbr` session
+  if one is running, or creates a new one
+
+## Usage
+
+### Starting a session
+
+Click "PBR TMUX" in Windows Terminal, or from any WSL2 shell:
+
+```bash
+tmux new-session -A -s pbr
+```
+
+### Launching Claude Code
+
+```bash
+pbr-tmux launch
+# Or directly:
+cmd.exe /c claude
+```
+
+### Common workflows
+
+**Split-pane monitoring:** Use `Ctrl-b |` to split horizontally, run `pbr-tmux status`
+in the side pane while Claude works in the main pane.
+
+**Multiple sessions:** `pbr-tmux launch` in different windows for parallel Claude
+sessions. Use `pbr-tmux switch` to jump between them.
+
+**Auto-cycle (Phase 80):** `pbr-tmux cycle --non-interactive` sends `/clear` then
+`/pbr:resume-work` to the Claude pane for hands-free workflow continuation.
+
+### Automatic Session Cycling via auto-continue.js
+
+When running in autonomous mode with `features.auto_continue: true`, PBR automatically triggers session cycling based on `session_phase_limit` (default: 3 phases per session).
+
+**How it works:**
+1. `session-tracker.js` tracks completed phases in `.planning/.session-tracker`
+2. Counter resets to 0 at session start (via `progress-tracker.js`)
+3. Counter increments after each executor completion (via `event-handler.js`)
+4. When `auto-continue.js` detects the limit is reached AND `process.env.TMUX` is set:
+   - It spawns a detached process: `sleep 3 && tmux send-keys "/clear" Enter && sleep 1 && tmux send-keys "/pbr:resume-work" Enter`
+   - The current session pauses, then a fresh session starts automatically
+5. Outside TMUX, a banner displays manual instructions instead
+
+**Configure the limit:**
+
+```
+/pbr:settings session_phase_limit 5   # pause after 5 phases
+/pbr:settings session_phase_limit 0   # disable auto-pause
+```
+
+See `references/config-reference.md` for the full `session_phase_limit` specification.
+
+## Troubleshooting
+
+### Windows .exe hangs in tmux
+
+**Symptom:** `cmd.exe /c claude`, `explorer.exe`, or other Windows executables freeze.
+
+**Fix:** Check your terminal setting:
+
+```bash
+tmux show -g default-terminal
+# Must output: tmux-256color
+```
+
+If it shows `screen-256color`, update `~/.tmux.conf` and kill the tmux server:
+
+```bash
+tmux kill-server
+tmux  # Restart with new config
+```
+
+### Path issues
+
+Windows drives mount at `/mnt/{letter}/` in WSL2. If Claude cannot find your project,
+verify you are in the correct `/mnt/` path:
+
+```bash
+pwd               # Should show /mnt/d/Repos/your-project (not /home/user/...)
+ls .planning/     # Should show STATE.md if PBR is set up
+```
+
+### Clipboard
+
+Install `xclip` for full clipboard support (WSLg provides the X server on Windows 11):
+
+```bash
+sudo apt install xclip
+```
+
+Without xclip, tmux falls back to `clip.exe` which works for ASCII but may garble
+Unicode characters.
+
+### Font rendering
+
+Fonts are controlled by Windows Terminal, not tmux. If status bar icons or gum menus
+look broken, install a Nerd Font (JetBrainsMono Nerd Font recommended) and set it in
+the Windows Terminal profile.
+
+### Claude Code clipboard warnings
+
+Cosmetic warnings about clipboard access. Install `xclip` to suppress them. These do
+not affect Claude Code functionality.
+
+### gum not found
+
+`pbr-tmux` works without gum -- it falls back to bash `select` menus automatically.
+Install gum (Step 2) for the polished interactive experience.
+
+### tmux send-keys not working
+
+Verify basic send-keys functionality:
+
+```bash
+tmux send-keys -t 0 "echo hello" Enter
+```
+
+If Claude is mid-processing when you send keys, keystrokes queue in the terminal
+buffer. Add `sleep 0.5` between sequential `send-keys` commands for reliability.
+
+For the critical `cmd.exe /c claude` path, verify:
+
+```bash
+tmux new-session -d -s test "cmd.exe /c claude"
+sleep 3
+tmux send-keys -t test "/help" Enter
+```
+
+### Status bar shows "no-pbr"
+
+The status bar script cannot find `.planning/STATE.md`. Check:
+
+1. `~/.pbr-project-path` points to the correct WSL2 path (use `/mnt/` prefix)
+2. Or `PBR_PROJECT_DIR` environment variable is set
+3. The project has a `.planning/STATE.md` file
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `.tmux.conf` | TMUX configuration (repo root) |
+| `tools/pbr-tmux/pbr-tmux` | Main CLI entry point |
+| `tools/pbr-tmux/operations.sh` | Operation implementations |
+| `tools/pbr-tmux/lib/pbr-state.sh` | Status bar script |
+| `tools/pbr-tmux/lib/tmux-helpers.sh` | Shared tmux helper functions |
+| `tools/pbr-tmux/lib/gum-fallback.sh` | UI abstraction (gum/bash fallback) |
+| `tools/pbr-tmux/windows-terminal-profile.json` | Windows Terminal profile fragment |