Add weekly state machine diagram generator for agentic workflows#19682
Open
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
Contributor
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.