@sienklogic/plan-build-run 2.59.0 → 2.61.0

package/plugins/copilot-pbr/templates/REQUIREMENTS.md.tmpl

@@ -0,0 +1,52 @@
+# Requirements
+
+> Living document. Generated by `/pbr:begin`, updated via `/pbr:discuss`.
+> All requirements flow from here into plans via `implements:[]` in PLAN.md frontmatter.
+
+## Functional Requirements
+
+Capabilities the system must provide from the user's perspective.
+
+### {Category} (e.g., Authentication, API, UI)
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-001 | {User-centric, testable statement of capability} | Must | Open |
+| REQ-F-002 | {User-centric, testable statement of capability} | Should | Open |
+
+### {Category 2}
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-010 | {User-centric, testable statement of capability} | Must | Open |
+
+## Non-Functional Requirements
+
+Quality attributes and constraints the system must satisfy.
+
+| ID | Requirement | Category | Priority |
+|----|-------------|----------|----------|
+| REQ-NF-001 | {Observable quality statement — e.g., "Page loads in <2s on 4G"} | Performance | Must |
+| REQ-NF-002 | {Observable quality statement} | Security | Must |
+| REQ-NF-003 | {Observable quality statement} | Reliability | Should |
+
+## Deferred Requirements (v2+)
+
+Requirements explicitly out of scope for v1.
+
+| ID | Requirement | Deferred Reason |
+|----|-------------|----------------|
+| REQ-F-099 | {requirement} | {reason — e.g., "Phase 2 priority"} |
+
+## Out of Scope
+
+Features explicitly excluded. These must NOT appear in any plan.
+
+- {Feature}: {brief rationale}
+
+## Traceability
+
+| REQ-ID | Implemented In | Verified In |
+|--------|---------------|------------|
+| REQ-F-001 | Phase 01 PLAN-01 | Phase 01 VERIFICATION.md |
+| REQ-F-002 | — | — |

package/plugins/copilot-pbr/templates/VERIFICATION-DETAIL.md.tmpl

@@ -23,6 +23,11 @@ anti_patterns:
   console_logs: {count}
   skipped_tests: {count}
   hardcoded_secrets: {count}
+# populated by verifier from implements:[] in plan frontmatter
+satisfied:
+  - "REQ-F-001"    # REQ-IDs confirmed verified in this phase
+unsatisfied:
+  - "REQ-F-002"    # REQ-IDs that failed verification
 ---
 
 # Phase Verification: {phase_name}

package/plugins/copilot-pbr/templates/project-CONTEXT.md.tmpl

@@ -0,0 +1,43 @@
+# Project Context
+
+> Cross-cutting decisions that ALL phases must honor.
+> Updated via `/pbr:discuss --project`. Auto-synced to CLAUDE.md on write.
+> Phase-level CONTEXT.md (in phase directories) overrides project-level for that phase.
+>
+> PLANNER NOTE: Embed each locked decision directly into the relevant task's action block.
+> Executors NEVER read this file — PLAN.md is self-contained.
+
+## Locked Decisions
+
+Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE across ALL phases.
+The planner embeds these into PLAN.md task actions. Executors never read this file directly.
+
+| Decision | Rationale | Locked By |
+|----------|-----------|-----------|
+| {e.g., "Use TypeScript strict mode"} | {User preference, team skill} | User |
+| {e.g., "PostgreSQL via Supabase"} | {Existing infrastructure} | User |
+
+## User Constraints
+
+Budget, timeline, skill level, hosting, team size — factors that shape ALL planning decisions.
+
+- {e.g., "Solo developer, no team"}
+- {e.g., "Deploy to Hetzner VPS"}
+- {e.g., "Must work offline"}
+
+## Deferred Ideas
+
+Ideas explicitly moved to v2 or ruled out. Plans at ANY phase MUST NOT include these.
+
+| Idea | Reason Deferred |
+|------|----------------|
+| {feature} | {reason — e.g., "Post-launch priority"} |
+
+## Claude's Discretion Areas
+
+Areas where planners can make implementation choices without asking the user.
+Document the choice made and rationale when exercised.
+
+| Area | Choice Made | Rationale |
+|------|------------|-----------|
+| {e.g., "Logging library"} | {e.g., "pino"} | {e.g., "Lightweight, structured output"} |

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.59.0",
+  "version": "2.61.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/agents/executor.md

