@vibecompass/vibecompass 0.2.0 → 0.2.1

package/README.md

@@ -28,8 +28,6 @@ Not shipped yet:
 
 The package is publishable now as the file-contract and read-model core. The
 broader local-primary sync workflow is still being built on top of it.
-The lane-aware session workflow is intended to publish as `0.2.0`; the local
-package may remain at `0.1.0` until the publish pass.
 
 ## Requirements
 
@@ -84,6 +82,7 @@ npx -y @vibecompass/vibecompass init \
   --close-session-git-publish \
   --close-session-git-remote origin \
   --start-session \
+  --session-id mcp-dogfood \
   --session-working-on "Validate the local-first MCP workflow"
 ```
 
@@ -143,8 +142,8 @@ the builder closes the session with `vibecompass close-session --session
 
 Active builder sessions are named lanes under
 `sessions/active/<lane-id>/`. Use one lane per active feature or workstream.
-`start-session` without `--id` opens the compatibility `default` lane only
-when no other lanes are active; concurrent work should pass `--id`.
+`start-session` requires `--id <lane-id>` for every lane, including the first
+one in a project.
 Finalized sessions are append-only notes named
 `sessions/YYYY-MM-DD-N-title.md`, so multiple sessions on the same day
 increment `N`. Decisions remain append-only in `decisions/`; a session note
@@ -234,6 +233,7 @@ Options:
 - `--with-agents`: create a starter `AGENTS.md` if it does not already exist
 - `--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
 - `--close-session-git-publish`: store that the close-session workflow includes a Git publish step
 - `--close-session-git-remote <name>`: optional default Git remote name for that stored publish step
 - `--force`: overwrite an existing `project.yaml`
@@ -247,7 +247,7 @@ include a Git publish step and which remote name to use for that step.
 ### `vibecompass start-session`
 
 ```text
-vibecompass start-session --working-on <text> [options]
+vibecompass start-session --id <lane-id> --working-on <text> [options]
 ```
 
 Options:
@@ -255,7 +255,7 @@ Options:
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--tooling-root <path>`: workspace root that contains `CLAUDE.md`; defaults to cwd
 - `--working-on <text>`: required active-session summary
-- `--id <lane-id>`: optional lane ID; defaults to `default` only when no lanes are active
+- `--id <lane-id>`: required lane ID
 - `--feature <slug>`: repeatable feature slug for the lane
 - `--repo <id>`: repeatable repo ID for the lane
 - `--claim <path>`: repeatable path claim for overlap warnings

package/package.json

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

package/src/cli.js

@@ -62,6 +62,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       const sessionResult = await startProjectSession({
         rootDir: initPlan.initOptions.rootDir,
         toolingRootDir: initPlan.initOptions.toolingRootDir,
+        sessionId: initPlan.sessionPlan.sessionId,
         workingOn: initPlan.sessionPlan.workingOn,
         ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
       });
@@ -69,6 +70,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Updated ${sessionResult.claudePath}\n`);
       io.stdout.write(`Created ${sessionResult.wipFilePath}\n`);
       io.stdout.write(`Created ${sessionResult.handoffFilePath}\n`);
+      writeAgentFileSyncResult(io, sessionResult.agentFileSync);
     }
 
     return 0;
@@ -83,6 +85,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     io.stdout.write(`Updated ${result.claudePath}\n`);
     io.stdout.write(`Created ${result.wipFilePath}\n`);
     io.stdout.write(`Created ${result.handoffFilePath}\n`);
+    writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
 
@@ -127,6 +130,8 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
     });
     io.stdout.write(`Current session lane: ${result.current}\n`);
+    io.stdout.write(`Updated ${result.claudePath}\n`);
+    writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
 
@@ -270,6 +275,9 @@ export function parseCliArgs(argv) {
       case '--session-working-on':
         parsed.sessionWorkingOn = value;
         break;
+      case '--session-id':
+        parsed.sessionId = value;
+        break;
       case '--close-session-git-remote':
         parsed.closeSessionGitRemote = value;
         break;
@@ -306,6 +314,7 @@ export function parseCliArgs(argv) {
       force: parsed.force,
       startSession: parsed.startSession,
       sessionWorkingOn: parsed.sessionWorkingOn,
+      sessionId: parsed.sessionId,
       closeSessionGitPublish: parsed.closeSessionGitPublish,
       closeSessionGitRemote: parsed.closeSessionGitRemote,
       ...(parsed.withWorkflow || parsed.withClaude || parsed.withAgents
@@ -604,7 +613,7 @@ function usageText() {
   return [
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
-    '  vibecompass start-session --working-on <text> [options]',
+    '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
     '  vibecompass close-session --title <text> --completed <text> --next-step <text> [options]',
     '  vibecompass end-session --title <text> --completed <text> --next-step <text> [options]  # alias',
     '  vibecompass list-sessions [options]',
@@ -629,6 +638,7 @@ function usageText() {
     '  --with-agents                        Create a starter AGENTS.md if missing',
     '  --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',
     '  --close-session-git-publish          Include a Git publish step in the stored close-session workflow',
     '  --close-session-git-remote <name>    Default Git remote name for that close-session publish step',
     '  --force                              Overwrite an existing project.yaml',
@@ -637,7 +647,7 @@ function usageText() {
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
     '  --working-on <text>                  Required active-session summary',
-    '  --id <lane-id>                       Optional active session lane ID. Defaults to default when no lanes exist',
+    '  --id <lane-id>                       Required active session lane ID',
     '  --feature <slug>                     Repeatable feature slug for the lane',
     '  --repo <id>                          Repeatable repo ID for the lane',
     '  --claim <path>                       Repeatable path claim for overlap warnings',

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

@@ -36,7 +36,7 @@ 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 `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.',

