harald/nixcfg
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs(opencode): make workflow-design Mermaid diagrams Forgejo-compatible

Browse source 
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 `<br/>` safe.

The ADR text and prose continue to use `@<name>` references — those
live in markdown, not Mermaid, and render the same.
This commit is contained in:
Harald Hoyer 2026-05-08 10:24:57 +02:00
parent af0c1d6ea5
commit 0b15944d1c
1 changed files with 26 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

51
config/opencode/workflow-design.md
View file

@ -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<br/>@pm reads TODO/ID.md]
P3[Phase 3: Plan<br/>write plan.md]
P4{Phase 4: Review Plan<br/>@check + @simplify<br/>max 3 cycles}
P5[Phase 5: Split into Tasks<br/>write task-N.md]
P55{Phase 5.5: Review Split<br/>@check<br/>max 2 cycles}
P6[Phase 6: Write Tests<br/>@test ± stub-first @make]
P7[Phase 7: Implement<br/>@make]
P7E{Test-design escalation<br/>max 2 cycles}
P8{Phase 8: Final Review<br/>@check + @simplify<br/>max 3 cycles}
P9[Phase 9: Commit + TODO + Follow-ups + Summary]
P1["Phase 1: Sanity Check"]
P2["Phase 2: Issue Context<br/>pm reads TODO/ID.md"]
P3["Phase 3: Plan<br/>write plan.md"]
P4{"Phase 4: Review Plan<br/>check + simplify<br/>max 3 cycles"}
P5["Phase 5: Split into Tasks<br/>write task-N.md"]
P55{"Phase 5.5: Review Split<br/>check<br/>max 2 cycles"}
P6["Phase 6: Write Tests<br/>test, stub-first make"]
P7["Phase 7: Implement<br/>make"]
P7E{"Test-design escalation<br/>max 2 cycles"}
P8{"Phase 8: Final Review<br/>check + simplify<br/>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: <ISSUE_ID>, status: Todo, label: bug/followup/tech-debt)
with parent ISSUE_ID, status Todo
and label bug, followup, or tech-debt
end note
Done --> [*]