From 0b15944d1c5c42726e885768e6811faaab7d52bb Mon Sep 17 00:00:00 2001 From: Harald Hoyer Date: Fri, 8 May 2026 10:24:57 +0200 Subject: [PATCH] docs(opencode): make workflow-design Mermaid diagrams Forgejo-compatible MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forgejo's Mermaid parser is stricter than GitHub's and rejected two diagrams in workflow-design.md: 1. Flowchart 3.1 — `@check`, `@test`, `@make` in pipe-delimited edge labels were tokenised as LINK_ID (newer Mermaid uses `@{...}` for edge IDs), e.g. `P7E -->|@check → @test → @make| P7` failed at the first @. 2. State diagram 3.2 — the second colon inside transition labels (`escalate: test_design`) collided with the `:` field separator that splits transition from label. Drops the @-prefix from labels in all three diagrams (`@check` → `check` in prose-of-the-label only; ADRs and prose elsewhere keep `@check` backticked, which is just markdown). Replaces second colons with descriptive text. Drops parentheses from state-diagram transition labels. Drops the Unicode arrow `→` in favour of plain words. Quotes the flowchart node-label strings to keep `
` safe. The ADR text and prose continue to use `@` references — those live in markdown, not Mermaid, and render the same. --- config/opencode/workflow-design.md | 51 +++++++++++++++--------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md index 4f0d41d..b33d566 100644 --- a/config/opencode/workflow-design.md +++ b/config/opencode/workflow-design.md @@ -40,27 +40,27 @@ High-level happy path with the major escalation arms. ```mermaid flowchart TD - P1[Phase 1: Sanity Check] - P2[Phase 2: Issue Context
@pm reads TODO/ID.md] - P3[Phase 3: Plan
write plan.md] - P4{Phase 4: Review Plan
@check + @simplify
max 3 cycles} - P5[Phase 5: Split into Tasks
write task-N.md] - P55{Phase 5.5: Review Split
@check
max 2 cycles} - P6[Phase 6: Write Tests
@test ± stub-first @make] - P7[Phase 7: Implement
@make] - P7E{Test-design escalation
max 2 cycles} - P8{Phase 8: Final Review
@check + @simplify
max 3 cycles} - P9[Phase 9: Commit + TODO + Follow-ups + Summary] + P1["Phase 1: Sanity Check"] + P2["Phase 2: Issue Context
pm reads TODO/ID.md"] + P3["Phase 3: Plan
write plan.md"] + P4{"Phase 4: Review Plan
check + simplify
max 3 cycles"} + P5["Phase 5: Split into Tasks
write task-N.md"] + P55{"Phase 5.5: Review Split
check
max 2 cycles"} + P6["Phase 6: Write Tests
test, stub-first make"] + P7["Phase 7: Implement
make"] + P7E{"Test-design escalation
max 2 cycles"} + P8{"Phase 8: Final Review
check + simplify
max 3 cycles"} + P9["Phase 9: Commit + TODO + Follow-ups + Summary"] P1 --> P2 --> P3 --> P4 P4 -->|ACCEPTABLE| P5 --> P55 - P4 -->|NEEDS WORK / BLOCK| P3 + P4 -->|NEEDS WORK or BLOCK| P3 P55 -->|ACCEPTABLE| P6 --> P7 P55 -->|NEEDS WORK| P5 P55 -->|BLOCK plan-level| P3 P7 --> P8 - P7 -.->|escalate: test_design| P7E - P7E -->|@check → @test → @make| P7 + P7 -.->|escalate test_design| P7E + P7E -->|check then test then make| P7 P7E -.->|2 cycles exhausted| P3 P8 -->|ACCEPTABLE| P9 P8 -->|production-code finding| P7 @@ -75,20 +75,20 @@ The pattern when `@make` cannot reach GREEN. ```mermaid stateDiagram-v2 - [*] --> Dispatched: orchestrator dispatches @make - Dispatched --> EntryCheck: run tests, verify RED + [*] --> Dispatched: orchestrator dispatches make + Dispatched --> EntryCheck: run tests verify RED EntryCheck --> Implementing: failure code matches handoff EntryCheck --> EntryEscalation: test-quality concern Implementing --> GreenReached: tests pass within 2-3 attempts - Implementing --> MidEscalation: escalate: test_design - Implementing --> MidStuck: incomplete, no flag - MidStuck --> Implementing: re-dispatch with @check notes (1 retry) + Implementing --> MidEscalation: escalate test_design flag + Implementing --> MidStuck: incomplete no flag + MidStuck --> Implementing: re-dispatch with check notes 1 retry MidStuck --> MidEscalation: still failing on retry EntryEscalation --> CheckDiag MidEscalation --> CheckDiag CheckDiag --> TestRedesign: confirmed test-design error - CheckDiag --> Dispatched: rejected (production issue) - TestRedesign --> Dispatched: @test fixes, fresh entry validation + CheckDiag --> Dispatched: rejected production issue + TestRedesign --> Dispatched: test fixes fresh entry validation Dispatched --> PlanRevisit: 2 escalation cycles exhausted GreenReached --> [*] PlanRevisit --> [*]: back to Phase 3 @@ -101,13 +101,14 @@ How TODO entries move through statuses, with sub-issue filing during a run. ```mermaid stateDiagram-v2 [*] --> Todo: issue file created - Todo --> InProgress: Phase 2 (workflow starts) - InProgress --> Done: Phase 9 (run completes successfully) - InProgress --> Todo: workflow fails (failure handler adds comment) + Todo --> InProgress: Phase 2 workflow starts + InProgress --> Done: Phase 9 run completes + InProgress --> Todo: workflow fails, failure handler adds comment note right of InProgress New sub-issues may be filed during Phase 9 - (parent: , status: Todo, label: bug/followup/tech-debt) + with parent ISSUE_ID, status Todo + and label bug, followup, or tech-debt end note Done --> [*]