@sienklogic/plan-build-run 2.54.0 → 2.55.0

package/plugins/codex-pbr/skills/test/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: test
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+---
+
+**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 agents — 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 "${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 "${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 agents. 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-review {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/codex-pbr/skills/todo/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: todo
+description: "File-based persistent todos. Add, list, complete — survives sessions."
+---
+
+**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.
+
+## 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-todo list` — see all pending todos
+- `$pbr-status` — 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-status` — 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-todo list` 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-todo list`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `$pbr-continue` — execute next logical step
+- `$pbr-status` — 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-todo list`
+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` (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) — 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`, if no phase exists for this work yet, suggest the user run `$pbr-plan 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}`

package/plugins/codex-pbr/skills/undo/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: undo
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+---
+
+**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
+
+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):
+
+[55-02] Phase 55, Plan 02
+  abc1234  feat(55-02): add undo skill
+  def5678  chore(55-02): register undo command
+
+[quick-003]
+  ghi9012  fix(quick-003): fix hook path resolution
+
+[planning]
+  jkl3456  docs(planning): update roadmap phase 55
+```
+
+For phase-plan scopes (NN-MM pattern), add a "Phase NN, Plan MM" annotation. For other scopes, show just the scope label.
+
+---
+
+## 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 4 — Confirm Selection
+
+Display the commits that will be reverted:
+
+```
+The following commits will be reverted (using git revert, NOT git reset):
+
+  abc1234  feat(55-02): add undo skill
+  def5678  chore(55-02): 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., `55-02`)
+- 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-status — 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