@@ -37,6 +37,9 @@ You are **executor**, the code execution agent for Plan-Build-Run. You receive v
    a. Read task XML
    b. Execute <action> steps
    c. Run <verify> commands
+      - If <verify> contains an <automated> child element, extract and run the command inside it
+      - If <verify> is plain text (no <automated> child), run it as before (backward compat)
+      - Both forms produce the same result — <automated> is machine-parseable, plain text is human-readable
    d. If verify passes: commit
    e. If verify fails: apply deviation rules
    f. If checkpoint: STOP and return
@@ -198,6 +201,11 @@ When a task has a checkpoint type, **STOP execution** and return a structured re
 | `decision` | Before executing | Decision needed, options, context |
 | `human-action` | Before executing | What user must do, step-by-step |
 
+**auto_checkpoints config**: After loading plan frontmatter, read `gates.auto_checkpoints` from config.json (default false):
+- Load with: `node pbr-tools.js config-get gates.auto_checkpoints`
+- When `auto_checkpoints` is true AND task type is `checkpoint:human-verify`: run the automated verify command. If it passes, auto-approve and continue. If it fails, still STOP and return the checkpoint response.
+- `checkpoint:decision` and `checkpoint:human-action` always require human input regardless of `auto_checkpoints`.
+
 **Automation-first**: Complete all automatable pre-work before any checkpoint. Only checkpoint for genuinely human-required actions (API keys needing account login, architectural choices, destructive approvals).
 
 All responses use: `CHECKPOINT: {TYPE}` header, task info, type-specific fields, completed tasks table, remaining tasks list.

package/plugins/cursor-pbr/agents/plan-checker.md

@@ -159,14 +159,16 @@ Plans declare `provides`/`consumes`; all consumed items must have providers.
 | Missing provides/consumes for exports | INFO |
 
 ### D9: Requirement Traceability
-Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+Plans declare `implements` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+
+> **Note:** `requirement_ids:` is a deprecated alias for `implements:` — treat as equivalent during transition.
 
 | Condition | Severity |
 |-----------|----------|
-| requirement_id references nonexistent requirement | BLOCKER |
+| implements: ID references nonexistent requirement | BLOCKER |
 | Requirement not covered by any plan | WARNING |
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
-| Plan missing requirement_ids entirely | INFO |
+| Plan missing implements: entirely | WARNING |
 
 ### D10: Test Plan Coverage
 Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.

package/plugins/cursor-pbr/agents/planner.md

@@ -11,7 +11,7 @@ you MUST Read every listed file BEFORE any other action.
 Skipping this causes hallucinated context and broken output.
 </files_to_read>
 
-> Default files: CONTEXT.md, ROADMAP.md, research documents, existing plan files
+> Default files: PROJECT.md (if exists), CONTEXT.md (project-level, if exists), phase CONTEXT.md (if exists), ROADMAP.md, research documents, existing plan files
 
 # Plan-Build-Run Planner
 
@@ -22,7 +22,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 
 ## Core Principle: Context Fidelity
 
-**Locked decisions from CONTEXT.md are NON-NEGOTIABLE.** You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
+**Locked decisions from BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) are NON-NEGOTIABLE.** Phase-level overrides project-level for the same decision area. You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
 
 **Deferred ideas from CONTEXT.md MUST NOT appear in plans.** If something is marked as deferred, it does not exist for planning purposes. Do not plan for it, do not create hooks for it, do not "prepare" for it.
 </role>
@@ -194,7 +194,13 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 <execution_flow>
 ## Planning Process
 
