Add weekly state machine diagram generator for agentic workflows#19682
Conversation
Weekly workflow that reads all .md agentic workflows in the repo, extracts triggers, labels, safe-outputs, handovers, and conditions, then renders a Mermaid diagram + tables in docs/state-machine.md. Outputs: - Summary table (workflow / trigger / reads / writes / key labels) - Mermaid stateDiagram showing full issue + PR lifecycle - Label dictionary (who applies, who reads, what it means) - Handover map (workflow A → workflow B, mechanism) Opens a PR to update the diagram. allowed-files: docs/** only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Applied: Mermaid stateDiagram-v2 best practices (composite states, choice nodes, direction LR, classDef styling, notes), Anthropic prompt guide (XML tags, role, concrete examples), Peli audit-workflows pattern. Key changes: - Multiple diagrams by dimension (issues, PRs, labels, handovers) instead of one giant unreadable diagram - Composite states for PR types (fork, non-fork, regression-test) - Change detection via source fingerprint comment - skip if unchanged - Diagram guidelines section teaching Mermaid techniques - Concrete example showing Issue Lifecycle structure - Screen-wide LR layout, max ~15 states per diagram - Label dictionary + handover map as tables (not diagrams) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Actors: 👤 contributor, 👤 maintainer, 🤖 agent:<name>, ⚙️ CI, ⏰ scheduler Every diagram edge shows WHO performs the transition. CI is always present — PRs go through build/test, agents react to CI results. Never skip the CI step in diagrams. Incremental updates: read existing state-machine.md as starting point, update only sections affected by workflow changes. Minimal diffs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adversarial review by Opus 4.7 + 4.6 found 6 blocking issues. Generation test by Opus 4.7 produced excellent output but confirmed the prompt was overfit to current 3 workflows. Fixes applied: - Future-proof: agent discovers lifecycle groups from data, not hardcoded Issue/PR sections. Handles file/branch workflows (aw-auto-update) and meta-workflows (itself) without prompt changes. - Mermaid: cross-composite transitions go outside blocks (syntax fix). Removed broken example. No fake workflow names. - Fingerprint: sha256 content hash instead of file size. - Incremental: reads existing output, updates only changed sections. - Bloat: removed <context>, actor definitions, filler sentences. Cut from 173 to 75 lines — same capability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
T-Gro
added
the
NO_RELEASE_NOTES
|
github-project-automation
Bot
moved this from New
to In Progress
in F# Compiler and Tooling
T-Gro
left a comment
T-Gro
left a comment
There was a problem hiding this comment.
Review: Agentic State Machine Diagram Generator
Looks good — clean, well-scoped automation workflow.
Strengths
- Data-driven design: Rule 5 (
Do not hardcode sections ... Let the data decide) ensures the generator stays correct as workflows are added/removed — no manual catalog maintenance. - Incremental updates via sha256 fingerprinting: Avoids unnecessary churn PRs when nothing has changed (
nooppath). - Tight output scope:
allowed-files: [".github/workflows/docs/**"]prevents the agent from modifying anything outside documentation. - Good prompt hygiene: The
<role>,<rules>,<process>,<diagram-guidelines>sections are clear and well-structured. The 75-line prompt is compact for what it does. - Lock file is properly compiled via
gh aw compile(v0.68.3).
Minor observations (non-blocking)
-
Cron schedule
0 0 */7 * *: This runs every 7th day-of-month (1st, 8th, 15th, 22nd, 29th), not truly "every 7 days". In months with 31 days, there will be a 3-day gap between the 29th and the 1st. A weekly cron like0 0 * * 0(every Sunday) would give more uniform intervals. Since this is non-critical documentation generation, this is fine as-is. -
min-integrity: noneon the GitHub toolset: This is standard for repos/read-oriented workflows, but worth noting it means the agent can call any repo API without integrity checks. Acceptable here sinceallowed-filesconstrains the output. -
No
checkout:block in the.md: The lock file does includeactions/checkoutfor.githuband.agentsfolders. The agent will need repo access tols .github/workflows/*.mdandsha256sum— this works becausebash: true+ checkout happen in the compiled workflow. Just noting that the.mdsource relies on implicit checkout behavior. -
Line 76 uses
</output>tag: The closing tag on line 76 is</output>but the corresponding opening tag is<diagram-guidelines>— this appears to be a copy-paste artifact. It doesn't affect functionality sincegh aw compiletreats the content as opaque prompt text, but it's a minor inconsistency.
github-project-automation
Bot
moved this from In Progress
to Done
in F# Compiler and Tooling
2 participants
Weekly workflow that reads all
.github/workflows/*.md, extracts triggers/labels/handovers/actors, and renders Mermaid diagrams + tables in.github/workflows/docs/state-machine.md. Opens a PR when sources change (sha256 fingerprint). Incremental updates on subsequent runs.75 lines.
repos+bashtoolset,create-pull-requestoutput scoped todocs/**only.Discovers lifecycle groups from data — not hardcoded to current workflows. Handles issue workflows, PR workflows, file/branch workflows, and meta-workflows without prompt changes.