npm - vibe-coding-master - Versions diffs - 0.0.7 → 0.0.8 - Mend

vibe-coding-master 0.0.7 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +47 -11
package/dist/backend/adapters/filesystem.js +13 -0
package/dist/backend/adapters/git-adapter.js +79 -1
package/dist/backend/api/artifact-routes.js +13 -7
package/dist/backend/api/message-routes.js +2 -0
package/dist/backend/api/task-routes.js +14 -0
package/dist/backend/server.js +2 -1
package/dist/backend/services/command-dispatcher.js +4 -2
package/dist/backend/services/harness-service.js +22 -4
package/dist/backend/services/message-service.js +1 -1
package/dist/backend/services/project-service.js +46 -9
package/dist/backend/services/session-service.js +7 -5
package/dist/backend/services/status-service.js +3 -1
package/dist/backend/services/task-service.js +118 -4
package/dist/backend/templates/harness/gitignore.js +9 -0
package/dist-frontend/assets/index-CuiNNOzj.css +32 -0
package/dist-frontend/assets/{index-Bp49_End.js → index-D59GuHCR.js} +18 -18
package/dist-frontend/index.html +2 -2
package/docs/cc-best-practices.md +16 -4
package/docs/product-design.md +105 -14
package/docs/v1-architecture-design.md +163 -29
package/docs/v1-implementation-plan.md +131 -15
package/package.json +1 -1
package/dist-frontend/assets/index-BNASqKEK.css +0 -32

package/dist-frontend/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VibeCodingMaster</title>
-    <script type="module" crossorigin src="/assets/index-Bp49_End.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BNASqKEK.css">
+    <script type="module" crossorigin src="/assets/index-D59GuHCR.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CuiNNOzj.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/cc-best-practices.md CHANGED Viewed

@@ -68,6 +68,7 @@ Recommended structure:
 ```text
 repo/
   CLAUDE.md
+  .gitignore
   docs/
     ARCHITECTURE.md
@@ -95,6 +96,7 @@ repo/
     commands/
   .ai/
+    vcm/                 # ignored local VCM control state
     task-specs/
     handoffs/
       <task-slug>/
@@ -957,8 +959,8 @@ Worktree isolation is by task, not by role:
 ```text
 one task
-  -> one branch
-  -> one worktree
+  -> one branch: feature/<task-slug>
+  -> one worktree: .ai/vcm/worktrees/<task-slug>
   -> one handoff directory
   -> architect -> coder -> reviewer in sequence
 ```
@@ -1436,8 +1438,8 @@ Default rule:
 ```text
 one task
