@vibecompass/vibecompass 0.3.3 → 0.3.4

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://vibecompass.dev">
+    <img src="https://raw.githubusercontent.com/jack-whimvy/vibecompass/main/brand/logo-a4.png" alt="VibeCompass" height="96" />
+  </a>
+</p>
+
 # @vibecompass/vibecompass
 
 Local-first project-memory core for [VibeCompass](https://vibecompass.dev).
@@ -243,7 +249,16 @@ npx -y @vibecompass/vibecompass sync-agents --root .compass
 ```
 
 Content outside those markers is preserved. Existing files without markers are
-reported as warnings and left untouched.
+reported as warnings and left untouched unless you explicitly adopt them:
+
+```bash
+npx -y @vibecompass/vibecompass sync-agents --root .compass --adopt-existing
+```
+
+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
+same adoption step for existing files, but the prompt defaults to no.
 
 Connect hosted VibeCompass later when you want browser views, team sync, or hosted docs-review:
 
@@ -314,6 +329,7 @@ Options:
 - `--with-workflow`: generate `context.md` plus workflow guide files
 - `--with-claude`: create a starter `CLAUDE.md` if it does not already exist
 - `--with-agents`: create a starter `AGENTS.md` if it does not already exist
+- `--adopt-existing-agent-files`: append managed blocks to existing unmarked agent files
 - `--start-session`: open the first builder session after init
 - `--session-working-on <text>`: required with `--start-session` outside guided mode
 - `--session-id <lane-id>`: required with `--start-session`; names the first builder lane
@@ -440,12 +456,13 @@ Options:
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--tooling-root <path>`: directory where agent files are written; defaults to cwd
 - `--format <name>`: optional format filter: `claude_md`, `agents_md`, `cursor_rules`, or `copilot_instructions`
+- `--adopt-existing`: append managed blocks to existing unmarked files
 - `--dry-run`: show planned writes without changing files
 
 This command generates enabled agent-instruction files from canonical project
 memory. It creates missing files with managed markers, replaces existing
 managed regions, preserves content outside markers, and warns instead of
-overwriting existing unmarked files.
+overwriting existing unmarked files unless `--adopt-existing` is supplied.
 
 ### `vibecompass docs-review`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -78,6 +78,14 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Left existing ${filePath} untouched\n`);
     }
 
