@sienklogic/plan-build-run 2.59.0 → 2.61.0

package/plugins/copilot-pbr/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 GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-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/copilot-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/copilot-pbr/skills/discuss/SKILL.md

@@ -35,9 +35,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."
@@ -63,6 +66,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/copilot-pbr/skills/health/SKILL.md

@@ -61,6 +61,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`.

package/plugins/copilot-pbr/skills/import/SKILL.md

@@ -49,7 +49,15 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number
 2. Parse optional `--from <filepath>` flag (path to the external document to import)
 3. Parse optional `--skip-checker` flag (skip plan validation step)
+3b. Parse optional `--prd <filepath>` flag.
+    - If `--prd` is present: **branch into PRD Import Flow (Steps A–G below)** immediately after writing `.active-skill`.
+    - Do NOT proceed to Step 2 (standard import flow). The --prd branch is a completely separate execution path.
+    - If both `--prd` and `--from` are present: treat `--prd` as the primary flag; `--from` is ignored with an [INFO] note.
+    - If `--prd` is present but no filepath follows: display error "Missing filepath for --prd flag." and stop.
 4. **CRITICAL: Write .active-skill NOW.** Write the text "import" to `.planning/.active-skill` using the Write tool.
+
+**→ If --prd flag was set: jump to PRD Import Flow (Step A). Do not continue to Step 2.**
+
 5. Validate:
    - Phase exists in ROADMAP.md
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
@@ -61,6 +69,253 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 
 ---
 
+## PRD Import Flow
+
+> **Entered when `--prd <filepath>` is present in $ARGUMENTS. Steps A–G replace Steps 2–11 entirely for this path.**
+
+---
+
+### Step A: Read and Validate PRD File
+
+1. Read the file at the `--prd <filepath>` path.
+2. If the file does not exist: display the "Import file not found" error from the Error Handling section and stop.
+3. If the file is empty or < 100 characters: display error "PRD file appears empty or too short to extract meaningful content." and stop.
+4. Store the full PRD content for use in Steps B–E.
+
+---
+
+### Step B: Gap Detection — Identify Missing Sections (inline)
+
+Analyze the PRD content for the presence of these six required sections:
+
+| Section | What to look for |
+|---------|-----------------|
+| Project name / title | A clear product name or title |
+| Problem statement | What problem the product solves, who it's for |
+| Goals / success criteria | Measurable outcomes, KPIs, or acceptance tests |
+| Functional requirements | Feature list, user stories, or capabilities |
+| Non-functional requirements | Performance, security, reliability constraints |
+| Out of scope / deferred | Explicitly excluded features |
+
+For each section that is **absent or ambiguous**, record it as a gap.
+
+**If 1–3 gaps found:** Batch all gaps into ≤ 3 AskUserQuestion calls (max 4 options each). Ask the user to supply the missing info:
+
+- If 1 gap: one AskUserQuestion with a freeform prompt.
+- If 2–3 gaps: group into 2 AskUserQuestion calls of related topics (e.g., "Requirements" and "Constraints/Scope").
+- If > 3 gaps: group all into exactly 3 AskUserQuestion calls. Do NOT exceed 3 calls.
+
+Example AskUserQuestion for missing requirements:
+
+```
+Use AskUserQuestion:
+  question: "The PRD doesn't clearly specify functional requirements. Please describe the main features or capabilities this product must have."
+  header: "Fill Gap"
+  options: []   ← freeform (no options means free text input)
+  multiSelect: false
+```
+
+**If 0 gaps:** proceed directly to Step C with no prompts.
+
+Incorporate user answers into the extraction context used in Step C.
+
+---
+
+### Step C: Extract 3 Files Inline (PROJECT.md, REQUIREMENTS.md, CONTEXT.md)
+
+Using the PRD content (plus any gap-fill answers from Step B), generate the content for three files. Do this inline in your context — no agents for these three files.
+
+**C1. Generate PROJECT.md content** using `templates/PROJECT.md.tmpl` as the structure:
+
+- `{project_name}`: extract from PRD title/header
+- `{ONE sentence core value statement}`: extract from problem statement / vision
+- Vision section: 2-3 sentences from PRD problem statement
+- Scope — In Scope: features from functional requirements section
+- Scope — Out of Scope: features from "out of scope" section (or mark "None specified" if absent)
+- Success Criteria: from goals/KPIs section
+- Stakeholders: extract if present; default to "Primary user: end users of the product"
+- Milestones line: leave as "Planned in {N} phases across 1 milestone — see .planning/ROADMAP.md"
+
+**C2. Generate REQUIREMENTS.md content** using `templates/REQUIREMENTS.md.tmpl` as the structure:
+
+- Functional Requirements: each feature/capability from PRD becomes one REQ-F-xxx row
+- Number from REQ-F-001 sequentially
+- Priority: "Must" for core features, "Should" for nice-to-haves (infer from PRD language)
+- Non-Functional Requirements: from performance/security/reliability section if present
+- Deferred Requirements: items from "out of scope" section
+- Traceability table: leave "Implemented In" and "Verified In" columns as "—"
+
+**C3. Generate CONTEXT.md content** using `templates/project-CONTEXT.md.tmpl` as the structure:
+
+- Locked Decisions: extract any explicit technology choices or constraints from PRD
+- User Constraints: extract deployment, team size, budget, timeline if mentioned
+- Deferred Ideas: items from "out of scope" section
+- Claude's Discretion Areas: leave empty (executor will fill as they work)
+
+---
+
+### Step D: Confirmation Gate
+
+**Check config:** Read `.planning/config.json`. If `prd.auto_extract` is `true`, skip this step entirely and proceed directly to Step E.
+
+**If prd.auto_extract is false (default):**
+
+Display a preview of the three generated files (show first 10 lines of each with a `...` truncation).
+
+Then present the confirmation gate using the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
+
+```
+Use AskUserQuestion:
+  question: "Approve these extracted files? (PROJECT.md, REQUIREMENTS.md, CONTEXT.md — ROADMAP.md will be generated next)"
+  header: "Approve?"
+  options:
+    - label: "Approve"          description: "Write files and generate ROADMAP.md"
+    - label: "Request changes"  description: "Describe what to adjust before writing"
+    - label: "Abort"            description: "Cancel PRD import"
+  multiSelect: false
+```
+
+- **Approve**: proceed to Step E.
+- **Request changes**: ask user what to change (AskUserQuestion freeform), revise the affected file(s) inline, and re-display the gate. Repeat until Approve or Abort.
+- **Abort**: delete `.planning/.active-skill` and stop with message: "PRD import cancelled."
+
+---
+
+### Step E: Check for Existing Files and Write PROJECT.md, REQUIREMENTS.md, CONTEXT.md
+
+For each of the three files (`PROJECT.md`, `REQUIREMENTS.md`, `CONTEXT.md` in `.planning/`):
+
+1. Check if the file already exists (Glob `.planning/PROJECT.md`, etc.).
+2. If it exists: use AskUserQuestion yes-no pattern:
+   ```
+   question: ".planning/{filename} already exists. Overwrite it?"
+   header: "Overwrite?"
+   options:
+     - label: "Yes"  description: "Replace existing file"
+     - label: "No"   description: "Keep existing, skip this file"
+   ```
+   - If No: skip writing that file.
+3. Write approved content to:
+   - `.planning/PROJECT.md`
+   - `.planning/REQUIREMENTS.md`
+   - `.planning/CONTEXT.md`
+
+---
+
+### Step F: Delegate ROADMAP.md Generation to pbr:planner
+
+Display: `◐ Generating ROADMAP.md via planner...`
+
+Spawn the planner subagent:
+
+```
+Task({
+  subagent_type: "pbr:planner",
+  prompt: "
+You are the planner agent in Roadmap Mode.
+
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/PROJECT.md
+2. .planning/REQUIREMENTS.md
+3. .planning/CONTEXT.md
+</files_to_read>
+
+Generate `.planning/ROADMAP.md` from the project files above.
+
+Use the roadmap template at `${PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
+Apply Requirement Coverage Validation: every requirement in REQUIREMENTS.md must appear in at least one phase.
+Apply the Dual Format requirement: Quick-scan checklist at top + detailed phase descriptions.
+Wrap all phases in a Milestone section named after the project.
+
+Write ROADMAP.md to `.planning/ROADMAP.md`.
+Output your completion marker when done: ## PLANNING COMPLETE
+"
+})
+```
+
+After the Task() completes:
+
+- Confirm `.planning/ROADMAP.md` exists (Glob check).
+- If missing: display error "Planner failed to generate ROADMAP.md. Run /pbr:plan to retry." and proceed to Step G anyway (the other 3 files are already written).
+
+---
+
+### Step G: State Updates, Commit, and Summary
+
+**G1. Initialize STATE.md** (if it does not already exist):
+
+- Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js state load`
+- If STATE.md does not exist: create `.planning/STATE.md` with frontmatter fields:
+  ```
+  project: {project_name from PROJECT.md}
+  current_phase: 1
+  status: planning
+  source: prd-import
+  prd_file: {filepath}
+  ```
+
+**G2. Update STATE.md** with PRD import status:
+
+- Set `status: planning`
+- Note `source: prd-import` and `prd_file: {filepath}`
+
+**G3. Commit (if planning.commit_docs is true in config):**
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+```
+docs(planning): init project docs from PRD import
+```
+
+Stage: `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, `.planning/CONTEXT.md`, `.planning/ROADMAP.md` (if generated), `.planning/STATE.md`.
+
+**G4. Delete `.planning/.active-skill`.**
+
+**G5. Display completion banner:**
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PRD IMPORT COMPLETE ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Project**: {project_name}
+**Source**: {prd_filepath}
+
+Files generated:
+  ✓ .planning/PROJECT.md
+  ✓ .planning/REQUIREMENTS.md
+  ✓ .planning/CONTEXT.md
+  {✓ or ✗} .planning/ROADMAP.md
+
+Requirements extracted: {count} REQ-IDs
+Gaps filled: {count} (via interactive prompts)
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan Phase 1** — generate execution plans for the first phase
+
+`/pbr:plan 1`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:discuss` — review and refine decisions before planning
+- `/pbr:status` — see full project overview
+```
+
+---
+
+> **End of PRD Import Flow. Steps 2–11 below apply only to the standard --from flow.**
+
+---
+
 ### Step 2: Load Full Project Context (inline)
 
 Read all relevant context files. This context is used for conflict detection in Step 4.
@@ -500,6 +755,22 @@ File not found: {filepath}
 **To fix:** Check the path and try again.
 ```
 
+### PRD file too short
+If the PRD file is < 100 characters:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+PRD file appears empty or too short to extract meaningful content.
+
+**To fix:** Provide a more complete PRD document (minimum ~100 characters).
+```
+
+### PRD import cancelled
+If user selects "Abort" at the confirmation gate (Step D):
+Display: "PRD import cancelled." and delete `.planning/.active-skill`.
+
 ### Import document too vague
 If the imported document contains no actionable tasks, display:
 ```
@@ -536,3 +807,7 @@ Present remaining issues and ask user to decide: proceed or intervene.
 | `.planning/ROADMAP.md` | Plans Complete + Status updated to `planned` | Step 8a |
 | `.planning/STATE.md` | Updated with plan status and import source | Step 8b |
 | `.planning/CONTEXT.md` | Updated if blockers surfaced new locked decisions | Step 8d |
+| `.planning/PROJECT.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/REQUIREMENTS.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/CONTEXT.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/ROADMAP.md` | Generated by planner subagent | Step F (PRD flow) |

package/plugins/copilot-pbr/skills/plan/SKILL.md

@@ -484,7 +484,17 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 - Or make small inline edits to plan files directly
 
 **If user selects 'Approve':**
-- **CONTEXT.md compliance reporting**: If `.planning/CONTEXT.md` exists, compare all locked decisions against the generated plans. Print: "CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks" where M = locked decisions that are reflected in at least one task, N = total locked decisions. If any locked decisions are unmapped, list them as warnings.
+- **CONTEXT.md compliance reporting**: Check locked decisions from BOTH sources:
+  a. Project-level: `.planning/CONTEXT.md` (if exists) — cross-cutting decisions for all phases
+  b. Phase-level: `.planning/phases/{NN}-{slug}/CONTEXT.md` (if exists) — phase-specific decisions
+     Phase-level decisions override project-level for the same decision area.
+
+  Collect ALL locked decisions from both files (deduplicate identical decision text).
+  Compare against the generated plan tasks. Print:
+  `CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks`
+  where M = locked decisions reflected in at least one task action, N = total unique locked decisions.
+  If any locked decisions are unmapped, list them as warnings.
+  If neither CONTEXT.md exists: skip this check silently.
 - **Dependency fingerprinting**: For each dependency phase (phases that this phase depends on, per ROADMAP.md):
   1. Find all SUMMARY.md files in the dependency phase directory
   2. Compute a fingerprint string for each: `"len:{bytes}-mod:{mtime}"` and add as a `dependency_fingerprints` map in each plan's YAML frontmatter — this allows the build skill to detect stale plans if dependencies were rebuilt.

package/plugins/copilot-pbr/skills/shared/context-loader-task.md

@@ -28,6 +28,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
@@ -65,6 +66,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)

package/plugins/copilot-pbr/skills/status/SKILL.md

@@ -111,6 +111,16 @@ Parse the JSON response. Capture:
 
 Store these for use in Step 4 display and Step 5 routing.
 
+6. **`.planning/CONTEXT.md`** (project-level, if exists)
+   - Note: project-level locked decisions file
+
+### Step 1d: Check Project Documents
+
+Check existence of the three project-level documents and record their status for Step 4 display:
+- `.planning/PROJECT.md` — exists or not
+- `.planning/REQUIREMENTS.md` — exists or not
+- `.planning/CONTEXT.md` — exists or not
+
 ### Step 2: Scan Phase Directories
 
 For each phase listed in ROADMAP.md:
@@ -221,6 +231,13 @@ Phase Status:
 | 2. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
 | ...
 
+**Project documents:**
+| File | Status |
+|------|--------|
+| PROJECT.md | {exists / not found — run /pbr:begin} |
+| REQUIREMENTS.md | {exists / not found — run /pbr:begin} |
+| CONTEXT.md | {exists / not found — run /pbr:discuss --project} |
+
 {If context tier is DEGRADING, POOR, or CRITICAL:}
 ⚠ Context: {percentage}% used ({tier}) — {recommendation_text}
   Run `/compact` to reclaim context before spawning more agents.

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

@@ -0,0 +1,41 @@
+# {project_name}
+
+> {ONE sentence core value statement}
+
+## Vision
+
+{2-3 sentences describing the product and problem it solves. Who is it for? What does it replace or improve?}
+
+## Scope
+
+### In Scope (v1)
+
+{Bulleted list of features and capabilities committed for this project.}
+
+- {Feature area}: {brief description}
+
+### Out of Scope
+
+{Features explicitly excluded from this project.}
+
+- {Feature}: {brief reason why excluded}
+
+## Success Criteria
+
+{Observable conditions that define project success. Each must be testable.}
+
+- {Criterion 1 — specific and measurable}
+- {Criterion 2 — specific and measurable}
+- {Criterion 3 — specific and measurable}
+
+## Stakeholders
+
+{Who cares about this project and why.}
+
+- **Primary user**: {description}
+- **Team**: {description}
+
+## Milestones
+
+{project_name} planned in {phase_count} phases across {milestone_count} milestone(s).
+See `.planning/ROADMAP.md` for phase details.