@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/skills/scan/SKILL.md

@@ -11,14 +11,14 @@ allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCANNING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:scan — Codebase Analysis
+# /pbr:map-codebase — Codebase Analysis
 
 You are running the **scan** skill. Your job is to analyze an existing codebase and produce a comprehensive map of its structure, architecture, conventions, and concerns. This is the entry point for brownfield projects — codebases that already have code before Plan-Build-Run is introduced.
 
@@ -90,7 +90,7 @@ Before spawning agents, do a quick scan to identify what we're working with. Thi
 4. **Read existing docs** — README.md, architecture docs, .env.example
 5. **Write `.planning/codebase/RECON.md`** with project type, scale, key directories, entry points, and quick stats
 
-Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+Refer to the "Reconnaissance Detection Reference" section of `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` for the full detection checklists.
 
 ### Step 3: Spawn Analysis Agents
 
@@ -119,13 +119,21 @@ Display to the user:
 
 Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each area in `scan.mapper_areas`. All should be spawned in a single response for maximum parallelism.
 
-For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
+For each agent, read `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
 - `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
 - `{project_path}`: the working directory
 - `{recon_data}`: contents of RECON.md
 - `{scale}`: detected scale from Step 2
 - `{output_path}`: `.planning/codebase/`
 
+**Prepend this block to each mapper prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/codebase/RECON.md — baseline reconnaissance data (if exists)
+</files_to_read>
+```
+
 | Agent | Focus | Output Files | When |
 |-------|-------|-------------|------|
 | 1 | tech | STACK.md, INTEGRATIONS.md | Always |
@@ -145,6 +153,18 @@ All agents run in parallel. As each completes, display:
 
 (Only display lines for the focus areas that were actually spawned.)
 
+### Step 4b: Check Completion Markers
+
+After each codebase-mapper Task() completes, check the Task() output for the `## MAPPING COMPLETE` marker:
+
+- If `## MAPPING COMPLETE` is present: the mapper finished successfully, proceed normally
+- If the marker is missing: warn the user that the mapper may not have completed successfully:
+  ```
+  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
+  Output may be incomplete — check .planning/codebase/ for partial results.
+  ```
+  Continue to Step 5 verification regardless (the file existence checks will catch truly missing output).
+
 ### Step 5: Verify Output
 
 After all agents complete, verify the expected files exist:
@@ -172,17 +192,17 @@ For any missing files, display:
 Missing analysis output: {filename}
 Agent that failed: {focus_area} mapper
 
-**To fix:** Re-run with `/pbr:scan` and select "Refresh a specific area" → {focus_area}.
+**To fix:** Re-run with `/pbr:map-codebase` and select "Refresh a specific area" → {focus_area}.
 ```
 
 ### Step 6: Present Summary
 
-Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
+Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-brand.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCAN COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 Project: {type} ({scale})
 Stack: {primary language} + {framework}
@@ -209,23 +229,25 @@ Top concerns:
 
 Then use the "Next Up" routing block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Start a project** — use the scan results to plan your work
 
-`/pbr:begin`
+`/pbr:new-project`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
-- `/pbr:milestone new` — create a milestone to address concerns
-- `/pbr:status` — see project status
+- `/pbr:new-milestone` — create a milestone to address concerns
+- `/pbr:progress` — see project status
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ### Step 7: Git Integration
@@ -278,7 +300,7 @@ If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-n
 - Note their existence in STRUCTURE.md
 - Flag large committed binaries as a concern
 
-### Scan before /pbr:begin
+### Scan before /pbr:new-project
 - This is a valid and encouraged workflow
 - Scan results become input for the begin skill
 - Create `.planning/` and `.planning/codebase/` if needed

package/plugins/pbr/skills/scan/templates/mapper-prompt.md.tmpl

@@ -1,4 +1,4 @@
-<!-- Source: scan/SKILL.md | Purpose: Prompt template for spawning codebase-mapper agents during /pbr:scan -->
+<!-- Source: scan/SKILL.md | Purpose: Prompt template for spawning codebase-mapper agents during /pbr:map-codebase -->
 
 You are codebase-mapper with focus="{focus_area}".
 

package/plugins/pbr/skills/setup/SKILL.md

@@ -1,180 +1,67 @@
 ---
 name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
 allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 ---
 
-**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.**
+**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 tokens. Begin executing Step 1 immediately.**
 
 ## Step 0 — Immediate Output
 
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:setup — Plan-Build-Run Setup Wizard
+# /pbr:setup — Plan-Build-Run Reconfigure
 
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
 
 ---
 
 ## Step 1: Detect Project State
 
-Check if `.planning/` directory exists in the current working directory.
+Check if `.planning/config.json` exists.
 
-**If `.planning/` exists**:
-- Read `.planning/config.json` to check current settings
-- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
-- Skip to Step 3 (model selection)
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
-
-```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
-
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
-```
-
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "sonnet"
-  },
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2,
-    "use_teams": false
-  },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
-  },
-  "git": {
-    "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
-  },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
-  }
-}
+**If `.planning/config.json` does NOT exist:**
+Display:
 ```
