@vibecompass/vibecompass 0.1.0 → 0.2.1

package/README.md

@@ -14,7 +14,9 @@ Shipped today:
 - interactive guided init for placement, workflow bootstrap, and first-session setup
 - generated `context.md` plus opt-in workflow guide files
 - opt-in starter `CLAUDE.md` / `AGENTS.md` templates that are created once and never overwritten
-- `vibecompass start-session` / `vibecompass close-session` for the local builder workflow
+- `vibecompass start-session` / `vibecompass close-session` for lane-aware local builder workflow
+- `vibecompass list-sessions` / `vibecompass switch-session` for multiple active session lanes
+- `vibecompass end-session` as a discoverable alias for `close-session`
 - `vibecompass sync-agents` for generated `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md` views
 - canonical file scanning and validation
 - `state/manifest.json` generation
@@ -39,6 +41,9 @@ broader local-primary sync workflow is still being built on top of it.
 npx -y @vibecompass/vibecompass --help
 ```
 
+The npm package is scoped under the VibeCompass org, but the installed CLI
+command is intentionally unscoped: `vibecompass`.
+
 ### Library
 
 ```bash
@@ -77,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"
 ```
 
@@ -98,6 +104,7 @@ If you do not chain straight into a first session from `init`, open one later:
 
 ```bash
 npx -y @vibecompass/vibecompass start-session \
+  --id mcp-dogfood \
   --working-on "Validate the MCP dogfood workflow against the docs repo"
 ```
 
@@ -105,29 +112,49 @@ Close the active builder session:
 
 ```bash
 npx -y @vibecompass/vibecompass close-session \
+  --session mcp-dogfood \
   --title "Workflow Parity Commands" \
   --completed "Added package-owned start-session and close-session commands" \
   --next-step "Run the package publish dry-run"
 ```
 
+`end-session` is accepted as an alias for the same lifecycle step and flags:
+`npx -y @vibecompass/vibecompass end-session ...`.
+
 The package CLI owns filesystem lifecycle only. The default scaffolded
 workflow also uses prompt commands inside your coding tool:
 
 ```text
 start session      # builder role trigger
 join as reviewer   # reviewer role trigger
-review handoff     # reviewer reads the latest note, wip.md, handoff.md, and diffs
-address review     # builder reads reviewer feedback, responds inline, and continues
+review handoff     # reviewer reads selected-lane wip.md, handoff.md, and diffs
+address review     # builder reads selected-lane feedback, responds inline, and continues
 ```
 
 Those prompt commands are documented in the generated `context.md`,
 `CLAUDE.md`, and `AGENTS.md` templates. They are not additional
 `vibecompass` CLI subcommands.
 Reviewer handback is explicit in the package-managed workflow: the reviewer
-ends the pass by updating `wip.md` + `handoff.md`, and the builder closes
-the session with `vibecompass close-session` using the defaults stored in
+ends the pass by updating the selected lane's `wip.md` + `handoff.md`, and
+the builder closes the session with `vibecompass close-session --session
+<lane-id>` using the defaults stored in
 `project.yaml.metadata.workflow.close_session`.
 
+Active builder sessions are named lanes under
+`sessions/active/<lane-id>/`. Use one lane per active feature or workstream.
+`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
+can reference a decision, but the decision file is the durable source of truth.
+
+For higher-risk work, use planning mode as a prompt-level step inside the
+active session. Planning mode should read the same context, propose scope and
+tradeoffs, and record the agreed plan in the selected lane's `wip.md`; it
+should not create a separate lifecycle artifact or finalize decisions until
+you approve implementation.
+
 Generate agent-instruction files from project memory:
 
 ```bash
@@ -206,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`
@@ -219,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:
@@ -227,10 +255,31 @@ 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>`: 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
 - `--date <YYYY-MM-DD>`: optional explicit session date
 
 This command updates the `Current session` block in `CLAUDE.md` and creates
-`sessions/wip.md` plus `sessions/handoff.md` for the next session number.
+`sessions/active/<lane-id>/session.yaml`, `wip.md`, and `handoff.md` for the
+next session number. It also updates `sessions/active/index.yaml`.
+
+### `vibecompass list-sessions`
+
+```text
+vibecompass list-sessions [options]
+```
+
+Lists active session lanes and marks the current lane.
+
+### `vibecompass switch-session`
+
+```text
+vibecompass switch-session <lane-id> [options]
+```
+
+Changes the current lane in `sessions/active/index.yaml`.
 
 ### `vibecompass close-session`
 
@@ -238,12 +287,17 @@ This command updates the `Current session` block in `CLAUDE.md` and creates
 vibecompass close-session --title <text> --completed <text> --next-step <text> [options]
 ```
 
