npm - vibe-coding-master - Versions diffs - 0.3.32 → 0.4.1 - Mend

vibe-coding-master 0.3.32 → 0.4.1

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 (23) hide show

package/README.md +1 -1
package/dist/backend/api/harness-routes.js +56 -0
package/dist/backend/api/session-routes.js +5 -0
package/dist/backend/api/translation-routes.js +4 -0
package/dist/backend/cli/install-vcm-harness.js +12 -0
package/dist/backend/server.js +10 -8
package/dist/backend/services/claude-hook-service.js +42 -2
package/dist/backend/services/harness-revision.js +32 -0
package/dist/backend/services/harness-service.js +324 -118
package/dist/backend/services/session-service.js +385 -13
package/dist/backend/templates/harness/harness-engineer-agent.js +63 -0
package/dist/shared/constants.js +11 -1
package/dist-frontend/assets/index-kJDZAzjD.css +32 -0
package/dist-frontend/assets/index-uYhgIwNK.js +94 -0
package/dist-frontend/index.html +2 -2
package/docs/full-harness-baseline.md +1 -1
package/docs/product-design.md +1 -1
package/docs/v0.4-harness-optimization-plan.md +662 -0
package/docs/{v0.4-custom-workflow-plan.md → v0.5-custom-workflow-plan.md} +15 -11
package/docs/vcm-cc-best-practices.md +7 -12
package/package.json +1 -1
package/dist-frontend/assets/index-BaIbh99h.js +0 -94
package/dist-frontend/assets/index-BvUHLq4X.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-BaIbh99h.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BvUHLq4X.css">
+    <script type="module" crossorigin src="/assets/index-uYhgIwNK.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-kJDZAzjD.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/full-harness-baseline.md CHANGED Viewed

@@ -130,9 +130,9 @@ Project-scoped runtime state lives in the base repository:
 ```text
 <baseRepoRoot>/.ai/vcm/gate-reviewer/session.json
+<baseRepoRoot>/.ai/vcm/harness-engineer/session.json
 <baseRepoRoot>/.ai/vcm/translations/
 <baseRepoRoot>/.ai/vcm/bootstrap/session.json
-<baseRepoRoot>/.ai/vcm/bootstrap/bootstrap.log
 ```
 App-local state lives under `vcmDataDir`:

package/docs/product-design.md CHANGED Viewed

@@ -825,9 +825,9 @@ Project-scoped local files:
 ```text
 .ai/vcm/gate-reviewer/session.json
+.ai/vcm/harness-engineer/session.json
 .ai/vcm/translations/
 .ai/vcm/bootstrap/session.json
-.ai/vcm/bootstrap/bootstrap.log
 ```
 External Claude transcripts:

package/docs/v0.4-harness-optimization-plan.md ADDED Viewed