-  -> one branch
-  -> one worktree
+  -> one branch: feature/<task-slug>
+  -> one worktree: .ai/vcm/worktrees/<task-slug>
   -> one handoff directory
   -> one PR
 ```
@@ -1477,9 +1479,19 @@ Branch rules:
 - never do AI implementation work directly on the main branch
 - one task branch should map to one task worktree
+- VCM-managed task branches should use `feature/<task-slug>`
+- VCM-managed task worktrees should live under `.ai/vcm/worktrees/<task-slug>`
+- `.gitignore` should contain a VCM managed block that ignores `.ai/vcm/`
+- a task should not switch to a different branch/worktree after creation; create a new task instead
 - large work should use phase commits on the same task branch unless phases are independently releasable
 - if a task becomes too large, split it into child tasks with explicit branch and PR ownership
+Cleanup rules:
+- after task completion, remove the task worktree only after role sessions are stopped and uncommitted work is handled
+- remove VCM task/session/message/orchestration metadata with the worktree cleanup
+- keep the task branch by default until PR merge; delete it only with explicit confirmation
 Small commits:
 - one commit per phase

package/docs/product-design.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # VibeCodingMaster Product Design
-Last updated: 2026-05-30
+Last updated: 2026-05-31
-This document describes the product that the current code implements. It intentionally removes older CLI-first, tmux, raw-PTY-translation, and main-page artifact-panel designs that are no longer part of V1.
+This document describes the current product direction and implemented V1 behavior for VCM.
 ## 1. Product Positioning
@@ -24,7 +24,7 @@ VCM is not a hosted SaaS product. It runs locally, connects to a local repositor
 VCM V1 must make multi-session Claude Code work visible and recoverable:
 - Connect a local Git repository.
-- Create a named task.
+- Create a named task with its own branch and task-level worktree by default.
 - Start, stop, restart, and resume one Claude Code session per role.
 - Keep role terminals embedded in one GUI.
 - Preserve task state, session state, handoff files, message history, and raw terminal logs.
@@ -32,6 +32,7 @@ VCM V1 must make multi-session Claude Code work visible and recoverable:
 - Let users choose between manual message approval and auto orchestration.
 - Install or update VCM role rules into `CLAUDE.md` and `.claude/agents/*.md`.
 - Provide a low-cost translation layer so the user can write Chinese while Claude Code receives English engineering instructions.
+- Clean up completed task worktrees and VCM task metadata when the task is done.
 ## 3. Non-Goals
@@ -39,6 +40,8 @@ V1 does not include:
 - tmux.
 - Worktree isolation per role.
+- Switching a task to a different branch or worktree after task creation.
+- A separate `Create task worktree` action after the task already exists.
 - Concurrent edits across roles as a product workflow.
 - Automatic confirmation of Claude Code permission prompts.
 - A main-page artifact inspector.
@@ -61,6 +64,72 @@ project-manager
 The workflow is a soft guide in V1. VCM computes readiness from handoff artifact checks and session state, then shows the result in the sidebar. It does not block the user from manually starting a role out of order.
+### 4.1 Task Worktree Model
+Task-level worktree management is the current model for multi-task parallelism:
+```text
+one task
+  -> one branch
+  -> one git worktree
+  -> one handoff directory
+  -> one set of role sessions
+```
+VCM must not create worktrees per role. `project-manager`, `architect`, `coder`, and `reviewer` for the same task all run in the same task worktree and hand off sequentially.
+When the user creates a task, VCM creates the branch and worktree immediately. There is no separate later button named `Create task worktree`, and a task cannot be switched to another worktree after creation.
+Branch naming:
+```text
+feature/<task-name>
+```
+Worktree path:
+```text
+<base-repo>/.ai/vcm/worktrees/<task-name>
+```
+Example:
+```text
+base repo: /workspace
+task: docs-cleanup
+branch: feature/docs-cleanup
+worktree: /workspace/.ai/vcm/worktrees/docs-cleanup
+```
+The repo's `.gitignore` must ignore `.ai/vcm/`. This is mandatory because the task worktrees live under `.ai/vcm/worktrees/`, and the base repository must not see nested worktree files as untracked source files.
+Task creation flow:
+```text
+New Task submit
+  -> validate task name
+  -> derive branch feature/<task-name>
+  -> derive worktree path .ai/vcm/worktrees/<task-name>
+  -> verify .ai/vcm/ is ignored and the base repo is clean
+  -> git worktree add -b feature/<task-name> .ai/vcm/worktrees/<task-name> <base-ref>
+  -> create task metadata
+  -> create handoff structure inside the task worktree
+  -> open the task workspace with role session cwd = task worktree
+```
+Task cleanup flow:
+```text
+task complete
+  -> stop running role sessions
+  -> verify task worktree is safe to remove
+  -> remove git worktree
+  -> remove VCM task/session/message/orchestration metadata
+  -> keep or delete branch according to guarded branch cleanup policy
+```
+Branch deletion should be a separate guarded confirmation, ideally only after the branch is merged or the user explicitly confirms deletion. Worktree cleanup itself removes the local working directory and task metadata.
 ## 5. Roles
 ### Project Manager
@@ -179,20 +248,25 @@ The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or
 There is no separate `Pause orchestration` or `Resume orchestration` control in the GUI. The current product model is one on/off toggle.
-`VCM Harness` shows whether VCM managed blocks are installed/up to date in the project rules files.
+`VCM Harness` shows whether VCM managed blocks are installed/up to date in the project rules files and `.gitignore`.
-`New Task` contains one input:
+`New Task` contains:
 - `task name`
+- a checked, non-optional `Create worktree and branch` indicator
+- generated branch preview: `feature/<task-name>`
+- generated worktree preview: `.ai/vcm/worktrees/<task-name>`
 There is no optional title input in the current UI.
+The worktree/branch path is the normal VCM task model, not a separate mode users toggle later. The checked indicator is shown so the user understands what will happen; VCM should not require a separate worktree creation action later.
 ### Task Workspace
 The task workspace header is one compact row:
 ```text
-TASK WORKSPACE  <task>  <branch>   [Project Manager] [Architect] [Coder] [Reviewer] [Refresh]
+TASK WORKSPACE  <task>  <branch>  <worktree>   [Project Manager] [Architect] [Coder] [Reviewer] [Refresh]
 ```
 Role tabs show the session status for each role.
@@ -268,6 +342,7 @@ On repository connect, VCM checks:
 ```text
 CLAUDE.md
+.gitignore
 .claude/agents/project-manager.md
 .claude/agents/architect.md
 .claude/agents/coder.md
@@ -284,6 +359,17 @@ If a file already exists, VCM only inserts or replaces the managed block:
 <!-- VCM:END -->
 ```
+For `.gitignore`, VCM uses hash comments:
+```gitignore
+# VCM:BEGIN version=1
+.ai/vcm/
+.vcm/
+# VCM:END
+```
+`.ai/vcm/` is the active VCM local control area. `.vcm/` is included only as a legacy ignore rule for older VCM state.
 VCM must preserve all user-authored content outside the managed block.
 After applying harness changes, the UI tells the user what changed and recommends reviewing and committing those files.
@@ -445,17 +531,20 @@ App-level settings:
 Repository-level VCM state:
 ```text
-.vcm/config.json
-.vcm/tasks/<task>.json
-.vcm/sessions/<task>.json
-.vcm/messages/<task>.jsonl
-.vcm/orchestration/<task>.json
+.ai/vcm/config.json
+.ai/vcm/tasks/<task>.json
+.ai/vcm/sessions/<task>.json
+.ai/vcm/messages/<task>.jsonl
+.ai/vcm/orchestration/<task>.json
+.ai/vcm/worktrees/<task>/
 ```
-Repo handoff artifacts:
+In task-worktree mode, the base repository's `.ai/vcm/` directory is the project control area. Task source changes and handoff artifacts live inside the task worktree at `.ai/vcm/worktrees/<task>/`.
+Task worktree local files:
 ```text
-.ai/handoffs/<task>/
+.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
 ```
 External Claude transcripts:
@@ -489,7 +578,8 @@ This protects against publishing raw TypeScript bin files or missing frontend as
 VCM V1 is successful when:
 - A user can connect a repo without global Git safe-directory setup.
-- A user can create a task and start all four role sessions.
+- A user can create a task, which creates `feature/<task>` and `.ai/vcm/worktrees/<task>`.
+- A user can start all four role sessions in that task worktree.
 - Switching roles never loses the embedded terminal.
 - Restart creates a fresh Claude session; Resume reconnects to the persisted one.
 - Permission modes are reflected in the Claude command.
@@ -500,3 +590,4 @@ VCM V1 is successful when:
 - Translation reads Claude transcript JSONL reliably after start, resume, and restart.
 - Terminal and translation panel have equal, stable reading space.
 - Harness install/update preserves user content outside VCM managed blocks.
+- Completed tasks can cleanly remove their worktree and VCM task metadata without affecting other tasks.

package/docs/v1-architecture-design.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # V1 Architecture Design
-Last updated: 2026-05-30
+Last updated: 2026-05-31
 This document describes the architecture implemented by the current VCM codebase.
@@ -28,7 +28,7 @@ browser
   -> claude --agent <role>
 ```
-The app is local-first. It writes repository task state under `.vcm/`, handoff artifacts under `.ai/handoffs/`, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
+The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
 ## 2. Processes And Ports
@@ -96,7 +96,7 @@ Responsibilities:
 - Render workflow panel.
 - Render settings section with Messages, Events, Auto orchestration.
 - Render harness status/actions.
-- Render one-field task creation form.
+- Render task creation form with one task-name field, a checked non-optional worktree/branch indicator, and generated branch/path previews.
 - Render task list.
 - Render Messages and Events modals.
@@ -112,7 +112,7 @@ Responsibilities:
 - Fetch task status, messages, and orchestration state.
 - Poll those every three seconds.
-- Render compact header with task title, branch, role tabs, and Refresh.
+- Render compact header with task title, branch, immutable worktree path, role tabs, and Refresh.
 - Hold per-role permission mode selection.
 - Render one `SessionConsole` per role but only show the active role.
 - Emit workflow/messages/orchestration/events back to `App` so sidebar stays synchronized.
@@ -202,8 +202,8 @@ POST /api/projects/connect
   -> resolve path
   -> check path exists
   -> check .git marker directly
-  -> create .vcm/config.json
-  -> ensure .ai/handoffs and .vcm state dirs
+  -> create .ai/vcm/config.json
+  -> ensure .ai/vcm state dirs
   -> read branch and dirty state
   -> record recent repo path in ~/.vcm/settings.json
 ```
@@ -222,7 +222,118 @@ git -c safe.directory=<repoRoot> -c safe.directory=<realpath(repoRoot)> ...
 VCM does not require global `safe.directory` configuration.
-## 6. Task And Artifact Model
+## 6. Task Worktree Architecture
+Task-level worktree management is the current architecture for multi-task parallelism.
+Rule:
+```text
+one VCM task = one branch + one git worktree + one handoff directory + one role-session set
+```
+Branch name:
+```text
+feature/<taskSlug>
+```
+Worktree path:
+```text
+<baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+```
+VCM does not support switching a task to another branch or worktree after creation. If the user needs a different branch/worktree, they should create a new task.
+VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
+```text
+.ai/vcm/worktrees/<taskSlug>/
+  project-manager session cwd
+  architect session cwd
+  coder session cwd
+  reviewer session cwd
+```
+### 6.1 Base Repo vs Task Worktree
+VCM distinguishes:
+- `baseRepoRoot`: repository the user connected.
+- `taskRepoRoot`: git worktree path for a specific task.
+- `branch`: `feature/<taskSlug>`.
+- `worktreePath`: same as `taskRepoRoot`.
+Project-level VCM control state stays under the base repo:
+```text
+<baseRepoRoot>/.ai/vcm/config.json
+<baseRepoRoot>/.ai/vcm/tasks/<task>.json
+<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/
+```
+Task source changes and handoff artifacts live in the task worktree:
+```text
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
+```
+This central base-state model lets VCM list and manage multiple tasks while each task's code changes happen in a separate worktree.
+### 6.2 Git Ignore Requirement
+The base repository must ignore `.ai/vcm/`.
+Reason:
+- `.ai/vcm/worktrees/<task>` is a nested git worktree.
+- Without `.ai/vcm/` in `.gitignore`, the base repo sees worktree files as untracked noise.
+- `.ai/vcm` also contains local task/session/message metadata that should not be committed by default.
+The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task worktree creation.
+### 6.3 Task Creation Flow
+```text
+POST /api/tasks
+  -> validate taskSlug
+  -> compute branch feature/<taskSlug>
+  -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+  -> assert branch does not already exist
+  -> assert worktreePath does not already exist
+  -> assert .ai/vcm/ is ignored by Git
+  -> assert base repo has no uncommitted changes
+  -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> create handoff structure in taskRepoRoot
+  -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
+```
+The default `baseRef` is the connected repo's current `HEAD`.
+### 6.4 Task Cleanup Flow
+```text
+POST /api/tasks/:taskSlug/cleanup
+  -> require no running role sessions
+  -> load task metadata
+  -> verify worktree path belongs under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> check worktree status
+  -> refuse cleanup when uncommitted work exists unless force is explicitly requested
+  -> git worktree remove <worktreePath>
+  -> delete central task/session/message/orchestration metadata
+```
+Branch deletion is intentionally separate:
+- Keep `feature/<taskSlug>` by default.
+- Allow branch deletion only with explicit confirmation.
+- Prefer allowing deletion only when the branch has been merged, or when the user force-confirms.
+## 7. Task And Artifact Model
 File:
@@ -234,7 +345,7 @@ File:
 Task state:
 ```text
-.vcm/tasks/<task>.json
+<baseRepoRoot>/.ai/vcm/tasks/<task>.json
 ```
 Each task stores:
@@ -242,8 +353,10 @@ Each task stores:
 - `taskSlug`
 - optional `title`
 - timestamps
-- repo root
-- branch at task creation
+- `baseRepoRoot`
+- `worktreePath`
+- `repoRoot` / `taskRepoRoot`
+- branch, always `feature/<taskSlug>` for VCM-created tasks
 - handoff directory
 - status
 - optional spec path
@@ -253,15 +366,16 @@ Task creation:
 ```text
 POST /api/tasks
   -> validate slug
+  -> create branch and worktree
   -> create handoff directories
   -> create artifact templates
-  -> write .vcm/tasks/<task>.json
+  -> write base .ai/vcm/tasks/<task>.json
 ```
 Handoff directory:
 ```text
-.ai/handoffs/<task>/
+<taskRepoRoot>/.ai/handoffs/<task>/
   role-commands/
     architect.md
     coder.md
@@ -287,7 +401,7 @@ Artifact checks are simple V1 checks:
 They are used for workflow readiness, not content quality judgment.
-## 7. Workflow Computation
+## 8. Workflow Computation
 File:
@@ -315,7 +429,7 @@ Step readiness:
 The report is displayed in the sidebar `Workflow` section.
-## 8. Session Runtime
+## 9. Session Runtime
 Files:
@@ -360,7 +474,7 @@ Permission flags:
 Session persistence:
 ```text
-.vcm/sessions/<task>.json
+<baseRepoRoot>/.ai/vcm/sessions/<task>.json
 ```
 The persisted record includes:
@@ -380,7 +494,9 @@ The persisted record includes:
 If a runtime process is gone but the role has a Claude session id, `getRoleSession` returns a recoverable `resumable` status.
-## 9. Terminal Runtime
+In task-worktree mode, `cwd` must be the immutable task worktree path. Role sessions must not start in the base repo when a task worktree exists.
+## 10. Terminal Runtime
 File:
@@ -391,7 +507,7 @@ The runtime:
 - spawns `node-pty`
 - sets `TERM=xterm-256color`
 - sets color-friendly env vars
-- appends raw PTY output to `.ai/handoffs/<task>/logs/<role>.log`
+- appends raw PTY output to `<taskRepoRoot>/.ai/handoffs/<task>/logs/<role>.log`
 - emits terminal output/input/exit events to WebSocket subscribers
 - replays the log on terminal WebSocket subscribe
@@ -412,7 +528,7 @@ Server messages:
 - exit
 - error
-## 10. Message Bus
+## 11. Message Bus
 Files:
@@ -423,8 +539,8 @@ Files:
 State:
 ```text
-.vcm/messages/<task>.jsonl
-.vcm/orchestration/<task>.json
+.ai/vcm/messages/<task>.jsonl
+.ai/vcm/orchestration/<task>.json
 .ai/handoffs/<task>/messages/<message-id>.md
 ```
@@ -458,7 +574,9 @@ The backend writes a `[VCM MESSAGE]` envelope to the target terminal and appends
 The backend still exposes pause/resume orchestration API routes and stores `paused` for compatibility. The current GUI only toggles `mode` between `manual` and `auto`.
-## 11. Role Command Compatibility
+Messages and orchestration snapshots are central project state under `baseRepoRoot/.ai/vcm`. Message body markdown lives in the task worktree handoff directory.
+## 12. Role Command Compatibility
 Files:
@@ -488,7 +606,7 @@ The dispatcher:
 This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
-## 12. Harness Service
+## 13. Harness Service
 File:
@@ -498,6 +616,7 @@ Harness files:
 ```text
 CLAUDE.md
+.gitignore
 .claude/agents/project-manager.md
 .claude/agents/architect.md
 .claude/agents/coder.md
@@ -512,6 +631,15 @@ Managed block:
 <!-- VCM:END -->
 ```
+`.gitignore` uses the same VCM managed-block concept with hash comments:
+```gitignore
+# VCM:BEGIN version=1
+.ai/vcm/
+.vcm/
+# VCM:END
+```
 The service:
 - checks whether files exist
@@ -522,7 +650,7 @@ The service:
 It must not overwrite user content outside the VCM block.
-## 13. Translation Architecture
+## 14. Translation Architecture
 Files:
@@ -626,7 +754,7 @@ POST translation/send -> runtime.write(session.id, englishText + "\r")
 The backend strips trailing newlines before appending `\r`.
-## 14. API Surface
+## 15. API Surface
 Project:
@@ -651,8 +779,11 @@ GET  /api/tasks
 POST /api/tasks
 GET  /api/tasks/:taskSlug
 GET  /api/tasks/:taskSlug/status
+POST /api/tasks/:taskSlug/cleanup
 ```
+There is no task-level "switch worktree" API. Worktree selection happens only at task creation.
 Sessions:
 ```text
@@ -708,7 +839,7 @@ WebSockets:
 /ws/translation/:sessionId
 ```
-## 15. Error Handling
+## 16. Error Handling
 File:
@@ -733,7 +864,7 @@ Fastify error handler returns:
 }
 ```
-## 16. Packaging Architecture
+## 17. Packaging Architecture
 `package.json` publishes built artifacts:
@@ -755,7 +886,7 @@ Important scripts:
 - `prepack`: build and package verification
 - `postinstall`: fixes `node-pty` spawn helper when needed
-## 17. Security And Safety Boundaries
+## 18. Security And Safety Boundaries
 Current boundaries:
@@ -764,13 +895,16 @@ Current boundaries:
 - Relaxed Claude permission modes are user-selected per role launch.
 - Translation API key is local in `~/.vcm/settings.json`.
 - Translation output is UI/runtime state only unless a user or role copies it into a file.
-- Handoff artifacts and `.vcm` state live in the connected repository; users should decide what to commit or ignore.
+- `.ai/vcm` is local project control state and must be ignored by Git.
+- Task handoff artifacts live in the task worktree and users should decide whether those artifacts belong in task commits.
+- Task worktrees are created only during task creation; VCM does not expose branch/worktree switching APIs.
 - Sandbox isolation should come from a devContainer, Docker container, VM, or other user-controlled environment.
-## 18. Known Implementation Boundaries
+## 19. Known Implementation Boundaries
 - No tmux backend.
 - No per-role worktree manager.
+- No branch switching for an existing task.
 - No main-page artifact inspector.
 - No raw PTY output translation.
 - No hard workflow gate enforcement.