+No Plan-Build-Run project found in this directory.
 
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
+/pbr:setup is for reconfiguring existing projects.
+To start a new project, run: /pbr:new-project
 
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
+/pbr:new-project includes everything /pbr:setup used to do, plus deep requirements gathering and roadmap creation.
 ```
+Stop. Do not proceed further.
+
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
 
 ---
 
-## Step 2: Project Type (new projects only)
+## Step 2: Model Selection
 
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
 
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
-
-Update config.json with any changes.
-
----
-
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
   header: "Models"
   options:
     - label: "Balanced (Recommended)"
@@ -183,19 +70,20 @@ AskUserQuestion:
       description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
     - label: "Budget"
       description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
 
-Apply the selected profile to `config.json`:
-- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
-- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
-- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet, context_window_tokens=1000000, agent_checkpoint_pct=65
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50
+- **Keep current**: no change to models block, no change to context_window_tokens
 
 ---
 
-## Step 4: Workflow Preferences
+## Step 3: Workflow Features
 
-```
-AskUserQuestion:
+Use AskUserQuestion:
   question: "Which workflow features do you want enabled?"
   header: "Features"
   multiSelect: true
@@ -208,9 +96,8 @@ AskUserQuestion:
       description: "Require verification AND review to pass before advancing phases"
     - label: "Git branching"
       description: "Create a branch per phase for cleaner PR history"
-```
 
-Apply selections:
+Apply selections (others unchanged):
 - **Auto-continue**: Set `features.auto_continue: true`
 - **TDD mode**: Set `features.tdd_mode: true`
 - **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
@@ -218,36 +105,132 @@ Apply selections:
 
 ---
 
-## Step 5: Verification
+## Step 4: CLAUDE.md Integration
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
+
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
+
+If "Yes", append/create:
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:progress` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
+---
+
+## Step 5: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
 
-Run a quick health check:
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
 
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
+Display the report:
 
-Display results:
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
 
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
 ```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent /pbr:setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: Write Updated Config
+
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
+
+Write the updated config.json to disk with all applied changes.
+
+---
+
+## Step 7: Verification
+
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
+
+Display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
+
+Run /pbr:progress to see current project state.
 ```
 
 ---
 
 ## Error Handling
 
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
 - If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/commit-planning-docs.md

@@ -16,6 +16,14 @@ If `planning.commit_docs: false` or config.json missing:
 - Skip the commit step
 ```
 
+**Note:** CLI state commands (`state advance-plan`, `phase complete`, `state update-progress`) automatically update STATE.md and ROADMAP.md. The commit step here covers planning artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md), not state files -- those are updated atomically by CLI commands.
+
+## Session Affinity
+
+When a session ID is available (from `.planning/.session.json`), append `[session:{short_id}]` to the commit description, where `short_id` is the first 8 characters of the session_id. This enables conflict tracing when multiple sessions modify planning docs concurrently.
+
+Example: `docs(planning): capture phase 3 discussion decisions [session:a1b2c3d4]`
+
 ## Commit Messages by Skill
 
 | Skill | Commit message format |

package/plugins/pbr/skills/shared/context-budget.md

@@ -12,9 +12,47 @@ Every skill that spawns agents or reads significant content must follow these ru
 
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
 4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
-5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
+5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause-work` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
+
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+**Applies to:** build, plan, review skills — any skill that reads back subagent artifacts.
+
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## State Consolidation Impact
+
+State consolidation (Phase 5) reduces core planning files from 5 to 3:
+- CONTEXT.md is now merged into PROJECT.md ## Context section
+- HISTORY.md is now merged into STATE.md ## History section
+- This reduces per-phase context loading overhead — fewer files to read, same information
+
+**File size estimates (post-consolidation):**
+- PROJECT.md: ~2-4 KB (includes Context section)
+- STATE.md: ~3-6 KB (includes History section)
+- ROADMAP.md: ~3-8 KB (depending on phase count)
+- config.json: ~1-2 KB
+
+**Note:** PROJECT.md is larger now with the merged Context section. Factor this into context budget when loading project state.
 
 ## Customization
 
@@ -38,3 +76,30 @@ Additionally for this skill:
 - {Skill-specific rule 1}
 - {Skill-specific rule 2}
 ```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.