vibe-coding-master 0.0.17 → 0.2.1

package/README.md

@@ -11,7 +11,7 @@ VCM is designed for long-running coding work where one Claude Code conversation
 
 Each role runs as a real Claude Code process inside an embedded terminal. The GUI lets the user start, stop, resume, restart, switch, observe, and manually intervene in those sessions without juggling separate terminal windows.
 
-## Current V1 Capabilities
+## Current Capabilities
 
 - GUI-first task workspace.
 - Collapsible sidebar with repository connection, settings, harness status, task creation, and task list.
@@ -25,7 +25,9 @@ Each role runs as a real Claude Code process inside an embedded terminal. The GU
   - `--dangerously-skip-permissions`
 - PM-mediated role messaging through VCM-dispatched route files.
 - Manual and automatic orchestration modes.
-- VCM harness installer for `CLAUDE.md`, `.claude/agents/*.md`, and the VCM-managed `.gitignore` block.
+- Two-stage VCM harness setup: deterministic fixed install plus AI-assisted bootstrap.
+- VCM-managed root rules, four role agents, repo-local VCM skills, Claude Code hooks, generated-context tools, and PR template.
+- Rust generated context for module indexing and crate-external public surface indexing.
 - Translation panel powered by an OpenAI-compatible low-cost model.
 - Durable task state, session state, raw terminal logs, handoff artifacts, and message history.
 
@@ -134,14 +136,15 @@ Important container notes:
 1. Start VCM.
 2. Open the GUI.
 3. In the sidebar, open `Repository Path`, enter a repository path or choose one from `Recent`, then click `Connect`.
-4. Review `VCM Harness`; if files need install/update, click `Install / Update`.
-5. Review any changed harness files and commit them if they look right.
-6. Create a task from `New Task` with a single task name.
-7. Select the task from `Tasks`.
-8. Use the role tabs in the task header to switch between `Project Manager`, `Architect`, `Coder`, and `Reviewer`.
-9. Choose the permission mode for the active role.
-10. Click `Start`, `Resume`, `Restart`, or `Stop` as needed.
-11. Talk mostly to `project-manager`; let PM coordinate the other roles through VCM messaging.
+4. Review `VCM Harness`; if fixed files need install/update, click `Install / Update`.
+5. If bootstrap checks are incomplete, click `Run Bootstrap` and let the visible Claude Code bootstrap session fill project-specific docs and generated context.
+6. Review and commit harness changes when they look right.
+7. Create a task from `New Task` with a single task name.
+8. Select the task from `Tasks`.
+9. Use the role tabs in the task header to switch between `Project Manager`, `Architect`, `Coder`, and `Reviewer`.
+10. Choose the permission mode for the active role.
+11. Click `Start`, `Resume`, `Restart`, or `Stop` as needed.
+12. Talk mostly to `project-manager`; let PM coordinate the other roles through VCM messaging.
 
 The recommended flow is:
 
@@ -171,13 +174,13 @@ The `Create worktree and branch` option is selected by default when creating a t
 
 VCM will not create worktrees per role. `project-manager`, `architect`, `coder`, and `reviewer` for the same task share the same task worktree.
 
-The user can turn this option off. In that mode, VCM creates the task metadata and handoff structure in the connected repository, records the current branch, and starts role sessions from the connected repository path.
+The user can turn this option off. In that mode, VCM creates app-local task metadata, creates the handoff structure in the connected repository, records the current branch, and starts role sessions from the connected repository path.
 
 VCM will not offer a separate `Create task worktree` button after a task exists, and a task should not be switched to another branch/worktree mode after creation.
 
 Because worktrees live under `.claude/worktrees/`, the connected repository must ignore both `.ai/vcm/` and `.claude/worktrees/`. Apply the VCM Harness before creating tasks so `.gitignore` contains the managed ignore block. The base repository must also be clean because the task branch/worktree is created from the connected repo's current `HEAD`.
 
