@vibecompass/vibecompass 0.5.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

@@ -31,6 +31,7 @@ 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`
@@ -69,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:
@@ -194,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
@@ -205,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
@@ -694,6 +707,11 @@ 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
 landed, preserving the recorded `llm` / `model` so future sessions know

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.5.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();
@@ -195,6 +198,7 @@ async function applyDocsReviewOutput(options) {
   }
 
   validateArchitectureDocBlocks(blocks);
+  const warnings = createArchitectureDocSizeWarnings(blocks);
 
   const applied = [];
   for (const block of blocks) {
@@ -215,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(),
@@ -232,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.`,
   };
 }
@@ -679,6 +684,19 @@ function validateArchitectureDocBlock(block) {
   }
 }
 
+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.');
@@ -1081,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}`,
@@ -1096,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:',
     '',
@@ -1113,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',
@@ -1124,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/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}`;
+}