@@ -0,0 +1,662 @@
+# VCM 0.4 Harness Optimization Plan
+Last updated: 2026-06-22
+This document defines the VCM 0.4 product plan.
+The original VCM 0.4 custom workflow engine plan has moved to
+`docs/v0.5-custom-workflow-plan.md`. VCM 0.4 will focus on the current fixed
+workflow, project harness quality, and visual harness configuration.
+## 1. Product Goal
+VCM 0.4 should make the existing VCM workflow easier to understand, tune, and
+improve without requiring a fully free custom workflow engine.
+The current workflow remains the default product shape:
+```text
+project-manager
+  -> architect
+  -> coder
+  -> reviewer
+  -> architect
+  -> project-manager
+```
+Optional project-level tool roles, such as Gate Reviewer and Translator, stay
+outside the core chain unless VCM explicitly routes work to them.
+The target outcome:
+- users can inspect all VCM harness content from the UI
+- users can adjust role definitions, skills, and project harness settings safely
+- users can ask a dedicated Harness Engineer to improve project harness quality
+- every proposed harness change is shown as a diff before it is applied
+- VCM fixed managed blocks remain protected
+- VCM product or template problems can be reported upstream as GitHub issues
+- the current workflow becomes more reliable without adding arbitrary workflow
+  graph editing in 0.4
+## 2. Scope Decision
+VCM 0.4 is not the free custom workflow release.
+The previous custom workflow plan is still valuable, but it is too large for the
+next release because it requires a workflow engine, node model, branch
+conditions, artifact contracts, graph editing, workflow run state, and migration
+rules.
+VCM 0.4 should instead be:
+```text
+Harness Engineer + Harness Studio
+```
+This gives users direct control over the system they already use every day:
+roles, skills, managed blocks, project instructions, session defaults, and
+harness update flow.
+## 3. Non-Goals
+VCM 0.4 should not:
+- build a general workflow graph editor
+- replace the current fixed VCM role chain
+- allow arbitrary user-defined workflow nodes
+- allow AI to silently edit harness files
+- let any role overwrite VCM fixed managed blocks
+- make auxiliary roles part of the main task flow by default
+- submit external GitHub issues without explicit user confirmation
+- require users to understand Claude Code hook internals
+## 4. Core Concepts
+### 4.1 Fixed Harness
+Fixed harness content is VCM-owned template content installed into a project.
+It includes managed blocks in files such as:
+- `CLAUDE.md`
+- `.claude/agents/project-manager.md`
+- `.claude/agents/architect.md`
+- `.claude/agents/coder.md`
+- `.claude/agents/reviewer.md`
+- `.claude/agents/gate-reviewer.md`
+- `.claude/agents/translator.md`
+- `.claude/skills/*/SKILL.md`
+- `.ai/tools/*`
+- `.ai/vcm-harness-manifest.json`
+VCM fixed content is updated by VCM releases and the harness installer. It must
+remain deterministic and recoverable.
+### 4.2 Project Harness Customization
+Project harness customization is repository-specific guidance layered around
+VCM fixed content.
+Examples:
+- project coding rules
+- domain terminology
+- repository-specific testing commands
+- module boundaries
+- review preferences
+- role behavior tweaks
+- scaffold conventions
+- project-specific validation expectations
+Project harness customization is the primary editable surface for VCM 0.4.
+### 4.3 Harness Engineer
+`harness-engineer` is a project-scoped Claude Code tool role.
+It understands:
+- VCM fixed harness rules
+- project-specific harness content
+- role definitions
+- skills
+- project docs
+- harness manifest state
+- the boundary between VCM product defects and project harness defects
+It helps users improve the harness, but it is not part of the task workflow
+round state.
+## 5. Harness Engineer Role
+### 5.1 Role Identity
+Recommended role id:
+```text
+harness-engineer
+```
+Recommended display name:
+```text
+Harness Engineer
+```
+The role should be project-scoped, not task-scoped.
+Session behavior:
+- one long-lived session per project
+- default action is resume existing session
+- restart is available from the Harness Engineer session panel
+- closing a task does not stop this role
+- this role does not keep a VCM task round running
+- this role can be opened from Harness Studio
+### 5.2 Responsibilities
+Harness Engineer is responsible for:
+- reading current project harness files
+- understanding VCM fixed harness constraints
+- accepting user feedback about role behavior or harness quality
+- diagnosing whether a problem is project-specific or VCM-level
+- proposing harness changes as reviewable diffs
+- explaining the impact of proposed changes
+- identifying which active sessions may need restart or a reminder
+- helping the user keep harness content concise and consistent
+- drafting VCM GitHub issues for product or template problems
+### 5.3 Boundaries
+Harness Engineer must not:
+- silently apply changes
+- edit business source code as part of harness maintenance
+- overwrite VCM fixed managed blocks
+- submit GitHub issues without user confirmation
+- include private project code, logs, or secrets in an upstream issue
+- modify task workflow state
+- act as PM, Architect, Coder, Reviewer, Gate Reviewer, or Translator
+### 5.4 Allowed Files
+Harness Engineer may inspect:
+- `CLAUDE.md`
+- `.claude/agents/**`
+- `.claude/skills/**`
+- `.ai/tools/**`
+- `.ai/vcm-harness-manifest.json`
+- `.ai/generated/**`
+- project docs such as `docs/ARCHITECTURE.md` and `docs/TESTING.md`
+- VCM state relevant to harness status
+Harness Engineer may propose edits to:
+- project-editable harness sections
+- role files outside protected fixed managed blocks
+- project docs used by harness
+- project-specific skill guidance when allowed
+Harness Engineer may not directly edit VCM fixed managed blocks. If it finds a
+fixed block problem, it should create a VCM issue draft instead.
+## 6. Harness Studio UI
+VCM 0.4 should add a Harness Studio UI for inspecting and configuring harness
+content.
+### 6.1 Entry Point
+The existing VCM Harness sidebar group can become the entry point.
+Recommended actions:
+- Open Harness Studio
+- Refresh harness status
+- Apply fixed harness update
+- Run bootstrap
+- Commit & rebase task
+- Open Harness Engineer session
+### 6.2 Main Views
+Harness Studio should include:
+- Overview
+- Agents
+- Skills
+- Root Context
+- Project Docs
+- Tools
+- Harness Status
+- Proposed Changes
+- VCM Feedback
+### 6.3 Overview
+Overview should show:
+- fixed harness status
+- bootstrap status
+- modified harness files
+- outdated managed blocks
+- missing expected files
+- active task worktree sync status
+- Harness Engineer session status
+- recent harness actions
+### 6.4 Agents
+Agents view should show:
+- Project Manager
+- Architect
+- Coder
+- Reviewer
+- Gate Reviewer
+- Translator
+- Harness Engineer
+For each agent:
+- file path
+- role type: core, optional flow role, or tool role
+- session scope: task or project
+- managed block status
+- editable project section
+- default model
+- default effort
+- permission mode
+- restart requirement after changes
+The UI should make role type visible:
+- core workflow role: participates in task flow
+- optional flow role: participates only when enabled
+- tool role: project utility, not part of task flow
+### 6.5 Skills
+Skills view should show installed VCM skills:
+- `vcm-route-message`
+- `vcm-final-acceptance`
+- `vcm-harness-bootstrap`
+- `vcm-long-running-validation`
+- `vcm-gate-review`
+For each skill:
+- file path
+- description
+- managed block status
+- whether it is current
+- related roles
+- editable project notes when supported
+### 6.6 Root Context
+Root Context view should show:
+- `CLAUDE.md`
+- VCM fixed managed block status
+- project-specific sections
+- warnings for duplicated or conflicting rules
+- active session refresh guidance
+### 6.7 Project Docs
+Project Docs view should show durable harness-relevant docs:
+- architecture docs
+- module docs
+- testing docs
+- public surface docs
+- module index
+- generated docs
+It should show whether docs are missing, stale, or incomplete.
+### 6.8 Tools
+Tools view should show:
+- `.ai/tools/run-long-check`
+- `.ai/tools/watch-job`
+- `.ai/tools/vcm-bash-guard`
+- `.ai/tools/request-gate-review`
+- generated doc tools
+For each tool:
+- path
+- executable status
+- managed status
+- purpose
+- related skill
+### 6.9 Proposed Changes
+All Harness Engineer changes must flow through Proposed Changes.
+The UI should show:
+- changed files
+- unified diff
+- generated summary
+- risk notes
+- affected roles
+- whether active sessions need restart or reminder
+- apply, discard, or revise actions
+No harness edit should be applied without user confirmation.
+### 6.10 VCM Feedback
+VCM Feedback view handles upstream VCM issues.
+When Harness Engineer finds a VCM-level product or fixed template issue, it
+should create an issue draft for:
+```text
+https://github.com/CodingForMoney/VibeCodingMaster
+```
+The user must review and confirm before VCM submits the issue.
+## 7. Change Review Model
+All modifications require reviewable diffs.
+Required flow:
+```text
+User feedback or harness diagnosis
+  -> Harness Engineer proposes changes
+  -> VCM stores a pending change set
+  -> UI shows diff and impact
+  -> User confirms
+  -> VCM applies the changes
+  -> VCM refreshes harness status
+  -> User may commit and rebase active task worktrees
+```
+Harness Engineer can explain, revise, or discard pending changes, but it cannot
+skip the review step.
+## 8. VCM Issue Feedback Flow
+Harness Engineer must classify issues before acting:
+```text
+Project harness issue
+  -> propose project harness diff
+VCM product or fixed template issue
+  -> draft GitHub issue for CodingForMoney/VibeCodingMaster
+```
+### 8.1 Issue Draft Requirements
+A VCM issue draft should include:
+- title
+- problem description
+- reproduction steps
+- expected behavior
+- actual behavior
+- VCM version
+- affected harness files or UI areas
+- impact
+- suggested fix if known
+- sanitized context only
+### 8.2 Privacy Rules
+Issue drafts must not include:
+- private source code
+- secrets
+- private file contents
+- full terminal logs
+- private repository names unless user confirms
+- user identity or environment details unless necessary
+Harness Engineer should summarize private context instead of copying it.
+### 8.3 Submission Rule
+VCM may submit the issue only after explicit user confirmation.
+Before submission, UI should show:
+- target repository
+- final issue title
+- final issue body
+- privacy warning
+- submit or cancel action
+## 9. Managed Block Policy
+VCM managed blocks remain protected.
+Managed blocks use markers such as:
+```text
+<!-- VCM:BEGIN version=1 -->
+...
+<!-- VCM:END -->
+```
+or:
+```text
+# VCM:BEGIN version=1
+...
+# VCM:END
+```
+Rules:
+- VCM installer owns fixed managed block content.
+- Harness Engineer must not directly rewrite fixed managed block content.
+- Project-specific customization should live outside fixed managed blocks.
+- If a fixed managed block is wrong, create a VCM issue draft.
+- If a managed block is stale, users should run fixed harness update.
+- If a managed block is user-modified, VCM should warn before replacing it.
+## 10. Session Refresh Policy
+Claude Code sessions do not automatically re-read every changed instruction file
+in a reliable, user-visible way.
+VCM tracks a project-level `harnessRevision`.
+Revision behavior:
+- fixed harness update increments the revision when it changes files
+- Harness Studio file saves increment the revision when content changes
+- each Claude Code role session records the revision it started or resumed with
+- session views compare the recorded revision with the current project revision
+- stale sessions are shown as `outdated`
+VCM offers:
+- `Notify role`: send a compact update message into the running session, asking
+  the role to re-read `CLAUDE.md`, its agent definition, and relevant skills
+- `Restart`: start a fresh Claude Code process when role definition, hook, or
+  core harness changes are significant
+- `Resume`: for stopped sessions, reload through the normal Claude Code startup
+  path
+Harness Engineer should include session impact in every proposed change.
+## 11. Storage
+Recommended storage:
+```text
+<baseRepoRoot>/.ai/vcm/harness/
+  pending-changes/
+  applied-changes/
+  issue-drafts/
+  diagnostics/
+<baseRepoRoot>/.ai/vcm/harness-engineer/
+  session.json
+```
+Guidelines:
+- pending changes are review artifacts
+- applied change records are lightweight audit metadata
+- issue drafts are user-reviewable
+- no unnecessary terminal logs
+- no hidden external submissions
+## 12. Backend Capabilities
+VCM backend should provide APIs for:
+- listing harness files
+- reading harness file content
+- validating managed blocks
+- computing diffs
+- storing pending change sets
+- applying confirmed changes
+- discarding pending changes
+- refreshing harness status
+- starting, resuming, restarting, and stopping Harness Engineer
+- creating VCM issue drafts
+- submitting confirmed GitHub issues
+GitHub issue creation should be optional and graceful:
+- if GitHub auth is unavailable, keep the issue draft and show manual copy
+- if network fails, preserve the draft and allow retry
+## 13. Safety and Permissions
+Default safety rules:
+- Harness Engineer can read project harness files.
+- Harness Engineer can write only through VCM pending change sets by default.
+- Direct file writes should be reserved for confirmed apply operations.
+- VCM should validate paths before applying changes.
+- External issue submission always requires user confirmation.
+- Fixed managed block edits are blocked unless performed by the VCM installer.
+The safest default is:
+```text
+AI proposes.
+VCM diffs.
+User approves.
+VCM applies.
+```
+## 14. Relation to Current Workflow
+VCM 0.4 should not change the task execution model by default.
+Current behavior remains:
+- PM coordinates the task.
+- Architect plans and evaluates complex fixes.
+- Coder implements.
+- Reviewer validates.
+- Gate Reviewer optionally performs gate reviews.
+- Translator remains a project translation tool role.
+- Harness Engineer maintains harness quality.
+Harness Engineer is not included in:
+- role tab bar for a task
+- VCM round completion detection
+- task close cleanup
+- PM dispatch flow
+It is opened from Harness Studio as a project tool session.
+## 15. Implementation Phases
+### Phase 1: Harness Engineer Role
+- Add `harness-engineer` role definition.
+- Install `.claude/agents/harness-engineer.md`.
+- Add project-scoped session persistence.
+- Add UI entry to open Harness Engineer session.
+- Ensure it is not part of task round state.
+Success condition: users can start or resume Harness Engineer for a project
+without affecting active tasks.
+### Phase 2: Harness Inventory and Status UI
+- Add Harness Studio shell.
+- List agents, skills, root context, tools, and project docs.
+- Show managed block status.
+- Show stale, missing, and modified harness files.
+Success condition: users can understand current harness state without opening
+files manually.
+### Phase 3: Diff-Based Harness Changes
+- Add pending change set model.
+- Let Harness Engineer propose changes.
+- Show diffs in UI.
+- Require user confirmation before apply.
+- Refresh harness status after apply.
+Success condition: no harness change is applied invisibly.
+### Phase 4: Session Impact and Worktree Sync
+- Track `harnessRevision` for project harness changes.
+- Mark sessions with older revisions as `outdated`.
+- Offer `Notify role` for running stale sessions.
+- Keep restart available for stronger reload needs.
+- Integrate with existing Commit & rebase task flow.
+Success condition: harness updates do not leave active task worktrees or active
+role sessions silently stale.
+### Phase 5: VCM Issue Feedback
+- Add VCM issue draft model.
+- Add issue draft UI.
+- Add optional GitHub issue submission after confirmation.
+- Add privacy checks and manual copy fallback.
+Success condition: Harness Engineer can help users report VCM product or fixed
+template problems upstream safely.
+## 16. Open Decisions
+Before implementation, decide:
+- final role name: `harness-engineer` or `harness-maintainer`
+- exact editable sections in each harness file
+- whether pending change sets store full file snapshots or patches
+- GitHub integration method for issue submission
+- whether Harness Engineer can run validation commands directly
+- how to show session restart impact in the UI
+- whether applied change audit records should be committed or ignored
+## 17. Design Summary
+VCM 0.4 should optimize the workflow VCM already has.
+The important product move is not free-form workflow editing. The important
+move is making harness configuration visible, reviewable, and improvable.
+Harness Engineer gives users an AI collaborator that understands both VCM's
+fixed harness and the project's local harness. Harness Studio gives users a
+safe place to inspect and apply changes. The GitHub issue feedback flow closes
+the loop when a project-level harness problem is actually a VCM product or
+template problem.
+VCM 0.5 can then build on this foundation with the full custom workflow engine.