@sienklogic/plan-build-run 2.0.2 → 2.1.0

package/dashboard/src/routes/pages.routes.js

@@ -1,19 +1,23 @@
 import { Router } from 'express';
 import { getPhaseDetail, getPhaseDocument } from '../services/phase.service.js';
 import { getRoadmapData } from '../services/roadmap.service.js';
+import { parseStateFile, derivePhaseStatuses } from '../services/dashboard.service.js';
 import { listPendingTodos, getTodoDetail, createTodo, completeTodo } from '../services/todo.service.js';
 
 const router = Router();
 
 router.get('/phases', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
-  const roadmapData = await getRoadmapData(projectDir);
+  const [roadmapData, stateData] = await Promise.all([
+    getRoadmapData(projectDir),
+    parseStateFile(projectDir)
+  ]);
 
   const templateData = {
     title: 'Phases',
     activePage: 'phases',
     currentPath: '/phases',
-    phases: roadmapData.phases,
+    phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
     milestones: roadmapData.milestones
   };
 
@@ -223,13 +227,16 @@ router.post('/todos/:id/done', async (req, res) => {
 
 router.get('/roadmap', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
-  const roadmapData = await getRoadmapData(projectDir);
+  const [roadmapData, stateData] = await Promise.all([
+    getRoadmapData(projectDir),
+    parseStateFile(projectDir)
+  ]);
 
   const templateData = {
     title: 'Roadmap',
     activePage: 'roadmap',
     currentPath: '/roadmap',
-    phases: roadmapData.phases,
+    phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
     milestones: roadmapData.milestones
   };
 

package/dashboard/src/services/dashboard.service.js

@@ -24,7 +24,20 @@ export async function parseStateFile(projectDir) {
   try {
     const path = join(projectDir, '.planning', 'STATE.md');
     const raw = await readFile(path, 'utf-8');
-    const content = stripBOM(raw);
+    const content = stripBOM(raw).replace(/\r\n/g, '\n');
+
+    // Parse YAML frontmatter if present (STATE.md v2 format)
+    let frontmatter = {};
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      for (const line of fmMatch[1].split('\n')) {
+        const kv = line.match(/^(\w+):\s*(.+)/);
+        if (kv) {
+          const val = kv[2].trim().replace(/^"(.*)"$/, '$1');
+          frontmatter[kv[1]] = val;
+        }
+      }
+    }
 
     // Extract project name from **Current focus:** line
     let projectName = 'Unknown Project';
@@ -76,13 +89,23 @@ export async function parseStateFile(projectDir) {
       progress = Math.ceil((currentPhaseId / totalPhases) * 100);
     }
 
+    // Determine phase status from frontmatter or body text
+    // "built", "verified", "complete" all mean the current phase is done
+    const fmStatus = (frontmatter.status || '').toLowerCase();
+    const phaseStatus = ['built', 'verified', 'complete', 'reviewed'].includes(fmStatus)
+      ? 'complete'
+      : ['building', 'planning', 'planned', 'in-progress'].includes(fmStatus)
+        ? 'in-progress'
+        : fmStatus || 'unknown';
+
     return {
       projectName,
       currentPhase: {
         id: currentPhaseId,
         total: totalPhases,
         name: phaseName,
-        planStatus
+        planStatus,
+        status: phaseStatus
       },
       lastActivity: {
         date: activityDate,
@@ -94,7 +117,7 @@ export async function parseStateFile(projectDir) {
     if (error.code === 'ENOENT') {
       return {
         projectName: 'Unknown Project',
-        currentPhase: { id: 0, total: 0, name: 'Not Started', planStatus: 'N/A' },
+        currentPhase: { id: 0, total: 0, name: 'Not Started', planStatus: 'N/A', status: 'unknown' },
         lastActivity: { date: '', description: 'No activity recorded' },
         progress: 0
       };
@@ -132,7 +155,7 @@ export async function parseRoadmapFile(projectDir) {
 
     // 2. Parse descriptions from Phase Details: "### Phase NN: Name\n**Goal**: ..."
     const goalMap = new Map();
-    const goalRegex = /### Phase (\d+):\s*(.+)\n\*\*Goal\*\*:\s*(.+)/g;
+    const goalRegex = /### Phase (\d+):\s*(.+)\n\*\*Goal:?\*\*:?\s*(.+)/g;
     for (const match of content.matchAll(goalRegex)) {
       goalMap.set(parseInt(match[1], 10), match[3].trim());
     }
@@ -158,11 +181,28 @@ export async function parseRoadmapFile(projectDir) {
       progressPhases.push({ id, name, description, status });
     }
 
-    // Use Progress table if available, otherwise fall back to checkbox parsing
+    // 4. Parse H3 Phase Details: "### Phase N: Name\n**Goal:** ..."
+    const h3Phases = [];
+    const h3Regex = /### Phase (\d+):\s*(.+)\n\*\*Goal\*?\*?:?\*?\*?\s*(.+)/g;
+    for (const match of content.matchAll(h3Regex)) {
+      const id = parseInt(match[1], 10);
+      const name = match[2].trim();
+      const description = match[3].trim();
+      // Check checkbox map for status, default to not-started
+      const cbInfo = checkboxMap.get(id);
+      h3Phases.push({
+        id,
+        name,
+        description,
+        status: cbInfo?.status || 'not-started'
+      });
+    }
+
+    // Use Progress table if available, then checkbox list, then H3 headings
     let phases;
     if (progressPhases.length > 0) {
       phases = progressPhases;
-    } else {
+    } else if (checkboxMap.size > 0) {
       phases = [...checkboxMap.entries()]
         .map(([id, info]) => ({
           id,
@@ -171,6 +211,8 @@ export async function parseRoadmapFile(projectDir) {
           status: info.status
         }))
         .sort((a, b) => a.id - b.id);
+    } else {
+      phases = h3Phases.sort((a, b) => a.id - b.id);
     }
 
     const completed = phases.filter(p => p.status === 'complete').length;
@@ -193,23 +235,45 @@ export async function parseRoadmapFile(projectDir) {
  * @param {string} projectDir - Absolute path to the project root
  * @returns {Promise<{projectName: string, currentPhase: object, lastActivity: object, progress: number, phases: Array}>}
  */
+/**
+ * Derive phase statuses by combining roadmap phases with STATE.md context.
+ * Phases before the current phase are marked complete.
+ * The current phase gets its status from STATE.md.
+ * Phases after the current phase keep their roadmap status (typically not-started).
+ *
+ * @param {Array} phases - Raw phases from parseRoadmapFile
+ * @param {{id: number, status: string}} currentPhase - Current phase from parseStateFile
+ * @returns {Array} Phases with derived statuses
+ */
+export function derivePhaseStatuses(phases, currentPhase) {
+  const currentId = currentPhase.id;
+  const currentStatus = currentPhase.status || 'unknown';
+  return phases.map(phase => {
+    // If the roadmap already has explicit status (from progress table/checkboxes), keep it
+    if (phase.status === 'complete') return phase;
+
+    if (phase.id < currentId) {
+      return { ...phase, status: 'complete' };
+    }
+    if (phase.id === currentId) {
+      return { ...phase, status: currentStatus === 'complete' ? 'complete' : 'in-progress' };
+    }
+    return phase;
+  });
+}
+
 export async function getDashboardData(projectDir) {
   const [stateData, roadmapData] = await Promise.all([
     parseStateFile(projectDir),
     parseRoadmapFile(projectDir)
   ]);
 
-  // Derive "in-progress" status for the current phase
-  const phases = roadmapData.phases.map(phase => ({
-    ...phase,
-    status: (phase.id === stateData.currentPhase.id && phase.status !== 'complete')
-      ? 'in-progress'
-      : phase.status
-  }));
-
-  // Prefer roadmap progress if phases exist, otherwise use state progress
-  const progress = roadmapData.phases.length > 0
-    ? roadmapData.progress
+  const phases = derivePhaseStatuses(roadmapData.phases, stateData.currentPhase);
+
+  // Recalculate progress from derived phase statuses
+  const completedPhases = phases.filter(p => p.status === 'complete').length;
+  const progress = phases.length > 0
+    ? Math.ceil((completedPhases / phases.length) * 100)
     : stateData.progress;
 
   return {

package/dashboard/src/services/phase.service.js

@@ -109,16 +109,19 @@ export async function getPhaseDetail(projectDir, phaseId) {
   const phaseFiles = await readdir(phaseFullPath);
 
   // Filter and sort PLAN.md files
-  const planRegex = /^\d{2}-\d{2}-PLAN\.md$/;
-  const planIdRegex = /^(\d{2}-\d{2})-PLAN\.md$/;
+  // Supports both naming conventions:
+  //   - NN-NN-PLAN.md (plan ID embedded in filename)
+  //   - PLAN.md (single plan per phase, ID derived from phase directory)
+  const planRegex = /^(?:\d{2}-\d{2}-)?PLAN\.md$/;
   const planFiles = phaseFiles
     .filter(f => planRegex.test(f))
     .sort();
 
   // Build summary paths and read them in parallel
-  const summaryPaths = planFiles.map(planFile => {
-    const match = planFile.match(planIdRegex);
-    const planId = match[1];
+  // Derive planId from filename (NN-NN-PLAN.md) or phase directory (PLAN.md -> NN-01)
+  const summaryPaths = planFiles.map((planFile, index) => {
+    const idMatch = planFile.match(/^(\d{2}-\d{2})-PLAN\.md$/);
+    const planId = idMatch ? idMatch[1] : `${phaseId.padStart(2, '0')}-${String(index + 1).padStart(2, '0')}`;
     return { planId, planFile, summaryPath: join(phaseFullPath, `SUMMARY-${planId}.md`) };
   });
 
@@ -196,25 +199,28 @@ export async function getPhaseDocument(projectDir, phaseId, planId, docType) {
   const phaseName = formatPhaseName(phaseDir.name);
   const phaseFullPath = join(phasesDir, phaseDir.name);
 
-  const fileName = docType === 'plan'
-    ? `${planId}-PLAN.md`
-    : `SUMMARY-${planId}.md`;
+  // Try plan ID-prefixed filename first, then fall back to plain PLAN.md
+  // Supports both "01-01-PLAN.md" and "PLAN.md" naming conventions
+  const fileNames = docType === 'plan'
+    ? [`${planId}-PLAN.md`, 'PLAN.md']
+    : [`SUMMARY-${planId}.md`];
 
-  // Validate the path stays within the phase directory
-  const filePath = validatePath(phaseFullPath, fileName);
-
-  try {
-    const doc = await readMarkdownFile(filePath);
-    return {
-      phaseId,
-      planId,
-      docType,
-      phaseName,
-      frontmatter: doc.frontmatter,
-      html: doc.html
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
+  for (const fileName of fileNames) {
+    const filePath = validatePath(phaseFullPath, fileName);
+    try {
+      const doc = await readMarkdownFile(filePath);
+      return {
+        phaseId,
+        planId,
+        docType,
+        phaseName,
+        frontmatter: doc.frontmatter,
+        html: doc.html
+      };
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
   }
+  return null;
 }

package/dashboard/src/services/roadmap.service.js

@@ -35,7 +35,7 @@ async function countPlansForPhase(projectDir, phaseId) {
     if (!phaseDir) return 0;
 
     const phaseFiles = await readdir(join(phasesDir, phaseDir.name));
-    return phaseFiles.filter(f => /^\d{2}-\d{2}-PLAN\.md$/.test(f)).length;
+    return phaseFiles.filter(f => /^(?:\d{2}-\d{2}-)?PLAN\.md$/.test(f)).length;
   } catch (err) {
     if (err.code === 'ENOENT') return 0;
     throw err;
@@ -52,7 +52,7 @@ function extractAllDependencies(roadmapContent) {
   const dependencyMap = new Map();
 
   // Match Phase Details sections: "### Phase NN: ..." followed by "**Depends on**: ..."
-  const sectionRegex = /### Phase (\d+):[\s\S]*?\*\*Depends on\*\*:\s*([^\n]+)/g;
+  const sectionRegex = /### Phase (\d+):[\s\S]*?\*\*Depends on:?\*\*:?\s*([^\n]+)/g;
   let match;
 
   while ((match = sectionRegex.exec(roadmapContent)) !== null) {
@@ -92,7 +92,7 @@ function extractMilestones(roadmapContent) {
   const projectTitle = titleMatch ? titleMatch[1].trim() : 'Project';
 
   // Parse explicit milestones: "## Milestone: Name\n\n**Goal:** ...\n**Phases:** N - M"
-  const milestoneRegex = /## Milestone:\s*(.+)\n\n\*\*Goal:\*\*\s*(.+)\n\*\*Phases:\*\*\s*(\d+)\s*-\s*(\d+)/g;
+  const milestoneRegex = /## Milestone:\s*(.+)\n+\*\*Goal:?\*\*:?\s*(.+)\n\*\*Phases:?\*\*:?\s*(\d+)\s*-\s*(\d+)/g;
   const explicit = [];
   for (const match of roadmapContent.matchAll(milestoneRegex)) {
     explicit.push({

package/dashboard/src/views/partials/phase-content.ejs

@@ -10,14 +10,15 @@
   </header>
   <%
     // Map verification status to CSS status-badge data-status values
+    var vStatus = verification.status || verification.verdict || 'unknown';
     var verificationCssStatus = 'not-started';
-    if (verification.status === 'passed') verificationCssStatus = 'complete';
-    else if (verification.status === 'failed') verificationCssStatus = 'blocked';
-    else if (verification.status === 'partial') verificationCssStatus = 'in-progress';
+    if (vStatus === 'passed') verificationCssStatus = 'complete';
+    else if (vStatus === 'failed') verificationCssStatus = 'blocked';
+    else if (vStatus === 'partial') verificationCssStatus = 'in-progress';
   %>
   <p>
     <span class="status-badge" data-status="<%= verificationCssStatus %>">
-      <%= verification.status.toUpperCase() %>
+      <%= vStatus.toUpperCase() %>
     </span>
     <% if (verification.verified) { %>
       &nbsp; Verified: <%= new Date(verification.verified).toLocaleString() %>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

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

@@ -11,7 +11,7 @@
   "homepage": "https://github.com/SienkLogic/plan-build-run",
   "repository": "https://github.com/SienkLogic/plan-build-run",
   "license": "MIT",
-  "logo": "assets/logo.png",
+  "logo": "../assets/logo.svg",
   "keywords": ["cursor", "context-engineering", "development-workflow", "subagent-delegation"],
   "category": "developer-tools",
   "tags": ["planning", "workflow", "structured-development", "context-management"],

package/plugins/cursor-pbr/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## v2.0.0 (2026-02-19)
+
+Initial release of Plan-Build-Run for Cursor.
+
+### Features
+
+- 21 skills covering the full development lifecycle: begin, plan, build, review, debug, and more
+- 10 specialized agents with fresh context windows for delegation without context rot
+- Shared hook scripts with the Claude Code plugin for consistent behavior
+- Cross-plugin compatibility: shared `.planning/` state directory works with both Cursor and Claude Code
+- File-based state management with structured planning, execution, and verification phases
+- Atomic commits with deviation handling and self-verification
+- Goal-backward verification ensuring builds match plans

package/plugins/cursor-pbr/README.md

@@ -0,0 +1,118 @@
+# Plan-Build-Run for Cursor
+
+A structured development workflow plugin for Cursor that solves context rot through disciplined subagent delegation, file-based state, and goal-backward verification.
+
+## Installation
+
+### Automated Setup (Recommended)
+
+The setup script creates symlinks from your project's `.cursor/` directory to the PBR plugin, so rules and agents are discovered automatically by Cursor.
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1
+```
+
+This installs:
+- `.cursor/rules/pbr-workflow.mdc` — Workflow rules (auto-loaded when `.planning/` exists)
+- `.cursor/agents/*.md` — 10 specialized agent definitions
+
+### Manual Setup
+
+If you prefer not to use the setup script:
+
+1. Copy or symlink `rules/pbr-workflow.mdc` into your project's `.cursor/rules/` directory
+2. Copy or symlink all files from `agents/` into your project's `.cursor/agents/` directory
+3. Skills (in `skills/`) are prompt templates — paste a skill's `SKILL.md` content into Cursor chat to invoke it, or reference the skill directory if Cursor supports skill discovery
+
+### Uninstall
+
+Remove the symlinks created by setup:
+
+```bash
+rm .cursor/rules/pbr-workflow.mdc
+rm .cursor/agents/*.md    # only PBR agent files
+```
+
+## Quick Start
+
+The core workflow follows four steps per phase:
+
+```
+/pbr:begin     — Define your project: requirements, research, roadmap
+/pbr:plan 1    — Create a detailed plan for phase 1
+/pbr:build 1   — Execute the plan with atomic commits
+/pbr:review 1  — Verify the build matched the plan
+```
+
+Repeat `plan` / `build` / `review` for each phase in your roadmap.
+
+## Skills (21)
+
+| Skill | Description |
+|-------|-------------|
+| begin | Start a new project. Deep questioning, research, requirements, and roadmap. |
+| build | Execute all plans in a phase. Spawns agents to build in parallel, commits atomically. |
+| config | Configure settings: depth, model profiles, features, git, and gates. |
+| continue | Execute the next logical step automatically. No prompts, no decisions. |
+| debug | Systematic debugging with hypothesis testing. Persistent across sessions. |
+| discuss | Talk through a phase before planning. Identifies gray areas and captures decisions. |
+| explore | Explore ideas, think through approaches, and route insights to the right artifacts. |
+| health | Check planning directory integrity. Find and fix corrupted state. |
+| help | Command reference and workflow guide. |
+| import | Import external plans. Validates context, detects conflicts, generates PLAN.md. |
+| milestone | Manage milestones: new, complete, audit, gaps. |
+| note | Zero-friction idea capture. Append, list, or promote notes to todos. |
+| pause | Save your current session state for later resumption. |
+| plan | Create a detailed plan for a phase. Research, plan, and verify before building. |
+| quick | Execute an ad-hoc task with atomic commits. Skips full plan/review. |
+| resume | Pick up where you left off. Restores context and suggests next action. |
+| review | Verify the build matched the plan. Automated checks plus walkthrough. |
+| scan | Analyze an existing codebase. Maps structure, architecture, conventions, and concerns. |
+| setup | Onboarding wizard. Initialize project, select models, verify setup. |
+| status | Show current project status and suggest what to do next. |
+| todo | File-based persistent todos. Add, list, complete — survives sessions. |
+
+Skills live in `skills/{name}/SKILL.md`. Each is a self-contained prompt that can be pasted into Cursor chat or invoked as a slash command if Cursor discovers the plugin manifest.
+
+## Agents (10)
+
+| Agent | Description |
+|-------|-------------|
+| codebase-mapper | Explores codebases and writes structured analysis across four focus areas. |
+| debugger | Systematic debugging using scientific method with hypothesis testing and evidence tracking. |
+| executor | Executes plan tasks with atomic commits, deviation handling, and self-verification. |
+| general | Lightweight agent for ad-hoc tasks that don't fit specialized roles. |
+| integration-checker | Cross-phase integration and E2E flow verification. |
+| plan-checker | Verifies plans will achieve phase goals before execution via goal-backward analysis. |
+| planner | Creates executable phase plans with task breakdown, dependency analysis, and wave assignment. |
+| researcher | Unified research agent for project domains and implementation approaches. |
+| synthesizer | Fast synthesis of multiple research outputs into coherent recommendations. |
+| verifier | Goal-backward phase verification against the real codebase. |
+
+## Configuration
+
+Plan-Build-Run stores all state in a `.planning/` directory at your project root:
+
+- `.planning/config.json` — Workflow settings (~62 properties across 12 keys)
+- `.planning/STATE.md` — Current position and status
+- `.planning/ROADMAP.md` — Phase structure, goals, and dependencies
+- `.planning/phases/NN-slug/` — Per-phase plans, summaries, and verification reports
+
+Run `/pbr:config` to interactively adjust settings like depth, model profiles, and gate behavior.
+
+## Cross-Plugin Compatibility
+
+This plugin works alongside the Claude Code version of Plan-Build-Run. Both plugins share the same `.planning/` directory and file formats, so you can switch between Cursor and Claude Code without losing state. Hook scripts under `plugins/pbr/scripts/` are shared between both plugins via relative paths.
+
+## Links
+
+- Repository: [https://github.com/SienkLogic/plan-build-run](https://github.com/SienkLogic/plan-build-run)
+- License: MIT

package/plugins/cursor-pbr/agents/codebase-mapper.md

@@ -0,0 +1,108 @@
+---
+name: codebase-mapper
+description: "Explores existing codebases and writes structured analysis documents. Four focus areas: tech, arch, quality, concerns."
+model: sonnet
+readonly: false
+---
+
+# Plan-Build-Run Codebase Mapper
+
+You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run development system. You explore existing codebases and produce structured documentation that helps other agents (and humans) understand the project's technology stack, architecture, conventions, and concerns.
+
+## Core Philosophy
+
+- **Document quality over brevity.** Be thorough. Other agents depend on your analysis for accurate planning and execution.
+- **Always include file paths.** Every claim must reference the actual code location. Never say "the config file" — say "`tsconfig.json` at project root" or "`src/config/database.ts`".
+- **Write current state only.** No temporal language ("recently added", "will be changed", "was refactored"). Document WHAT IS, not what was or will be.
+- **Be prescriptive, not descriptive.** When documenting conventions: "Use this pattern" not "This pattern exists."
+- **Evidence-based.** Read the actual files. Don't guess from file names or directory structures.
+
+---
+
+### Forbidden Files
+
+When exploring, NEVER commit or recommend committing:
+- `.env` files (except `.env.example` or `.env.template`)
+- `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
+- Files containing `credential` or `secret` in their name
+- `*.keystore`, `*.jks` — Java keystores
+- `id_rsa`, `id_ed25519` — SSH keys
+
+If encountered, note in CONCERNS.md under "Security Considerations" but do NOT include contents.
+
+---
+
+## Focus Areas
+
+You receive ONE focus area per invocation. All output is written to `.planning/codebase/` (create if needed). **Do NOT commit** — the orchestrator handles commits.
+
+| Focus | Output Files | Templates |
+|-------|-------------|-----------|
+| `tech` | STACK.md, INTEGRATIONS.md | `templates/codebase/STACK.md.tmpl`, `templates/codebase/INTEGRATIONS.md.tmpl` |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md | `templates/codebase/ARCHITECTURE.md.tmpl`, `templates/codebase/STRUCTURE.md.tmpl` |
+| `quality` | CONVENTIONS.md, TESTING.md | `templates/codebase/CONVENTIONS.md.tmpl`, `templates/codebase/TESTING.md.tmpl` |
+| `concerns` | CONCERNS.md | `templates/codebase/CONCERNS.md.tmpl` |
+
+Read the relevant `.tmpl` file(s) and fill in all placeholder fields with data from your analysis.
+
+---
+
+## Exploration Process
+
+> **Cross-platform**: Use Glob, Read, and Grep tools — not Bash `ls`, `find`, or `cat`. Bash file commands fail on Windows.
+
+1. **Orientation** — Glob for source files, config files, docs, Docker, CI/CD to understand project shape.
+2. **Deep Inspection** — Read 5-10+ key files per focus area (package.json, configs, entry points, core modules).
+3. **Pattern Recognition** — Identify repeated conventions across the codebase.
+4. **Write Documentation** — Write to `.planning/codebase/` using the templates. Write documents as you go to manage context.
+
+---
+
+## Output Budget
+
+| Artifact | Target | Hard Limit |
+|----------|--------|------------|
+| STACK.md | ≤ 800 tokens | 1,200 tokens |
+| INTEGRATIONS.md | ≤ 600 tokens | 1,000 tokens |
+| ARCHITECTURE.md | ≤ 1,000 tokens | 1,500 tokens |
+| STRUCTURE.md | ≤ 600 tokens | 1,000 tokens |
+| CONVENTIONS.md | ≤ 800 tokens | 1,200 tokens |
+| TESTING.md | ≤ 600 tokens | 1,000 tokens |
+| CONCERNS.md | ≤ 600 tokens | 1,000 tokens |
+| Total per focus area (2 docs) | ≤ 1,400 tokens | 2,200 tokens |
+
+**Guidance**: Tables over prose. Version numbers and file paths are the high-value data — skip explanations of what well-known tools do. The planner reads these documents to make decisions; give it decision-relevant facts, not tutorials.
+
+---
+
+## Quality Standards
+
+1. Every claim must reference actual file paths (with line numbers when possible)
+2. Verify versions from package.json/lock files, not from memory
+3. Read at least 5-10 key files per focus area — file names lie, check source
+4. Include actual code examples from the codebase, not generic examples
+5. Stop before 50% context usage — write documents incrementally
+
+---
+
+## Universal Anti-Patterns
+
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT trust SUMMARY.md or other agent claims without verifying codebase
+3. DO NOT use vague language — be specific and evidence-based
+4. DO NOT present training knowledge as verified fact
+5. DO NOT exceed your role — recommend the correct agent if task doesn't fit
+6. DO NOT modify files outside your designated scope
+7. DO NOT add features or scope not requested — log to deferred
+8. DO NOT skip steps in your protocol, even for "obvious" cases
+9. DO NOT contradict locked decisions in CONTEXT.md
+10. DO NOT implement deferred ideas from CONTEXT.md
+11. DO NOT consume more than 50% context before producing output
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
+
+Additionally for this agent:
+
+1. DO NOT guess technology versions — read package.json or equivalent
+2. DO NOT use temporal language ("recently added", "old code")
+3. DO NOT produce generic documentation — every claim must reference this specific codebase
+4. DO NOT commit the output — the orchestrator handles commits