+`vibecompass end-session` accepts the same options and runs the same close
+path. `close-session` remains the canonical command name in generated workflow
+metadata and docs.
+
 Options:
 
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--tooling-root <path>`: workspace root that contains `CLAUDE.md`; defaults to cwd
 - `--title <text>`: required finalized session-note title
 - `--worked-on <text>`: optional override for the "What we worked on" section
+- `--session <lane-id>`: active lane to close; required when multiple lanes are active
 - `--completed <text>`: repeatable completed item
 - `--decision <text>`: repeatable decision reference or summary
 - `--model <text>`: optional repeatable model contribution entry
@@ -251,7 +305,8 @@ Options:
 - `--next-step <text>`: repeatable next-session instruction
 
 This command finalizes the active scratchpad into
-`sessions/YYYY-MM-DD-N-display-title.md`, deletes `wip.md` / `handoff.md`, and
+`sessions/YYYY-MM-DD-N-display-title.md`, deletes the closed lane directory
+under `sessions/active/<lane-id>/`, updates `sessions/active/index.yaml`, and
 updates the `Current session` block in `CLAUDE.md`. If no `--model` flags are
 provided, the session note records `Not recorded.` under `Models used`.
 This is the final builder lifecycle step after the last `address review`
@@ -283,15 +338,15 @@ These are the default prompt commands used by the scaffolded workflow files:
 
 - `start session`: builder role trigger
 - `join as reviewer`: reviewer role trigger
-- `review handoff`: reviewer reads the latest finalized note, `wip.md`, `handoff.md`, and relevant diffs before appending findings
-- `address review`: builder reads the latest reviewer feedback in `wip.md` / `handoff.md`, responds inline, applies accepted changes, and refreshes the builder handoff
+- `review handoff`: reviewer reads the selected lane's latest `wip.md`, `handoff.md`, latest finalized note, and relevant diffs before appending findings
+- `address review`: builder reads the latest reviewer feedback in the selected lane's `wip.md` / `handoff.md`, responds inline, applies accepted changes, and refreshes the builder handoff
 
 They are prompt commands for AI-tool behavior, not package CLI commands.
-Reviewer handback ends when the reviewer has updated `wip.md` and
-`handoff.md`; there is no extra reviewer-exit step. The builder remains
-in builder role, uses `address review` until findings are resolved or
-explicitly deferred, and then runs `vibecompass close-session` using the
-workflow defaults recorded in `project.yaml`.
+Reviewer handback ends when the reviewer has updated the selected lane's
+`wip.md` and `handoff.md`; there is no extra reviewer-exit step. The builder
+remains in builder role, uses `address review` until findings are resolved or
+explicitly deferred, and then runs `vibecompass close-session --session
+<lane-id>` using the workflow defaults recorded in `project.yaml`.
 
 ## JavaScript API
 

package/package.json

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

package/src/cli.js

@@ -4,7 +4,7 @@ import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { initializeProjectMemory } from './init.js';
 import { resolveInitCliOptions } from './setup.js';
-import { closeProjectSession, startProjectSession } from './session.js';
+import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 
 export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
@@ -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,10 +85,11 @@ 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;
   }
 
-  if (parsed.command === 'close-session') {
+  if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     const result = await closeProjectSession({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -104,6 +107,34 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'list-sessions') {
+    const result = await listProjectSessions({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    io.stdout.write(`Active session lanes${result.current ? ` (current: ${result.current})` : ''}:\n`);
+    if (result.lanes.length === 0) {
+      io.stdout.write('- None\n');
+    } else {
+      for (const lane of result.lanes) {
+        const marker = lane.id === result.current ? '*' : '-';
+        io.stdout.write(`${marker} ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}\n`);
+      }
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'switch-session') {
+    const result = await switchProjectSession({
+      ...parsed.options,
+      ...(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;
+  }
+
   if (parsed.command === 'sync-agents') {
     const result = await syncAgentInstructionFiles({
       ...parsed.options,
@@ -128,10 +159,18 @@ export function parseCliArgs(argv) {
       return parseStartSessionArgs(rest);
     }
 
-    if (command === 'close-session') {
+    if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
 
+    if (command === 'list-sessions') {
+      return parseListSessionsArgs(rest);
+    }
+
+    if (command === 'switch-session') {
+      return parseSwitchSessionArgs(rest);
+    }
+
     if (command === 'sync-agents') {
       return parseSyncAgentsArgs(rest);
     }
@@ -236,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;
@@ -272,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
@@ -322,6 +365,18 @@ function parseStartSessionArgs(argv) {
       case '--working-on':
         parsed.workingOn = value;
         break;
+      case '--id':
+        parsed.sessionId = value;
+        break;
+      case '--feature':
+        parsed.features = [...(parsed.features ?? []), value];
+        break;
+      case '--repo':
+        parsed.repos = [...(parsed.repos ?? []), value];
+        break;
+      case '--claim':
+        parsed.claims = [...(parsed.claims ?? []), value];
+        break;
       case '--date':
         parsed.date = value;
         break;
@@ -381,6 +436,9 @@ function parseCloseSessionArgs(argv) {
       case '--worked-on':
         parsed.workedOn = value;
         break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
       case '--completed':
         parsed.completed.push(value);
         break;
@@ -413,6 +471,80 @@ function parseCloseSessionArgs(argv) {
   };
 }
 
+function parseListSessionsArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'list-sessions',
+    options: parsed,
+  };
+}
+
+function parseSwitchSessionArgs(argv) {
+  const parsed = {};
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Unexpected argument "${positional[1]}".`);
+  }
+
+  if (!parsed.sessionId && positional[0]) {
+    parsed.sessionId = positional[0];
+  }
+
+  return {
+    command: 'switch-session',
+    options: parsed,
+  };
+}
+
 function parseSyncAgentsArgs(argv) {
   const parsed = {};
 
@@ -481,8 +613,11 @@ 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]',
+    '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
     '',
     'Init options:',
