@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/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}/scripts/pbr-tools.js" 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}/scripts/pbr-tools.js" 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/plugins/pbr/skills/todo/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: todo
 description: "File-based persistent todos. Add, list, complete — survives sessions."
-allowed-tools: Read, Write, Bash, Glob, Grep
-argument-hint: "add <description> | list [theme] | done <NNN>"
+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.**
@@ -12,9 +12,9 @@ argument-hint: "add <description> | list [theme] | done <NNN>"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO                                       ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -76,15 +76,17 @@ theme: {inferred-theme}
 
 8. Confirm with branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO ADDED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO ADDED ✓                               ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {description}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Work on it now** or see your task list
 
@@ -92,13 +94,13 @@ theme: {inferred-theme}
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
-- `/pbr:todo list` — see all pending todos
-- `/pbr:status` — see project status
+- `/pbr:check-todos` — see all pending todos
+- `/pbr:progress` — see project status
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ### `list [theme]`
@@ -118,21 +120,23 @@ Pending Todos:
 
 5. Offer actions with branded routing:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Pick a todo** — mark one done or start working
 
-`/pbr:todo done <NNN>`
+`/pbr:todo work <NNN>` — start working on a todo
+`/pbr:todo done <NNN>` — mark a todo as complete
+
 
-───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `/pbr:quick` — work on one now
-- `/pbr:status` — see project status
+- `/pbr:progress` — see project status
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ### `done <NNN>`
@@ -146,39 +150,120 @@ Pending Todos:
 
 Todo {NNN} not found in pending todos.
 
-**To fix:** Run `/pbr:todo list` to see available numbers.
+**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. Delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
+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 ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO COMPLETED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {title}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **See remaining tasks**
 
-`/pbr:todo list`
+`/pbr:check-todos`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:status` — see project status
+- `/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

package/plugins/pbr/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

package/plugins/pbr/templates/CONTEXT.md.tmpl

@@ -1,7 +1,7 @@
 # CONTEXT.md Template
 
 > Referenced by: begin skill (Step 9c), discuss skill, plan skill
-> Created during /pbr:begin. Updated by /pbr:discuss and /pbr:plan --assumptions.
+> Created during /pbr:new-project. Updated by /pbr:discuss-phase and /pbr:plan-phase --assumptions.
 
 ## Structure