+    if (initPlan.agentFileSyncPlan) {
+      const agentFileSync = await syncAgentInstructionFiles({
+        ...initPlan.agentFileSyncPlan,
+        ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+      });
+      writeAgentFileSyncResult(io, agentFileSync);
+    }
+
     if (initPlan.sessionPlan) {
       const sessionResult = await startProjectSession({
         rootDir: initPlan.initOptions.rootDir,
@@ -402,6 +410,11 @@ export function parseCliArgs(argv) {
       continue;
     }
 
+    if (token === '--adopt-existing-agent-files') {
+      parsed.adoptExistingAgentFiles = true;
+      continue;
+    }
+
     if (token === '--start-session') {
       parsed.startSession = true;
       continue;
@@ -508,6 +521,7 @@ export function parseCliArgs(argv) {
       sessionId: parsed.sessionId,
       closeSessionGitPublish: parsed.closeSessionGitPublish,
       closeSessionGitRemote: parsed.closeSessionGitRemote,
+      adoptExistingAgentFiles: parsed.adoptExistingAgentFiles,
       ...(parsed.withWorkflow || parsed.withClaude || parsed.withAgents
         ? {
             bootstrap: {
@@ -804,6 +818,11 @@ function parseSyncAgentsArgs(argv) {
       continue;
     }
 
+    if (token === '--adopt-existing') {
+      parsed.adoptExisting = true;
+      continue;
+    }
+
     if (!token.startsWith('--')) {
       throw new Error(`Unexpected argument "${token}".`);
     }
@@ -1087,6 +1106,10 @@ function writeAgentFileSyncResult(io, result) {
     const suffix = item.warning ? ` — ${item.warning}` : '';
     const stream = item.warning ? io.stderr : io.stdout;
     stream.write(`- ${item.relativePath}: ${item.status}${suffix}\n`);
+    if (item.conflicts?.length > 0) {
+      const lineNumbers = item.conflicts.map((conflict) => conflict.line).join(', ');
+      io.stderr.write(`  possible workflow overlap on lines ${lineNumbers}; review existing instructions if behavior conflicts.\n`);
+    }
   }
 }
 
@@ -1138,6 +1161,7 @@ function usageText() {
     '  --with-workflow                      Scaffold context.md and workflow guide files',
     '  --with-claude                        Create a starter CLAUDE.md if missing',
     '  --with-agents                        Create a starter AGENTS.md if missing',
+    '  --adopt-existing-agent-files         Adopt existing unmarked agent files after init',
     '  --start-session                      Open the first builder session after init',
     '  --session-working-on <text>          Required with --start-session outside guided mode',
     '  --session-id <lane-id>                Required with --start-session; names the first builder lane',
@@ -1187,6 +1211,7 @@ function usageText() {
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',
     '  --format <name>                      Optional format: claude_md, agents_md, cursor_rules, copilot_instructions',
+    '  --adopt-existing                     Append managed blocks to existing unmarked files',
     '  --dry-run                            Show planned writes without changing files',
     '',
     'Sync transport options:',

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

@@ -17,6 +17,17 @@ 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',
+];
 
 export async function syncAgentInstructionFiles(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
@@ -26,6 +37,8 @@ export async function syncAgentInstructionFiles(options = {}) {
     : cwd;
   const requestedFormat = normalizeOptionalString(options.format);
   const dryRun = Boolean(options.dryRun);
+  const adoptExisting = Boolean(options.adoptExisting);
+  const existingOnly = Boolean(options.existingOnly);
 
   const projectConfig = await readProjectConfig(rootDir);
   const selection = resolveEnabledFormats(projectConfig, requestedFormat);
@@ -56,8 +69,27 @@ export async function syncAgentInstructionFiles(options = {}) {
   for (const format of selection.formats) {
     const outputPath = path.join(toolingRootDir, format.path);
     const existingContent = await readExistingFile(outputPath);
+
+    if (existingOnly && existingContent === null) {
+      results.push({
+        format: format.name,
+        path: outputPath,
+        relativePath: toPosix(path.relative(toolingRootDir, outputPath)),
+        status: 'skipped-missing',
+        warning: null,
+        changed: false,
+        conflicts: [],
+      });
+      continue;
+    }
+
     const generatedContent = format.render(context);
-    const applied = applyManagedBlock(existingContent, generatedContent);
+    const applied = applyManagedBlock(existingContent, generatedContent, {
+      adoptExisting,
+    });
+    const conflicts = applied.status === 'adopt'
+      ? scanPotentialWorkflowConflicts(existingContent)
+      : [];
 
     if (!dryRun && applied.warning === null && applied.content !== existingContent) {
       await mkdir(path.dirname(outputPath), { recursive: true });
@@ -71,6 +103,7 @@ export async function syncAgentInstructionFiles(options = {}) {
       status: dryRun && applied.warning === null ? `dry-run-${applied.status}` : applied.status,
       warning: applied.warning,
       changed: applied.warning === null && applied.content !== existingContent,
+      conflicts,
     });
   }
 
@@ -86,6 +119,10 @@ export function getSupportedAgentFormats() {
   return FORMATS.map((format) => format.name);
 }
 
+export function getSupportedAgentFilePaths() {
+  return FORMATS.map((format) => format.path);
+}
+
 async function readProjectConfig(rootDir) {
   const source = await readFile(path.join(rootDir, 'project.yaml'), 'utf8');
   return parseSimpleYaml(source, { sourceName: 'project.yaml' });
@@ -145,3 +182,22 @@ function normalizeOptionalString(value) {
 function toPosix(value) {
   return value.split(path.sep).join('/');
 }
+
+function scanPotentialWorkflowConflicts(content) {
+  if (typeof content !== 'string' || content.trim() === '') {
+    return [];
+  }
+
+  return content
+    .split(/\r?\n/)
+    .map((line, index) => ({
+      line: index + 1,
+      text: line,
+      normalized: line.toLowerCase(),
+    }))
+    .filter((entry) => CONFLICT_SCAN_PATTERNS.some((pattern) => entry.normalized.includes(pattern)))
+    .map(({ line, text }) => ({
+      line,
+      text: text.trim(),
+    }));
+}

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

@@ -6,7 +6,7 @@ export function renderManagedBlock(content) {
   return `${START_MARKER}\n${trimmed}\n${END_MARKER}\n`;
 }
 
-export function applyManagedBlock(existingContent, generatedContent) {
+export function applyManagedBlock(existingContent, generatedContent, options = {}) {
   const block = renderManagedBlock(generatedContent);
 
   if (existingContent === null) {
@@ -21,6 +21,15 @@ export function applyManagedBlock(existingContent, generatedContent) {
   const endIndex = existingContent.indexOf(END_MARKER);
 
   if (startIndex === -1 && endIndex === -1) {
+    if (options.adoptExisting) {
+      const separator = existingContent === '' || existingContent.endsWith('\n') ? '' : '\n';
+      return {
+        status: 'adopt',
+        content: `${existingContent}${separator}${block}`,
+        warning: null,
+      };
+    }
+
     return {
       status: 'warning',
       content: existingContent,

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

@@ -22,6 +22,10 @@ export function renderSharedInstructionBody(context, options = {}) {
     '',
     intro,
     '',
+    `Read \`${context.rootDir}/context.md\` for the full VibeCompass workflow protocol when it exists.`,
+    '',
+    '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 memory root: \`${context.rootDir}\``,
     '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',

package/src/setup.js

@@ -3,6 +3,8 @@ import { access, readFile, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { promisify } from 'node:util';
+import { getSupportedAgentFilePaths } from './generators/agent-files/index.js';
+import { END_MARKER, START_MARKER } from './generators/agent-files/markers.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -68,6 +70,14 @@ export async function resolveInitCliOptions(options, environment = {}) {
     },
     placementPattern: resolved.placementPattern ?? null,
     guidedSummary,
+    agentFileSyncPlan: resolved.adoptExistingAgentFiles
+      ? {
+          rootDir: resolved.rootDir,
+          toolingRootDir: resolved.toolingRootDir,
+          adoptExisting: true,
+          existingOnly: true,
+        }
+      : null,
     sessionPlan: resolved.startSession
       ? {
           sessionId: resolved.sessionId,
@@ -336,6 +346,22 @@ async function completeGuidedInitOptions(options, environment) {
     }
   }
 
+  if (resolved.adoptExistingAgentFiles === undefined) {
+    const adoptionCandidates = await findExistingUnmarkedAgentFiles({
+      cwd,
+      toolingRootDir: resolved.toolingRootDir,
+    });
+
+    if (adoptionCandidates.length > 0) {
+      writeAgentAdoptionPreview(prompter, adoptionCandidates);
+      resolved.adoptExistingAgentFiles = await askConfirm(
+        prompter,
+        'Append VibeCompass managed sections to existing agent instruction files?',
+        false,
+      );
+    }
+  }
+
   if (!resolved.startSession) {
     resolved.startSession = await askConfirm(
       prompter,
@@ -558,6 +584,65 @@ function reposMatchDetected(repos, detectedRepos) {
   return repos.every((repo) => detectedKeys.has(`${repo.id}\n${repo.remote}`));
 }
 
+async function findExistingUnmarkedAgentFiles(context) {
+  const toolingRootDir = path.resolve(context.cwd, context.toolingRootDir ?? '.');
+  const candidates = [];
+
+  for (const relativePath of getSupportedAgentFilePaths()) {
+    const filePath = path.join(toolingRootDir, relativePath);
+    let content = null;
+    try {
+      content = await readFile(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (content.includes(START_MARKER) || content.includes(END_MARKER)) {
+      continue;
+    }
+
+    candidates.push({
+      relativePath,
+      conflicts: scanPotentialAgentWorkflowConflicts(content),
+    });
+  }
+
+  return candidates;
+}
+
+function writeAgentAdoptionPreview(prompter, candidates) {
+  prompter.write('Existing agent instruction files without VibeCompass markers:\n');
+  for (const candidate of candidates) {
+    prompter.write(`- ${candidate.relativePath}: VibeCompass can append a managed block at the end of this file.\n`);
+    if (candidate.conflicts.length > 0) {
+      prompter.write(`  possible workflow overlap on lines ${candidate.conflicts.map((conflict) => conflict.line).join(', ')}\n`);
+    }
+  }
+  prompter.write('Content outside the managed block stays user-owned and will not be rewritten.\n');
+}
+
+function scanPotentialAgentWorkflowConflicts(content) {
+  const patterns = [
+    'session',
+    'handoff',
+    'decisions',
+    'wip.md',
+    'review handoff',
+    'close-session',
+    'address review',
+    'builder',
+    'reviewer',
+  ];
+
+  return content
+    .split(/\r?\n/)
+    .map((line, index) => ({
+      line: index + 1,
+      normalized: line.toLowerCase(),
+    }))
+    .filter((entry) => patterns.some((pattern) => entry.normalized.includes(pattern)));
+}
+
 async function promptForRepos(prompter, cwd) {
   const repoCount = await askInteger(prompter, 'How many repos belong to this logical project?', {
     defaultValue: 1,