-When a task is complete, VCM provides a red `Close Task` action. Closing a task shows a destructive confirmation, stops VCM-managed running role sessions for that task, then deletes the task worktree, deletes the task branch by default, removes the base task index entry, and removes task runtime metadata. VCM does not preflight running sessions or uncommitted changes before closing. Tasks created without a worktree only remove VCM metadata because they do not own a separate branch/worktree.
+When a task is complete, VCM provides a red `Close Task` action. Closing a task shows a destructive confirmation, stops VCM-managed running role sessions for that task, then deletes the task worktree, deletes the task branch by default, removes the app-local task record, and removes task runtime metadata. VCM does not preflight running sessions or uncommitted changes before closing. Tasks created without a worktree only remove VCM metadata because they do not own a separate branch/worktree.
 
 ## Sidebar UI
 
@@ -186,7 +189,7 @@ The left sidebar is intentionally compact and collapsible:
 - `Repository Path`: path input on one row; `Recent` and `Connect` on the next row.
 - `Repository`: connected path, branch, and working tree state. `Working tree: uncommitted changes` means `git status --porcelain` is not empty.
 - `Settings`: `Theme`, `Round alert`, `Try alert`, `Messages`, and `Events`.
-- `VCM Harness`: status for `CLAUDE.md`, role agent files, and `.gitignore`.
+- `VCM Harness`: fixed-install status, bootstrap completion checks, and the bootstrap terminal when one is running.
 - `New Task`: one `task name` input.
 - `Tasks`: task list and task status.
 
@@ -196,6 +199,8 @@ All sidebar sections are collapsed by default. When no task is selected, `Reposi
 
 The task header has a global `Translate` button next to `Close Task`. It opens a translation panel beside the embedded terminal for the role consoles and keeps the same on/off setting while switching roles. The terminal and translation panel split the available width evenly.
 
+The task header does not include a manual `Refresh` button. Task status, role status, messages, orchestration state, and round completion state refresh automatically. The remaining `Refresh` button lives only in the sidebar `VCM Harness` section and is for rechecking harness files.
+
 Translation settings are local and stored in:
 
 ```text
@@ -228,18 +233,34 @@ Translation behavior:
 
 ## Project Harness
 
-VCM works best when the connected repository contains VCM collaboration rules as normal project files. On first connect, VCM checks:
+VCM works best when the connected repository contains VCM collaboration rules as normal project files. Harness setup has two stages.
+
+Fixed install is deterministic. It installs or updates VCM-owned files and managed blocks:
 
 ```text
 CLAUDE.md
 .gitignore
+.claude/settings.json
 .claude/agents/project-manager.md
 .claude/agents/architect.md
 .claude/agents/coder.md
 .claude/agents/reviewer.md
+.claude/skills/vcm-route-message/SKILL.md
+.claude/skills/vcm-final-acceptance/SKILL.md
+.claude/skills/vcm-long-running-validation/SKILL.md
+.claude/skills/vcm-harness-bootstrap/SKILL.md
+.ai/vcm-harness-manifest.json
+.ai/tools/generate-module-index
+.ai/tools/generate-public-surface
+.ai/tools/run-long-check
+.ai/tools/watch-job
+.github/pull_request_template.md
 ```
 
-If a file is missing, VCM can create a recommended default. If a file already exists, VCM preserves user-authored content and only inserts or replaces a managed block:
+Repo-local skills are installed as `.claude/skills/<skill-name>/SKILL.md` so
+Claude Code can register them.
+
+If a managed-block file already exists, VCM preserves user-authored content and only inserts or replaces the VCM block:
 
 ```md
 <!-- VCM:BEGIN version=1 -->
@@ -256,11 +277,24 @@ For `.gitignore`, VCM uses a gitignore-native managed block:
 # VCM:END
 ```
 
