@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/workflows/verify-work.md

@@ -0,0 +1,465 @@
+<purpose>
+Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /pbr:plan-phase --gaps.
+
+User tests, Claude records. One test at a time. Plain text responses.
+</purpose>
+
+<philosophy>
+**Show expected, ask if reality matches.**
+
+Claude presents what SHOULD happen. User confirms or describes what's different.
+- "yes" / "y" / "next" / empty → pass
+- Anything else → logged as issue, severity inferred
+
+No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
+</philosophy>
+
+<template>
+@~/.claude/plan-build-run/templates/UAT.md
+</template>
+
+<process>
+
+<step name="initialize" priority="first">
+If $ARGUMENTS contains a phase number, load context:
+
+```bash
+INIT=$(node ~/.claude/plan-build-run/bin/pbr-tools.js init verify-work "${PHASE_ARG}")
+```
+
+Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
+</step>
+
+<step name="check_active_session">
+**First: Check for active UAT sessions**
+
+```bash
+find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
+```
+
+**If active sessions exist AND no $ARGUMENTS provided:**
+
+Read each file's frontmatter (status, phase) and Current Test section.
+
+Display inline:
+
+```
+## Active UAT Sessions
+
+| # | Phase | Status | Current Test | Progress |
+|---|-------|--------|--------------|----------|
+| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
+| 2 | 05-auth | testing | 1. Login Form | 0/4 |
+
+Reply with a number to resume, or provide a phase number to start new.
+```
+
+Wait for user response.
+
+- If user replies with number (1, 2) → Load that file, go to `resume_from_file`
+- If user replies with phase number → Treat as new session, go to `create_uat_file`
+
+**If active sessions exist AND $ARGUMENTS provided:**
+
+Check if session exists for that phase. If yes, offer to resume or restart.
+If no, continue to `create_uat_file`.
+
+**If no active sessions AND no $ARGUMENTS:**
+
+```
+No active UAT sessions.
+
+Provide a phase number to start testing (e.g., /pbr:verify-work 4)
+```
+
+**If no active sessions AND $ARGUMENTS provided:**
+
+Continue to `create_uat_file`.
+</step>
+
+<step name="find_summaries">
+**Find what to test:**
+
+Use `phase_dir` from init (or run init if not already done).
+
+```bash
+ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
+```
+
+Read each SUMMARY.md to extract testable deliverables.
+</step>
+
+<step name="extract_tests">
+**Extract testable deliverables from SUMMARY.md:**
+
+Parse for:
+1. **Accomplishments** - Features/functionality added
+2. **User-facing changes** - UI, workflows, interactions
+
+Focus on USER-OBSERVABLE outcomes, not implementation details.
+
+For each deliverable, create a test:
+- name: Brief test name
+- expected: What the user should see/experience (specific, observable)
+
+Examples:
+- Accomplishment: "Added comment threading with infinite nesting"
+  → Test: "Reply to a Comment"
+  → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
+
+Skip internal/non-observable items (refactors, type changes, etc.).
+</step>
+
+<step name="create_uat_file">
+**Create UAT file with all tests:**
+
+```bash
+mkdir -p "$PHASE_DIR"
+```
+
+Build test list from extracted deliverables.
+
+Create file:
+
+```markdown
+---
+status: testing
+phase: XX-name
+source: [list of SUMMARY.md files]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: 1
+name: [first test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: [pending]
+
+...
+
+## Summary
+
+total: [N]
+passed: 0
+issues: 0
+pending: [N]
+skipped: 0
+
+## Gaps
+
+[none yet]
+```
+
+Write to `.planning/phases/XX-name/{phase}-UAT.md`
+
+Proceed to `present_test`.
+</step>
+
+<step name="present_test">
+**Present current test to user:**
+
+Read Current Test section from UAT file.
+
+Display using checkpoint box format:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Verification Required                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Test {number}: {name}**
+
+{expected}
+
+──────────────────────────────────────────────────────────────
+→ Type "pass" or describe what's wrong
+──────────────────────────────────────────────────────────────
+```
+
+Wait for user response (plain text, no AskUserQuestion).
+</step>
+
+<step name="process_response">
+**Process user response and update file:**
+
+**If response indicates pass:**
+- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓"
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: pass
+```
+
+**If response indicates skip:**
+- "skip", "can't test", "n/a"
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: skipped
+reason: [user's reason if provided]
+```
+
+**If response is anything else:**
+- Treat as issue description
+
+Infer severity from description:
+- Contains: crash, error, exception, fails, broken, unusable → blocker
+- Contains: doesn't work, wrong, missing, can't → major
+- Contains: slow, weird, off, minor, small → minor
+- Contains: color, font, spacing, alignment, visual → cosmetic
+- Default if unclear: major
+
+Update Tests section:
+```
+### {N}. {name}
+expected: {expected}
+result: issue
+reported: "{verbatim user response}"
+severity: {inferred}
+```
+
+Append to Gaps section (structured YAML for plan-phase --gaps):
+```yaml
+- truth: "{expected behavior from test}"
+  status: failed
+  reason: "User reported: {verbatim user response}"
+  severity: {inferred}
+  test: {N}
+  artifacts: []  # Filled by diagnosis
+  missing: []    # Filled by diagnosis
+```
+
+**After any response:**
+
+Update Summary counts.
+Update frontmatter.updated timestamp.
+
+If more tests remain → Update Current Test, go to `present_test`
+If no more tests → Go to `complete_session`
+</step>
+
+<step name="resume_from_file">
+**Resume testing from UAT file:**
+
+Read the full UAT file.
+
+Find first test with `result: [pending]`.
+
+Announce:
+```
+Resuming: Phase {phase} UAT
+Progress: {passed + issues + skipped}/{total}
+Issues found so far: {issues count}
+
+Continuing from Test {N}...
+```
+
+Update Current Test section with the pending test.
+Proceed to `present_test`.
+</step>
+
+<step name="complete_session">
+**Complete testing and commit:**
+
+Update frontmatter:
+- status: complete
+- updated: [now]
+
+Clear Current Test section:
+```
+## Current Test
+
+[testing complete]
+```
+
+Commit the UAT file:
+```bash
+node ~/.claude/plan-build-run/bin/pbr-tools.js commit "test({phase}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase}-UAT.md"
+```
+
+Present summary:
+```
+## UAT Complete: Phase {phase}
+
+| Result | Count |
+|--------|-------|
+| Passed | {N}   |
+| Issues | {N}   |
+| Skipped| {N}   |
+
+[If issues > 0:]
+### Issues Found
+
+[List from Issues section]
+```
+
+**If issues > 0:** Proceed to `diagnose_issues`
+
+**If issues == 0:**
+```
+All tests passed. Ready to continue.
+
+- `/pbr:plan-phase {next}` — Plan next phase
+- `/pbr:execute-phase {next}` — Execute next phase
+```
+</step>
+
+<step name="diagnose_issues">
+**Diagnose root causes before planning fixes:**
+
+```
+---
+
+{N} issues found. Diagnosing root causes...
+
+Spawning parallel debug agents to investigate each issue.
+```
+
+- Load diagnose-issues workflow
+- Follow @~/.claude/plan-build-run/workflows/diagnose-issues.md
+- Spawn parallel debug agents for each issue
+- Collect root causes
+- Update UAT.md with root causes (set frontmatter status to `diagnosed`)
+- Proceed to `present_gap_closure_next`
+
+Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
+</step>
+
+<step name="present_gap_closure_next">
+**Defer gap planning to a fresh context window.**
+
+Do NOT spawn planners or checkers inline — by this point in the session, context is heavily used from UAT testing and diagnosis. Gap planning needs fresh context for quality results.
+
+Commit the diagnosed UAT file:
+
+```bash
+node ~/.claude/plan-build-run/bin/pbr-tools.js commit "test({phase}): diagnose UAT gaps - {issues} issues found" --files ".planning/phases/XX-name/{phase}-UAT.md"
+```
+
+Present:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PBR ► GAPS DIAGNOSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {Name}** — {N} issue(s) diagnosed
+
+| # | Issue | Severity | Root Cause |
+|---|-------|----------|------------|
+| 1 | {truth 1} | {severity} | {root_cause} |
+| 2 | {truth 2} | {severity} | {root_cause} |
+
+Diagnoses saved to: {phase}-UAT.md
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan fixes** — create gap closure plans from diagnoses
+
+`/pbr:plan-phase {phase} --gaps`
+
+<sub>`/clear` first → fresh context window for quality planning</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:execute-phase {phase} --gaps-only` — if fix plans already exist
+- Re-run `/pbr:verify-work {phase}` — test additional scenarios
+
+───────────────────────────────────────────────────────────────
+```
+
+**STOP HERE.** Do not spawn planners or checkers. The user will `/clear` and run `/pbr:plan-phase --gaps` in a fresh context where the planner gets full context budget for quality gap closure plans.
+</step>
+
+</process>
+
+<update_rules>
+**Batched writes for efficiency:**
+
+Keep results in memory. Write to file only when:
+1. **Issue found** — Preserve the problem immediately
+2. **Session complete** — Final write before commit
+3. **Checkpoint** — Every 5 passed tests (safety net)
+
+| Section | Rule | When Written |
+|---------|------|--------------|
+| Frontmatter.status | OVERWRITE | Start, complete |
+| Frontmatter.updated | OVERWRITE | On any file write |
+| Current Test | OVERWRITE | On any file write |
+| Tests.{N}.result | OVERWRITE | On any file write |
+| Summary | OVERWRITE | On any file write |
+| Gaps | APPEND | When issue found |
+
+On context reset: File shows last checkpoint. Resume from there.
+</update_rules>
+
+<severity_inference>
+**Infer severity from user's natural language:**
+
+| User says | Infer |
+|-----------|-------|
+| "crashes", "error", "exception", "fails completely" | blocker |
+| "doesn't work", "nothing happens", "wrong behavior" | major |
+| "works but...", "slow", "weird", "minor issue" | minor |
+| "color", "spacing", "alignment", "looks off" | cosmetic |
+
+Default to **major** if unclear. User can correct if needed.
+
+**Never ask "how severe is this?"** - just infer and move on.
+</severity_inference>
+
+<integration_health>
+## Integration Health Score
+
+After UAT testing completes, calculate integration health to quantify system quality:
+
+```bash
+SCORE=$(node ~/.claude/plan-build-run/bin/pbr-tools.js integration-score --raw)
+```
+
+The integration score uses the **5-state export model** (CONNECTED, IMPORTED_NOT_USED, ORPHANED, MISMATCHED, MISSING_EXPORT) to classify every export and calculates per-category scores for:
+- **Exports** -- percentage of exports in CONNECTED state
+- **API Coverage** -- percentage of routes with active consumers
+- **Auth Protection** -- percentage of sensitive routes with auth checks
+- **E2E Flows** -- percentage of user flows completing end-to-end
+
+Include the score in the UAT completion summary when a VERIFICATION.md exists.
+
+For CRUD entity verification, use the 10-step template:
+@~/.claude/plan-build-run/templates/crud-flow-verification.md
+</integration_health>
+
+<success_criteria>
+- [ ] UAT file created with all tests from SUMMARY.md
+- [ ] Tests presented one at a time with expected behavior
+- [ ] User responses processed as pass/issue/skip
+- [ ] Severity inferred from description (never asked)
+- [ ] Batched writes: on issue, every 5 passes, or completion
+- [ ] Committed on completion
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: UAT.md committed with diagnoses (status: diagnosed)
+- [ ] If issues: user directed to `/pbr:plan-phase --gaps` in fresh context
+- [ ] Integration health score calculated when VERIFICATION.md available
+- [ ] Ready for next step when complete
+</success_criteria>

package/plugins/codex-pbr/.codex/config.toml

@@ -0,0 +1,101 @@
+# PBR Workflow Configuration for Codex CLI
+# Copy this file to your project's .codex/config.toml and customize as needed.
+#
+# Each [profiles.*] section defines a named agent profile that can be selected
+# when Codex runs PBR skills. Uncomment and adjust the fields you want to change.
+#
+# Reference: https://github.com/openai/codex
+
+# ---------------------------------------------------------------------------
+# Sandbox Settings
+# ---------------------------------------------------------------------------
+# Controls which shell commands Codex is allowed to run during builds.
+# Adjust based on your project's build toolchain.
+
+[sandbox]
+# allow = ["bash", "git", "npm", "node", "python", "pip", "cargo", "make"]
+# deny  = ["curl", "wget", "ssh"]
+
+# ---------------------------------------------------------------------------
+# PBR Agent Profiles
+# ---------------------------------------------------------------------------
+# Each profile corresponds to a PBR agent role. Codex selects the appropriate
+# profile based on the active skill. You can override model and instructions
+# per role to tune cost/quality tradeoffs.
+
+# Research agent — explores domain, reads docs, summarizes findings.
+# Called by: $pbr-explore, $pbr-begin, $pbr-plan (research phase)
+[profiles.pbr-researcher]
+# description = "Research agent: investigates domain and summarizes findings"
+# model = "o4-mini"
+# instructions = "Focus on gathering factual information. Cite sources."
+
+# Planner agent — creates detailed, task-level phase plans.
+# Called by: $pbr-plan, $pbr-begin
+[profiles.pbr-planner]
+# description = "Planner agent: produces structured PLAN.md files"
+# model = "o3"
+# instructions = "Output valid PLAN.md frontmatter. Define must_haves precisely."
+
+# Executor agent — implements tasks from a PLAN.md, commits each task.
+# Called by: $pbr-build
+[profiles.pbr-executor]
+# description = "Executor agent: implements plan tasks with atomic commits"
+# model = "o4-mini"
+# instructions = "One task per commit. Follow the plan exactly. No scope creep."
+
+# Verifier agent — checks build output against plan must_haves.
+# Called by: $pbr-review
+[profiles.pbr-verifier]
+# description = "Verifier agent: produces VERIFICATION.md with evidence"
+# model = "o4-mini"
+# instructions = "Check evidence in the codebase. Do not assume correctness."
+
+# Integration checker agent — validates cross-component integration.
+# Called by: $pbr-health, $pbr-scan
+[profiles.pbr-integration-checker]
+# description = "Integration checker: validates cross-component contracts"
+# model = "o4-mini"
+# instructions = "Focus on interface boundaries and data flow between modules."
+
+# Debugger agent — hypothesis-driven bug investigation.
+# Called by: $pbr-debug
+[profiles.pbr-debugger]
+# description = "Debugger agent: systematic hypothesis-driven investigation"
+# model = "o3"
+# instructions = "Form falsifiable hypotheses. Test each before moving on."
+
+# Codebase mapper agent — creates ARCHITECTURE.md and related codebase docs.
+# Called by: $pbr-explore, $pbr-begin
+[profiles.pbr-mapper]
+# description = "Mapper agent: documents codebase structure and architecture"
+# model = "o4-mini"
+# instructions = "Be concise. Focus on structure over implementation details."
+
+# Synthesizer agent — aggregates research and produces structured summaries.
+# Called by: $pbr-explore, $pbr-discuss
+[profiles.pbr-synthesizer]
+# description = "Synthesizer agent: aggregates findings into structured output"
+# model = "o4-mini"
+# instructions = "Extract key insights. Surface tensions and open questions."
+
+# General agent — handles ad-hoc tasks and one-off instructions.
+# Called by: $pbr-do, $pbr-discuss
+[profiles.pbr-general]
+# description = "General agent: flexible agent for miscellaneous PBR tasks"
+# model = "o4-mini"
+# instructions = "Follow PBR workflow rules. Commit with correct format."
+
+# Audit agent — analyzes session logs for workflow compliance.
+# Called by: $pbr-audit
+[profiles.pbr-audit]
+# description = "Audit agent: reviews session logs and produces compliance reports"
+# model = "o4-mini"
+# instructions = "Be objective. Report findings without judgment."
+
+# Dev-sync agent — synchronizes changes across plugin derivatives.
+# Called internally — not a user-facing skill.
+[profiles.pbr-dev-sync]
+# description = "Dev-sync agent: propagates pbr/ changes to cursor-pbr/ and codex-pbr/"
+# model = "o4-mini"
+# instructions = "Apply diffs exactly. Do not add scope beyond the sync target."