@vibecompass/vibecompass 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.6.0 - 2026-05-25
+
+- Bump docs-review to `VibeCompass Docs Review Prompt v2`.
+- Add a staged docs-review workflow: evidence inventory, coverage plan, bounded doc generation, and apply/verify.
+- Add retrieval-oriented metadata expectations so generated architecture docs are useful future context without requiring broad token-heavy loads.
+- Add soft `oversized_architecture_doc` warnings for accepted architecture docs over the 12000-byte budget.
+- Include package-owned workflow registry files in the npm tarball.
+
+## 0.5.0
+
+- Previous published release.

package/README.md

@@ -20,7 +20,7 @@ Shipped today:
 - interactive guided init for placement, workflow bootstrap, and first-session setup
 - lightweight starter architecture/session memory plus example-only decision guidance
 - generated `context.md` plus opt-in workflow guide files
-- opt-in starter `CLAUDE.md` / `AGENTS.md` templates that are created once and never overwritten
+- opt-in starter `CLAUDE.md` / `AGENTS.md` templates that are created only when missing, with VibeCompass-managed regions for future refreshes
 - `vibecompass start-session` / `vibecompass close-session` for lane-aware local builder workflow
 - `vibecompass list-sessions` / `vibecompass switch-session` for multiple active session lanes
 - `vibecompass end-session` as a discoverable alias for `close-session`
@@ -31,6 +31,8 @@ Shipped today:
 - `vibecompass docs-review --submit-hosted` — submit the review request to the hosted app and poll for proposal/artifact output
 - `vibecompass docs-review --run-local --provider anthropic` — local provider adapter that saves review output locally
 - `vibecompass docs-review --apply-output` — apply accepted architecture-doc blocks into canonical `architecture/` docs
+- docs-review prompt v2 with staged evidence inventory, coverage planning, bounded doc generation, retrieval metadata, and soft oversized-doc warnings
+- strict docs-review output validation for architecture-doc fences, duplicate paths, and required frontmatter
 - `vibecompass docs-review --complete` — mark the review accepted after the docs land
 - hosted sync commands: `push`, `pull-preview`, `pull-export`, and `apply-export`
 - canonical file scanning and validation
@@ -68,6 +70,15 @@ command is intentionally unscoped: `vibecompass`.
 npm install @vibecompass/vibecompass
 ```
 
+## Latest release
+
+`0.6.0` upgrades docs-review to `VibeCompass Docs Review Prompt v2`.
+The generated review prompt now guides the LLM through evidence inventory,
+coverage planning, bounded architecture-doc generation, and apply/verify.
+Accepted architecture docs over the 12000-byte soft budget are still applied,
+but surface an `oversized_architecture_doc` warning so users can compact them
+before future LLM sessions load that context.
+
 ## Quickstart
 
 Most users should start with the guided bootstrap:
@@ -144,6 +155,11 @@ AGENTS.md           # at the tooling root, only if missing and --with-agents is
 
 `context.md` is a derived package-owned file. Re-running `init --force --with-workflow`
 regenerates it; do not treat it as a hand-edited source document.
+Starter `CLAUDE.md` / `AGENTS.md` files include VibeCompass managed markers
+when the package creates them, so later `sync-agents` and session lifecycle
+commands can refresh the generated region without warning. If those files
+already exist without markers, init leaves them untouched unless you explicitly
+adopt them.
 
 Check an initialized root without writing files:
 
@@ -188,9 +204,9 @@ remind you with a non-blocking warning if no completed review exists.
 
 What happens:
 
-1. The CLI asks which LLM you'll use, then prints a versioned prompt template with fixed review criteria.
+1. The CLI asks which LLM you'll use, then prints a versioned staged review prompt with fixed review criteria.
 2. You paste that prompt into your AI tool (Claude Code, Codex, Cursor, etc.).
-3. The AI reads your repo and writes architecture docs under
+3. The AI inventories project memory and source evidence, proposes a coverage plan, then writes only accepted architecture docs under
    `architecture/<domain>/<feature>/<component>.md`.
 4. Run `vibecompass docs-review --apply-output` after accepting fenced
    architecture-doc blocks, or `--complete` if accepted docs were written
@@ -199,8 +215,11 @@ What happens:
 The guided prompt is deterministic apart from project-specific fields
 (`project`, `mode`, `root`, provider, and model). It uses the same structure
 VibeCompass dogfoods: read project memory first, inspect source evidence,
-write component docs with review metadata, preserve the starter overview, and
-emit accepted docs as `vibecompass-architecture-doc` blocks.
+build a coverage plan, write retrieval-oriented component docs with review
+metadata, preserve the starter overview, and emit accepted docs as
+`vibecompass-architecture-doc` blocks. The prompt includes a soft 12000-byte
+budget per generated architecture doc so future LLM sessions can load targeted
+context without pulling oversized narrative files by default.
 
 Plain `--guided` never calls an AI itself. You stay in control of which
 provider runs the review and what gets saved. Use `--run-local --provider
@@ -283,7 +302,7 @@ Generate agent-instruction files from project memory:
 npx -y @vibecompass/vibecompass sync-agents --root .compass
 ```
 
-`sync-agents` writes only VibeCompass managed regions:
+`sync-agents` writes compact VibeCompass bootloader regions:
 
 ```md
 <!-- vibecompass:start - managed by VibeCompass, do not edit -->
