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.
Operational rules in commands/workflow.md and the agent files have
been accreting through repeated patches, with the rationale scattered
across commit messages and conversations. New gaps kept surfacing
after the fact (Phase 7 mid-impl escalation, Phase 8 routing for
test-design findings, Phase 5.5 entirely missing) because there was
no single place to audit the flow.
Adds config/opencode/workflow-design.md as a sibling to commands/
and agents/. It is the design rationale and decision log; operational
rules stay in the command and agent files. The intended flow is:
discuss new ideas / failure modes here → reach a decision → update
the operational files → record the decision in the ADR log.
Pre-populated with: cast & responsibilities table; three Mermaid
diagrams (phase pipeline, Phase 7 escalation state machine, issue
lifecycle); a routing matrix that lists every observed (phase,
signal) → action pair so gaps are visible at a glance; 12 ADRs
covering decisions made over the past several days (forge-agnostic,
TODO/ folder, worktree-only, polyglot agents, absolute-path dispatch,
run artifacts on disk, stub-first Rust TDD, @test inside cfg(test)
mod, Phase 5.5, single-mode @pm, file follow-ups, Phase 7 mid-impl
escalation); and 5 open questions teed up for future discussion.