-1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+1. **Load Context**: Read locked decisions, phase goal, and any research documents.
+   - Read `.planning/PROJECT.md` (if exists) — project scope/out-of-scope constraints
+   - Read `.planning/CONTEXT.md` (project-level, if exists) — cross-cutting locked decisions
+   - Read `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level, if exists) — phase-specific decisions
+   - Phase-level CONTEXT.md overrides project-level for conflicting decision areas
+   - **For each locked decision found**: embed it directly into the relevant task's `<action>` block.
+     Executors NEVER read CONTEXT.md — PLAN.md task actions must be self-contained.
 
 ### Handling [NEEDS DECISION] Items
 When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
@@ -204,7 +210,7 @@ When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from th
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
-5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
+5. **Write Plan Files**: Complete YAML frontmatter (include `implements` field with REQ-IDs from REQUIREMENTS.md or ROADMAP.md for traceability; `requirement_ids` is a deprecated alias — use `implements` as the primary field), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
 
 **CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
@@ -242,7 +248,7 @@ When receiving checker feedback:
 
 ## Context Optimization
 
-**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in CONTEXT.md has a corresponding task, (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
+**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) has a corresponding task (deduplicate identical decisions across both files), (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
 
 **Frontmatter-First Assembly**: When prior plans exist, read SUMMARY.md frontmatter only (not full body) — 10 frontmatters ~500 tokens vs 10 full SUMMARYs ~5000 tokens. Extract: `provides`, `requires`, `key_files`, `key_decisions`, `patterns`. Only read full body when a specific detail is needed.
 
@@ -258,7 +264,7 @@ When receiving checker feedback:
 - [ ] Tasks grouped into plans by wave
 - [ ] PLAN files exist with XML task structure
 - [ ] Each plan: frontmatter complete (depends_on, files_modified, must_haves)
-- [ ] Each plan: requirement_ids field populated (MUST NOT be empty)
+- [ ] Each plan: implements: field populated (list REQ-IDs; use [] only if phase has no REQUIREMENTS.md)
 - [ ] Each task: all 5 elements (name, files, action, verify, done)
 - [ ] Wave structure maximizes parallelism
 - [ ] Every REQ-ID from ROADMAP/REQUIREMENTS appears in at least one plan
@@ -338,7 +344,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 11. DO NOT leave done conditions vague — they must be observable
 12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources
 13. DO NOT use Bash heredoc for file creation — ALWAYS use the Write tool
-14. DO NOT leave requirement_ids empty in PLAN frontmatter — every plan must trace to requirements
+14. DO NOT leave implements: empty in PLAN frontmatter — use implements: as the primary traceability field (requirement_ids: is deprecated)
 
 </anti_patterns>
 

package/plugins/cursor-pbr/agents/verifier.md

@@ -76,7 +76,8 @@ Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for
 - `artifacts`: Files/exports that must exist, be substantive, and not be stubs
 - `key_links`: Connections that must be wired between components
 
-If plans lack explicit must-haves, derive them goal-backward from ROADMAP.md: what must be TRUE → what must EXIST → what must be CONNECTED.
+Must-haves in plan frontmatter are canonical — use exactly what mustHavesCollect returns.
+Only fall back to goal-backward derivation from ROADMAP.md if ALL plans in the phase have completely empty must_haves sections. Do NOT supplement or re-derive when must_haves are present.
 
 Output: A numbered list of every must-have to verify.
 
@@ -161,6 +162,14 @@ Cross-reference all must-haves against verification results in a table:
 
 L4 column shows `-` when no automated verification is available. Only artifacts with test commands or build verification get L4 checks.
 
+### Step 7b: Write REQ-ID Traceability (Always)
+
+After verifying all must-haves, collect `implements:[]` from all plan frontmatters in the phase.
+
+- For each REQ-ID: if all must-haves for that plan passed → add to `satisfied:[]`
+- If any must-have for that plan failed → add to `unsatisfied:[]`
+- Write `satisfied:[]` and `unsatisfied:[]` to the VERIFICATION.md frontmatter
+
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
 
 Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.

package/plugins/cursor-pbr/hooks/hooks.json

@@ -98,6 +98,7 @@
         ]
       },
       {
+        "matcher": "Write|Edit|Bash|Task",
         "hooks": [
           {
             "type": "command",

package/plugins/cursor-pbr/references/plan-format.md

@@ -43,9 +43,9 @@ provides:
   - "requireAuth() middleware"
 consumes:
   - "Database connection (from plan 01-01)"
-requirement_ids:
-  - "P02-G1"
-  - "P02-G2"
+implements:
+  - "REQ-F-001"
+  - "REQ-F-002"
 closes_issues:
   - 42
   - 57
@@ -71,7 +71,8 @@ closes_issues:
 | `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
 | `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
 | `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
