@vibecompass/vibecompass 0.3.1 → 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
@@ -327,11 +343,14 @@ Guided init can also record workflow defaults in
 `project.yaml.metadata.workflow`, including whether close-session should
 include a Git publish step and which remote name to use for that step.
 
-Guided init is inference-first for the common single-repo case: it reads
-`package.json`, detects the current Git `origin`, asks you to confirm the
-detected repo, and maps a friendly setup goal to the stored project mode.
-Hosted credentials are deferred by default; run `vibecompass connect-hosted`
-when you are ready to connect the local root to `vibecompass.dev`.
+Guided init is inference-first for common repo layouts: it reads `package.json`,
+detects the current Git `origin` when you run it inside a repo, or scans a
+parent workspace for immediate child repos when the parent is not itself a Git
+checkout. It asks once before using detected repos, maps a friendly setup goal
+to the stored project mode, places single-child repo memory under that child
+repo, and uses workspace-root placement for multi-repo parent folders. Hosted
+credentials are deferred by default; run `vibecompass connect-hosted` when you
+are ready to connect the local root to `vibecompass.dev`.
 
 ### `vibecompass connect-hosted`
 
@@ -437,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.1",
+  "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

@@ -1,8 +1,10 @@
 import { execFile } from 'node:child_process';
-import { access, readFile } from 'node:fs/promises';
+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,
@@ -220,14 +230,18 @@ async function completeGuidedInitOptions(options, environment) {
     resolved.mode = setupGoal === 'share-later' ? 'local-primary' : setupGoal;
   }
 
