@vibecompass/vibecompass 0.3.4 → 0.5.0

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/read-model.js

@@ -14,7 +14,7 @@ export async function loadProjectReadModel(rootDir) {
     throw new Error(`Cannot build read model with canonical parse errors.\n${details}`);
   }
 
-  const existingManifest = await readManifestIfPresent(rootDir);
+  const existingManifest = normalizeReadableManifest(await readManifestIfPresent(rootDir));
   const currentManifest = generateStateManifest(scanResult, {
     generatedAt: existingManifest?.generated_at ?? new Date(),
     sync: existingManifest?.sync,
@@ -555,3 +555,19 @@ async function readManifestIfPresent(rootDir) {
     return null;
   }
 }
+
+function normalizeReadableManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') {
+    return null;
+  }
+
+  if (!manifest.canonical || typeof manifest.canonical !== 'object') {
+    return null;
+  }
+
+  if (typeof manifest.canonical.manifest_hash !== 'string') {
+    return null;
+  }
+
+  return manifest;
+}

package/src/refresh-workflow.js

@@ -0,0 +1,236 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { inspectProjectCompatibility } from './compatibility.js';
+import { prepareStateManifest, writeStateManifest } from './manifest.js';
+import { serializeProjectConfig } from './project-yaml.js';
+import { buildWorkflowScaffoldFiles } from './scaffold.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import { PACKAGE_VERSION } from './version.js';
+
+export async function refreshWorkflow(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const toolingRootDir = options.toolingRootDir
+    ? path.resolve(cwd, options.toolingRootDir)
+    : cwd;
+  const apply = Boolean(options.apply);
+  const dryRun = !apply;
+
+  const compatibility = await inspectProjectCompatibility({ rootDir, cwd });
+  if (apply && compatibility.package.status === 'ahead' && !options.allowDowngradeTemplates) {
+    throw new Error(
+      'This root was refreshed by a newer VibeCompass package. Pass --allow-downgrade-templates to apply older templates with this CLI.',
+    );
+  }
+
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const projectConfig = await readProjectConfig(projectFilePath);
+  const rootRelativePath = toPosix(path.relative(toolingRootDir, rootDir) || '.');
+  const contextRelativeToToolingRoot = toPosix(
+    path.relative(toolingRootDir, path.join(rootDir, 'context.md')) || 'context.md',
+  );
+
+  const workflowFiles = await planWorkflowFiles({
+    rootDir,
+    toolingRootDir,
+    projectConfig,
+    rootRelativePath,
+    contextRelativeToToolingRoot,
+  });
+
+  if (apply) {
+    await applyWorkflowFiles(workflowFiles);
+  }
+
+  const projectStamp = planProjectStamp(projectConfig, compatibility, {
+    updatePackageStamp: Boolean(options.updatePackageStamp),
+  });
+  if (apply && projectStamp.changed) {
+    await mkdir(path.dirname(projectFilePath), { recursive: true });
+    await writeFile(projectFilePath, serializeProjectConfig(projectStamp.projectConfig), 'utf8');
+  }
+
+  const manifest = apply
+    ? await writeStateManifest(rootDir)
+    : await prepareStateManifest(rootDir);
+
+  const agentFileSync = await syncAgentInstructionFiles({
+    rootDir,
+    toolingRootDir,
+    dryRun,
+  });
+
+  return {
+    rootDir,
+    toolingRootDir,
+    dryRun,
+    applied: apply,
+    compatibility,
+    projectFile: {
+      path: projectFilePath,
+      status: projectStamp.status,
+      changed: projectStamp.changed,
+      packageVersion: projectStamp.packageVersion,
+      warning: projectStamp.warning,
+    },
+    workflowFiles: workflowFiles.map((file) => ({
+      kind: file.kind,
+      path: file.path,
+      relativePath: toPosix(path.relative(rootDir, file.path)),
+      status: file.status,
+      changed: file.changed,
+      warning: file.warning,
+    })),
+    manifest: {
+      path: manifest.manifestPath,
+      status: apply ? 'updated' : 'planned-update',
+      documentCount: manifest.manifest.canonical.document_count,
+      warningCount: manifest.manifest.canonical.warning_count,
+    },
+    agentFileSync,
+  };
+}
+
+async function readProjectConfig(projectFilePath) {
+  try {
+    return parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${path.dirname(projectFilePath)}. Run "vibecompass init" first.`);
+    }
+
+    throw error;
+  }
+}
+
+async function planWorkflowFiles(options) {
+  const scaffold = buildWorkflowScaffoldFiles(options);
+  const files = [];
+
+  for (const file of scaffold.files) {
+    const existingContent = await readExistingFile(file.path);
+    const safety = resolveWorkflowFileSafety(file, existingContent);
+    const changed = safety.status !== 'skipped' && existingContent !== file.content;
+    files.push({
+      ...file,
+      existingContent,
+      status: changed ? (existingContent === null ? 'create' : 'update') : safety.status,
+      changed,
+      warning: safety.warning,
+    });
+  }
+
+  return files;
+}
+
+function resolveWorkflowFileSafety(file, existingContent) {
+  if (existingContent === null) {
+    return { status: 'create', warning: null };
+  }
+
+  if (existingContent === file.content) {
+    return { status: 'unchanged', warning: null };
+  }
+
+  if (file.kind === 'context') {
+    return { status: 'update', warning: null };
+  }
+
+  if (isGeneratedWorkflowGuide(file.kind, existingContent)) {
+    return { status: 'update', warning: null };
+  }
+
+  return {
+    status: 'skipped',
+    warning: 'Existing workflow guide does not match a VibeCompass-generated guide shape; left untouched.',
+  };
+}
+
+function isGeneratedWorkflowGuide(kind, content) {
+  // These sentinel strings are the safety boundary for refreshing guide files.
+  // Keep them in lockstep with the scaffold guide templates.
+  if (kind === 'architecture-guide') {
+    return content.includes('Each component doc is canonical. This README is only a convenience guide.');
+  }
+  if (kind === 'decisions-guide') {
+    return content.includes('This README is guidance only; canonical decision content lives in the domain files.');
+  }
+  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;
+}
+
+// Refresh writes are intentionally non-atomic, matching init/scaffold behavior.
+async function applyWorkflowFiles(files) {
+  for (const file of files) {
+    if (!file.changed || file.status === 'skipped') {
+      continue;
+    }
+
+    await mkdir(path.dirname(file.path), { recursive: true });
+    await writeFile(file.path, file.content, 'utf8');
+  }
+}
+
+function planProjectStamp(projectConfig, compatibility, options) {
+  const currentMetadata = projectConfig.metadata && typeof projectConfig.metadata === 'object'
+    ? projectConfig.metadata
+    : {};
+  const currentStamp = currentMetadata.package_version;
+  const hasStringStamp = typeof currentStamp === 'string' && currentStamp.trim() !== '';
+  const missingStamp = currentStamp === undefined || currentStamp === null || currentStamp === '';
+  const shouldStamp = missingStamp || Boolean(options.updatePackageStamp);
+
+  if (!shouldStamp) {
+    return {
+      projectConfig,
+      status: 'unchanged',
+      changed: false,
+      packageVersion: hasStringStamp ? currentStamp : null,
+      warning: ['behind', 'invalid'].includes(compatibility.package.status)
+        ? 'Existing package stamp left untouched; pass --update-package-stamp to update it.'
+        : null,
+    };
+  }
+
+  const nextConfig = {
+    ...projectConfig,
+    metadata: {
+      ...currentMetadata,
+      package_version: PACKAGE_VERSION,
+    },
+  };
+  const changed = currentStamp !== PACKAGE_VERSION;
+
+  return {
+    projectConfig: nextConfig,
+    status: changed ? (missingStamp ? 'stamp-create' : 'stamp-update') : 'unchanged',
+    changed,
+    packageVersion: PACKAGE_VERSION,
+    warning: null,
+  };
+}
+
+async function readExistingFile(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}

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 = [];
@@ -53,27 +56,13 @@ export async function scaffoldInitFiles(options) {
     };
   }
 
-  const contextFilePath = path.join(options.rootDir, 'context.md');
+  const workflowScaffold = buildWorkflowScaffoldFiles(options);
+  const contextFilePath = workflowScaffold.contextFilePath;
   // context.md is a derived artifact owned by the package; regenerate it on rerun.
-  await writeFile(contextFilePath, generateContextMarkdown(options), 'utf8');
+  await writeFile(contextFilePath, workflowScaffold.context.content, 'utf8');
   createdFiles.push(contextFilePath);
 
-  const workflowFiles = [
-    {
-      path: path.join(options.rootDir, 'architecture', 'README.md'),
-      content: generateArchitectureGuide(options.projectConfig),
-    },
-    {
-      path: path.join(options.rootDir, 'decisions', 'README.md'),
-      content: generateDecisionsGuide(options.projectConfig),
-    },
-    {
-      path: path.join(options.rootDir, 'sessions', 'README.md'),
-      content: generateSessionsGuide(options.projectConfig),
-    },
-  ];
-
-  for (const file of workflowFiles) {
+  for (const file of [...workflowScaffold.guides, ...workflowScaffold.workflowFiles]) {
     const outcome = await writeIfMissing(file.path, file.content);
     if (outcome.created) {
       createdFiles.push(file.path);
@@ -113,6 +102,48 @@ export async function scaffoldInitFiles(options) {
   };
 }
 
+export function buildWorkflowScaffoldFiles(options) {
+  const contextFilePath = path.join(options.rootDir, 'context.md');
+  const context = {
+    kind: 'context',
+    path: contextFilePath,
+    content: generateContextMarkdown(options),
+  };
+
+  const guides = [
+    {
+      kind: 'architecture-guide',
+      path: path.join(options.rootDir, 'architecture', 'README.md'),
+      content: generateArchitectureGuide(options.projectConfig),
+    },
+    {
+      kind: 'decisions-guide',
+      path: path.join(options.rootDir, 'decisions', 'README.md'),
+      content: generateDecisionsGuide(options.projectConfig),
+    },
+    {
+      kind: 'sessions-guide',
+      path: path.join(options.rootDir, 'sessions', 'README.md'),
+      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,
+    workflowFiles,
+    files: [context, ...guides, ...workflowFiles],
+  };
+}
+
 async function writeIfMissing(filePath, content) {
   if (await fileExists(filePath)) {
     return { created: false };
@@ -173,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');
@@ -213,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\`.
@@ -230,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\`.
@@ -367,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.
 
@@ -425,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.
 `;
@@ -511,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.**
@@ -549,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) {