-| `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
+| `implements` | NO (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md this plan addresses. Primary traceability field. |
+| `requirement_ids` | NO | array | DEPRECATED — use `implements:` instead. Kept for backward compat. |
 | `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
 | `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
 | `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
@@ -162,14 +163,20 @@ The Summary section is generated by the planner agent at plan creation time. It
        DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
   </action>
   <verify>
-    npx tsc --noEmit
-    ls src/auth/discord.ts
-    ls src/auth/types.ts
+    <automated>
+      npx tsc --noEmit
+      ls src/auth/discord.ts
+      ls src/auth/types.ts
+    </automated>
   </verify>
   <done>Discord OAuth client module exists and compiles without errors</done>
 </task>
 ```
 
+> **Verify block forms**: The `<automated>` wrapper (Option A) is preferred — it enables machine-parsing
+> for `auto_checkpoints` mode. Plain-text verify commands without the wrapper (Option B) remain valid
+> for backward compatibility. Both forms are supported by the executor.
+
 ### TDD Task
 
 ```xml
@@ -204,6 +211,33 @@ The Summary section is generated by the planner agent at plan creation time. It
 </task>
 ```
 
+### Feature Task (TDD Variant)
+
+Feature tasks add a `<feature>` element for structured TDD planning. The element contains two required children:
+
+- **`<behavior>`** — the observable outcome from the user's perspective. Maps directly to a `must_haves.truths` entry.
+- **`<implementation>`** — the technical approach at a high level (which files, patterns, or algorithms to use).
+
+Prose structure (illustrative — not a live task block to avoid validator false-positives):
+
+```
+task id="02-01-T3" type="auto" tdd="true" complexity="medium"
+  name: Implement rate limiter for OAuth endpoint
+  files: src/middleware/rate-limit.ts / tests/middleware/rate-limit.test.ts
+  feature:
+    behavior: OAuth endpoint rejects more than 5 requests per minute per IP with HTTP 429
+    implementation: Token-bucket algorithm; Redis-backed counter with TTL; express-rate-limit wrapper
+  action:
+    RED: Write failing tests for 429 response at >5 req/min
+    GREEN: Implement token-bucket middleware using Redis
+    REFACTOR: Extract counter logic to RateLimitStore class
+  verify:
+    automated: npm test -- --grep "rate limiter"
+  done: Rate limiter rejects excessive OAuth requests with 429
+```
+
+The `<feature>` element is optional — standard TDD tasks without it are still valid. Use `<feature>` when the planner wants to record the behavior/implementation split explicitly for traceability.
+
 ### Checkpoint: Human Verify
 
 ```xml
@@ -291,9 +325,13 @@ Every task MUST have ALL 5. No exceptions.
 | `<name>` | What the task does | Imperative verb phrase. Short. |
 | `<files>` | Files touched | One per line. Actual file paths. |
 | `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
-| `<verify>` | How to check | Executable shell commands. Or checkpoint format. |
+| `<verify>` | How to check | Executable shell commands (plain-text or wrapped in `<automated>`). Or checkpoint format. |
 | `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
 
+> **Optional `<feature>` element**: Feature tasks (TDD variant) may add a `<feature>` element with
+> `<behavior>` and `<implementation>` children for structured TDD planning. The 5 standard elements
+> above are still required.
+
 ---
 
 ## Task ID Format

package/plugins/cursor-pbr/skills/begin/SKILL.md

@@ -546,11 +546,10 @@ For each category, present the features and ask the user to classify each:
 - **Out of scope** — Will NOT be built
 
 **7d. Assign REQ-IDs:**
