Skip to content

Commit a0d60bd

Browse files
mrsimpsonmrsimpson
committed
feat: add QRSPI-inspired workflow with 5 alignment phases + execution
Create qrspi.yaml workflow implementing the QRSPI (QRISPY) framework adapted for our YAML-based state machine architecture. The workflow has 6 phases: Questions → Research → Design Discussion → Structure Outline → Plan → Implement, enforcing documentation-only work during alignment phases and vertical slice decomposition before coding.
1 parent 1c8e69e commit a0d60bd

4 files changed

Lines changed: 391 additions & 1 deletion

File tree

‎.vibe/development-plan-feat-qrspi-workflow.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Development Plan: repo (feat/qrspi-workflow 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+
Einen QRSPI-inspirierten Workflow erstellen, der das Problem löst, dass Agenten zu schnell Code schreiben ohne Exploration. Inspiriert von Dex Horthy's QRSPI (QRISPY) Framework und Danijel's Agent-Setup.
8+
9+
## Key Decisions
10+
- **QRSPI als Inspiration, nicht 1:1 Kopie**: Wir adaptieren die 5 Alignments-Phasen für unsere YAML-basierte Workflow-Architektur
11+
- **Keine Magic Words**: Das Default-Verhalten muss korrekt sein — keine geheimen Trigger-Phrasen
12+
- **Feature-Ticket während Research verstecken**: Agent sammelt facts ohne premature opinions
13+
- **Design Discussion als eigenständige Phase**: Brain Dump + menschliche Überprüfung vor dem Plan
14+
- **Structure Outline als "C Header File"**: Signatures, neue Typen, Vertical Slices
15+
- **Implement completes to questions (not a terminal state)**: After implementation, the workflow returns to `questions` for the next feature — consistent with the iterative nature of the QRSPI philosophy
16+
- **Abandon always returns to questions**: All `abandon_feature` transitions route to `questions`, providing a clean reset point
17+
- **Domain 'code'**: Workflow is classified under the 'code' domain for discoverability
18+
- **Complexity 'high'**: Reflects the 6-phase nature requiring more upfront investment
19+
20+
## Notes
21+
- Bestehende EPCC-Workflow hat nur 4 Phasen (explore → plan → code → commit)
22+
- QRSPI hat 8 Phasen: Questions → Research → Design Discussion → Structure Outline → Plan → Work Tree → Implement → PR
23+
- Die Kerninnovation von QRSPI: 5 Phasen für Alignment, 3 für Execution
24+
- **Unser Workflow: 6 Phasen** — Work Tree in Plan integriert → Q→R→D→S→P→I
25+
- Context Window sollte unter 40% bleiben, bei 60% fresh session starten
26+
- Vertical Slices (testable Einheiten) statt horizontal layers
27+
28+
## Explore
29+
### Tasks
30+
- [x] QRSPI-Blogpost von Alex Lavaee gelesen und analysiert
31+
- [x] EPCC-Workflow YAML (resources/workflows/epcc.yaml) analysiert
32+
- [x] Workflow-Architektur verstanden (WorkflowManager, YAML-Loader, State Machine)
33+
- [x] Projekt-spezifische Workflows (.vibe/workflows/) untersucht
34+
- [x] opencode.json Konfiguration analysiert
35+
- [x] QRSPI-Design-Entscheidungen dokumentiert
36+
37+
### Completed
38+
- [x] Created development plan file
39+
- [x] QRSPI-Blogpost gelesen: 3 Failure Modes von RPI identifiziert (Instruction Budget, Magic Words, Plan-Reading Illusion)
40+
- [x] QRSPI-Phasen verstanden: Q→R→D→S→P→W→I→PR
41+
- [x] EPCC-Workflow analysiert: 4 Phasen, aber Exploration ist zu kurz
42+
- [x] Workflow-Architektur: YAML-basierte State Machines in resources/workflows/, Projekt-Workflows in .vibe/workflows/
43+
- [x] Design-Entscheidungen getroffen: Feature-Ticket verstecken, Design Discussion eigenständig, Vertical Slices enforced
44+
45+
## Plan
46+
### Tasks
47+
- [x] Analyze EPCC workflow YAML structure and schema constraints
48+
- [x] Understand WorkflowManager architecture (predefined vs project workflows)
49+
- [x] Understand StateMachineLoader and allowed_file_patterns feature
50+
- [x] Understand start_development handler and transition engine
51+
- [x] Design QRSPI workflow state machine with 7 phases
52+
- [x] Define phase transitions and file restrictions
53+
- [x] Write QRSPI workflow YAML file
54+
- [x] Validate YAML against schema constraints
55+
- [x] Create Code phase implementation tasks
56+
- [x] **Work Tree in Plan integrieren**: Work Tree als separater State entfernt, Task-Organisation wird Teil der Plan-Phase
57+
58+
### Completed
59+
- [x] **Architecture Analysis**: EPCC workflow uses YAML-based state machines with `allowed_file_patterns` for phase-specific file restrictions. The WorkflowManager loads workflows from `resources/workflows/` (predefined) and `.vibe/workflows/` (project-specific). The StateMachineLoader validates states, transitions, and provides `getAllowedFilePatterns()` for runtime enforcement.
60+
- [x] **Phase Design Decision**: QRSPI workflow will have 6 phases (Questions → Research → Design Discussion → Structure Outline → Plan → Implement), mapping to the QRSPI philosophy of 5 alignment phases + 1 execution phase. The PR phase is intentionally excluded as a state — it's a human review process, not an agent phase.
61+
- [x] **File Restriction Strategy**: Alignment phases (Questions, Research, Design Discussion, Structure Outline, Plan) restrict to `['**/*.md', '**/*.txt', '**/*.adoc']` to enforce documentation-only work. Execution phase (Implement) allows `['**/*']`.
62+
- [x] **Feature Ticket Hiding**: Research phase instructions explicitly tell the agent to identify the problem WITHOUT reading the feature ticket, collecting facts first.
63+
- [x] **Brain Dump Enforcement**: Design Discussion phase instructs a ~200 line markdown brain dump before any planning.
64+
- [x] **Vertical Slices**: Structure Outline phase enforces "C Header File" style signatures and vertical slice decomposition.
65+
- [x] **Phase Count Finalized**: 6 Phasen (Q→R→D→S→P→I) — Work Tree als separater State entfernt, Task-Organisation in Plan integriert
66+
- [x] **YAML File Created**: `resources/workflows/qrspi.yaml` written with all 6 phases, transitions, and file restrictions
67+
68+
## Code
69+
### Tasks
70+
- [x] Create `resources/workflows/qrspi.yaml` with 6 QRSPI phases
71+
- Phase: `questions` — surface knowledge gaps, validate assumptions, define research scope
72+
- Phase: `research` — factual codebase map WITHOUT reading the feature ticket
73+
- Phase: `design_discussion` — ~200 line brain dump, present options to user
74+
- Phase: `structure_outline` — "C Header File" style signatures + vertical slices
75+
- Phase: `plan` — tactical document + task organization (Work Tree content integriert)
76+
- Phase: `implement` — write code following the plan, build/lint/test each slice
77+
- [x] Verify YAML is valid against `state-machine-schema.json`
78+
- [x] Verify all state transitions reference valid states
79+
- [x] Verify `allowed_file_patterns` are consistent (md/txt/adoc for alignment phases, `**/*` for implement)
80+
- [x] Test workflow loads correctly via WorkflowManager
81+
82+
### Completed
83+
- [x] **Created `resources/workflows/qrspi.yaml`** with 6 QRSPI phases (Questions → Research → Design Discussion → Structure Outline → Plan → Implement)
84+
- `questions` phase: Surface knowledge gaps, validate assumptions, define research scope
85+
- `research` phase: Factual codebase map WITHOUT reading the feature ticket (collect facts first)
86+
- `design_discussion` phase: ~200 line brain dump with design options, trade-offs, and recommendation
87+
- `structure_outline` phase: "C Header File" style signatures, new types, vertical slice decomposition
88+
- `plan` phase: Tactical implementation document with task organization (Work Tree content integrated)
89+
- `implement` phase: Write code following the plan, build/lint/test each vertical slice
90+
- [x] **YAML validated against `state-machine-schema.json`**: All required properties present, no schema violations
91+
- [x] **All state transitions reference valid states**: 6 states, all transitions point to existing states
92+
- [x] **File restrictions consistent**: Alignment phases restrict to `['**/*.md', '**/*.txt', '**/*.adoc']`, Implement allows `['**/*']`
93+
- [x] **All states reachable from initial state**: BFS reachability analysis confirms no orphaned states
94+
- [x] **Workflow loads correctly via WorkflowManager**: Loaded as predefined workflow in domain 'code'
95+
- [x] **Test suite updated**: Added 'qrspi' to expected core workflows list in `workflow-validation.test.ts`
96+
- [x] **All 735 tests pass**: 385 (core) + 286 (server) + 64 (opencode) — zero regressions
97+
98+
## Commit
99+
### Tasks
100+
- [ ] *To be added when this phase becomes active*
101+
102+
### Completed
103+
*None yet*
104+
105+
106+
107+
---
108+
*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/test/unit/workflow-validation.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,13 @@ describe('Workflow Validation', () => {
3131
expect(workflows.length).toBeGreaterThan(0);
3232

3333
// Check that we have the expected core workflows
34-
const expectedCoreWorkflows = ['bugfix', 'waterfall', 'epcc', 'minor'];
34+
const expectedCoreWorkflows = [
35+
'bugfix',
36+
'waterfall',
37+
'epcc',
38+
'minor',
39+
'qrspi',
40+
];
3541
const workflowNames = workflows.map(w => w.name);
3642
for (const workflow of expectedCoreWorkflows) {
3743
expect(workflowNames).toContain(workflow);

‎packages/visualizer/src/services/workflow-list.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ export const workflowList = [
1212
'minor',
1313
'posts',
1414
'pr-review',
15+
'qrspi',
1516
'sdd-bugfix',
1617
'sdd-bugfix-crowd',
1718
'sdd-feature',

0 commit comments

Comments
 (0)