vibe-coding-master 0.4.42 → 0.5.1

package/docs/v0.5-custom-workflow-plan.md

@@ -1,788 +0,0 @@
-# VCM 0.5 Custom Workflow Plan
-
-Last updated: 2026-06-22
-
-This plan was originally drafted as the VCM 0.4 custom workflow plan. It moved
-to VCM 0.5 when VCM 0.4 was narrowed to harness optimization, Harness Engineer,
-and Harness Studio.
-
-This document defines the proposed VCM 0.5 custom workflow architecture.
-
-VCM 0.5 should turn the current fixed role chain into a configurable workflow
-system. Users should be able to compose the task process, edit role definitions,
-choose role runtime policies, and decide where gates, checks, and human review
-belong. The product should still feel like VCM: local, visible, recoverable, and
-oriented around explicit AI role sessions.
-
-## 1. Product Goal
-
-The current VCM workflow is intentionally opinionated:
-
-```text
-project-manager
-  -> architect
-  -> coder
-  -> reviewer
-  -> architect
-  -> project-manager
-```
-
-That default is useful, but it cannot fit every team, repository, or task type.
-Some users need heavier architecture review. Some need a fast bug-fix workflow.
-Some need long-lived planning sessions. Some want fresh implementation sessions.
-Some want mandatory final gates only for high-risk tasks.
-
-VCM 0.5 should make these choices explicit and configurable without turning the
-app into a fragile scripting environment.
-
-The target outcome:
-
-- users can define reusable workflow templates
-- users can customize roles and role instructions from the UI
-- users can configure session lifecycle per role
-- users can add review gates and validation nodes at specific points
-- VCM can show exactly where a task is in the workflow
-- VCM can pause, retry, skip, or reroute a node without losing task state
-- existing VCM workflows keep working through a built-in default template
-
-## 2. Core Principle
-
-Workflow state must be owned by VCM, not inferred from terminals.
-
-Role sessions are execution resources. They can start, stop, restart, fail, or
-survive across several workflow nodes. A workflow run is the source of truth for
-what should happen next.
-
-The key separation:
-
-```text
-Workflow Definition
-  declarative template selected by the user
-
-Workflow Run
-  one task's execution state for the selected definition
-
-Node Instance
-  one concrete execution step inside the run
-
-Role Session
-  long-lived or short-lived terminal/runtime used by role nodes
-```
-
-This separation prevents the main flow from ending only because one terminal
-stopped, and it prevents a long-lived role session from falsely keeping a task
-running when no workflow node is active.
-
-## 3. Non-Goals
-
-VCM 0.5 should not:
-
-- become a general BPMN engine
-- allow arbitrary untrusted code inside workflow definitions
-- require users to understand internal hook details
-- force every task to use a visual workflow editor
-- make the current default workflow disappear
-- mix auxiliary tools into the main engineering workflow
-- treat every terminal session as a workflow participant
-
-## 4. Workflow Definition Model
-
-A workflow definition is a versioned, declarative template.
-
-Recommended top-level shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "standard-feature-workflow",
-  "version": "1.0.0",
-  "name": "Standard Feature Workflow",
-  "description": "Default PM -> Architect -> Coder -> Reviewer flow.",
-  "roles": {},
-  "nodes": [],
-  "edges": [],
-  "variables": {},
-  "artifacts": {},
-  "policies": {}
-}
-```
-
-Definitions should be data, not executable scripts. VCM can validate them,
-render them in the UI, diff them, migrate them, and safely run them.
-
-### 4.1 Built-In Templates
-
-VCM should ship with built-in templates:
-
-- `standard-feature-workflow`: current default multi-role flow
-- `small-change-workflow`: PM plus direct implementation and review
-- `docs-workflow`: planning, content update, validation, final acceptance
-- `review-heavy-workflow`: stricter gates around architecture and final diff
-- `hotfix-workflow`: minimal planning, focused fix, mandatory validation
-
-The built-in templates should be read-only. Users can duplicate one into a
-custom template and edit the copy.
-
-### 4.2 Storage
-
-Workflow definitions and runtime state should not be mixed.
-
-Recommended storage:
-
-```text
-~/.vcm/workflows/
-  user-level workflow templates
-
-<baseRepoRoot>/.ai/vcm/workflow-runs/<taskSlug>/
-  runtime state for a task's workflow run
-
-<baseRepoRoot>/.ai/vcm/handoffs/
-  existing durable role handoff artifacts
-```
-
-Project-specific workflow selection can live in the existing VCM settings
-system. If a team wants to share templates through Git, VCM should provide
-export/import instead of silently writing runtime files into source-controlled
-paths.
-
-### 4.3 Version Pinning
-
-Each task must pin the workflow definition version at task creation time.
-
-If a user edits a workflow template later, existing tasks should continue using
-the pinned snapshot. VCM can offer an explicit "migrate task workflow" action,
-but it must never silently change the process for an active task.
-
-## 5. Role Definition Model
-
-A role definition describes what the role is, how it runs, and what artifacts it
-is expected to produce or consume.
-
-Recommended shape:
-
-```json
-{
-  "id": "architect",
-  "displayName": "Architect",
-  "engine": "claude-code",
-  "instructions": {
-    "mode": "managed-file",
-    "path": ".claude/agents/architect.md"
-  },
-  "model": {
-    "default": "inherit",
-    "allowed": ["inherit", "opus", "sonnet"]
-  },
-  "effort": {
-    "default": "inherit",
-    "allowed": ["inherit", "low", "medium", "high", "max"]
-  },
-  "permissions": {
-    "default": "inherit"
-  },
-  "sessionPolicy": {
-    "lifecycle": "per-task"
-  },
-  "artifacts": {
-    "reads": [],
-    "writes": []
-  }
-}
-```
-
-The UI should let users edit the role name, description, instruction body,
-model, effort, permission profile, working directory, session lifecycle, and
-artifact contracts.
-
-### 5.1 Instruction Sources
-
-VCM should support several instruction modes:
-
-- `managed-file`: VCM installs and updates a role file in the repo harness
-- `inline`: the workflow template stores the role instruction text
-- `external-file`: the workflow references a user-selected local file
-- `built-in`: the role uses a bundled VCM role definition
-
-Managed files should still use protected template blocks where needed, so VCM
-can update the stable harness section without deleting user edits.
-
-### 5.2 Session Lifecycle Policies
-
-Session lifecycle should be explicit per role:
-
-- `per-task`: one session is kept for the whole task
-- `per-node`: a fresh session is started for each node execution
-- `restart-before-node`: the role is restarted before running this node
-- `manual`: VCM prepares the role, but the user starts and drives it manually
-- `disabled`: the role exists in the template but is not active for this run
-
-This is one of the main 0.5 features. Different roles need different memory
-and isolation tradeoffs:
-
-- PM usually benefits from task continuity.
-- Architect may benefit from continuity across planning and final assessment.
-- Coder may benefit from either continuity or a fresh implementation session.
-- Reviewer often benefits from fresh context and independent judgment.
-- A gate reviewer often benefits from narrow context and strict artifact input.
-
-### 5.3 Runtime Engines
-
-The role model should not assume every role uses the same CLI.
-
-Recommended initial engines:
-
-- `claude-code`
-- `manual`
-- `command`
-
-`manual` nodes let the workflow wait for a human decision. `command` nodes run
-predefined local checks that VCM can supervise.
-
-## 6. Node Types
-
-The workflow graph is made of typed nodes. Each node type has a small, stable
-contract that VCM can validate and display.
-
-### 6.1 Role Turn Node
-
-Runs one prompt through one role session.
-
-Fields:
-
-- role id
-- prompt template
-- input artifacts
-- expected output artifacts
-- timeout policy
-- retry policy
-- session lifecycle override
-
-Example uses:
-
-- ask architect for a plan
-- ask coder to implement a scoped plan
-- ask reviewer to validate a diff
-- ask PM to summarize final status
-
-### 6.2 Review Gate Node
-
-Runs an independent review against specific artifacts.
-
-Fields:
-
-- reviewer role id
-- gate name
-- required inputs
-- report path
-- decision schema
-- pass condition
-- failure handling
-
-Recommended decision values:
-
-```text
-approve
-request_changes
-```
-
-The gate should identify issues. Routing after `request_changes` belongs to the
-workflow definition and VCM orchestration, not to the gate role.
-
-### 6.3 Command Check Node
-
-Runs a local command with a declared purpose and captures output.
-
-Fields:
-
-- command template
-- working directory
-- environment policy
-- success exit codes
-- output artifact path
-- timeout
-
-Example uses:
-
-- unit tests
-- format checks
-- type checks
-- lint checks
-- repository-specific validation scripts
-
-### 6.4 Artifact Check Node
-
-Validates that required files exist and match expected shape.
-
-Fields:
-
-- file path
-- required or optional
-- schema type
-- maximum size
-- validation rules
-
-This node should catch missing handoff files, empty reports, invalid gate
-decisions, and stale artifacts before the next role receives bad input.
-
-### 6.5 Human Decision Node
-
-Pauses the workflow and asks the user to choose.
-
-Fields:
-
-- prompt
-- choices
-- default choice
-- required artifact context
-- timeout behavior
-
-Example uses:
-
-- approve high-risk migration
-- choose between two architecture options
-- skip a failed gate with recorded override
-- retry a failed command
-
-### 6.6 Branch Node
-
-Routes based on workflow state or artifact content.
-
-Example conditions:
-
-- gate decision is `approve`
-- gate decision is `request_changes`
-- command check passed
-- user selected retry
-- task risk level is high
-
-Branch logic should use a constrained expression format, not arbitrary code.
-
-### 6.7 Fan-Out / Fan-In Node
-
-Runs several independent checks or reviews, then joins results.
-
-The first implementation can keep role turns sequential for safety. The data
-model should still support future parallelism where it is safe.
-
-### 6.8 Finalization Node
-
-Marks the workflow run complete after required acceptance conditions pass.
-
-It should collect:
-
-- final user-facing summary
-- changed files
-- validation evidence
-- unresolved risks
-- PR or commit status when applicable
-
-## 7. Edges and Routing
-
-Edges connect nodes and define what happens next.
-
-Recommended shape:
-
-```json
-{
-  "from": "review-plan",
-  "to": "implement",
-  "when": "decision == 'approve'"
-}
-```
-
-Routing must be visible in the UI. Users should be able to understand why VCM
-picked the next node.
-
-VCM should support:
-
-- unconditional next step
-- branch by decision
-- retry edge
-- skip edge with recorded reason
-- override edge with recorded user approval
-- loop with maximum iteration count
-
-Every loop must have an explicit maximum iteration count or a human decision
-node. This prevents accidental infinite role ping-pong.
-
-## 8. Artifact Contracts
-
-Workflow nodes should communicate through explicit artifacts, not implicit
-terminal history.
-
-Artifact contracts should define:
-
-- path
-- owner node
-- reader nodes
-- required shape
-- freshness rule
-- append or replace behavior
-- maximum expected size
-
-Example:
-
-```json
-{
-  "id": "architecturePlan",
-  "path": ".ai/vcm/handoffs/architecture-plan.md",
-  "owner": "architect-plan",
-  "readers": ["plan-review-gate", "coder-implementation"],
-  "required": true,
-  "writeMode": "replace",
-  "freshness": "after-node-start"
-}
-```
-
-Artifact contracts solve several current problems:
-
-- VCM can reject empty or stale reports.
-- VCM can show exactly what evidence a node used.
-- Gate inputs can stay narrow and repeatable.
-- Role prompts can be shorter because the artifact list is explicit.
-- Replanning can target the right artifact instead of replaying the whole task.
-
-## 9. Prompt Templates
-
-Each role turn should use a compact prompt template with variables and artifact
-references.
-
-Recommended variable syntax:
-
-```text
-{{task.name}}
-{{task.userRequest}}
-{{artifact.architecturePlan.path}}
-{{workflow.currentNode.name}}
-{{previousNode.summary}}
-```
-
-Prompt templates should avoid duplicating permanent role rules. Stable role
-behavior belongs in role instructions. Node prompts should focus on the current
-job, inputs, expected output, and decision contract.
-
-## 10. Workflow Run State
-
-Each task should have one workflow run state file.
-
-Recommended shape:
-
-```json
-{
-  "taskSlug": "example-task",
-  "workflowId": "standard-feature-workflow",
-  "workflowVersion": "1.0.0",
-  "status": "running",
-  "currentNodeId": "coder-implementation",
-  "nodeRuns": [],
-  "roleSessions": {},
-  "artifacts": {},
-  "events": []
-}
-```
-
-Workflow run status:
-
-```text
-created
-running
-waiting_for_user
-waiting_for_role
-waiting_for_command
-failed
-completed
-cancelled
-```
-
-Node run status:
-
-```text
-pending
-running
-completed
-failed
-skipped
-overridden
-cancelled
-```
-
-Role session status:
-
-```text
-not_started
-starting
-idle
-running
-stopping
-failed
-exited
-```
-
-The workflow run decides whether the task is active. Role sessions only report
-execution state into the run.
-
-## 11. Hooks and State Updates
-
-Hooks should report role runtime events into VCM, but they should not decide
-workflow completion by themselves.
-
-Important events:
-
-- role session started
-- prompt submitted
-- role output stopped
-- command started
-- command completed
-- artifact written
-- artifact validated
-- gate decision recorded
-- user decision recorded
-
-VCM should map hook events to the active node run. If no workflow node is
-waiting for that role, the event is recorded as session activity but must not
-change workflow progress.
-
-This rule is critical for long-lived sessions.
-
-## 12. Permissions and Safety
-
-Workflow definitions should declare required permissions before execution.
-
-Permission layers:
-
-- workflow-level defaults
-- role-level defaults
-- node-level overrides
-- user approval policy
-
-VCM should show a permission summary before starting a task:
-
-- repository roots that may be read
-- paths that may be written
-- commands that may run
-- network policy
-- sandbox profile
-- roles that can edit source files
-- roles that are read-only reviewers
-
-Recommended safety defaults:
-
-- PM can write VCM metadata and handoff files.
-- Architect can write plans, docs, and approved scaffold files.
-- Coder can edit implementation files within task scope.
-- Reviewer is read-only except for review reports.
-- Gate reviewers are read-only except for gate reports.
-- Command nodes can write only declared output artifacts unless explicitly
-  approved.
-
-## 13. UI Design
-
-VCM 0.5 needs two UI layers:
-
-1. Running task view
-2. Workflow builder view
-
-### 13.1 Running Task View
-
-The running task view should show:
-
-- selected workflow template
-- current node
-- next expected node
-- active role session
-- node status timeline
-- role session status
-- required artifacts
-- gate decisions
-- validation results
-- retry / skip / override actions when allowed
-
-The existing terminal workspace remains important, but the workflow graph should
-be the primary explanation for what VCM is doing.
-
-### 13.2 Workflow Builder
-
-The workflow builder should support:
-
-- duplicate built-in template
-- add role
-- edit role instructions
-- configure model, effort, permissions, and session lifecycle
-- add node
-- connect nodes
-- configure branch conditions
-- define artifact contracts
-- define gate decision schema
-- configure retry and override policies
-- preview generated role prompts
-- validate workflow definition
-- dry-run with mock outputs
-
-The first UI version can be form-driven with a compact graph preview. A fully
-free-form visual canvas is useful later, but the first implementation should
-prioritize correctness and validation.
-
-### 13.3 Role Editor
-
-The role editor should include:
-
-- display name
-- engine
-- instruction source
-- instruction editor
-- default model
-- default effort
-- permission profile
-- working directory
-- session lifecycle
-- owned artifacts
-- read artifacts
-
-VCM should warn when a role instruction conflicts with the workflow contract.
-For example, if a node expects a report file but the role instruction says not
-to write files, the workflow should fail validation before running.
-
-## 14. Validation
-
-Workflow validation should run before a task starts.
-
-Checks:
-
-- unique role ids
-- unique node ids
-- all edges reference existing nodes
-- every non-final node has at least one outgoing edge
-- every branch condition references valid fields
-- every required artifact has exactly one owner
-- every required artifact has a validation rule
-- every loop has a max iteration count or human decision node
-- every role node references an active role
-- every gate has a valid decision schema
-- every command node has a timeout
-- selected engines are available
-- required permission profile is valid
-
-VCM should block invalid workflows before task creation.
-
-## 15. Migration Plan
-
-The current VCM flow becomes a built-in template:
-
-```text
-standard-feature-workflow@1
-```
-
-Migration steps:
-
-1. Introduce workflow definition and run state data structures.
-2. Express the current hardcoded flow as a built-in workflow definition.
-3. Route existing orchestration through the workflow engine.
-4. Preserve existing task behavior by default.
-5. Add UI for selecting a built-in workflow at task creation.
-6. Add custom template duplication and editing.
-7. Add richer node types and branch policies.
-
-Existing tasks should continue with their current runtime state. New tasks can
-use workflow definitions once the engine is enabled.
-
-## 16. Implementation Phases
-
-### Phase 1: Workflow Engine Foundation
-
-- Define workflow schema.
-- Define run state schema.
-- Add built-in `standard-feature-workflow`.
-- Convert current orchestration to run through workflow nodes.
-- Keep current UI mostly unchanged.
-- Add workflow event log.
-
-Success condition: current tasks behave the same, but VCM state knows the active
-workflow node instead of inferring flow from role stops.
-
-### Phase 2: Role and Session Customization
-
-- Add role definition editor.
-- Add session lifecycle policies.
-- Add model, effort, permission, and working directory configuration per role.
-- Add role instruction source options.
-- Add role session state visualization.
-
-Success condition: users can customize role behavior without editing harness
-files manually.
-
-### Phase 3: Workflow Builder MVP
-
-- Add template selection at task creation.
-- Add duplicate built-in template.
-- Add form-based node editor.
-- Add edge editor.
-- Add artifact contract editor.
-- Add validation before save.
-- Add compact graph preview.
-
-Success condition: users can create a custom linear or lightly branching
-workflow from the UI.
-
-### Phase 4: Advanced Gates and Branching
-
-- Add reusable gate node configuration.
-- Add retry / skip / override policies.
-- Add loop limits.
-- Add human decision nodes.
-- Add fan-out / fan-in data model.
-
-Success condition: review-heavy and hotfix workflows can be modeled without
-hardcoded special cases.
-
-### Phase 5: Sharing and Auditability
-
-- Add export/import for workflow templates.
-- Add workflow diff view.
-- Add task run replay timeline.
-- Add workflow run diagnostics.
-- Add template migration assistant.
-
-Success condition: users can share, inspect, and evolve workflows safely.
-
-## 17. Open Decisions
-
-The following details should be decided before implementation:
-
-- exact workflow JSON schema
-- whether custom templates should support YAML in addition to JSON
-- how much graph editing belongs in 0.5 versus later versions
-- final expression language for branch conditions
-- whether command nodes should use allowlisted command templates only
-- how workflow templates are imported, exported, and named
-- how to present workflow validation errors in the UI
-- how task creation should choose between default and custom workflow templates
-
-## 18. Recommended 0.5 Scope
-
-The strongest 0.5 scope is:
-
-- workflow engine foundation
-- built-in default workflow expressed as data
-- workflow run state as source of truth
-- role definition model
-- session lifecycle policies
-- template selection
-- custom template duplication
-- form-based role editor
-- form-based node editor for linear workflows
-- explicit artifact contracts
-- workflow validation
-
-Advanced graph editing, complex parallel execution, and template marketplace
-features should wait until the core state model is stable.
-
-## 19. Design Summary
-
-Custom workflows are a major VCM capability because they move the product from a
-single hardcoded process to a configurable local AI workbench.
-
-The important design choice is not the graph UI. The important design choice is
-making workflow runs the source of truth and treating role sessions as managed
-execution resources. Once that separation is in place, custom roles, long-lived
-sessions, fresh review sessions, reusable gates, artifact validation, and
-auditable task progress all become coherent parts of one system.