Skip to content

Commit a32e651

Browse files
mrsimpsonmrsimpson
committed
feat: add true terminal states to all workflows with $DONE_DEFAULT instruction
Remove all outgoing transitions from final states of 14 workflows to make them truly terminal. Add $DONE_DEFAULT placeholder that instructs agents to present results and create PRs (on GitHub repos) without transitioning to any other state. Key changes: - Updated ProjectDocsManager to include $DONE_DEFAULT with explicit 'do NOT transition' instruction - Removed all transitions from final states in 13 workflows - Added explicit 'done' state to TDD workflow (exits TDD cycle) - Deleted obsolete state-machine.ts (100% dead code) - Updated test expectations for new $DONE_DEFAULT value All 385+286+64 tests pass.
1 parent 0b65c88 commit a32e651

21 files changed

Lines changed: 209 additions & 546 deletions

‎.vibe/development-plan-feat-add-terminal-done-state.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Development Plan: repo (feat/add-terminal-done-state branch)
2+
3+
*Generated on 2026-05-26 by Vibe Feature MCP*
4+
*Workflow: [epcc](https://codemcp.github.io/workflows/workflows/epcc)*
5+
6+
## Goal
7+
Make final states of all workflows truly terminal by removing their outgoing transitions. Add a `$DONE_DEFAULT` placeholder to final state instructions that gets substituted at runtime with PR creation and result presentation instructions.
8+
9+
## Key Decisions
10+
1. **Remove, don't add**: Instead of adding a new `done` state, remove ALL outgoing transitions from the existing final states. They become truly terminal by having zero transitions.
11+
2. **`$DONE_DEFAULT` runtime substitution**: Add `$DONE_DEFAULT` to each final state's `default_instructions`. The `InstructionGenerator` already applies variable substitution (via `ProjectDocsManager.getVariableSubstitutions()`), so `$DONE_DEFAULT` will be replaced at runtime with actual instructions.
12+
3. **Terminal detection already works**: The PlantUML renderer (lines 191-203 of `PlantUMLRenderer.ts`) detects states with zero transitions and renders them with `--> [*]`. No changes needed.
13+
4. **No schema change**: `transitions: []` is already valid per the TypeScript type (`transitions: YamlTransition[]`).
14+
5. **Remove obsolete `state-machine.ts`**: The hardcoded state machine (`packages/core/src/state-machine.ts`) is 100% dead code. Remove it entirely.
15+
6. **TDD exception**: The TDD workflow's `refactor` state is not truly terminal — it's the last phase of the iterative TDD cycle. Added an explicit `done` state so agents can exit the cycle. The `refactor` state keeps its cycle transitions (`refactoring_complete → red`, `need_different_approach → green`) while `feature_complete` now transitions to `done` instead of looping back to `explore`.
16+
17+
## Notes
18+
- Currently, 14 workflows have final states with outgoing transitions (loop-back to initial, backward transitions, abandon transitions).
19+
- Removing all outgoing transitions from these final states makes them truly terminal.
20+
- The `$DONE_DEFAULT` instruction will tell agents what to do when they reach the final state (PR creation for GitHub repos, present results to user).
21+
- If agents need to go back to an earlier state or abandon, they can use `proceed_to_phase` to jump to any phase.
22+
- **Critical finding on `state-machine.ts`**: The hardcoded state machine is 100% dead code. Zero source files import from it. Zero tests cover it. Zero runtime code calls its functions. **Decision: Remove it entirely instead of updating it.**
23+
24+
---
25+
26+
## Explore
27+
### Tasks
28+
- [x] Research all workflow YAML files to understand the current state machine structure
29+
- [x] Identify the final state/transition pattern in each workflow
30+
- [x] Examine the hardcoded state machine (`state-machine.ts`) and its terminal behavior
31+
- [x] Review the JSON schema for state machine validation
32+
- [x] Check the PlantUML renderer's terminal state detection logic
33+
- [x] Review the visualizer's state rendering (initial vs terminal states)
34+
- [x] **Investigate whether `state-machine.ts` is actually used** — confirmed 100% dead code
35+
- [x] **Investigate `$DONE_DEFAULT` runtime substitution** — `InstructionGenerator.applyVariableSubstitution()` already handles `$PLACEHOLDER` patterns via `ProjectDocsManager.getVariableSubstitutions()`
36+
- [x] Document findings and create implementation plan
37+
38+
### Completed
39+
- [x] Created development plan file
40+
- [x] Analyzed all 25 YAML workflow files
41+
- [x] Identified the loop-back pattern: final state → initial state
42+
- [x] Reviewed hardcoded state machine (`state-machine.ts`) — confirmed obsolete dead code
43+
- [x] Reviewed schema (`state-machine-schema.json`)
44+
- [x] Reviewed PlantUML renderer (already handles terminal states)
45+
- [x] Documented implementation plan with refined scope
46+
47+
### Final State Analysis
48+
49+
**14 workflows with final states that have outgoing transitions** (need changes):
50+
51+
| Workflow | Final State | Outgoing Transitions |
52+
|---|---|---|
53+
| **boundary-testing** | `finalize` | `need_test_changes` → `test_suite_implementation`, `finalization_complete` → `architecture_analysis` |
54+
| **bugfix** | `finalize` | `need_fix_changes` → `fix`, `finalization_complete` → `reproduce`, `abandon_bug` → `reproduce` |
55+
| **epcc** | `commit` | `need_code_changes` → `code`, `commit_complete` → `explore`, `abandon_feature` → `explore` |
56+
| **greenfield** | `finalize` | `need_code_changes` → `code`, `finalization_complete` → `ideation`, `abandon_project` → `ideation` |
57+
| **minor** | `finalize` | `need_implementation_changes` → `implement`, `finalization_complete` → `explore`, `abandon_feature` → `explore` |
58+
| **posts** | `distribution` | `distribution_complete` → `discovery`, `need_final_review` → `illustration`, `abandon_post` → `discovery` |
59+
| **pr-review** | `publish_review` | `review_published` → `determine_intent` |
60+
| **qrspi** | `commit` | `commit_complete` → `questions`, `need_code_changes` → `implement`, `abandon_feature` → `questions` |
61+
| **skilled-bugfix** | `finalize` | `need_fix_changes` → `fix`, `finalization_complete` → `reproduce`, `abandon_bug` → `reproduce` |
62+
| **skilled-epcc** | `commit` | `need_code_changes` → `code`, `commit_complete` → `explore`, `abandon_feature` → `explore` |
63+
| **skilled-greenfield** | `finalize` | `need_code_changes` → `code`, `finalization_complete` → `ideation`, `abandon_project` → `ideation` |
64+
| **slides** | `deliver` | `delivery_complete` → `ideate`, `need_final_review` → `review`, `abandon_presentation` → `ideate` |
65+
| **tdd** | `refactor` | `refactoring_complete` → `red`, `need_different_approach` → `green`, `feature_complete` → `explore`, `abandon_feature` → `explore` |
66+
| **waterfall** | `finalize` | `need_final_changes` → `implementation`, `finalization_complete` → `requirements` |
67+
68+
**11 workflows already terminal or with no loop-back to initial** (no changes needed):
69+
- `business-analysis` — `analysis_complete` has `transitions: []` (already terminal)
70+
- `sdd-greenfield` — `document` has `transitions: []` (already terminal)
71+
- `sdd-greenfield-crowd` — `document` has self-loop only
72+
- `sdd-bugfix-crowd` — `verify` has backward transitions only
73+
- `sdd-bugfix` — `verify` has backward transitions only
74+
- `sdd-feature-crowd` — `implement` has backward transitions only
75+
- `sdd-feature` — `implement` has backward transitions only
76+
- `adr` — `commit` has backward transition only
77+
- `big-bang-conversion` — `conversion_readiness` has self-loops and backward only
78+
- `c4-analysis` — `analysis_complete` has backward transition only
79+
- `game-beginner` — `celebrate` loops to `imagine` (non-initial)
80+
81+
### Runtime Substitution Infrastructure
82+
83+
The `$DONE_DEFAULT` substitution is already supported:
84+
85+
1. `InstructionGenerator.applyVariableSubstitution()` (line 70-90 of `instruction-generator.ts`) replaces `$PLACEHOLDER` patterns
86+
2. `ProjectDocsManager.getVariableSubstitutions()` (line 445-466 of `project-docs-manager.ts`) returns the substitutions map
87+
3. Both `proceed-to-phase.ts` and `whats-next.ts` call `instructionGenerator.generateInstructions()` which applies substitution
88+
89+
We just need to add `$DONE_DEFAULT` to the substitutions map and to the final states' `default_instructions`.
90+
91+
---
92+
93+
## Plan
94+
### Tasks
95+
- [x] **Add `$DONE_DEFAULT` to substitutions map**: Updated `ProjectDocsManager.getVariableSubstitutions()` to include `$DONE_DEFAULT` with instructions: "Feature work is complete. If this is a GitHub repository: create a PR. Always: present the final result to the user."
96+
97+
- [x] **Update 14 final states**: Removed all `transitions` from the final states and added `$DONE_DEFAULT` to their `default_instructions`:
98+
- `boundary-testing` → `finalize`
99+
- `bugfix` → `finalize`
100+
- `epcc` → `commit`
101+
- `greenfield` → `finalize`
102+
- `minor` → `finalize`
103+
- `posts` → `distribution`
104+
- `pr-review` → `publish_review`
105+
- `qrspi` → `commit`
106+
- `skilled-bugfix` → `finalize`
107+
- `skilled-epcc` → `commit`
108+
- `skilled-greenfield` → `finalize`
109+
- `slides` → `deliver`
110+
- `tdd` → `done` (NEW: added explicit done state)
111+
- `waterfall` → `finalize`
112+
113+
Template for each final state:
114+
```yaml
115+
<final_state>:
116+
description: '...'
117+
default_instructions: |
118+
...existing instructions...
119+
120+
$DONE_DEFAULT
121+
transitions: []
122+
```
123+
124+
**TDD exception**: `refactor` is not truly terminal — it's the last phase of the TDD cycle. Added explicit `done` state:
125+
- `refactoring_complete → red` (kept: TDD cycle transition)
126+
- `need_different_approach → green` (kept: TDD cycle transition)
127+
- `feature_complete → done` (changed from `explore`: exits TDD cycle)
128+
- `abandon_feature → explore` (kept: abandon transition)
129+
- `done` state: `transitions: []`, includes `$DONE_DEFAULT`
130+
131+
- [x] **Remove obsolete `state-machine.ts`**: Deleted `packages/core/src/state-machine.ts` and its re-export from `packages/core/src/index.ts`.
132+
133+
- [x] **Write tests**: Updated `project-docs-manager.test.ts` to include `$DONE_DEFAULT` in expected substitutions map. All 385 tests pass.
134+
135+
- [x] **Verify all workflows still load correctly** after changes: Build succeeded, all tests pass.
136+
137+
### Completed
138+
*All tasks completed during Code phase*
139+
140+
---
141+
142+
## Code
143+
### Tasks
144+
- [x] Add `$DONE_DEFAULT` to `ProjectDocsManager.getVariableSubstitutions()`
145+
- [x] Update 14 final states in YAML workflows (13 with removed transitions + TDD with new `done` state)
146+
- [x] Remove obsolete `state-machine.ts` and its re-export from `index.ts`
147+
- [x] Update existing test for `$DONE_DEFAULT` substitution
148+
- [x] Verify build and all 385 tests pass
149+
150+
### Completed
151+
*All Code phase tasks completed*
152+
153+
## Commit
154+
### Tasks
155+
- [ ] *To be implemented during Commit phase*
156+
157+
### Completed
158+
*None yet*
159+
160+
161+
---
162+
*This plan is maintained by the LLM. Tool responses provide guidance on which section to focus on and what tasks to work on.*

‎packages/core/src/index.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ export * from './state-machine-types.js';
66
export * from './interfaces/index.js';
77

88
// State machine and workflow management
9-
export * from './state-machine.js';
109
export * from './state-machine-loader.js';
1110
export * from './workflow-manager.js';
1211
export * from './transition-engine.js';

‎packages/core/src/project-docs-manager.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,8 @@ export class ProjectDocsManager {
462462
$VIBE_DIR: vibeDir,
463463
$BRANCH_NAME: branchDirName,
464464
$VIBE_ROLE: agentRole,
465+
$DONE_DEFAULT:
466+
'Feature work is complete. Do NOT transition to any other state — this is a terminal state. If this is a GitHub repository: create a PR. Always: present the final result to the user.',
465467
};
466468
}
467469

0 commit comments

Comments
 (0)