@@ -291,13 +310,23 @@ npx -y @vibecompass/vibecompass sync-agents --root .compass
 <!-- vibecompass:end -->
 ```
 
-Content outside those markers is preserved. Existing files without markers are
-reported as warnings and left untouched unless you explicitly adopt them:
+Content outside those markers is preserved. Package-created starter files
+include managed markers from the beginning. Existing user files without markers
+are reported as warnings and left untouched unless you explicitly adopt them:
 
 ```bash
 npx -y @vibecompass/vibecompass sync-agents --root .compass --adopt-existing
 ```
 
+The managed block intentionally stays short: project-memory root, read order,
+prompt-command routing, and hard safety rules. Detailed workflow lives in
+`context.md` and generated files under `workflows/`, so `CLAUDE.md`, `AGENTS.md`,
+`.cursorrules`, and Copilot instructions do not duplicate long protocol text.
+`CLAUDE.md` starters also keep the mutable `Current session` block above the
+managed region because session lifecycle commands update it. `AGENTS.md`
+starters are intentionally just the managed bootloader; add Codex/team notes
+before or after the marker block if needed, and `sync-agents` will preserve them.
+
 Adoption appends a managed VibeCompass block to the end of existing unmarked
 agent files, preserves everything outside the markers, and reports possible
 workflow-overlap lines before you rely on the result. Guided init may offer the
@@ -665,7 +694,23 @@ Accepted review content.
 ```
 ````
 
