@vibecompass/vibecompass 0.2.0 → 0.3.0

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

@@ -35,14 +35,14 @@ export function renderSharedInstructionBody(context, options = {}) {
     '',
     '## 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 and `join as reviewer` for review work.',
-    '- Use `vibecompass start-session --id <lane-id>` for concurrent lanes. Omitting `--id` opens the compatibility `default` lane only when no other lanes are active.',
+    '- 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 `vibecompass close-session --session <lane-id>`; `vibecompass end-session` is an accepted alias.',
+    '- 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.',

package/src/index.js

@@ -1,5 +1,6 @@
 export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
 export { initializeProjectMemory } from './init.js';
+export { preflightDocsReview } from './docs-review.js';
 export { scanProjectMemory } from './project-memory.js';
 export {
   closeProjectSession,

package/src/init.js

@@ -21,10 +21,10 @@ export async function initializeProjectMemory(options) {
 
   await writeProjectFile(projectFilePath, normalized.projectConfig, normalized.force);
   const gitignoreUpdated = await ensureStateIgnored(gitignorePath);
+  const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
   const manifestResult = await writeStateManifest(normalized.rootDir, {
     generatedAt: normalized.generatedAt,
   });
-  const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
 
   return {
     rootDir: normalized.rootDir,
@@ -137,6 +137,7 @@ function normalizeInitOptions(options) {
     rootDir,
     toolingRootDir,
     projectConfig,
+    generatedAt: preparedOptions.generatedAt,
   });
 
   return {
@@ -182,6 +183,7 @@ function normalizeBootstrapOptions(bootstrap, context) {
     contextRelativeToToolingRoot: toPosix(
       path.relative(context.toolingRootDir, contextFilePath) || 'context.md',
     ),
+    generatedAt: context.generatedAt,
   };
 }
 

package/src/manifest.js

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
 import { scanProjectMemory } from './project-memory.js';
+import { listProjectSessions } from './session.js';
 
 export const STATE_VERSION = 1;
 
@@ -50,13 +51,18 @@ export function generateStateManifest(scanResult, options = {}) {
       warning_count: warningCount,
     },
     documents: manifestDocuments,
+    ...(options.activeSessions ? { active_sessions: options.activeSessions } : {}),
     ...(options.sync ? { sync: options.sync } : {}),
   };
 }
 
 export async function writeStateManifest(rootDir, options = {}) {
   const scanResult = await scanProjectMemory(rootDir);
-  const manifest = generateStateManifest(scanResult, options);
+  const activeSessions = await readActiveSessionsForManifest(rootDir);
+  const manifest = generateStateManifest(scanResult, {
+    ...options,
+    ...(activeSessions ? { activeSessions } : {}),
+  });
   const stateDir = path.join(rootDir, 'state');
   const manifestPath = path.join(stateDir, 'manifest.json');
 
@@ -70,6 +76,33 @@ export async function writeStateManifest(rootDir, options = {}) {
   };
 }
 
+async function readActiveSessionsForManifest(rootDir) {
+  const sessions = await listProjectSessions({ rootDir });
+  if (sessions.lanes.length === 0 && !sessions.current) {
+    return null;
+  }
+
+  return {
+    current: sessions.current,
+    lanes: sessions.lanes.map((lane) => ({
+      id: lane.id,
+      status: lane.status ?? 'active',
+      working_on: lane.workingOn,
+      feature_slugs: lane.features ?? [],
+      repos: lane.repos ?? [],
+      claimed_paths: lane.claims ?? [],
+      started_at: lane.startedAt ?? null,
+      ...(lane.decisionSnapshot
+        ? {
+          decision_snapshot: {
+            highest_decision_id: lane.decisionSnapshot.highestDecisionId ?? null,
+          },
+        }
+        : {}),
+    })),
+  };
+}
+
 function toIsoString(value) {
   return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
 }

package/src/project-memory.js

@@ -5,7 +5,7 @@ import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const PROJECT_FILE = 'project.yaml';
-const NON_CANONICAL_DECISION_FILES = new Set(['INDEX.md', 'README.md']);
+const NON_CANONICAL_DECISION_FILES = new Set(['EXAMPLE.md', 'INDEX.md', 'README.md']);
 const NON_CANONICAL_SESSION_FILES = new Set(['wip.md', 'handoff.md', 'README.md']);
 const NON_CANONICAL_ARCHITECTURE_FILES = new Set(['README.md']);
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);

package/src/scaffold.js

@@ -1,4 +1,4 @@
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveWorkflowSettings } from './workflow.js';
 