+  const detectedRepos = inferredProject.repos ?? [];
+
   if (!Array.isArray(resolved.repos) || resolved.repos.length === 0) {
-    if (inferredProject.repo) {
-      const useDetectedRepo = await askConfirm(
+    if (detectedRepos.length > 0) {
+      const useDetectedRepos = await askConfirm(
         prompter,
-        `Use detected Git repo ${inferredProject.repo.remote}?`,
+        formatDetectedReposPrompt(detectedRepos),
         true,
       );
-      resolved.repos = useDetectedRepo ? [inferredProject.repo] : await promptForRepos(prompter, cwd);
+      resolved.repos = useDetectedRepos
+        ? detectedRepos.map((repo) => toProjectRepo(repo))
+        : await promptForRepos(prompter, cwd);
     } else {
       resolved.repos = await promptForRepos(prompter, cwd);
     }
@@ -235,7 +249,15 @@ async function completeGuidedInitOptions(options, environment) {
 
   let recommendation = null;
   if (!resolved.placementPattern) {
-    if (inferredProject.repo && resolved.repos.length === 1) {
+    if (inferredProject.source === 'child-repos' && detectedRepos.length > 1 && reposMatchDetected(resolved.repos, detectedRepos)) {
+      recommendation = recommendPlacementPattern({
+        repoCount: detectedRepos.length,
+        usesSharedWorkspace: true,
+      });
+      resolved.placementPattern = recommendation.pattern;
+      prompter.write(`Recommended placement: ${recommendation.pattern}\n`);
+      prompter.write(`${recommendation.reason}\n`);
+    } else if (detectedRepos.length === 1 && reposMatchDetected(resolved.repos, detectedRepos)) {
       recommendation = recommendPlacementPattern({ repoCount: 1 });
       resolved.placementPattern = recommendation.pattern;
     } else {
@@ -248,7 +270,9 @@ async function completeGuidedInitOptions(options, environment) {
   }
 
   if (!resolved.toolingRootDir) {
-    if (inferredProject.repo && resolved.repos.length === 1 && resolved.placementPattern === PLACEMENT_PATTERNS.PRIMARY_REPO) {
+    if (resolved.placementPattern === PLACEMENT_PATTERNS.PRIMARY_REPO && detectedRepos.length === 1 && reposMatchDetected(resolved.repos, detectedRepos)) {
+      resolved.toolingRootDir = detectedRepos[0].directory;
+    } else if (resolved.placementPattern === PLACEMENT_PATTERNS.WORKSPACE_ROOT && inferredProject.source === 'child-repos' && detectedRepos.length > 1 && reposMatchDetected(resolved.repos, detectedRepos)) {
       resolved.toolingRootDir = '.';
     } else {
       const ownerLabel = describePlacementOwner(resolved.placementPattern);
@@ -322,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,
@@ -381,26 +421,43 @@ async function completeGuidedInitOptions(options, environment) {
 }
 
 async function inferProjectFromCwd(cwd) {
-  const [packageName, gitInfo] = await Promise.all([
+  const [packageName, gitInfo, childRepos] = await Promise.all([
     readPackageName(cwd),
     readGitInfo(cwd),
+    discoverChildGitRepos(cwd),
   ]);
   const projectName = packageName ?? path.basename(cwd);
 
-  if (!gitInfo?.remote) {
-    return { projectName, repo: null };
+  if (gitInfo?.remote) {
+    const remoteSlug = extractRemoteSlug(gitInfo.remote);
+    const repoId = suggestRepoId(remoteSlug ?? packageName ?? path.basename(gitInfo.root ?? cwd));
+
+    return {
+      projectName,
+      source: 'current-repo',
+      repos: [
+        {
+          id: repoId,
+          remote: gitInfo.remote,
+          directory: '.',
+          ...(gitInfo.branch ? { defaultBranch: gitInfo.branch } : {}),
+        },
+      ],
+    };
   }
 
-  const remoteSlug = extractRemoteSlug(gitInfo.remote);
-  const repoId = suggestRepoId(remoteSlug ?? packageName ?? path.basename(gitInfo.root ?? cwd));
+  if (childRepos.length > 0) {
+    return {
+      projectName,
+      source: 'child-repos',
+      repos: childRepos,
+    };
+  }
 
   return {
     projectName,
-    repo: {
-      id: repoId,
-      remote: gitInfo.remote,
-      ...(gitInfo.branch ? { defaultBranch: gitInfo.branch } : {}),
-    },
+    source: 'none',
+    repos: [],
   };
 }
 
@@ -437,6 +494,155 @@ async function readGitInfo(cwd) {
   }
 }
 
+async function discoverChildGitRepos(cwd) {
+  let entries = [];
+  try {
+    entries = await readdir(cwd, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates = entries
+    .filter((entry) => entry.isDirectory() && isScannableWorkspaceChild(entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  const discovered = await Promise.all(candidates.map(async (entry) => {
+    const directory = entry.name;
+    const absoluteDirectory = path.join(cwd, directory);
+    const [gitInfo, packageName] = await Promise.all([
+      readGitInfo(absoluteDirectory),
+      readPackageName(absoluteDirectory),
+    ]);
+
+    if (!gitInfo?.remote) {
+      return null;
+    }
+
+    if (gitInfo.root && !(await isSameDirectory(gitInfo.root, absoluteDirectory))) {
+      return null;
+    }
+
+    const remoteSlug = extractRemoteSlug(gitInfo.remote);
+    return {
+      id: suggestRepoId(remoteSlug ?? packageName ?? directory),
+      remote: gitInfo.remote,
+      directory,
+      ...(gitInfo.branch ? { defaultBranch: gitInfo.branch } : {}),
+    };
+  }));
+
+  const reposByDirectory = new Map();
+  for (const repo of discovered) {
+    if (repo && !reposByDirectory.has(repo.directory)) {
+      reposByDirectory.set(repo.directory, repo);
+    }
+  }
+
+  return [...reposByDirectory.values()].sort((left, right) => left.directory.localeCompare(right.directory));
+}
+
+function isScannableWorkspaceChild(name) {
+  if (!name || name.startsWith('.')) {
+    return false;
+  }
+
+  return !new Set([
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'out',
+    'target',
+    'vendor',
+  ]).has(name);
+}
+
+function formatDetectedReposPrompt(repos) {
+  if (repos.length === 1) {
+    const repo = repos[0];
+    const location = repo.directory && repo.directory !== '.' ? ` in ${repo.directory}` : '';
+    return `Use detected Git repo${location} (${repo.remote})?`;
+  }
+
+  return `Use ${repos.length} detected Git repos (${repos.map((repo) => repo.directory).join(', ')})?`;
+}
+
+function toProjectRepo(repo) {
+  return {
+    id: repo.id,
+    remote: repo.remote,
+    ...(repo.defaultBranch ? { defaultBranch: repo.defaultBranch } : {}),
+  };
+}
+
+function reposMatchDetected(repos, detectedRepos) {
+  if (!Array.isArray(repos) || repos.length !== detectedRepos.length) {
+    return false;
+  }
+
+  const detectedKeys = new Set(detectedRepos.map((repo) => `${repo.id}\n${repo.remote}`));
+  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,
@@ -872,6 +1078,18 @@ async function directoryExists(directoryPath) {
   }
 }
 
+async function isSameDirectory(left, right) {
+  try {
+    const [leftRealPath, rightRealPath] = await Promise.all([
+      realpath(left),
+      realpath(right),
+    ]);
+    return leftRealPath === rightRealPath;
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
 function toRelativeIfInsideCwd(targetPath, cwd) {
   const absolute = path.resolve(cwd, targetPath);
   const relative = path.relative(cwd, absolute);