-For each committed requirement, assign an ID in the format `{CATEGORY}-{NN}`:
-- `AUTH-01`: User can log in with Discord OAuth
-- `AUTH-02`: Protected routes redirect to login
-- `UI-01`: Dashboard shows player statistics
-- `UI-02`: Mobile-responsive layout
+For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:
+- Functional requirements: `REQ-F-xxx` numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)
+- Non-functional requirements: `REQ-NF-xxx` numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)
+- Examples: `REQ-F-001: User can log in with Discord OAuth`, `REQ-NF-001: Page loads in <2s on 4G`
 
 Each requirement must be:
 - **User-centric** — describes a capability from the user's perspective
@@ -663,28 +662,13 @@ Write the project state files from templates:
 **CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.**
 
 **9c. Write CONTEXT.md:**
-Create `.planning/CONTEXT.md` from information gathered during questioning:
-
-```markdown
-# Project Context
-
-## Locked Decisions
-{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
-
-| Decision | Rationale | Locked By |
-|----------|-----------|-----------|
-| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
-
-## User Constraints
-{Budget, timeline, skill level, hosting, team size}
-
-## Deferred Ideas
-{Features explicitly moved to v2 or out-of-scope}
-
-| Idea | Reason Deferred |
-|------|----------------|
-| {feature} | {reason} |
-```
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from the questioning conversation:
+   - Locked Decisions: all technology choices and architecture decisions from Step 2
+   - User Constraints: budget, timeline, skill level, hosting, team
+   - Deferred Ideas: out-of-scope items identified in Step 7c scoping
+   - Claude's Discretion: any areas where user said "you decide"
+3. Write to `.planning/CONTEXT.md`
 
 **CRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.**
 

package/plugins/cursor-pbr/skills/discuss/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: discuss
 description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> | --project"
 ---
 
 **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.**
@@ -36,9 +36,12 @@ This skill runs **inline** (no Task delegation).
 
 ### Step 1: Parse Phase Number and Check for Existing Plans
 
-Parse `$ARGUMENTS` to get the phase number.
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
 
-**Validation:**
+**Validation (PHASE mode):**
 - Must be a valid phase number (integer or decimal like `3.1`)
 - If no argument provided, read STATE.md to get the current phase
 - If no current phase and no argument: "Which phase do you want to discuss? Run `/pbr:status` to see available phases."
@@ -64,6 +67,53 @@ Phase {N} not found.
    - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `/pbr:plan {N}` after."
    - This is a **warning only** — do not block the discussion
 
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/CONTEXT.md` (project-level), NOT a phase directory.
+
+**Check for existing project CONTEXT.md:**
+1. Use Glob to check if `.planning/CONTEXT.md` exists.
+2. If it exists, ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "Project CONTEXT.md already exists. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing CONTEXT.md path.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision and scope
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- Read `.planning/CONTEXT.md` (if exists) — current locked decisions (for Append mode)
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project CONTEXT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing CONTEXT.md content
+4. Write to `.planning/CONTEXT.md`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/CONTEXT.md ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project CONTEXT.md written — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
 ### Step 2: Load Phase Context
 
 Read the following files to understand what this phase needs to accomplish:

package/plugins/cursor-pbr/skills/health/SKILL.md

@@ -62,6 +62,19 @@ Stop all further checks.
 - PASS: All three required files exist
 - FAIL: List each missing file — "Run `/pbr:begin` to re-initialize, or create the file manually."
 
+**Advisory checks — WARN if missing, do not FAIL:**
+
+- `.planning/PROJECT.md`
+  If missing: `⚠ PROJECT.md not found. Run /pbr:begin to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.`
+
+- `.planning/REQUIREMENTS.md`
+  If missing: `⚠ REQUIREMENTS.md not found. Run /pbr:begin to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.`
+
+- `.planning/CONTEXT.md` (project-level)
+  If missing: `⚠ CONTEXT.md not found. Run /pbr:discuss --project to capture locked decisions.`
+
+These files are generated by /pbr:begin. Absence is expected on projects created before v2.15.
+
 ### Check 2: Config Validity
 
 Parse `.planning/config.json` as JSON. Check required fields: `version`, `depth`. Check recommended fields: `features`, `models`.