-`.ai/vcm/` is the active VCM local control area, and `.claude/worktrees/` is the Claude-compatible task worktree area. The base repo keeps the task index; each task runtime repo keeps its own session, message, orchestration, and translation state.
+`.ai/vcm/` is the active VCM local control area, and `.claude/worktrees/` is the Claude-compatible task worktree area. VCM keeps the task index in app-local project state under `~/.vcm/projects/`; each task runtime repo keeps its own session, message, orchestration, and translation state.
 
 VCM also JSON-merges `.claude/settings.json` to install Claude Code `UserPromptSubmit` and `Stop` hooks. The hooks post directly to the local VCM backend, so roles do not need a VCM CLI command to confirm delivery or report turn completion.
 
-After applying harness changes, VCM reports the exact files changed and reminds the user to review and commit them before starting long-running work.
+Bootstrap is AI-assisted. VCM starts a visible temporary Claude Code session in the connected repository and asks it to use the `vcm-harness-bootstrap` skill. Bootstrap fills project-specific content and generated context:
+
+```text
+CLAUDE.md project context outside the VCM managed block
+docs/ARCHITECTURE.md
+<module>/ARCHITECTURE.md
+docs/TESTING.md
+.ai/generated/module-index.json
+.ai/generated/public-surface.json
+```
+
+The generated-context tools currently target Rust projects. Non-Rust repositories can still install the fixed harness, but generated context should be treated as unsupported until project-specific generators exist.
+
+After applying harness changes or completing bootstrap, VCM reports the exact files changed or checks completed and reminds the user to review and commit them before starting long-running work.
 
 Role sessions learn VCM rules from `CLAUDE.md` and `.claude/agents/*.md`. VCM does not paste a long context block into the terminal at session start.
 
@@ -296,15 +330,14 @@ Runtime message and handoff files:
 .ai/vcm/messages/<task>.jsonl                 # under the task runtime repo
 .ai/vcm/orchestration/<task>.json             # under the task runtime repo
 .ai/vcm/handoffs/messages/<from-role>-<to-role>.md
-.ai/vcm/handoffs/role-commands/
 .ai/vcm/handoffs/logs/
 ```
 
-Each directed role route has exactly one message file. If a role changes its mind during one turn, it edits the same route file instead of creating another message. A blank file means no pending message; a non-empty file means pending work for VCM to submit.
+Each directed role route has exactly one message file. Route messages are the only dynamic task-dispatch files. If a role changes its mind during one turn, it edits the same route file instead of creating another message. A blank file means no pending message; a non-empty file means pending work for VCM to submit.
 
 ## Orchestration Modes
 
-VCM has a task-level `Auto orchestration` switch in the active role toolbar.
+VCM has a task-level `Auto orchestration` switch in the role console toolbar.
 
 When it is off, VCM is in manual mode:
 
@@ -365,19 +398,17 @@ For a connected repository, VCM uses:
 
 ```text
 ~/.vcm/projects/<project-id>/config.json
-<baseRepoRoot>/.ai/vcm/tasks/<task>.json
+~/.vcm/projects/<project-id>/tasks/<task>.json
 <baseRepoRoot>/.claude/worktrees/<task>/
 <taskRepoRoot>/.ai/vcm/sessions/<task>.json
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
 <taskRepoRoot>/.ai/vcm/translation/<task>/
 <taskRepoRoot>/.ai/vcm/handoffs/architecture-plan.md
-<taskRepoRoot>/.ai/vcm/handoffs/implementation-log.md
-<taskRepoRoot>/.ai/vcm/handoffs/validation-log.md
+<taskRepoRoot>/.ai/vcm/handoffs/known-issues.md
 <taskRepoRoot>/.ai/vcm/handoffs/review-report.md
 <taskRepoRoot>/.ai/vcm/handoffs/docs-sync-report.md
 <taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
