vibe-coding-master 0.3.22 → 0.3.24

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

@@ -0,0 +1,785 @@
+# VCM 0.4 Custom Workflow Plan
+
+Last updated: 2026-06-21
+
+This document defines the proposed VCM 0.4 custom workflow architecture.
+
+VCM 0.4 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.4 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.4 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.4 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`
+- `codex-cli`
+- `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.4 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.4 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.4 Scope
+
+The strongest 0.4 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.