@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -0,0 +1,151 @@
+---
+name: statusline
+description: "Install or configure the PBR status line in Claude Code."
+allowed-tools: Read, Write, Bash, AskUserQuestion
+argument-hint: "[install | uninstall | preview]"
+---
+
+**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 ~3,000 tokens. Begin executing Step 0 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STATUS LINE                                ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:statusline — Status Line Setup
+
+The PBR status line displays live project state (phase, plan, status, git branch, context usage) in the Claude Code terminal status bar.
+
+---
+
+## Subcommand Parsing
+
+Parse `$ARGUMENTS`:
+
+| Argument | Action |
+|----------|--------|
+| `install` or empty | Install/enable the status line |
+| `uninstall` or `remove` | Remove the status line configuration |
+| `preview` | Show what the status line looks like without installing |
+
+---
+
+## Subcommand: install (default)
+
+### Step 1: Locate the status-line script
+
+**CRITICAL: You must resolve the correct absolute path to `status-line.js`. Do NOT hardcode paths.**
+
+1. The script lives at `${CLAUDE_PLUGIN_ROOT}/scripts/status-line.js`
+2. Resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path using `pwd` or by checking the plugin root
+3. If running from a local plugin dir (`claude --plugin-dir .`), the path is the local repo's `plugins/pbr/scripts/status-line.js`
+4. If running from the installed plugin cache (`~/.claude/plugins/cache/`), use that path
+5. **Verify the script exists** with `ls` before proceeding. If it doesn't exist, show an error and stop.
+
+Store the resolved absolute path as `SCRIPT_PATH`.
+
+### Step 2: Read current settings
+
+Read `~/.claude/settings.json` (or `$HOME/.claude/settings.json`).
+
+- If the file doesn't exist: start with an empty object `{}`
+- If it exists: parse the JSON content
+- Check if `statusLine` key already exists:
+  - If yes and points to the same script: inform user "PBR status line is already installed." and stop (unless they want to reconfigure)
+  - If yes but points to a different command: warn user and ask if they want to replace it
+
+### Step 3: Configure settings.json
+
+Use AskUserQuestion:
+  question: "Install the PBR status line? This adds a `statusLine` entry to ~/.claude/settings.json."
+  header: "Install?"
+  options:
+    - label: "Install"  description: "Enable the PBR status line in Claude Code"
+    - label: "Preview first"  description: "Show a preview before installing"
+    - label: "Cancel"  description: "Don't install"
+  multiSelect: false
+
+If "Preview first": run the preview subcommand (show sample output), then ask again.
+If "Cancel": stop.
+If "Install":
+
+**CRITICAL: Use Read tool to read the file, then Write to update it. Do NOT use sed or other text manipulation on JSON files.**
+
+**CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+
+1. Read `~/.claude/settings.json`
+2. Write the original content to `~/.claude/settings.json.bak`
+3. Parse the JSON
+4. Set `statusLine` to:
+   ```json
+   {
+     "type": "command",
+     "command": "node \"SCRIPT_PATH\""
+   }
+   ```
+   Where `SCRIPT_PATH` is the resolved absolute path from Step 1. Use forward slashes even on Windows.
+5. Write the updated JSON back (preserve all other settings, use 2-space indentation)
+
+### Step 4: Verify and confirm
+
+Display:
+```
+✓ PBR status line installed
+
+  Script: {SCRIPT_PATH}
+  Config: ~/.claude/settings.json
+
+The status line will appear on your next Claude Code session.
+Restart Claude Code or run `/clear` to activate it now.
+
+Customize per-project via .planning/config.json:
+  "status_line": {
+    "sections": ["phase", "plan", "status", "git", "context"],
+    "brand_text": "PBR"
+  }
+```
+
+---
+
+## Subcommand: uninstall
+
+1. Read `~/.claude/settings.json`
+2. If no `statusLine` key: inform user "No status line configured." and stop
+3. **CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+4. Remove the `statusLine` key from the JSON
+5. Write the updated file
+5. Display: `✓ PBR status line removed. Restart Claude Code to take effect.`
+
+---
+
+## Subcommand: preview
+
+1. Locate and run the status-line script: `node {SCRIPT_PATH}`
+   - Pass sample stdin JSON: `{"context_window": {"used_percentage": 35}, "model": {"display_name": "Claude Opus 4.6"}, "cost": {"total_cost_usd": 0.42}}`
+2. Display the raw output to the user
+3. Also show a description of each section:
+   - **Phase**: Current phase number and name from STATE.md
+   - **Plan**: Plan progress (N of M)
+   - **Status**: Phase status keyword (planning, building, built, etc.)
+   - **Git**: Current branch + dirty indicator
+   - **Context**: Unicode bar showing context window usage (green/yellow/red)
+
+---
+
+## Edge Cases
+
+### No .planning/ directory
+The status line works even without `.planning/` — it will show only git and context sections. Installation doesn't require a PBR project.
+
+### Plugin installed from npm vs local
+The script path differs between `~/.claude/plugins/cache/plan-build-run/pbr/{version}/scripts/status-line.js` and a local `plugins/pbr/scripts/status-line.js`. The install command must resolve the actual path at install time.
+
+### Existing non-PBR status line
+If `statusLine` already exists with a different command, warn the user and confirm before replacing.

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