@@ -6,6 +6,45 @@ export async function scaffoldInitFiles(options) {
   const createdFiles = [];
   const skippedFiles = [];
 
+  await mkdir(path.join(options.rootDir, 'architecture'), { recursive: true });
+  await mkdir(path.join(options.rootDir, 'decisions'), { recursive: true });
+  await mkdir(path.join(options.rootDir, 'sessions'), { recursive: true });
+
+  const starterFiles = [
+    {
+      path: path.join(options.rootDir, 'decisions', 'EXAMPLE.md'),
+      content: generateDecisionExample(options.projectConfig),
+    },
+  ];
+
+  if (!(await hasCanonicalMarkdown(path.join(options.rootDir, 'architecture'), {
+    ignoredNames: new Set(['README.md']),
+  }))) {
+    starterFiles.push({
+      path: path.join(options.rootDir, 'architecture', 'overview', 'project-shape.md'),
+      content: generateStarterArchitectureDoc(options.projectConfig),
+    });
+  }
+
+  if (!(await hasCanonicalMarkdown(path.join(options.rootDir, 'sessions'), {
+    ignoredNames: new Set(['README.md', 'wip.md', 'handoff.md']),
+    ignoredDirectories: new Set(['active']),
+  }))) {
+    starterFiles.push({
+      path: path.join(options.rootDir, 'sessions', `${sessionDateFromGeneratedAt(options.generatedAt)}-1-project-memory-initialized.md`),
+      content: generateStarterSessionNote(options),
+    });
+  }
+
+  for (const file of starterFiles) {
+    const outcome = await writeIfMissing(file.path, file.content);
+    if (outcome.created) {
+      createdFiles.push(file.path);
+    } else {
+      skippedFiles.push(file.path);
+    }
+  }
+
   if (!options.workflow) {
     return {
       contextFilePath: null,
@@ -14,10 +53,6 @@ export async function scaffoldInitFiles(options) {
     };
   }
 
-  await mkdir(path.join(options.rootDir, 'architecture'), { recursive: true });
-  await mkdir(path.join(options.rootDir, 'decisions'), { recursive: true });
-  await mkdir(path.join(options.rootDir, 'sessions'), { recursive: true });
-
   const contextFilePath = path.join(options.rootDir, 'context.md');
   // context.md is a derived artifact owned by the package; regenerate it on rerun.
   await writeFile(contextFilePath, generateContextMarkdown(options), 'utf8');
@@ -97,6 +132,43 @@ async function fileExists(filePath) {
   }
 }
 
+async function hasCanonicalMarkdown(directoryPath, options = {}) {
+  const ignoredNames = options.ignoredNames ?? new Set();
+  const ignoredDirectories = options.ignoredDirectories ?? new Set();
+
+  try {
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        if (ignoredDirectories.has(entry.name)) {
+          continue;
+        }
+
+        if (await hasCanonicalMarkdown(path.join(directoryPath, entry.name), options)) {
+          return true;
+        }
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.endsWith('.md') && !ignoredNames.has(entry.name)) {
+        return true;
+      }
+    }
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+
+  return false;
+}
+
 function generateContextMarkdown(options) {
   const projectName = options.projectConfig.name;
   const rootRelativePath = options.rootRelativePath;
@@ -125,7 +197,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 
 ## Session model
 - VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream.
-- \`vibecompass start-session\` without \`--id\` opens the compatibility \`default\` lane only when no other lanes are active; use \`--id <lane-id>\` for concurrent work.
+- \`vibecompass start-session\` requires \`--id <lane-id>\` so each active lane has a meaningful feature or workstream name.
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
 - \`${rootRelativePath}/sessions/active/index.yaml\` is the authoritative current lane pointer; the tool-specific Current session block is a human-readable continuity summary, not the lane-selection source of truth.
 - Finalized sessions are append-only notes named \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; multiple sessions on the same day increment \`N\`.
@@ -135,7 +207,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 ${repos}
 
 ## Session roles
-| Trigger | Role | Owns session lifecycle? |
+| Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
 | "start session" | Builder | Yes — opens the session, keeps scratch files current, and writes the final session note |
 | "join as reviewer" | Reviewer | No — reviews the builder's work, appends findings, and updates handoff guidance |
@@ -146,14 +218,20 @@ ${repos}
 - \`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
 
 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. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
+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\`.
 \`vibecompass end-session\` is also accepted as an alias for \`vibecompass close-session\`; the canonical command name remains \`close-session\`.
 
 ## Workflow defaults
 ${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.
+
 ## Session startup
 1. Read \`${rootRelativePath}/project.yaml\`.
 2. Read the latest finalized session note in \`${rootRelativePath}/sessions/\`.
@@ -163,7 +241,7 @@ ${renderWorkflowDefaults(workflow)}
 6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
 
 ## Builder workflow
-At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`. Omit \`--id\` only for the first/default lane in a project with no other active lanes.
+At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`.
 If you manage files manually, create \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` and \`${rootRelativePath}/sessions/active/index.yaml\`, then create \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` if it does not exist:
 
 \`\`\`md
@@ -240,6 +318,119 @@ automatically by package commands.
 `;
 }
 
