@vibecompass/vibecompass 0.4.0 → 0.5.0

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,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
+- 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
@@ -144,6 +145,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:
 
@@ -283,7 +289,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 +297,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 +681,18 @@ 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.
 
 `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.5.0",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/docs-review.js

@@ -59,8 +59,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 +182,19 @@ 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 applied = [];
   for (const block of blocks) {
@@ -357,6 +364,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 +499,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 +619,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,7 +669,10 @@ 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}".`);
     }

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/)