@vibecompass/vibecompass 0.2.1 → 0.3.0

package/README.md

@@ -12,19 +12,28 @@ Shipped today:
 
 - `vibecompass init` for scaffolding a project-memory root
 - interactive guided init for placement, workflow bootstrap, and first-session setup
+- lightweight starter architecture/session memory plus example-only decision guidance
 - 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 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
+- `vibecompass docs-review --guided` — print a comprehensive review prompt for your chosen LLM to run
+- `vibecompass docs-review --submit-hosted` — submit the review request to the hosted app (execution paused; details below)
+- `vibecompass docs-review --run-local --provider anthropic` — local provider adapter that saves review output locally
+- `vibecompass docs-review --apply-output` — apply accepted architecture-doc blocks into canonical `architecture/` docs
+- `vibecompass docs-review --complete` — mark the review accepted after the docs land
 - canonical file scanning and validation
 - `state/manifest.json` generation
 - JavaScript read-model helpers for project, feature, decision, and file context
 
 Not shipped yet:
 
-- hosted sync commands such as push, pull-preview, and pull-export
+- hosted sync commands (push, pull-preview, pull-export)
+- hosted docs-review execution that runs the review and writes canonical docs
+- additional local docs-review providers beyond Anthropic
+- automatic acceptance of review findings without a local apply step
 
 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.
@@ -59,9 +68,9 @@ npx -y @vibecompass/vibecompass init --guided
 ```
 
 Guided init asks about repo topology, recommends a placement pattern
-(`workspace-root`, `dedicated-memory-repo`, or `primary-repo`), scaffolds the
-workflow files you opt into, and can open the first builder session
-immediately.
+(`workspace-root`, `dedicated-memory-repo`, or `primary-repo`), writes
+lightweight starter project memory, scaffolds the workflow files you opt into,
+and can open the first builder session immediately.
 
 When the owner directory is a workspace root or primary repo, the canonical
 root defaults to `.compass/` inside that directory. For a dedicated memory repo,
@@ -86,7 +95,22 @@ npx -y @vibecompass/vibecompass init \
   --session-working-on "Validate the local-first MCP workflow"
 ```
 
-That creates the canonical root plus, when workflow scaffolding is enabled:
+That creates the canonical root plus lightweight starter memory:
+
+```text
+PROJECT_MEMORY_ROOT/project.yaml
+PROJECT_MEMORY_ROOT/architecture/overview/project-shape.md
+PROJECT_MEMORY_ROOT/decisions/EXAMPLE.md      # example-only, ignored by canonical parsing
+PROJECT_MEMORY_ROOT/sessions/YYYY-MM-DD-1-project-memory-initialized.md
+PROJECT_MEMORY_ROOT/state/manifest.json
+```
+
+The starter architecture doc is intentionally marked as initial scaffold
+coverage. It is useful orientation, not a comprehensive review. Before risky
+implementation work, inspect the relevant code and replace or expand the
+starter docs with evidence-backed domain/feature/component docs.
+
+When workflow scaffolding is enabled, init also creates:
 
 ```text
 PROJECT_MEMORY_ROOT/context.md
@@ -100,6 +124,53 @@ AGENTS.md           # at the tooling root, only if missing and --with-agents is
 `context.md` is a derived package-owned file. Re-running `init --force --with-workflow`
 regenerates it; do not treat it as a hand-edited source document.
 
+## After init: generate real architecture docs
+
+`init` writes a small starter map of your project. To turn it into real
+architecture docs, run a docs-review and let your AI tool write them:
+
+```bash
+npx -y @vibecompass/vibecompass docs-review --guided
+```
+
+You can run this right after `init`, or any time later — for example after
+scope expands, or before risky implementation work. `start-session` will
+remind you with a non-blocking warning if no completed review exists.
+
+What happens:
+
+1. The CLI asks which LLM you'll use, then prints a versioned prompt template with fixed review criteria.
+2. You paste that prompt into your AI tool (Claude Code, Codex, Cursor, etc.).
+3. The AI reads your repo and writes architecture docs under
+   `architecture/<domain>/<feature>/<component>.md`.
+4. Run `vibecompass docs-review --apply-output` after accepting fenced
+   architecture-doc blocks, or `--complete` if accepted docs were written
+   manually.
+
+The guided prompt is deterministic apart from project-specific fields
+(`project`, `mode`, `root`, provider, and model). It uses the same structure
+VibeCompass dogfoods: read project memory first, inspect source evidence,
+write component docs with review metadata, preserve the starter overview, and
+emit accepted docs as `vibecompass-architecture-doc` blocks.
+
+The package never calls an AI itself — that's intentional. You stay in
+control of which provider runs the review and what gets saved.
+
+### Other ways to run a review
+
+- `--submit-hosted` sends the review request to the hosted app and records a
+  run ID. The hosted worker that actually runs the review and writes docs
+  isn't live yet, so the submission is durably accepted but no scan runs
+  against it.
+- `--run-local --provider anthropic` calls Anthropic directly with your
+  `ANTHROPIC_API_KEY` and saves the raw output to
+  `state/docs-review-output.md`.
+- `--apply-output` writes accepted fenced architecture-doc blocks from
+  `state/docs-review-output.md` into canonical `architecture/` docs and
+  completes the local review marker.
+
+For most users, stick with `--guided`.
+
 If you do not chain straight into a first session from `init`, open one later:
 
 ```bash