package/src/scaffold.js

@@ -125,7 +125,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\`.
@@ -163,7 +163,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

package/src/session.js

@@ -99,6 +99,10 @@ export async function startProjectSession(options) {
     status: 'active',
     workingOn,
   }, { current: sessionId });
+  const agentFileSync = await syncAgentInstructionFilesSafely({
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+  });
 
   return {
     rootDir: normalized.rootDir,
@@ -110,6 +114,7 @@ export async function startProjectSession(options) {
     handoffFilePath: lanePaths.handoffFilePath,
     sessionDate,
     sessionNumber: nextSessionNumber,
+    agentFileSync,
   };
 }
 
@@ -185,9 +190,10 @@ export async function closeProjectSession(options) {
   );
 
   const hadHandoff = await fileExists(lanePaths.handoffFilePath);
+  let activeSessionIndex = null;
   if (sessionId) {
     await rm(lanePaths.laneDir, { recursive: true, force: true });
-    await removeActiveSessionFromIndex(normalized, sessionId);
+    activeSessionIndex = await removeActiveSessionFromIndex(normalized, sessionId);
   } else {
     await rm(lanePaths.wipFilePath, { force: true });
     if (hadHandoff) {
@@ -195,16 +201,22 @@ export async function closeProjectSession(options) {
     }
   }
 
-  const updatedClaude = replaceCurrentSessionBlock(claude.content, {
-    date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
-    workingOn: 'Session closed. Ready for the next builder session.',
-    lastThingCompleted:
-      normalizeOptionalString(options?.lastThingCompleted) ??
-      `Closed session ${activeSession.sessionNumber} and wrote \`${sessionRelativePath}\`.`,
-    blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
-    nextSessionShould:
-      normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
-  });
+  const closedSummary = `Closed session ${activeSession.sessionNumber} and wrote \`${sessionRelativePath}\`.`;
+  const updatedClaude = replaceCurrentSessionBlock(
+    claude.content,
+    activeSessionIndex?.current
+      ? buildCurrentSessionFieldsForLane(activeSessionIndex.lanes.find((lane) => lane.id === activeSessionIndex.current), {
+          lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+        })
+      : {
+          date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
+          workingOn: 'Session closed. Ready for the next builder session.',
+          lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+          blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
+          nextSessionShould:
+            normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
+        },
+  );
 
   await writeFile(normalized.claudePath, updatedClaude, 'utf8');
   const agentFileSync = await syncAgentInstructionFilesSafely({
@@ -248,17 +260,35 @@ export async function switchProjectSession(options = {}) {
   const normalized = normalizeSessionPaths(options);
   const sessionId = validateLaneId(requireNonEmptyString(options?.sessionId, 'switch-session requires a session ID.'));
   const lanes = await listActiveSessionLanes(normalized);
+  const lane = lanes.find((item) => item.id === sessionId);
 
-  if (!lanes.some((lane) => lane.id === sessionId)) {
+  if (!lane) {
     throw new Error(`Active session lane "${sessionId}" does not exist.`);
   }
 
   await upsertActiveSessionIndex(normalized, null, { current: sessionId });
+  const claude = await readClaudeFile(normalized.claudePath);
+  await writeFile(
+    normalized.claudePath,
+    replaceCurrentSessionBlock(
+      claude.content,
+      buildCurrentSessionFieldsForLane(lane, {
+        lastThingCompleted: `Switched current lane to ${sessionId}.`,
+      }),
+    ),
+    'utf8',
+  );
+  const agentFileSync = await syncAgentInstructionFilesSafely({
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+  });
 
   return {
     rootDir: normalized.rootDir,
+    claudePath: normalized.claudePath,
     current: sessionId,
     lanes,
+    agentFileSync,
   };
 }
 
@@ -397,6 +427,26 @@ function replaceCurrentSessionBlock(content, fields) {
   return `${content.slice(0, sessionFence.bodyStart)}${blockBody}${content.slice(sessionFence.bodyEnd)}`;
 }
 
+function buildCurrentSessionFieldsForLane(lane, overrides = {}) {
+  if (!lane) {
+    throw new Error('Cannot update the Current session block without active lane metadata.');
+  }
+
+  const sessionDate = lane.sessionDate ?? normalizeSessionDate();
+  const sessionNumber = lane.sessionNumber || 0;
+  const workingOn = lane.workingOn ?? 'No summary recorded.';
+
+  return {
+    date: `${sessionDate} (session ${sessionNumber}, lane ${lane.id})`,
+    workingOn: `${workingOn} [${lane.id}]`,
+    lastThingCompleted:
+      overrides.lastThingCompleted ?? 'Current lane selected from `sessions/active/index.yaml`.',
+    blockers: overrides.blockers ?? 'No blocker recorded for the selected lane.',
+    nextSessionShould:
+      overrides.nextSessionShould ?? 'Continue the selected active lane from `sessions/active/index.yaml`.',
+  };
+}
+
 async function getNextSessionNumber(sessionsDir, sessionDate) {
   const sessions = await listFinalizedSessions(sessionsDir);
   const activeSessions = await listActiveSessionLanes({ sessionsDir, activeSessionsDir: path.join(sessionsDir, 'active') });
@@ -414,18 +464,13 @@ async function resolveStartSessionId(normalized, options) {
     return validateLaneId(explicitId);
   }
 
-  const lanes = await listActiveSessionLanes(normalized);
-  if (lanes.length > 0) {
-    throw new Error('Active session lanes already exist. Pass --id to start another lane explicitly.');
-  }
-
   if ((await fileExists(normalized.wipFilePath)) || (await fileExists(normalized.handoffFilePath))) {
     throw new Error(
       `Legacy active session scratch files already exist under ${normalized.sessionsDir}. Close or recover that session before starting a lane.`,
     );
   }
 
-  return 'default';
+  throw new Error('start-session requires --id <lane-id> so each active lane has a meaningful name.');
 }
 
 async function resolveExistingSessionId(normalized, options) {
@@ -547,16 +592,28 @@ async function upsertActiveSessionIndex(normalized, lane, options = {}) {
   await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, [...laneMap.values()]), 'utf8');
 }
 
+/**
+ * Removes a closed lane from the active index and returns the surviving lane
+ * state used to refresh the Current session block. `lanes` contains the full
+ * lane metadata read from each sibling lane's `session.yaml` / `wip.md`.
+ */
 async function removeActiveSessionFromIndex(normalized, sessionId) {
   const index = await readActiveSessionIndex(normalized);
   const lanes = (await listActiveSessionLanes(normalized)).filter((lane) => lane.id !== sessionId);
   const current = index.current === sessionId ? lanes[0]?.id ?? null : index.current;
   if (lanes.length === 0) {
     await rm(normalized.activeSessionsIndexPath, { force: true });
-    return;
+    return {
+      current: null,
+      lanes,
+    };
   }
 
   await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, lanes), 'utf8');
+  return {
+    current,
+    lanes,
+  };
 }
 
 async function listFinalizedSessions(sessionsDir) {

package/src/setup.js

@@ -40,6 +40,10 @@ export async function resolveInitCliOptions(options, environment = {}) {
     throw new Error('init requires --session-working-on when --start-session is used without guided setup.');
   }
 
+  if (resolved.startSession && !resolved.sessionId) {
+    throw new Error('init requires --session-id when --start-session is used.');
+  }
+
   return {
     initOptions: {
       rootDir: resolved.rootDir,
@@ -62,6 +66,7 @@ export async function resolveInitCliOptions(options, environment = {}) {
     guidedSummary,
     sessionPlan: resolved.startSession
       ? {
+          sessionId: resolved.sessionId,
           workingOn: resolved.sessionWorkingOn,
         }
       : null,
@@ -278,6 +283,15 @@ async function completeGuidedInitOptions(options, environment) {
     if (!resolved.sessionWorkingOn) {
       resolved.sessionWorkingOn = await askInput(prompter, 'What are you working on?');
     }
+
+    if (!resolved.sessionId) {
+      resolved.sessionId = await askInput(prompter, 'Session lane id', {
+        defaultValue: suggestLaneId(resolved.sessionWorkingOn),
+        validate(value) {
+          return validateLaneIdForPrompt(value);
+        },
+      });
+    }
   }
 
   if (resolved.closeSessionGitPublish === undefined && (resolved.bootstrap.workflow || resolved.startSession)) {
@@ -669,6 +683,46 @@ function suggestRepoId(value) {
   return slug || 'repo';
 }
 
+function suggestLaneId(value) {
+  const slug = String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 63)
+    .replace(/-+$/g, '');
+
+  return slug.length >= 3 ? slug : 'builder-session';
+}
+
+function validateLaneIdForPrompt(value) {
+  if (!/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(value)) {
+    return 'Lane id must be 3-64 lowercase letters, numbers, or hyphens, and must start and end with a letter or number.';
+  }
+
+  if ([
+    'active',
+    'current',
+    'default',
+    'false',
+    'handoff',
+    'index',
+    'new',
+    'no',
+    'null',
+    'off',
+    'on',
+    'sessions',
+    'state',
+    'true',
+    'wip',
+    'yes',
+  ].includes(value)) {
+    return `Lane id "${value}" is reserved.`;
+  }
+
+  return null;
+}
+
 function getRepoDirectoryHints(repo) {
   const hints = new Set();