@@ -503,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',
@@ -511,16 +647,21 @@ 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>                       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',
     '  --date <YYYY-MM-DD>                  Optional explicit session date',
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md current-session block',
     '  --blockers <text>                    Optional current blockers summary',
     '  --next-session-should <text>         Optional current-session handoff summary',
     '',
-    'Close-session options:',
+    'Close-session options (also accepted by end-session):',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
     '  --title <text>                       Required display title for the finalized session note',
     '  --worked-on <text>                   Optional override for "What we worked on"',
+    '  --session <lane-id>                  Active session lane to close',
     '  --completed <text>                   Repeatable completed item',
     '  --decision <text>                    Repeatable decision reference or summary',
     '  --model <text>                       Optional repeatable model contribution entry',
@@ -529,6 +670,10 @@ function usageText() {
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md completed summary',
     '  --next-session-should <text>         Optional override for the CLAUDE.md next-session summary',
     '',
+    'List/switch-session options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --session <lane-id>                  Lane ID for switch-session; positional ID is also accepted',
+    '',
     'Sync-agents options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',

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

@@ -26,16 +26,25 @@ export function renderSharedInstructionBody(context, options = {}) {
     `- Project memory root: \`${context.rootDir}\``,
     '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',
     '- Read the latest finalized session note under `sessions/` before resuming work.',
-    '- Read `sessions/wip.md` and `sessions/handoff.md` when they exist; they are the active builder/reviewer scratch files.',
+    '- Read `sessions/active/index.yaml` when it exists, then read the selected lane under `sessions/active/<lane-id>/`.',
+    '- Read the selected lane `wip.md` and `handoff.md` when they exist; they are the active builder/reviewer scratch files.',
     '- Read relevant `architecture/` and `decisions/` files before changing implementation.',
     '',
     '## Project Shape',
     ...renderProjectShape(context),
     '',
     '## 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>` 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 `sessions/wip.md` and `sessions/handoff.md`.',
+    '- 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.',
+    '- 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.',
     '',
     '## Recent Decisions',

package/src/index.js

@@ -1,7 +1,12 @@
 export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
 export { initializeProjectMemory } from './init.js';
 export { scanProjectMemory } from './project-memory.js';
-export { startProjectSession, closeProjectSession } from './session.js';
+export {
+  closeProjectSession,
+  listProjectSessions,
+  startProjectSession,
+  switchProjectSession,
+} from './session.js';
 export {
   syncAgentInstructionFiles,
   getSupportedAgentFormats,