1# Mermaid Skill Bakeoff2 3Same scenario, four subagent handoffs. These are not hand-authored fixtures; each lane received the local `SKILL.md` for that skill and the same PlanPack scenario prompt.4 5## Scenario6 7PlanPack is a JSON-first planning system for AI orchestrators. We need a Mermaid diagram for a technical human reviewing the planned pipeline for a feature called `collaborative-plan-comments`.8 9The feature lets a user open a PlanPack in the web viewer, review the human-readable plan, leave comments or quick actions on specific plan sections, copy/export those comments back to the orchestrator, and then have the orchestrator update the JSON plan.10 11The pipeline must preserve this opinionated method: planning/research/idea generation happen before consolidation; validation contract/test design is written before implementation; implementation and validation are separate agents; final code review can block or send mortem/process feedback back to the orchestrator. Show where work is serial vs parallel and where humans review.12 13## Viewer Links14 15- [Design Doc Mermaid](/mermaid/examples/subagent-design-doc-mermaid)16- [Pretty Mermaid](/mermaid/examples/subagent-pretty-mermaid)17- [Beautiful Mermaid](/mermaid/examples/subagent-beautiful-mermaid)18- [Mermaid To GIF](/mermaid/examples/subagent-mermaid-to-gif)19- [Mermaid Diagrams](/mermaid/examples/subagent-mermaid-diagrams)20- [Diagram Specialist](/mermaid/examples/subagent-mermaid-diagram-specialist)21- [Mermaid Visualizer](/mermaid/examples/subagent-mermaid-visualizer)22- [Mermaid To ProVerif](/mermaid/examples/subagent-mermaid-to-proverif)23- [GIF artifact](/mermaid/gif-demo)24 25## Design Doc Mermaid26 27### Handoff Prompt28 29Create a compact Mermaid workflow diagram for `collaborative-plan-comments`: show PlanPack JSON as source of truth, parallel research/ideas before consolidation, human viewer comments exported to the orchestrator, validation contract before implementation, separate implementation/validation agents, and code review blocking or feeding mortem/process notes back.30 31### Output32 33```mermaid34flowchart TD35  Brief["Feature brief: collaborative-plan-comments"] --> O["Orchestrator owns PlanPack JSON"]36 37  O --> P1["Research lane"]38  O --> P2["Idea generation lane"]39  O --> P3["Planning constraints lane"]40  P1 --> C["Consolidate findings into JSON plan"]41  P2 --> C42  P3 --> C43 44  C --> V["Web viewer opens PlanPack"]45  V --> H{"Human reviews readable plan"}46  H -->|"section comments"| CM["Comments tied to plan sections"]47  H -->|"quick actions"| QA["Approve / block / rescope / clarify"]48  CM --> EX["Copy or export comment bundle"]49  QA --> EX50  EX --> O2["Orchestrator applies feedback"]51  O2 --> JP["Updated PlanPack JSON"]52 53  JP --> VC["Write validation contract and test design"]54  VC --> HG{"Human gate: contract clear?"}55  HG -->|"revise"| O256  HG -->|"approved"| IA["Implementation agent builds feature"]57 58  VC --> VA0["Validation agent receives contract only"]59  IA --> IH["Implementation handoff"]60  IH --> VA["Validation agent verifies independently"]61  VA --> VR{"Validation passes?"}62  VR -->|"no"| O263  VR -->|"yes"| CR["Final code review"]64 65  CR --> CRD{"Review decision"}66  CRD -->|"block"| O267  CRD -->|"mortem / process feedback"| M["Structured feedback to orchestrator"]68  M --> O269  CRD -->|"approve"| Done["Ready for merge / release lane"]70```71 72## Pretty Mermaid73 74### Handoff Prompt75 76Create a compact, polished Mermaid flowchart for PlanPack `collaborative-plan-comments`: show parallel discovery before consolidation, human viewer section comments exported to the orchestrator, JSON plan revision, validation contract/test design before implementation, separate implementation and validation agents, human reviews, and final code-review block/mortem feedback loops.77 78### Output79 80```mermaid81flowchart TD82  A[Feature request: collaborative-plan-comments] --> O[Orchestrator opens draft PlanPack JSON]83  O --> P0{{Parallel discovery lanes}}84  P0 --> R[Research lane]85  P0 --> I[Idea generation lane]86  P0 --> C[Constraint and risk scan]87  R --> K[Consolidate findings]88  I --> K89  C --> K90  K --> H[Generate human-readable plan view]91  H --> V[Web viewer: human reviews plan sections]92  V --> M[Section comments and quick actions]93  M --> E[Copy/export comment bundle]94  E --> O2[Orchestrator imports feedback]95  O2 --> J[Update canonical JSON plan<br/>revisions + events]96  J --> T[Write validation contract<br/>and test design]97  T --> HR{{Human review: scope and contract}}98  HR -- revise --> O299  HR -- approve --> IM[Implementation agent<br/>builds from JSON plan]100  T --> VA0[Validation agent prepares checks<br/>from contract only]101  IM --> IH[Implementation handoff]102  IH --> VA[Validation agent runs independent validation]103  VA --> VR{{Human review: validation result}}104  VR -- fail / rescope --> O2105  VR -- pass --> CR[Final code review]106  CR --> D{Review outcome}107  D -- block --> O2108  D -- mortem / process feedback --> PF[Orchestrator updates plan process notes]109  PF --> O2110  D -- approve --> Done[Ready for release lane]111```112 113## Beautiful Mermaid114 115### Handoff Prompt116 117Create a compact, polished Mermaid flowchart for the `collaborative-plan-comments` PlanPack pipeline, showing serial vs parallel work, human review points, orchestrator JSON updates, separate implementation/validation agents, and final review feedback loops.118 119### Output120 121```mermaid122flowchart LR123  O[Orchestrator<br/>drafts JSON PlanPack] --> V[Web viewer<br/>renders readable plan]124  V --> H{{Human review<br/>plan sections}}125  H --> C[Section comments<br/>and quick actions]126  C --> X[Copy / export<br/>feedback bundle]127  X --> U[Orchestrator<br/>updates JSON plan]128  U --> D{Pre-consolidation<br/>parallel lanes}129  subgraph P[Parallel: explore before deciding]130    R[Research]131    I[Idea generation]132    Q[Risk / constraint scan]133  end134  D --> R135  D --> I136  D --> Q137  R --> K[Consolidate<br/>single planned pipeline]138  I --> K139  Q --> K140  K --> T[Write validation contract<br/>and test design]141  T --> HR{{Human review<br/>contract + plan}}142  HR --> A{Build lanes}143  subgraph B[Separate agents]144    IA[Implementation agent<br/>builds feature]145    VA[Validation agent<br/>prepares checks from contract]146  end147  A --> IA148  A --> VA149  IA --> M[Candidate implementation]150  VA --> W[Validation harness ready]151  M --> Z[Validation agent<br/>runs contract tests]152  W --> Z153  Z --> CR{{Final code review}}154  CR -->|approved| DONE[Ready to ship]155  CR -->|blocks| U156  CR -->|mortem / process feedback| U157```158 159## Mermaid To GIF160 161### Handoff Prompt162 163Animate this Mermaid pipeline as a compact technical GIF: show PlanPack JSON through viewer comments, orchestrator revision, research-first planning, contract-first testing, separate implementation/validation agents, human gates, and code-review feedback loops.164 165### Output166 167```mermaid168flowchart LR169  A[PlanPack JSON<br/>canonical source] --> B[Hash-pack viewer payload]170  B --> H1{{Human opens web viewer<br/>reviews readable plan}}171  H1 --> C[Section comments<br/>quick actions]172  C --> D[Copy/export feedback bundle]173  D --> O[Orchestrator imports feedback<br/>revises JSON plan]174  O --> S1[Info collection<br/>scope constraints blockers]175  S1 --> P1176  subgraph P1[Parallel before consolidation]177    I1[Idea generation<br/>divergent]178    R1[Research<br/>repo docs patterns tests]179    I2[Idea generation<br/>research-informed]180  end181  P1 --> K[Consolidation<br/>features milestones contract]182  K --> H2{{Human planning gate<br/>approve scope + validation}}183  H2 --> T[Test design agent<br/>validation contract to checks]184  T --> H3{{Human pre-implementation gate<br/>blocked/manual checks visible}}185  H3 --> M[Implementation agent<br/>serial slices unless isolated]186  M --> V[Independent validation agent<br/>fresh context no fixes]187  V --> CR[Final code review<br/>correctness risk tests scope]188  CR -->|pass| H4{{Human final handoff<br/>PR preview instructions}}189  CR -->|block| O190  CR -->|mortem/process feedback| O191  H4 -->|new comments| C192```193 194### GIF Notes195 196Style choice: `highlight-walk`.197 198Storyboard: JSON to viewer; human section comments; export feedback to orchestrator; research-first consolidation; contract, build, validate, review loop.199 200## Mermaid Diagrams201 202### Handoff Prompt203 204Create a compact Mermaid flowchart for `collaborative-plan-comments`: show PlanPack JSON as canonical, viewer section comments exported back to the orchestrator, PlanPack's serial/parallel pipeline, human review gates, validation-before-implementation, separate implementation/validation agents, and code review blocking or sending process feedback.205 206### Output207 208```mermaid209flowchart TD210  J[Canonical PlanPack JSON] --> P[Hash-pack viewer payload]211  P --> V[Web viewer: human-readable plan]212  V --> H1{Human reviews sections}213  H1 --> C[Section comments + quick actions]214  C --> X[Copy/export feedback bundle]215  X --> O[orchestrator.planpack.v1 updates JSON plan]216  O --> J217  J --> IC[information_collection]218  IC --> IG1[idea_generation: divergent]219  IG1 --> R1[research: repo patterns/docs/tests]220  IG1 --> IGP[parallel idea exploration]221  R1 --> IG2[idea_generation: research-informed]222  IGP --> IG2223  IG2 --> CON[consolidation: features + validation contract + milestones]224  CON --> G1{Human planning gate}225  G1 -->|request changes| O226  G1 -->|approve scope + validation| TD[test_design by testing.contract-first.v1]227  TD --> G2{Pre-implementation human gate}228  G2 -->|blocked decisions| O229  G2 -->|approved checks| IMP[implementation.serial.v1]230  IMP --> VH[implementation handoff]231  VH --> VAL[validation.independent.v1]232  VAL --> CR[code-review.thermonuclear.v1]233  CR --> G3{Final review gate}234  G3 -->|blockers| O235  G3 -->|mortem/process feedback| O236  G3 -->|approved| HAND[handoff: PR, preview, tests, blockers, next action]237```238 239## Diagram Specialist240 241### Handoff Prompt242 243Create a compact Mermaid flowchart for `collaborative-plan-comments` showing PlanPack JSON planning, web viewer human comments, export back to orchestrator, JSON plan update, research before consolidation, validation contract before implementation, separate implementation and validation agents, and final review feedback/blocking loops.244 245### Output246 247```mermaid248flowchart TD249  A[Orchestrator creates PlanPack JSON] --> B[Web viewer renders human-readable plan]250  B --> H1{{Human reviews plan sections}}251  H1 --> C[Comments and quick actions anchored to sections]252  C --> D[Copy/export comment bundle]253  D --> E[Orchestrator ingests comments]254  E --> F[Update JSON plan]255  F --> P0[Start pipeline]256  P0 --> R1[Research agent]257  P0 --> R2[Idea generation agent]258  P0 --> R3[Planning agent]259  R1 --> K[Consolidate findings into plan]260  R2 --> K261  R3 --> K262  K --> V0[Write validation contract and test design]263  V0 --> H2{{Human reviews plan and validation contract}}264  H2 -->|changes requested| E265  H2 -->|approved| I[Implementation agent builds feature]266  V0 --> VA[Validation agent prepares checks]267  I --> T[Run validation against contract]268  VA --> T269  T --> CR[Final code review]270  CR -->|approved| SHIP[Ready for merge/release]271  CR -->|blocks| E272  CR -->|mortem or process feedback| M[Capture feedback for orchestrator]273  M --> E274```275 276## Mermaid Visualizer277 278### Handoff Prompt279 280Create a compact professional Mermaid process flow for `collaborative-plan-comments`: show parallel discovery before consolidation, PlanPack JSON as canonical source, web viewer human section comments exported to the orchestrator, validation contract before implementation, separate implementation and validation agents, human gates, and final code-review block or mortem feedback loops.281 282### Output283 284```mermaid285flowchart TB286  brief["Feature brief: collaborative-plan-comments"] --> orchestrator["Orchestrator starts canonical PlanPack JSON"]287  orchestrator --> parallelStart{"Parallel discovery before consolidation"}288  parallelStart --> research["Research lane"]289  parallelStart --> ideas["Idea generation lane"]290  parallelStart --> constraints["Constraints and risk scan"]291  subgraph discovery["Parallel: explore before deciding"]292    research293    ideas294    constraints295  end296  research --> consolidate["Consolidate into one planned pipeline"]297  ideas --> consolidate298  constraints --> consolidate299  consolidate --> jsonPlan["PlanPack JSON updated"]300  jsonPlan --> viewer["Web viewer renders human-readable plan"]301  viewer --> humanPlan{"Human reviews plan sections"}302  humanPlan --> comments["Section comments"]303  humanPlan --> actions["Quick actions: approve, block, rescope, clarify"]304  comments --> exportBundle["Copy or export feedback bundle"]305  actions --> exportBundle306  exportBundle --> revise["Orchestrator imports feedback and revises JSON"]307  revise --> contract["Write validation contract and test design"]308  contract --> humanContract{"Human gate: scope and contract clear?"}309  humanContract -->|revise| revise310  humanContract -->|approve| buildStart{"Separate implementation and validation agents"}311  buildStart --> impl["Implementation agent builds feature from JSON plan"]312  buildStart --> valPrep["Validation agent prepares checks from contract only"]313  impl --> handoff["Implementation handoff"]314  valPrep --> validate["Independent validation agent verifies result"]315  handoff --> validate316  validate --> humanValidation{"Human review: validation evidence"}317  humanValidation -->|fail or rescope| revise318  humanValidation -->|pass| codeReview["Final code review"]319  codeReview --> outcome{"Review outcome"}320  outcome -->|block| revise321  outcome -->|mortem or process feedback| revise322  outcome -->|approve| ready["Ready for merge or release lane"]323```324 325## Mermaid To ProVerif326 327### Handoff Prompt328 329Create a compact Mermaid sequence diagram for PlanPack `collaborative-plan-comments`: human reviews/comments on plan sections in web viewer, exports comments to orchestrator, orchestrator updates JSON plan, preserves research-before-consolidation, validation-contract-before-implementation, separate implementation/validation agents, and code-review block/mortem feedback loops.330 331### Output332 333The lane explicitly reported a mismatch: `collaborative-plan-comments` is not a cryptographic protocol, so ProVerif-style secrecy/authentication modeling is not the right fit. Closest useful output was a Mermaid sequence diagram.334 335```mermaid336sequenceDiagram337    autonumber338    participant H as Human reviewer339    participant V as Web viewer340    participant P as PlanPack JSON341    participant O as Orchestrator342    participant R as Research/idea agents343    participant C as Consolidator344    participant T as Validation-contract agent345    participant I as Implementation agent346    participant Q as Validation agent347    participant CR as Code reviewer348    H->>V: Open PlanPack349    V->>P: Load JSON plan + rendered sections350    P-->>V: Human-readable plan with section anchors351    H->>V: Add comments / quick actions on sections352    V-->>H: Copy/export structured comment packet353    H->>O: Hand comments back to orchestrator354    O->>P: Apply comments as JSON plan deltas355    par Planning, research, and ideas before consolidation356        O->>R: Explore requirements, risks, options357        R-->>O: Findings and candidate approaches358    and Human review remains available359        H->>V: Re-review updated rendered plan360        V-->>H: Anchored comments/actions361    end362    O->>C: Consolidate research + comments363    C->>P: Write consolidated JSON plan364    O->>T: Write validation contract/test design365    T->>P: Add acceptance criteria, checks, test plan366    H->>V: Review consolidated plan + validation contract367    alt Human requests changes368        H->>O: Export more anchored comments369        O->>P: Update JSON plan370        O->>C: Re-consolidate before implementation371    else Human approves372        par Separate implementation and validation agents373            O->>I: Implement from JSON plan374            I-->>O: Code changes375        and376            O->>Q: Prepare independent validation from contract377            Q-->>O: Harness/checklist ready378        end379        O->>Q: Validate implementation against contract380        Q-->>O: Pass/fail evidence381        alt Validation fails382            O->>P: Update plan with failed checks + next actions383            O->>I: Rework implementation384        else Validation passes385            O->>CR: Final code review386            alt Review blocks387                CR-->>O: Blocking feedback388                O->>P: Record fixes, mortem, process feedback389                O->>I: Rework or split follow-up390            else Review approves391                CR-->>O: Approved for release lane392                O->>P: Mark implementation validated/reviewed393            end394        end395    end396```397