-<taskRepoRoot>/.ai/vcm/handoffs/role-commands/{architect,coder,reviewer}.md
 <taskRepoRoot>/.ai/vcm/handoffs/logs/{project-manager,architect,coder,reviewer}.log
 ```
 
@@ -414,7 +445,7 @@ npm run build
 
 - VCM does not use tmux.
 - VCM does not auto-confirm Claude Code permission prompts.
-- VCM does not isolate roles with separate worktrees in V1.
+- VCM does not isolate roles with separate worktrees; roles for one task share one task worktree.
 - VCM does not translate Claude output from raw PTY output; translation reads Claude transcript JSONL files.
 - VCM does not write translation output into handoff artifacts unless a user or role explicitly copies it there.
 - Role file writes happen in the task worktree when a task has a worktree.
@@ -423,6 +454,7 @@ npm run build
 See also:
 
 - `docs/product-design.md`
-- `docs/v1-architecture-design.md`
-- `docs/v1-implementation-plan.md`
-- `docs/cc-best-practices.md`
+- `docs/v0.2-implementation-plan.md`
+- `docs/vcm-cc-best-practices.md`
+- `docs/full-harness-baseline.md`
+- `docs/cc-best-practices.md` is archived and no longer maintained.

package/dist/backend/api/artifact-routes.js

@@ -87,11 +87,8 @@ function artifactNameToPath(paths, artifactName) {
     if (artifactName === "architecture-plan.md") {
         return paths.architecturePlanPath;
     }
-    if (artifactName === "implementation-log.md") {
-        return paths.implementationLogPath;
-    }
-    if (artifactName === "validation-log.md") {
-        return paths.validationLogPath;
+    if (artifactName === "known-issues.md") {
+        return paths.knownIssuesPath;
     }
     if (artifactName === "review-report.md") {
         return paths.reviewReportPath;
@@ -99,6 +96,9 @@ function artifactNameToPath(paths, artifactName) {
     if (artifactName === "docs-sync-report.md") {
         return paths.docsSyncReportPath;
     }
+    if (artifactName === "final-acceptance.md") {
+        return paths.finalAcceptancePath;
+    }
     throw new VcmError({
         code: "ARTIFACT_UNKNOWN",
         message: `Unknown artifact: ${artifactName}`,

package/dist/backend/api/harness-routes.js

@@ -8,6 +8,14 @@ export function registerHarnessRoutes(app, deps) {
         const project = await requireCurrentProject(deps.projectService);
         return deps.harnessService.applyHarness(project.repoRoot);
     });
+    app.get("/api/projects/harness/bootstrap", async () => {
+        const project = await requireCurrentProject(deps.projectService);
+        return deps.harnessService.getBootstrapStatus(project.repoRoot);
+    });
+    app.post("/api/projects/harness/bootstrap/start", async (request) => {
+        const project = await requireCurrentProject(deps.projectService);
+        return deps.harnessService.startHarnessBootstrap(project.repoRoot, request.body ?? {});
+    });
 }
 async function requireCurrentProject(projectService) {
     const project = await projectService.getCurrentProject();

package/dist/backend/server.js

@@ -10,7 +10,7 @@ import { createClaudeHookService } from "./services/claude-hook-service.js";
 import { createGitAdapter } from "./adapters/git-adapter.js";
 import { createAppSettingsService } from "./services/app-settings-service.js";
 import { createClaudeTranscriptService } from "./services/claude-transcript-service.js";
-import { createHarnessService } from "./services/harness-service.js";
+import { createHarnessService, createScriptFixedHarnessInstaller } from "./services/harness-service.js";
 import { createNodeFileSystemAdapter } from "./adapters/filesystem.js";
 import { createNodePtyTerminalRuntime } from "./runtime/node-pty-runtime.js";
 import { createOpenAiCompatibleTranslationProvider } from "./adapters/translation-provider.js";
@@ -128,8 +128,14 @@ export function createDefaultServerDeps(options = {}) {
     const runtime = createNodePtyTerminalRuntime({ fs });
     const registry = createSessionRegistry();
     const artifactService = createArtifactService(fs);
-    const harnessService = createHarnessService({ fs });
     const projectService = createProjectService({ fs, git, claude, appSettings });
+    const harnessService = createHarnessService({
+        fs,
+        runtime,
+        projectService,
+        apiUrl: options.apiUrl,
+        runFixedInstaller: createScriptFixedHarnessInstaller(path.join(getAppRoot(), "scripts/install-vcm-harness.mjs"))
+    });
     const taskService = createTaskService({ fs, git, artifactService, projectService });
     const sessionService = createSessionService({
         fs,

package/dist/backend/services/artifact-service.js

@@ -3,14 +3,14 @@ import { DISPATCHABLE_ROLES, ROLE_NAMES } from "../../shared/constants.js";
 import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderArchitecturePlanTemplate, renderDocsSyncReportTemplate, renderImplementationLogTemplate, renderMessageRouteTemplate, renderReviewReportTemplate, renderValidationLogTemplate } from "../templates/handoff.js";
+import { renderArchitecturePlanTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderMessageRouteTemplate, renderReviewReportTemplate } from "../templates/handoff.js";
 import { renderRoleCommandTemplate } from "../templates/role-command.js";
 const ARTIFACT_PATH_KEYS = [
     ["architecture-plan", "architecturePlanPath"],
-    ["implementation-log", "implementationLogPath"],
-    ["validation-log", "validationLogPath"],
+    ["known-issues", "knownIssuesPath"],
     ["review-report", "reviewReportPath"],
-    ["docs-sync-report", "docsSyncReportPath"]
+    ["docs-sync-report", "docsSyncReportPath"],
+    ["final-acceptance", "finalAcceptancePath"]
 ];
 const ROLE_COMMAND_PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|status:\s*draft)\s*(\n|$)/i;
 const DEFAULT_MESSAGE_ROUTES = [
@@ -45,10 +45,10 @@ export function createArtifactService(fs) {
                 },
                 messageRoutePaths: getDefaultMessageRoutePaths(messagesDir),
                 architecturePlanPath: path.posix.join(handoffDir, "architecture-plan.md"),
-                implementationLogPath: path.posix.join(handoffDir, "implementation-log.md"),
-                validationLogPath: path.posix.join(handoffDir, "validation-log.md"),
+                knownIssuesPath: path.posix.join(handoffDir, "known-issues.md"),
                 reviewReportPath: path.posix.join(handoffDir, "review-report.md"),
-                docsSyncReportPath: path.posix.join(handoffDir, "docs-sync-report.md")
+                docsSyncReportPath: path.posix.join(handoffDir, "docs-sync-report.md"),
+                finalAcceptancePath: path.posix.join(handoffDir, "final-acceptance.md")
             };
         },
         getMessageRoutePath(handoffDir, fromRole, toRole) {
@@ -65,14 +65,14 @@ export function createArtifactService(fs) {
         async createArtifactTemplates(input) {
             const paths = await this.ensureHandoffStructure(input);
             const files = [
-                [paths.roleCommandPaths.architect, renderRoleCommandTemplate(input.taskSlug, "architect")],
-                [paths.roleCommandPaths.coder, renderRoleCommandTemplate(input.taskSlug, "coder")],
-                [paths.roleCommandPaths.reviewer, renderRoleCommandTemplate(input.taskSlug, "reviewer")],
+                [paths.roleCommandPaths.architect, renderRoleCommandTemplate(input.taskSlug, "architect", input.repoRoot, input.branch)],
+                [paths.roleCommandPaths.coder, renderRoleCommandTemplate(input.taskSlug, "coder", input.repoRoot, input.branch)],
+                [paths.roleCommandPaths.reviewer, renderRoleCommandTemplate(input.taskSlug, "reviewer", input.repoRoot, input.branch)],
                 [paths.architecturePlanPath, renderArchitecturePlanTemplate(input.taskSlug)],
-                [paths.implementationLogPath, renderImplementationLogTemplate(input.taskSlug)],
-                [paths.validationLogPath, renderValidationLogTemplate(input.taskSlug)],
+                [paths.knownIssuesPath, renderKnownIssuesTemplate(input.taskSlug)],
                 [paths.reviewReportPath, renderReviewReportTemplate(input.taskSlug)],
                 [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)],
+                [paths.finalAcceptancePath, renderFinalAcceptanceTemplate(input.taskSlug)],
                 ...Object.values(paths.messageRoutePaths).map((messagePath) => [
                     messagePath,
                     renderMessageRouteTemplate()