@@ -265,6 +336,10 @@ This command updates the `Current session` block in `CLAUDE.md` and creates
 `sessions/active/<lane-id>/session.yaml`, `wip.md`, and `handoff.md` for the
 next session number. It also updates `sessions/active/index.yaml`.
 
+If no completed docs-review marker exists under `state/docs-review.json`,
+`start-session` prints a non-blocking warning that starter docs are not a
+comprehensive architecture review.
+
 ### `vibecompass list-sessions`
 
 ```text
@@ -332,6 +407,72 @@ memory. It creates missing files with managed markers, replaces existing
 managed regions, preserves content outside markers, and warns instead of
 overwriting existing unmarked files.
 
+### `vibecompass docs-review`
+
+```text
+vibecompass docs-review --guided [options]
+```
+
+Options:
+
+- `--root <path>`: project-memory root; defaults to `.compass`
+- `--guided`: print a comprehensive review prompt for your chosen LLM to run (recommended)
+- `--submit-hosted`: submit the review request to the hosted app (execution paused; submission durable)
+- `--run-local`: run the generated review request with a local provider
+- `--provider <name>`: local provider for `--run-local`; currently `anthropic`
+- `--run-local-anthropic`: compatibility alias for `--run-local --provider anthropic`
+- `--apply-output`: apply accepted architecture-doc blocks from review output
+- `--output <path>`: review output path for `--apply-output`; defaults to `state/docs-review-output.md`
+- `--complete`: mark accepted docs-review changes as completed in local state
+- `--llm <name>`: preferred LLM/provider to record for the review (e.g. `claude`, `codex`, `gemini`)
+- `--model <name>`: model name/version to record for the review
+- `--anthropic-env-var <name>`: env var for local Anthropic runtime; defaults to `ANTHROPIC_API_KEY`
+- `--max-tokens <number>`: local Anthropic output budget, 1024–32000; defaults to 16000
+
+Plain `--guided` does not call an AI itself; it prints a review prompt your
+chosen LLM runs. `--submit-hosted`, `--run-local`, and `--apply-output` are
+explicit alternative steps.
+
+Project-mode requirements:
+
+- `local-only` — `--guided` can use any external LLM; `--run-local` requires a supported local provider key
+- `local-primary` — hosted sync binding preferred for hosted submission; local provider key accepted for `--run-local`
+- `hosted-only` — hosted sync binding required
+
+`--run-local --provider anthropic` always uses local Anthropic regardless of
+hosted binding, so hosted precedence does not apply when that flag is set.
+
+`--submit-hosted` uses `sync.credential_env_var` and records the hosted run
+ID in `state/docs-review.json`. Submission is durable today; the hosted
+worker that runs the review and writes canonical docs is not yet live, so
+no scan executes against the submitted request. Local files stay untouched.
+
+`--run-local-anthropic` remains as a compatibility alias. New scripts should
+use `--run-local --provider anthropic`.
+
+`--apply-output` looks for accepted architecture docs in fenced blocks:
+
+````md
+```vibecompass-architecture-doc path=architecture/domain/feature/component.md
+---
+domain: Platform
+feature: Example
+component: Backend
+status: In progress
+---
+
+## Description
+Accepted review content.
+```
+````
+
+Only `architecture/*.md` paths are writable through this apply step.
+
+`vibecompass docs-review --complete` updates the marker in
+`state/docs-review.json` to `status: "completed"` once the docs have
+landed, preserving the recorded `llm` / `model` so future sessions know
+what reviewed the architecture.
+
 ### Prompt commands
 
 These are the default prompt commands used by the scaffolded workflow files:
@@ -340,19 +481,22 @@ These are the default prompt commands used by the scaffolded workflow files:
 - `join as reviewer`: reviewer role trigger
 - `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
+- `close session`: builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>`; `end session` is accepted as a synonym
 
 They are prompt commands for AI-tool behavior, not package CLI commands.
 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`.
+explicitly deferred, and then uses the `close session` prompt to run
+`vibecompass close-session --session <lane-id>` using the workflow defaults
+recorded in `project.yaml`.
 
 ## JavaScript API
 
 ```js
 import {
   initializeProjectMemory,
+  preflightDocsReview,
   startProjectSession,
   closeProjectSession,
   syncAgentInstructionFiles,

package/package.json

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

package/src/cli.js

@@ -3,6 +3,7 @@
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { initializeProjectMemory } from './init.js';
+import { preflightDocsReview } from './docs-review.js';
 import { resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
@@ -70,6 +71,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`);
+      writeWarnings(io, sessionResult.warnings);
       writeAgentFileSyncResult(io, sessionResult.agentFileSync);
     }
 
@@ -85,6 +87,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`);
+    writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
@@ -144,6 +147,47 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'docs-review') {
+    const result = await preflightDocsReview({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    }, {
+      io,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Docs-review: ${result.status}\n`);
+    if (result.llm) {
+      io.stdout.write(`LLM: ${result.llm}\n`);
+    }
+    if (result.model) {
+      io.stdout.write(`Model: ${result.model}\n`);
+    }
+    if (result.runtime) {
+      io.stdout.write(`Runtime: ${result.runtime.provider}\n`);
+    }
+    if (result.hosted) {
+      io.stdout.write(`Hosted run: ${result.hosted.run_id}\n`);
+    }
+    if (result.localReview) {
+      io.stdout.write(`Local review output: ${result.localReview.output_path}\n`);
+    }
+    if (result.applied) {
+      io.stdout.write(`Applied architecture docs: ${result.applied.architecture_docs.length}\n`);
+      for (const entry of result.applied.architecture_docs) {
+        io.stdout.write(`- ${entry.path} (${entry.status})\n`);
+      }
+    }
+    writeWarnings(io, result.warnings);
+    io.stdout.write(`Recorded ${result.statePath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    if (result.reviewPrompt) {
+      io.stdout.write('Architecture review prompt:\n');
+      io.stdout.write(`${result.reviewPrompt}\n`);
+    }
+    return 0;
+  }
+
   throw new Error(`Unknown command "${parsed.command}".`);
 }
 
@@ -175,6 +219,10 @@ export function parseCliArgs(argv) {
       return parseSyncAgentsArgs(rest);
     }
 
+    if (command === 'docs-review') {
+      return parseDocsReviewArgs(rest);
+    }
+
     return { command };
   }
 
@@ -587,6 +635,85 @@ function parseSyncAgentsArgs(argv) {
   };
 }
 
+function parseDocsReviewArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--guided') {
+      parsed.guided = true;
+      continue;
+    }
+
+    if (token === '--submit-hosted') {
+      parsed.submitHosted = true;
+      continue;
+    }
+
+    if (token === '--complete') {
+      parsed.complete = true;
+      continue;
+    }
+
+    if (token === '--run-local-anthropic') {
+      parsed.runLocalAnthropic = true;
+      continue;
+    }
+
+    if (token === '--run-local') {
+      parsed.runLocal = true;
+      continue;
+    }
+
+    if (token === '--apply-output') {
+      parsed.applyOutput = true;
+      continue;
+    }
+
+    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;
+      case '--llm':
+        parsed.llm = value;
+        break;
+      case '--model':
+        parsed.model = value;
+        break;
+      case '--anthropic-env-var':
+        parsed.anthropicEnvVar = value;
+        break;
+      case '--provider':
+        parsed.provider = value;
+        break;
+      case '--output':
+        parsed.outputPath = value;
+        break;
+      case '--max-tokens':
+        parsed.maxTokens = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'docs-review',
+    options: parsed,
+  };
+}
+
 function writeAgentFileSyncResult(io, result) {
   if (!result) {
     return;
@@ -600,6 +727,12 @@ function writeAgentFileSyncResult(io, result) {
   }
 }
 
+function writeWarnings(io, warnings = []) {
+  for (const warning of warnings) {
+    io.stderr.write(`Warning: ${warning}\n`);
+  }
+}
+
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
@@ -619,6 +752,7 @@ function usageText() {
     '  vibecompass list-sessions [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
+    '  vibecompass docs-review --guided [options]',
     '',
     'Init options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
@@ -679,6 +813,21 @@ function usageText() {
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',
     '  --format <name>                      Optional format: claude_md, agents_md, cursor_rules, copilot_instructions',
     '  --dry-run                            Show planned writes without changing files',
+    '',
+    'Docs-review options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --guided                             Accepted for the explicit comprehensive-review workflow',
+    '  --submit-hosted                      Submit the generated review request to hosted sync',
+    '  --complete                           Mark accepted docs-review changes as completed locally',
+    '  --run-local                          Run the generated review request with a local provider',
+    '  --provider <name>                    Local provider for --run-local. Currently: anthropic',
+    '  --run-local-anthropic                Compatibility alias for --run-local --provider anthropic',
+    '  --apply-output                       Apply accepted architecture doc blocks from review output',
+    '  --output <path>                      Review output path for --apply-output; defaults to state/docs-review-output.md',
+    '  --llm <name>                         Preferred LLM/provider to run the external architecture review',
+    '  --model <name>                       Model name to record for the review',
+    '  --anthropic-env-var <name>           Env var to use for local Anthropic docs-review runtime',
+    '  --max-tokens <number>                Local Anthropic max_tokens, 1024-32000. Defaults to 16000',
   ].join('\n');
 }