@@ -0,0 +1,212 @@
+---
+name: test
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "<phase-number>"
+---
+
+**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 ~7,600 tokens. Begin executing Step 1 immediately.**
+
+# /pbr:test — Post-Phase Test Generation
+
+You are the orchestrator for `/pbr:test`. This skill generates tests for code that was built WITHOUT TDD mode. It targets key files from completed phases and creates meaningful test coverage.
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Delegate** all test writing to executor subagents — never write test code in the main context
+- Read only SUMMARY.md frontmatter for `key_files` lists — do not read full summaries
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► GENERATING TESTS FOR PHASE {N}             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
+
+## Prerequisites
+
+- `.planning/config.json` exists
+- Phase has been built: SUMMARY.md files exist in `.planning/phases/{NN}-{slug}/`
+- Phase should NOT already have TDD coverage (check if `features.tdd_mode` is false in config — if TDD mode is enabled, warn user that tests should already exist and ask to proceed anyway)
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
+
+| Argument | Meaning |
+|----------|---------|
+| `3` | Generate tests for phase 3 |
+| (no number) | Use current phase from STATE.md |
+
+---
+
+## Step 1 — Gather Context
+
+**CRITICAL: Run init command to load project state efficiently.**
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs" init execute-phase {phase_number}
+```
+
+This returns STATE.md snapshot, phase plans, ROADMAP excerpt, and config — all in one call.
+
+## Step 2 — Detect Test Framework
+
+Scan the project root for test framework indicators:
+
+1. Check `package.json` for `jest`, `vitest`, `mocha`, `ava` in devDependencies
+2. Check for `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` (with `[tool:pytest]`)
+3. Check for `jest.config.*`, `vitest.config.*`, `.mocharc.*`
+4. Check for existing test directories: `tests/`, `test/`, `__tests__/`, `spec/`
+5. Check for existing test file patterns: `*.test.*`, `*.spec.*`, `test_*.py`
+
+If no test framework is detected, ask the user:
+
+Use AskUserQuestion:
+  question: "No test framework detected. Which should I use?"
+  header: "Framework"
+  options:
+    - label: "Jest"      description: "JavaScript/TypeScript testing (most common)"
+    - label: "Vitest"    description: "Vite-native testing (faster, ESM-friendly)"
+    - label: "pytest"    description: "Python testing framework"
+  multiSelect: false
+
+## Step 3 — Collect Target Files
+
+Read SUMMARY.md frontmatter from each plan in the phase to extract `key_files`:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/pbr-tools.cjs" frontmatter .planning/phases/{NN}-{slug}/SUMMARY.md
+```
+
+Collect all `key_files` across all plans in the phase. Filter to only source files (exclude config, docs, assets). Group by:
+- **High priority**: Files with business logic, API endpoints, data models
+- **Medium priority**: Utility functions, helpers, middleware
+- **Low priority**: Config, types-only files, constants
+
+Present the file list to the user:
+
+Use AskUserQuestion:
+  question: "Found {N} source files from phase {P}. Generate tests for which?"
+  header: "Scope"
+  options:
+    - label: "High priority only"  description: "{X} files — business logic, APIs, models"
+    - label: "High + Medium"       description: "{Y} files — adds utilities and helpers"
+    - label: "All files"           description: "{Z} files — comprehensive coverage"
+  multiSelect: false
+
+## Step 4 — Generate Test Plans
+
+For each target file, create a lightweight test plan (NOT a full PBR PLAN.md — just a task list):
+
+```
+File: src/auth/login.js
+Tests to generate:
+  - Happy path: valid credentials return token
+  - Error: invalid password returns 401
+  - Error: missing email returns 400
+  - Edge: expired session handling
+Framework: jest
+Output: tests/auth/login.test.js
+```
+
+## Step 5 — Spawn Executor Agents
+
+**CRITICAL: Delegate ALL test writing to subagents. Do NOT write test code in the main context.**
+
+For each target file (or batch of related files), spawn an executor agent:
+
+```
+Spawn subagent_type: "pbr:executor"
+
+Task: Generate tests for the following file(s):
+
+<files_to_test>
+{file_path}: {brief description from SUMMARY}
+</files_to_test>
+
+<test_framework>
+{detected framework name and version}
+Existing test directory: {path}
+Test file naming: {pattern, e.g., *.test.js}
+</test_framework>
+
+<test_plan>
+{test plan from Step 4}
+</test_plan>
+
+Instructions:
+1. Read each source file to understand the implementation
+2. Write test files following the project's existing test patterns
+3. Each test file should cover: happy path, error cases, edge cases
+4. Use the project's existing mocking patterns if any exist
+5. Run the tests to verify they pass: {test command}
+6. Commit with format: test({phase}-tests): add tests for {file}
+```
+
+Spawn up to `parallelization.max_concurrent_agents` agents in parallel for independent files.
+
+## Step 6 — Verify and Report
+
+After all agents complete, check results:
+
+1. Glob for new test files created in this session
+2. Run the test suite to verify all new tests pass:
+   ```bash
+   {test_command}
+   ```
+3. Count: files tested, tests written, tests passing
+
+Display completion:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TESTS GENERATED ✓                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Phase {N}: {X} test files created, {Y} tests passing
+
+Files tested:
+  - src/auth/login.js → tests/auth/login.test.js (8 tests)
+  - src/api/users.js → tests/api/users.test.js (12 tests)
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Run coverage check** to see how much is covered
+
+`npm test -- --coverage`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:verify-work {N}` — verify the full phase
+- `/pbr:continue` — execute next logical step
+
+
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** write test code in the main orchestrator context — always delegate to executor agents
+2. **DO NOT** generate tests for files not listed in SUMMARY.md key_files — stay scoped to the phase
+3. **DO NOT** skip running the tests — always verify they pass before reporting success
+4. **DO NOT** generate trivial tests (testing getters/setters, testing constants) — focus on behavior
+5. **DO NOT** read full source files in the orchestrator — let the executor agents read them

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

@@ -0,0 +1,301 @@
+---
+name: todo
+description: "File-based persistent todos. Add, list, complete — survives sessions."
+allowed-tools: Read, Write, Bash, Glob, Grep, Skill, AskUserQuestion
+argument-hint: "add <description> | list [theme] | done <NNN> | work <NNN>"
+---
+
+**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 ~7,600 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO                                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:todo — Persistent File-Based Todos
+
+## Why File-Based
+
+Native Claude Code Tasks are session-scoped — they vanish when the conversation ends. Plan-Build-Run todos are individual `.md` files in `.planning/todos/` that persist across sessions, context resets, and compactions.
+
+## STATE.md Validation
+
+Before any operation that requires project state (any operation except `--global`), check:
+
+If `.planning/STATE.md` does not exist and the operation requires it, display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No project state found.
+
+**To fix:** Run `/pbr:new-project` first, or use `--global` for project-independent todos.
+```
+
+Stop execution.
+
+## Subcommands
+
+Parse `$ARGUMENTS` to determine the subcommand:
+
+### `add <description>`
+
+1. Ensure `.planning/todos/pending/` directory exists
+2. Generate NNN: scan **both** `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, then increment by 1 (zero-padded to 3 digits)
+3. Generate slug: take the first ~4 meaningful words from the description, lowercase, hyphen-separated (e.g., "Add rate limiting to login" → `add-rate-limiting-login`)
+4. Infer theme from description (e.g., "auth" → security, "test" → testing, "UI" → frontend, "refactor" → quality)
+5. Check for duplicates — read existing pending todos, if a similar one exists, ask user via AskUserQuestion
+6. Create `.planning/todos/pending/{NNN}-{slug}.md`:
+
+```yaml
+---
+title: "{description}"
+status: pending
+priority: P2
+source: conversation
+created: {YYYY-MM-DD}
+theme: {inferred-theme}
+---
+
+## Goal
+
+{description expanded into a clear goal statement}
+
+## Scope
+
+{any relevant context from the current conversation, or bullet points of what's in/out of scope}
+
+## Acceptance Criteria
+
+- [ ] {primary acceptance criterion derived from description}
+```
+
+7. Update STATE.md Pending Todos section
+
+   If the Write fails, display:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  ERROR                                                       ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Failed to write todo file.
+
+   **To fix:** Check that `.planning/todos/pending/` exists and is writable.
+   ```
+
+8. Confirm with branded output:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO ADDED ✓                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Todo {NNN}:** {description}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Work on it now** or see your task list
+
+`/pbr:quick`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:check-todos` — see all pending todos
+- `/pbr:progress` — see project status
+
+
+```
+
+### `list [theme]`
+
+1. Read all files in `.planning/todos/pending/`
+2. Parse frontmatter from each
+3. If theme filter provided, filter by theme
+4. Display as table:
+
+```
+Pending Todos:
+| # | Title | Priority | Theme | Created |
+|---|-------|----------|-------|---------|
+| 074 | Status-line customization options | P2 | capability | 2026-02-10 |
+| 075 | Add WebSearch/WebFetch/Context7 to researcher | P2 | capability | 2026-02-10 |
+```
+
+5. Offer actions with branded routing:
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Pick a todo** — mark one done or start working
+
+`/pbr:todo work <NNN>` — start working on a todo
+`/pbr:todo done <NNN>` — mark a todo as complete
+
+
+
+**Also available:**
+- `/pbr:progress` — see project status
+
+
+```
+
+### `done <NNN>`
+
+1. Find `.planning/todos/pending/{NNN}-*.md` (match by number prefix)
+2. If not found, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Todo {NNN} not found in pending todos.
+
+**To fix:** Run `/pbr:check-todos` to see available numbers.
+```
+3. Ensure `.planning/todos/done/` directory exists (create if needed)
+4. Read the pending file content
+5. Update frontmatter in the content: set `status: done` and add `completed: {YYYY-MM-DD}`
+
+**CRITICAL: Write to done/ FIRST, verify it exists, THEN delete from pending/. Do NOT delete pending before confirming done/ write succeeded.**
+
+6. Write the updated content to `.planning/todos/done/{NNN}-{slug}.md`
+7. Verify the done/ file was written successfully: check that `.planning/todos/done/{NNN}-{slug}.md` exists and has content (use `ls` or Glob)
+   - If the done/ write failed, abort and display:
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     Failed to write to done/. Pending file preserved.
+
+     **To fix:** Check that `.planning/todos/done/` exists and is writable.
+     ```
+     Do NOT proceed to delete the pending file.
+8. Only THEN delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
+8. Update STATE.md
+9. Confirm with branded output:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO COMPLETED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Todo {NNN}:** {title}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**See remaining tasks**
+
+`/pbr:check-todos`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:progress` — see project status
+
+
+```
+
+### `work <NNN>`
+
+1. Find `.planning/todos/pending/{NNN}-*.md` (match by number prefix)
+2. If not found, display the same error block as `done` — suggest `/pbr:check-todos`
+3. Read the todo file content (frontmatter + body)
+4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
+
+5. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan-phase` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan-phase) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Todo {NNN}:** {title}
+**Routing to:** /pbr:{chosen-skill}
+```
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
+
+```
+{title}
+
+Context from todo {NNN}:
+{body content — Goal, Scope, Acceptance Criteria sections}
+```
+
+For `/pbr:plan-phase`, if no phase exists for this work yet, suggest the user run `/pbr:plan-phase add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill completes, remind the user:
+
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Mark this todo as done if the work is complete**
+
+`/pbr:todo done {NNN}`
+
+
+```
+
+### No arguments
+
+Show a brief summary: count of pending todos, grouped by theme, plus usage hint.
+
+## State Integration
+
+After any todo operation, update the "Pending Todos" section of STATE.md with the current count and list.
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config, commit todo changes:
+- `docs(planning): add todo {NNN}`
+- `docs(planning): complete todo {NNN}`