+function generateStarterArchitectureDoc(projectConfig) {
+  const repos = projectConfig.repos.map((repo) => repo.id);
+  const repoLines = projectConfig.repos
+    .map((repo) => `- \`${repo.id}\` — ${repo.remote}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
+    .join('\n');
+  const repoEvidence = projectConfig.repos
+    .map((repo) => `- \`${repo.id}:/\` — declared repository root`)
+    .join('\n');
+
+  return `---
+domain: Project
+feature: Overview
+component: Project Shape
+status: In progress
+repos:
+${repos.map((repoId) => `  - ${quoteYamlString(repoId)}`).join('\n')}
+confidence: Initial scaffold
+coverage: Initial scaffold
+---
+
+## Description
+Initial project-memory scaffold for ${projectConfig.name}.
+
+${projectConfig.description ? `${projectConfig.description}\n` : ''}This document is a starting map, not a comprehensive architecture review.
+
+## Details
+- Mode: \`${projectConfig.mode}\`
+- Documentation coverage: initial scaffold
+- Repo inventory:
+${repoLines}
+
+## Coverage
+Confirmed:
+- Project identity and mode from \`project.yaml\`
+- Declared repository IDs and remotes from \`project.yaml\`
+- Project-memory root layout created by \`vibecompass init\`
+
+Not yet documented:
+- Runtime architecture and data flow
+- Auth/session model
+- Database or persistence ownership
+- External integrations
+- Deployment, jobs, and observability
+- Test strategy
+- Feature/domain/component map beyond this placeholder
+
+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.
+- 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.
+
+## Involved files
+- \`project.yaml\`
+${repoEvidence}
+`;
+}
+
+function generateDecisionExample(projectConfig) {
+  return `# Decision Examples
+
+This file is example-only guidance for ${projectConfig.name}. It is intentionally ignored by VibeCompass canonical decision parsing and must not be treated as a real decision log.
+
+Real decisions belong in domain-grouped files such as \`cross-cutting.md\`, with append-only entries:
+
+\`\`\`md
+### D-001 — Example decision title
+**Timestamp:** YYYY-MM-DD HH:MM TZ
+**Decision:** What was decided.
+**Rationale:** Why this was the correct tradeoff.
+\`\`\`
+
+Do not copy this example as-is. Allocate real decision IDs from the current canonical decision log when a decision is accepted.
+`;
+}
+
+function generateStarterSessionNote(options) {
+  const sessionDate = sessionDateFromGeneratedAt(options.generatedAt);
+  const projectConfig = options.projectConfig;
+  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${repo.remote}`).join('\n');
+
+  return `# Session — ${sessionDate}-1 — Project Memory Initialized
+
+Generated by \`vibecompass init\`; this is initialization history, not a builder/reviewer work session.
+
+## What we worked on
+Initialized VibeCompass project memory for ${projectConfig.name}.
+
+## Completed
+- Created the project-memory root and \`project.yaml\`.
+- Created lightweight starter architecture memory.
+- Created example-only decision guidance without seeding real decisions.
+- Generated local state manifest data from canonical files.
+
+## Decisions made
+- No real project decisions were seeded by init. Use \`decisions/EXAMPLE.md\` only as format guidance.
+
+## Models used
+- VibeCompass init scaffold.
+
+## Blockers / open questions
+- Comprehensive architecture documentation has not been reviewed yet.
+- Declared repos:
+${repoLines}
+
+## Next session should start with
+1. Run \`vibecompass docs-review --guided\` 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.
+`;
+}
+
 function generateArchitectureGuide(projectConfig) {
   return `# Architecture
 
@@ -256,7 +447,7 @@ architecture/<domain-slug>/<feature-slug>/<component>.md
 - \`feature\`
 - \`component\`
 - \`status\`
-- optional \`repo\` or \`repos\`
+- \`repos\`: array of repo IDs, even for single-repo projects
 
 ## Recommended sections
 - \`## Description\`
@@ -328,7 +519,7 @@ Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 
 ## Session roles
 
-| Trigger | Role | Owns session lifecycle? |
+| Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
 | "start session" | Builder | Yes |
 | "join as reviewer" | Reviewer | No |
@@ -341,9 +532,10 @@ Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 - \`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. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+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
@@ -380,7 +572,7 @@ This workspace uses VibeCompass project memory rooted at \`${options.rootRelativ
 
 ## Session roles
 
-| Trigger | Role | Owns session lifecycle? |
+| 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 |
@@ -393,9 +585,10 @@ This workspace uses VibeCompass project memory rooted at \`${options.rootRelativ
 - \`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. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+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
@@ -442,3 +635,16 @@ function describeReviewerHandback(workflow) {
 
   return workflow.reviewerHandback;
 }
+
+function sessionDateFromGeneratedAt(value) {
+  const date = value ? new Date(value) : new Date();
+  if (Number.isNaN(date.getTime())) {
+    return new Date().toISOString().slice(0, 10);
+  }
+
+  return date.toISOString().slice(0, 10);
+}
+
+function quoteYamlString(value) {
+  return JSON.stringify(value);
+}