-Only `architecture/*.md` paths are writable through this apply step.
+The fence opening is strict: it must be exactly
+`vibecompass-architecture-doc path=<architecture/*.md>` with one `path`
+attribute and no extra attributes. Malformed architecture-doc fences report a
+targeted error instead of being treated as "no output found".
+
+Only `architecture/*.md` paths are writable through this apply step. Component
+docs require non-empty `domain`, `feature`, `component`, and `status`
+frontmatter. The project overview file,
+`architecture/overview/project-shape.md`, may use status-only frontmatter so it
+matches hosted docs-review proposal behavior. If one accepted output contains
+multiple blocks for the same architecture path, local apply fails rather than
+silently overwriting earlier accepted content.
+
+Accepted architecture docs over the soft 12000-byte size budget are applied
+with an `oversized_architecture_doc` warning instead of being rejected. Treat
+that warning as a prompt to compact the doc unless the extra detail is needed
+for future retrieval.
 
 `vibecompass docs-review --complete` updates the marker in
 `state/docs-review.json` to `status: "completed"` once the docs have

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {
@@ -11,8 +11,10 @@
     ".": "./src/index.js"
   },
   "files": [
+    "CHANGELOG.md",
     "src/*.js",
-    "src/generators/**/*.js"
+    "src/generators/**/*.js",
+    "src/workflows/**/*.js"
   ],
   "scripts": {
     "test": "node --test src/tests/*.test.js",

package/src/docs-review.js

@@ -5,6 +5,9 @@ import { parseFrontmatter } from './frontmatter.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v2';
+const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
+
 export async function preflightDocsReview(options = {}, environment = {}) {
   validateDocsReviewMode(options);
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
@@ -59,8 +62,10 @@ export async function preflightDocsReview(options = {}, environment = {}) {
   const localProvider = resolveLocalProvider(options);
   const runtime = resolveDocsReviewRuntime(project, {
     env,
+    guided: Boolean(options.guided),
     localProvider,
     runLocal: shouldRunLocal(options),
+    anthropicEnvVar: options.anthropicEnvVar ?? 'ANTHROPIC_API_KEY',
   });
   const reviewPrompt = renderReviewPrompt({
     project,
@@ -180,14 +185,20 @@ async function applyDocsReviewOutput(options) {
   const blocks = parseArchitectureDocBlocks(source);
 
   if (blocks.length === 0) {
+    const malformedFenceCount = countMalformedArchitectureDocFences(source);
+    if (malformedFenceCount > 0) {
+      throw new Error(
+        `Malformed architecture doc fence found in ${outputPath}. Expected fence openings like \`\`\`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` with exactly one path attribute and no extra attributes.`,
+      );
+    }
+
     throw new Error(
       `No accepted architecture doc blocks found in ${outputPath}. Expected fenced blocks like \`\`\`vibecompass-architecture-doc path=architecture/domain/feature/component.md\`.`,
     );
   }
 
-  for (const block of blocks) {
-    validateArchitectureDocBlock(block);
-  }
+  validateArchitectureDocBlocks(blocks);
+  const warnings = createArchitectureDocSizeWarnings(blocks);
 
   const applied = [];
   for (const block of blocks) {
@@ -208,6 +219,7 @@ async function applyDocsReviewOutput(options) {
     applied: {
       output_path: outputPath,
       architecture_docs: applied,
+      ...(warnings.length > 0 ? { warnings } : {}),
       applied_at: new Date().toISOString(),
     },
     completed_at: new Date().toISOString(),
@@ -225,7 +237,7 @@ async function applyDocsReviewOutput(options) {
     hosted: current.hosted ?? null,
     applied: marker.applied,
     reviewPrompt: null,
-    warnings: [],
+    warnings,
     message: `Applied ${applied.length} accepted architecture doc${applied.length === 1 ? '' : 's'} and completed the docs-review marker.`,
   };
 }
@@ -357,6 +369,13 @@ function validateDocsReviewMode(options) {
 }
 
 async function promptForReviewConfig(options, environment) {
+  if (options.llm && options.model) {
+    return normalizeReviewConfig({
+      llm: options.llm,
+      model: options.model,
+    });
+  }
+
   const prompter = createPrompter(environment.io, environment.runtime);
   try {
     if (!options.llm) {
@@ -485,6 +504,10 @@ function resolveDocsReviewRuntime(project, options) {
       };
     }
 
+    if (options.guided) {
+      return { provider: 'external' };
+    }
+
     throw new Error(
       `docs-review for local-primary projects requires a hosted sync binding or ${options.anthropicEnvVar}.`,
     );
@@ -601,6 +624,32 @@ function parseArchitectureDocBlocks(source) {
   return blocks;
 }
 
+function countMalformedArchitectureDocFences(source) {
+  const fencePattern = /^```vibecompass-architecture-doc\b.*$/gm;
+  const acceptedOpeningPattern = /^```vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
+  let count = 0;
+  let match;
+
+  while ((match = fencePattern.exec(source)) !== null) {
+    if (!acceptedOpeningPattern.test(match[0])) {
+      count += 1;
+    }
+  }
+
+  return count;
+}
+
+function validateArchitectureDocBlocks(blocks) {
+  const seenPaths = new Set();
+  for (const block of blocks) {
+    if (seenPaths.has(block.path)) {
+      throw new Error(`Accepted docs-review output contains duplicate architecture doc path: ${block.path}`);
+    }
+    seenPaths.add(block.path);
+    validateArchitectureDocBlock(block);
+  }
+}
+
 function normalizeBlockPath(value) {
   return String(value ?? '').trim().replaceAll('\\', '/');
 }
@@ -625,13 +674,29 @@ function validateArchitectureDocBlock(block) {
     throw new Error(`Accepted architecture doc ${block.path} must include frontmatter.`);
   }
 
-  for (const field of ['domain', 'feature', 'component', 'status']) {
+  const requiredFields = block.path === 'architecture/overview/project-shape.md'
+    ? ['status']
+    : ['domain', 'feature', 'component', 'status'];
+  for (const field of requiredFields) {
     if (typeof frontmatter.data[field] !== 'string' || frontmatter.data[field].trim() === '') {
       throw new Error(`Accepted architecture doc ${block.path} requires non-empty frontmatter field "${field}".`);
     }
   }
 }
 
+function createArchitectureDocSizeWarnings(blocks) {
+  return blocks
+    .map((block) => {
+      const byteLength = Buffer.byteLength(ensureTrailingNewline(block.content), 'utf8');
+      if (byteLength <= ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES) {
+        return null;
+      }
+
+      return `oversized_architecture_doc: ${block.path} is ${byteLength} bytes; soft budget is ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes. Consider compacting the doc to preserve future LLM context budget.`;
+    })
+    .filter(Boolean);
+}
+
 async function submitHostedDocsReview(options) {
   if (options.runtime.provider !== 'hosted') {
     throw new Error('docs-review --submit-hosted requires a hosted sync binding in project.yaml.');
@@ -1034,9 +1099,9 @@ function renderDocsReviewMessage(options) {
 
 function renderReviewPrompt(options) {
   return [
-    '# VibeCompass Docs Review Prompt v1',
+    `# ${DOCS_REVIEW_PROMPT_VERSION}`,
     '',
-    'Run a comprehensive VibeCompass architecture documentation review for the project-memory root below. Follow this prompt exactly; do not invent a different document structure.',
+    'Run a staged VibeCompass architecture documentation review for the project-memory root below. Follow this prompt exactly; do not invent a different document structure.',
     '',
     '## Review Context',
     `- Project memory root: ${options.rootDir}`,
@@ -1049,13 +1114,35 @@ function renderReviewPrompt(options) {
     '1. Read `project.yaml`.',
     '2. Read `context.md` if present.',
     '3. Read all canonical files under `architecture/`, `decisions/`, and finalized `sessions/`.',
-    '4. Inspect the declared repositories and cite concrete source, config, and test files before making implementation claims.',
+    '4. Inspect declared repositories before making implementation claims.',
+    '',
+    '## Staged Review Protocol',
+    'Stage 1 — Evidence inventory:',
+    '- Build a compact repo inventory from file paths, manifests/config files, route/job/test directories, and existing architecture frontmatter before reading large file bodies.',
+    '- Identify candidate domains, features, components, and ownership boundaries with concrete `repo:path` evidence.',
+    '- Do not fetch or summarize broad source bodies until the coverage plan says a file is needed.',
+    '',
+    'Stage 2 — Coverage plan:',
+    '- Propose the smallest useful architecture-doc set that will let future agents understand the project and retrieve targeted context.',
+    '- Prioritize entry points, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
+    '- Mark each proposed doc as `comprehensive`, `partial`, or `initial`, with the reason and blindspots.',
+    '- Ask for user acceptance before emitting fenced architecture-doc blocks.',
+    '',
+    'Stage 3 — Bounded doc generation:',
+    '- Generate only accepted docs, one complete fenced block per architecture path.',
+    '- Keep docs concise and retrieval-oriented: explain contracts, flows, invariants, and ownership; do not rewrite source code or produce file-by-file walkthroughs.',
+    `- Soft size budget: keep each generated architecture doc under ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes unless the extra detail is necessary and called out in Blindspots or Retrieval guidance.`,
+    '- Include only the most important involved files; prefer representative entry points and owned contracts over exhaustive file lists.',
+    '',
+    'Stage 4 — Apply and verify:',
+    '- After accepted blocks are written to `state/docs-review-output.md`, run `vibecompass docs-review --apply-output`.',
+    '- Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the output.',
     '',
     '## Architecture Doc Contract',
     'When creating or updating architecture docs, use the existing VibeCompass structure:',
     '- path: `architecture/<domain-slug>/<feature-slug>/<component-slug>.md` for component docs',
     '- frontmatter fields: `domain`, `feature`, `component`, `status`, plus `repo` or `repos` when implementation-scoped',
-    '- body sections: `## Description`, `## Review metadata`, `## Details`, `## Next steps`, `## Involved files`',
+    '- body sections: `## Description`, `## Review metadata`, `## Details`, `## Retrieval guidance`, `## Next steps`, `## Involved files`',
     '',
     'Use this exact Review metadata sub-header in every generated architecture doc:',
     '',
@@ -1066,6 +1153,8 @@ function renderReviewPrompt(options) {
     '- Confidence: high | medium | low',
     '- Coverage: comprehensive | partial | initial',
     '- Evidence: repo:path references inspected before making implementation claims',
+    '- Retrieval scope: when future agents should load this doc',
+    `- Token posture: compact unless the doc intentionally exceeds ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes`,
     '- Blindspots: explicit list, or "None identified" only when evidence is comprehensive',
     '',
     '## Review Rules',
@@ -1077,12 +1166,15 @@ function renderReviewPrompt(options) {
     '6. Put uncertainty in `Blindspots`; do not fill gaps with guesses.',
     '7. Do not append real `D-NNN` decisions without explicit user acceptance. Propose candidate decisions separately.',
     '8. Do not edit `decisions/INDEX.md` directly unless a canonical decision file was explicitly accepted and appended.',
+    '9. Optimize for future retrieval: project-level docs stay compact; component docs carry focused context for a specific area.',
     '',
     '## Output Contract',
     'First provide a concise findings summary with:',
     '- mapped areas',
     '- gaps/blindspots',
-    '- proposed architecture docs',
+    '- evidence inventory summary',
+    '- coverage plan and proposed architecture docs',
+    '- token-budget risks or oversized-doc candidates',
     '- proposed decisions, if any',
     '',
     'Then, for each architecture doc the user accepts, output one fenced block exactly like this:',

package/src/generators/agent-files/index.js

@@ -8,6 +8,7 @@ import { claudeMdFormat } from './claude-md.js';
 import { agentsMdFormat } from './agents-md.js';
 import { cursorRulesFormat } from './cursor-rules.js';
 import { copilotInstructionsFormat } from './copilot-instructions.js';
+import { getWorkflowConflictScanPatterns } from '../../workflows/registry.js';
 
 const FORMATS = [
   claudeMdFormat,
@@ -17,17 +18,7 @@ const FORMATS = [
 ];
 
 const FORMAT_MAP = new Map(FORMATS.map((format) => [format.name, format]));
-const CONFLICT_SCAN_PATTERNS = [
-  'session',
-  'handoff',
-  'decisions',
-  'wip.md',
-  'review handoff',
-  'close-session',
-  'address review',
-  'builder',
-  'reviewer',
-];
+const CONFLICT_SCAN_PATTERNS = getWorkflowConflictScanPatterns();
 
 export async function syncAgentInstructionFiles(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();

package/src/generators/agent-files/template.js

@@ -1,3 +1,5 @@
+import { renderPromptCommandLines } from '../../workflows/registry.js';
+
 export function buildAgentContext(readModel) {
   return {
     projectName: readModel.project.name ?? 'Unnamed project',
@@ -16,47 +18,40 @@ export function renderSharedInstructionBody(context, options = {}) {
   const intro =
     options.intro ??
     'Use VibeCompass project memory as the source of truth before making code changes.';
+  const contextPath = `${context.rootDir}/context.md`;
 
   return [
     `# ${heading}`,
     '',
     intro,
     '',
-    `Read \`${context.rootDir}/context.md\` for the full VibeCompass workflow protocol when it exists.`,
+    `This managed block is a compact bootloader. Read \`${contextPath}\` for the full VibeCompass workflow protocol; workflow-specific details live under \`${context.rootDir}/workflows/\`.`,
     '',
     'Existing project-specific coding, style, framework, and safety instructions outside this managed block remain authoritative. This block owns only VibeCompass project-memory workflow: sessions, handoffs, decisions, docs-review, and close-out.',
     '',
-    '## Read First',
+    '## Project Snapshot',
     `- Project memory root: \`${context.rootDir}\``,
-    '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',
-    '- Read the latest finalized session note under `sessions/` before resuming work.',
-    '- Read `sessions/active/index.yaml` when it exists, then read the selected lane under `sessions/active/<lane-id>/`.',
-    '- Read the selected lane `wip.md` and `handoff.md` when they exist; they are the active builder/reviewer scratch files.',
-    '- Read relevant `architecture/` and `decisions/` files before changing implementation.',
+    ...renderProjectSnapshot(context),
     '',
-    '## Project Shape',
-    ...renderProjectShape(context),
+    '## Read Order',
+    `1. Read \`${contextPath}\`.`,
+    `2. Read the latest finalized session note under \`${context.rootDir}/sessions/\`.`,
+    `3. If present, read \`${context.rootDir}/sessions/active/index.yaml\`, then the selected lane's \`wip.md\` and \`handoff.md\`.`,
+    `4. Read relevant \`${context.rootDir}/architecture/\` and \`${context.rootDir}/decisions/\` docs before editing implementation.`,
     '',
-    '## Workflow Rules',
-    '- VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream; finalized session notes are append-only history under `sessions/YYYY-MM-DD-N-title.md`.',
-    '- Use `start session` for builder work, `join as reviewer` for review work, and `close session` / `end session` when the builder is ready to close the selected lane.',
-    '- Use `vibecompass start-session --id <lane-id>` to open a named lane for every active feature or workstream.',
-    '- Use `vibecompass list-sessions` and `vibecompass switch-session <lane-id>` to inspect or change the current lane.',
-    '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
-    '- Use optional planning mode for risky or ambiguous work: read the same context, propose scope, and record the agreed plan in the selected lane `wip.md` before implementation.',
-    '- Use `review handoff` to ask a reviewer to inspect the active handoff.',
-    '- Use `address review` to process reviewer feedback from the selected lane `wip.md` and `handoff.md`.',
-    '- End the active builder session with the `close session` prompt, which runs close-out and ends with `vibecompass close-session --session <lane-id>`; `end session` and `vibecompass end-session` are accepted aliases.',
-    '- If stale scratch files block `start-session`, read them first, then close, recover, move, or delete them intentionally before retrying.',
-    '- Keep decisions append-only in `decisions/`. Session notes may reference decisions, but decisions are the durable source of truth.',
-    '- Treat generated agent files as views. Update canonical VibeCompass project memory instead of editing managed regions.',
+    '## Prompt Commands',
+    ...renderPromptCommandLines({ rootRelativePath: context.rootDir }),
+    '- The prompt commands above are agent behaviors. The `vibecompass` CLI commands remain the filesystem mechanics behind them.',
     '',
-    '## Recent Decisions',
-    ...renderDecisionLines(context.recentDecisions),
+    '## Hard Rules',
+    '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
+    '- Keep the selected lane `wip.md` and `handoff.md` current during active builder/reviewer work.',
+    '- Keep decisions append-only in `decisions/`; append accepted architectural decisions before implementing them.',
+    '- Do not edit this managed block directly. Update canonical VibeCompass memory, then rerun package commands such as `vibecompass sync-agents`.',
   ].join('\n');
 }
 
-function renderProjectShape(context) {
+function renderProjectSnapshot(context) {
   const lines = [];
 
   if (context.description) {
@@ -71,18 +66,22 @@ function renderProjectShape(context) {
     lines.push(`- Repo \`${repo.id}\`: ${repo.remote}`);
   }
 
-  for (const domain of context.domains.slice(0, 8)) {
-    const features = domain.features.map((feature) => feature.feature).join(', ');
-    lines.push(`- ${domain.domain}: ${features || 'No features recorded yet.'}`);
+  const domainCount = context.domains.length;
+  if (domainCount > 0) {
+    lines.push(`- Architecture domains recorded: ${domainCount}`);
   }
 
-  return lines.length > 0 ? lines : ['- No architecture domains recorded yet.'];
-}
+  if (context.recentDecisions.length > 0) {
+    lines.push(`- Latest decision: ${renderDecisionLine(context.recentDecisions[0])}`);
+  }
 
-function renderDecisionLines(decisions) {
-  if (!decisions || decisions.length === 0) {
-    return ['- No decisions recorded yet.'];
+  if (context.recentSessions.length > 0) {
+    lines.push(`- Latest session: ${context.recentSessions[0].title ?? context.recentSessions[0].path}`);
   }
 
-  return decisions.map((decision) => `- D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`);
+  return lines.length > 0 ? lines : ['- No project details recorded yet.'];
+}
+
+function renderDecisionLine(decision) {
+  return `D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`;
 }

package/src/project-memory.js

@@ -364,7 +364,9 @@ function parseArchitectureDocument(options) {
     }
 
     const data = frontmatter.data;
-    const requiredFields = ['domain', 'feature', 'component', 'status'];
+    const requiredFields = options.relativePath === 'architecture/overview/project-shape.md'
+      ? ['status']
+      : ['domain', 'feature', 'component', 'status'];
 
     for (const field of requiredFields) {
       if (typeof data[field] !== 'string' || data[field].trim() === '') {

package/src/refresh-workflow.js

@@ -161,6 +161,9 @@ function isGeneratedWorkflowGuide(kind, content) {
   if (kind === 'sessions-guide') {
     return content.includes('Those scratch files are session-scoped working artifacts, not finalized history.');
   }
+  if (kind === 'workflow-docs-review') {
+    return content.includes('Generated by VibeCompass. This file is a package-owned workflow guide');
+  }
 
   return false;
 }

package/src/scaffold.js

@@ -1,6 +1,9 @@
 import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveWorkflowSettings } from './workflow.js';
+import { getGeneratedWorkflowFiles, renderPromptCommandLines } from './workflows/registry.js';
+import { renderManagedBlock } from './generators/agent-files/markers.js';
+import { renderSharedInstructionBody } from './generators/agent-files/template.js';
 
 export async function scaffoldInitFiles(options) {
   const createdFiles = [];
@@ -59,7 +62,7 @@ export async function scaffoldInitFiles(options) {
   await writeFile(contextFilePath, workflowScaffold.context.content, 'utf8');
   createdFiles.push(contextFilePath);
 
-  for (const file of workflowScaffold.guides) {
+  for (const file of [...workflowScaffold.guides, ...workflowScaffold.workflowFiles]) {
     const outcome = await writeIfMissing(file.path, file.content);
     if (outcome.created) {
       createdFiles.push(file.path);
@@ -124,12 +127,20 @@ export function buildWorkflowScaffoldFiles(options) {
       content: generateSessionsGuide(options.projectConfig),
     },
   ];
+  const workflowFiles = getGeneratedWorkflowFiles({
+    rootRelativePath: options.rootRelativePath,
+  }).map((file) => ({
+    kind: file.kind,
+    path: path.join(options.rootDir, file.relativePath),
+    content: file.content,
+  }));
 
   return {
     contextFilePath,
     context,
     guides,
-    files: [context, ...guides],
+    workflowFiles,
+    files: [context, ...guides, ...workflowFiles],
   };
 }
 
@@ -193,6 +204,7 @@ function generateContextMarkdown(options) {
   const projectName = options.projectConfig.name;
   const rootRelativePath = options.rootRelativePath;
   const workflow = resolveWorkflowSettings(options.projectConfig);
+  const promptCommands = renderPromptCommandLines({ rootRelativePath }).join('\n');
   const repos = options.projectConfig.repos
     .map((repo) => `- \`${repo.id}\` → ${repo.remote}`)
     .join('\n');
@@ -233,12 +245,7 @@ ${repos}
 | "join as reviewer" | Reviewer | No — reviews the builder's work, appends findings, and updates handoff guidance |
 
 ## Session prompt commands
-- \`start session\` — builder role trigger
-- \`join as reviewer\` — reviewer role trigger
-- \`planning mode\` — optional prompt-level mode for scoping work before implementation
-- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
-- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
+${promptCommands}
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
 Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
@@ -250,7 +257,7 @@ ${renderWorkflowDefaults(workflow)}
 ## Documentation coverage
 - The architecture, decision, and session files created by init are an initial scaffold, not a comprehensive codebase review.
 - Before risky implementation work, inspect the relevant code and update the affected architecture docs.
-- Run \`vibecompass docs-review --guided\` when you want a comprehensive documentation review. That command is explicit because it may inspect source files and use AI or hosted scan infrastructure.
+- Use the \`docs review\` prompt command when you want the current AI session to run a comprehensive documentation review. It may run \`vibecompass docs-review --guided\` as package mechanics to record marker state and print the canonical review contract.
 
 ## Session startup
 1. Read \`${rootRelativePath}/project.yaml\`.
@@ -387,7 +394,7 @@ Not yet documented:
 Before changing any undocumented area, inspect the relevant code and update or add architecture docs.
 
 ## Next steps
-- Run \`vibecompass docs-review --guided\` for a comprehensive documentation review.
+- Use the \`docs review\` prompt command for a comprehensive documentation review.
 - Replace this placeholder with domain/feature/component docs as the project map becomes evidence-backed.
 - Keep architecture docs aligned with implementation changes during each builder session.
 
@@ -445,7 +452,7 @@ Initialized VibeCompass project memory for ${projectConfig.name}.
 ${repoLines}
 
 ## Next session should start with
-1. Run \`vibecompass docs-review --guided\` if you want a comprehensive documentation review.
+1. Use the \`docs review\` prompt command if you want a comprehensive documentation review.
 2. Inspect relevant code before making implementation changes in areas not covered by architecture docs.
 3. Replace starter placeholders with evidence-backed domain/feature/component docs.
 `;
@@ -531,33 +538,21 @@ Those scratch files are session-scoped working artifacts, not finalized history.
 }
 
 function generateClaudeTemplate(options) {
-  const workflow = resolveWorkflowSettings(options.projectConfig);
+  return [
+    generateClaudeSessionHeader(options),
+    renderManagedBlock(renderSharedInstructionBody(buildScaffoldAgentContext(options), {
+      heading: `${options.projectConfig.name} Claude Instructions`,
+      intro:
+        'Claude should use VibeCompass project memory as the source of truth before planning, editing, or reviewing code.',
+    })),
+  ].join('\n');
+}
 
+function generateClaudeSessionHeader(options) {
   return `# ${options.projectConfig.name} Workspace
 
 Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 
-## Session roles
-
-| Entry trigger | Role | Owns session lifecycle? |
-|---|---|---|
-| "start session" | Builder | Yes |
-| "join as reviewer" | Reviewer | No |
-| "planning mode" | Planner | No — scopes work inside the selected active lane before implementation |
-
-## Prompt commands
-
-- \`start session\` — builder role trigger
-- \`join as reviewer\` — reviewer role trigger
-- \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
-- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
-- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
-
-These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
-\`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
-
 ## Current session
 
 **Update this block at the start and end of every session.**
@@ -569,64 +564,28 @@ Last thing completed: Project memory bootstrap completed.
 Blockers: None recorded.
 Next session should: Read \`${options.contextRelativeToToolingRoot}\`, then open the first builder or reviewer session.
 \`\`\`
-
-## Startup
-- Read \`${options.contextRelativeToToolingRoot}\`
-- Follow the builder/reviewer protocol defined there
-- Use \`vibecompass start-session --id <lane-id>\`, \`vibecompass list-sessions\`, \`vibecompass switch-session <lane-id>\`, and \`vibecompass close-session --session <lane-id>\` to manage active lanes when possible
-- Treat \`${options.rootRelativePath}/sessions/active/index.yaml\` as the current lane source of truth; this Current session block is only a continuity summary
-- Keep the selected lane's \`${options.rootRelativePath}/sessions/active/<lane-id>/wip.md\` and \`${options.rootRelativePath}/sessions/active/<lane-id>/handoff.md\` current during an active session
-- Use planning mode when scope is unclear; record the agreed plan in the selected lane's \`wip.md\` before implementing
-- If stale scratch files block \`start-session\`, read them first, then close, recover, move, or delete them intentionally before retrying
-- Workflow defaults:
-${renderWorkflowDefaults(workflow)}
 `;
 }
 
 function generateAgentsTemplate(options) {
-  const workflow = resolveWorkflowSettings(options.projectConfig);
-
-  return `# ${options.projectConfig.name} Workspace
-
-This workspace uses VibeCompass project memory rooted at \`${options.rootRelativePath}\`.
-
-## Session roles
-
-| Entry trigger | Role | Owns session lifecycle? |
-|---|---|---|
-| "start session" | Builder | Yes — opens and closes the session lifecycle |
-| "join as reviewer" | Reviewer | No — reviews the builder's work and updates the handoff |
-| "planning mode" | Planner | No — scopes work inside the selected active lane before implementation |
-
-## Prompt commands
-
-- \`start session\` — builder role trigger
-- \`join as reviewer\` — reviewer role trigger
-- \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
-- \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
-- \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
-- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
+  return renderManagedBlock(renderSharedInstructionBody(buildScaffoldAgentContext(options), {
+    heading: `${options.projectConfig.name} Agent Instructions`,
+    intro:
+      'Agents should use VibeCompass project memory as the source of truth before planning, editing, or reviewing code.',
+  }));
+}
 
-These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
-\`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
-
-## Startup
-Before doing substantive work:
-1. Read \`${options.contextRelativeToToolingRoot}\`.
-2. Read the latest finalized session note under \`${options.rootRelativePath}/sessions/\`.
-3. If present, read \`${options.rootRelativePath}/sessions/active/index.yaml\` and choose the selected or current lane.
-4. If present, read \`${options.rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
-5. If present, read \`${options.rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
-6. Read the relevant docs under \`${options.rootRelativePath}/architecture/\` and \`${options.rootRelativePath}/decisions/\`.
-
-## Working rule
-Treat \`${options.contextRelativeToToolingRoot}\` as the local workflow source of truth for the builder/reviewer protocol and session scratch-file structure. When the package provides \`start-session\` / \`close-session\`, prefer those commands over hand-editing boilerplate.
-Use planning mode when scope is unclear; record the agreed plan in the selected lane's \`wip.md\` before implementing.
-If stale scratch files block \`start-session\`, read them first, then close, recover, move, or delete them intentionally before retrying.
-- Workflow defaults:
-${renderWorkflowDefaults(workflow)}
-`;
+function buildScaffoldAgentContext(options) {
+  return {
+    projectName: options.projectConfig.name ?? 'Unnamed project',
+    description: options.projectConfig.description ?? null,
+    mode: options.projectConfig.mode ?? null,
+    rootDir: options.rootRelativePath,
+    repos: options.projectConfig.repos ?? [],
+    domains: [],
+    recentDecisions: [],
+    recentSessions: [],
+  };
 }
 
 function renderWorkflowDefaults(workflow) {

package/src/setup.js

@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 import { getSupportedAgentFilePaths } from './generators/agent-files/index.js';
 import { END_MARKER, START_MARKER } from './generators/agent-files/markers.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { getWorkflowConflictScanPatterns } from './workflows/registry.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -859,17 +860,7 @@ function writeAgentAdoptionPreview(prompter, candidates) {
 }
 
 function scanPotentialAgentWorkflowConflicts(content) {
-  const patterns = [
-    'session',
-    'handoff',
-    'decisions',
-    'wip.md',
-    'review handoff',
-    'close-session',
-    'address review',
-    'builder',
-    'reviewer',
-  ];
+  const patterns = getWorkflowConflictScanPatterns();
 
   return content
     .split(/\r?\n/)

package/src/workflows/registry.js

@@ -0,0 +1,138 @@
+export const WORKFLOW_REGISTRY = [
+  {
+    id: 'session-lifecycle',
+    title: 'Session lifecycle',
+    detailPath: 'context.md',
+    summary: 'Builder/reviewer lane lifecycle, handoffs, planning mode, and close-out.',
+    promptCommands: [
+      { trigger: 'start session', summary: 'builder role trigger' },
+      { trigger: 'join as reviewer', summary: 'reviewer role trigger' },
+      { trigger: 'planning mode', summary: 'optional prompt-level mode for scoping work before implementation' },
+      { trigger: 'review handoff', summary: 'reviewer reads the selected lane handoff and appends findings' },
+      { trigger: 'address review', summary: 'builder processes reviewer feedback from the selected lane scratch files' },
+      { trigger: 'close session', summary: 'builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>`; `end session` and `vibecompass end-session` are accepted aliases' },
+    ],
+  },
+  {
+    id: 'docs-review',
+    title: 'Docs review',
+    detailPath: 'workflows/docs-review.md',
+    summary: 'Generate evidence-backed architecture docs from the user\'s preferred AI session.',
+    promptCommands: [
+      { trigger: 'docs review', summary: 'agent-led architecture documentation review using the preferred LLM prompt box' },
+    ],
+    generatedFileKind: 'workflow-docs-review',
+    renderFile: renderDocsReviewWorkflow,
+  },
+];
+
+export function getPromptCommands() {
+  return WORKFLOW_REGISTRY.flatMap((workflow) =>
+    workflow.promptCommands.map((command) => ({
+      ...command,
+      workflowId: workflow.id,
+      workflowTitle: workflow.title,
+      detailPath: workflow.detailPath,
+    })),
+  );
+}
+
+export function getWorkflowConflictScanPatterns() {
+  const patterns = new Set([
+    'session',
+    'handoff',
+    'decisions',
+    'wip.md',
+    'builder',
+    'reviewer',
+  ]);
+
+  for (const command of getPromptCommands()) {
+    const normalizedTrigger = command.trigger.toLowerCase();
+    patterns.add(normalizedTrigger);
+    patterns.add(slugifyPromptTrigger(normalizedTrigger));
+  }
+
+  return Array.from(patterns);
+}
+
+export function getGeneratedWorkflowFiles(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  return WORKFLOW_REGISTRY
+    .filter((workflow) => typeof workflow.renderFile === 'function')
+    .map((workflow) => ({
+      kind: workflow.generatedFileKind,
+      relativePath: workflow.detailPath,
+      content: workflow.renderFile({
+        rootRelativePath,
+        workflow,
+      }),
+    }));
+}
+
+export function renderPromptCommandLines(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  return getPromptCommands().map((command) => {
+    const detailPath = command.detailPath
+      ? ` Read \`${joinRootRelative(rootRelativePath, command.detailPath)}\` for the full workflow.`
+      : '';
+    return `- \`${command.trigger}\` — ${command.summary}.${detailPath}`;
+  });
+}
+
+function renderDocsReviewWorkflow(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  const projectYamlPath = joinRootRelative(rootRelativePath, 'project.yaml');
+  const contextPath = joinRootRelative(rootRelativePath, 'context.md');
+  const architecturePath = joinRootRelative(rootRelativePath, 'architecture/');
+  const decisionsPath = joinRootRelative(rootRelativePath, 'decisions/');
+  const sessionsPath = joinRootRelative(rootRelativePath, 'sessions/');
+  const outputPath = joinRootRelative(rootRelativePath, 'state/docs-review-output.md');
+
+  return `# VibeCompass Workflow — docs review
+
+Generated by VibeCompass. This file is a package-owned workflow guide and may be refreshed by \`vibecompass refresh-workflow --apply\`.
+
+## Prompt trigger
+
+When the user says \`docs review\`, run this workflow inside the current Claude Code, Codex, Cursor, or Copilot session. The npm package owns state markers and apply mechanics; the AI session owns repository inspection and writing accepted architecture docs.
+
+## Goal
+
+Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`.
+
+## Steps
+
+1. Read \`${projectYamlPath}\`, \`${contextPath}\`, existing \`${architecturePath}\`, \`${decisionsPath}\`, and finalized \`${sessionsPath}\` notes.
+2. Inspect the declared source repos in stages:
+   - inventory paths, manifests, configs, route/job/test directories, and existing architecture frontmatter first
+   - produce a coverage plan before reading broad source bodies
+   - read targeted source files only when the coverage plan needs evidence
+3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
+4. Present the evidence inventory, coverage plan, proposed architecture docs, blindspots, and token-budget risks before generating accepted docs.
+5. Draft only architecture docs the user accepts. Accepted docs must be fenced exactly as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`.
+6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
+7. Write the accepted fenced blocks to \`${outputPath}\`.
+8. Run \`vibecompass docs-review --apply-output\` to validate and apply the accepted blocks. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --complete\` after confirming the marker should be completed.
+9. Run \`vibecompass status\` to confirm the docs-review marker is complete. Report the applied architecture paths, any parser warnings such as oversized docs, and any blindspots documented in the accepted docs-review output.
+
+## Rules
+
+- Do not duplicate the full canonical review prompt in this file. The package command prints that contract from its current implementation.
+- Follow the canonical review prompt for evidence, blindspot, and decision-recommendation constraints.
+- Treat the package-owned prompt as the source of truth. Tool-specific skills may wrap this workflow, but should not define a divergent docs-review protocol.
+- Do not edit generated agent files directly. Update VibeCompass project memory or rerun package commands instead.
+`;
+}
+
+function slugifyPromptTrigger(trigger) {
+  return trigger.trim().replace(/\s+/g, '-');
+}
+
+function joinRootRelative(rootRelativePath, relativePath) {
+  if (!rootRelativePath || rootRelativePath === '.') {
+    return relativePath;
+  }
+
+  return `${rootRelativePath.replace(/\/$/, '')}/${relativePath}`;
+}