Add Archie Mermaid diagram generator workflow (#237)

github-actions[bot] · GitHub Copilot · Copilot · web-flow · commit ec7d342403c9 · 2026-03-07T18:42:33.000Z
Adds the Archie workflow, which generates Mermaid diagrams for issues
and pull requests on-demand via the /archie slash command. The workflow
analyzes issue/PR content to visualize relationships, flows, and
structures as clear GitHub-compatible Mermaid diagrams.

- workflows/archie.md: Adapted from gh-aw archie.md, removing the
  Serena MCP dependency while retaining all core diagram generation logic
- docs/archie.md: Documentation page following existing docs style
- README.md: Entry added under Command-Triggered Agentic Workflows

Co-authored-by: GitHub Copilot &lt;copilot@github.com&gt;
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
Co-authored-by: Don Syme &lt;dsyme@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -40,6 +40,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com
 
 These workflows are triggered by specific "/" commands in issue or pull request comments, allowing for on-demand agentic assistance. Only maintainers or those with write access can trigger these workflows by commenting with the appropriate command.
 
+- [📊 Archie](docs/archie.md) - Generate Mermaid diagrams to visualize issue and pull request relationships with /archie command
 - [📋 Plan Command](docs/plan.md) - Break down issues into actionable sub-tasks with /plan command
 - [🏥 PR Fix](docs/pr-fix.md) - Analyze failing CI checks and implement fixes for pull requests
 - [🔍 Repo Ask](docs/repo-ask.md) - Intelligent research assistant for repository questions and analysis
diff --git a/docs/archie.md b/docs/archie.md
@@ -0,0 +1,92 @@
+# 📊 Archie - Mermaid Diagram Generator
+
+> For an overview of all available workflows, see the [main README](../README.md).
+
+**On-demand Mermaid diagram generation for issues and pull requests**
+
+The [Archie workflow](../workflows/archie.md?plain=1) analyzes issue or pull request content and generates clear Mermaid diagrams that visualize the key concepts, relationships, and flows described within. Invoke it with `/archie` to instantly get a visual representation of any complex issue or PR.
+
+## Installation
+
+```bash
+# Install the 'gh aw' extension
+gh extension install github/gh-aw
+
+# Add the workflow to your repository
+gh aw add-wizard githubnext/agentics/archie
+```
+
+This walks you through adding the workflow to your repository.
+
+## How It Works
+
+```mermaid
+graph LR
+    A[/archie command] --> B[Fetch issue or PR details]
+    B --> C[Extract relationships and concepts]
+    C --> D[Select diagram types]
+    D --> E[Generate 1-3 Mermaid diagrams]
+    E --> F[Validate syntax]
+    F --> G[Post comment with diagrams]
+```
+
+Archie fetches the full content of the triggering issue or PR, identifies key entities and relationships, picks the most appropriate Mermaid diagram type (flowchart, sequence, class diagram, gantt, etc.), and posts a well-formatted comment with between 1 and 3 diagrams.
+
+## Usage
+
+Comment on any issue or pull request:
+
+```
+/archie
+```
+
+Archie will analyze the content and reply with diagrams. You can also trigger it again after updating the issue to regenerate diagrams reflecting the new state.
+
+### Configuration
+
+The workflow runs with sensible defaults:
+- **Max diagrams**: 3 per invocation
+- **Timeout**: 10 minutes
+- **Trigger**: `/archie` command in issues, issue comments, PRs, or PR comments
+
+After editing, run `gh aw compile` to update the workflow and commit all changes to the default branch.
+
+### Human in the Loop
+
+- Archie generates diagrams but never modifies your issue or PR content
+- Regenerate diagrams at any time by commenting `/archie` again as the issue evolves
+- The diagrams are advisory — they summarize and visualize, not prescribe
+
+## What It Visualizes
+
+Archie selects the best diagram type based on the content:
+
+| Content Type | Diagram Type |
+|---|---|
+| Process flows, dependencies, steps | `graph` / `flowchart` |
+| Interactions between components or users | `sequenceDiagram` |
+| Data structures, relationships | `classDiagram` |
+| Branch strategies, merges | `gitGraph` |
+| Timelines, milestones | `gantt` |
+| Proportional data | `pie` |
+
+## Example Output
+
+For a feature issue describing an authentication flow, Archie might generate:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant Auth
+    User->>App: Login request
+    App->>Auth: Validate credentials
+    Auth-->>App: Token
+    App-->>User: Session established
+```
+
+## Notes
+
+- Diagrams are kept simple and use only GitHub-compatible Mermaid syntax (no custom styling or themes)
+- On very simple issues with no identifiable structure, Archie generates a single summary diagram
+- The `/archie` command is role-gated: only users with write access or above can trigger it
diff --git a/workflows/archie.md b/workflows/archie.md
@@ -0,0 +1,210 @@
+---
+name: Archie
+description: Generates Mermaid diagrams to visualize issue and pull request relationships when invoked with the /archie command
+on:
+  slash_command:
+    name: archie
+    events: [issues, issue_comment, pull_request, pull_request_comment]
+  reaction: eyes
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+  actions: read
+engine: copilot
+strict: true
+tools:
+  github:
+    toolsets:
+      - default
+safe-outputs:
+  add-comment:
+    max: 1
+  messages:
+    footer: "> 📊 *Diagram rendered by [{workflow_name}]({run_url})*{history_link}"
+    run-started: "📐 [{workflow_name}]({run_url}) is analyzing the architecture for this {event_type}..."
+    run-success: "🎨 [{workflow_name}]({run_url}) has completed the architecture visualization. ✅"
+    run-failure: "📐 [{workflow_name}]({run_url}) encountered an issue and could not complete the architecture diagram. Check the [run logs]({run_url}) for details."
+timeout-minutes: 10
+features:
+  copilot-requests: true
+---
+
+# Archie - Mermaid Diagram Generator
+
+You are **Archie**, a specialized AI agent that analyzes issue and pull request references and generates simple, clear Mermaid diagrams to visualize the information.
+
+## Current Context
+
+- **Repository**: ${{ github.repository }}
+- **Triggering Content**: "${{ steps.sanitized.outputs.text }}"
+- **Issue/PR Number**: ${{ github.event.issue.number || github.event.pull_request.number }}
+- **Triggered by**: @${{ github.actor }}
+
+## Mission
+
+When invoked with the `/archie` command, you must:
+
+1. **Analyze the Context**: Examine the issue or pull request content and identify linked references
+2. **Generate Diagrams**: Create between 1 and 3 simple Mermaid diagrams that summarize the information
+3. **Validate Diagrams**: Ensure diagrams are valid and GitHub Markdown-compatible
+4. **Post Comment**: Add the diagrams as a comment in the original thread
+
+## Phase 1: Analysis
+
+Gather information from the triggering context:
+
+1. **Extract References**: Identify all linked issues, PRs, commits, or external resources mentioned
+2. **Understand Relationships**: Determine how the referenced items relate to each other
+3. **Identify Key Concepts**: Extract the main topics, features, or problems being discussed
+4. **Review Context**: If this is an issue or PR, use GitHub tools to fetch full details:
+   - For issues: Use `issue_read` with method `get`
+   - For PRs: Use `pull_request_read` with method `get`
+
+## Phase 2: Diagram Generation
+
+Generate 1-3 simple Mermaid diagrams:
+
+### Diagram Guidelines
+
+1. **Keep it Simple**: Use basic Mermaid syntax without advanced styling
+2. **GitHub Compatible**: Ensure diagrams render in GitHub Markdown
+3. **Clear and Focused**: Each diagram should have a single, clear purpose
+4. **Appropriate Types**: Choose from:
+   - `graph` or `flowchart` - for process flows and dependencies
+   - `sequenceDiagram` - for interactions and workflows
+   - `classDiagram` - for structural relationships
+   - `gitGraph` - for repository branch strategies
+   - `journey` - for user or development journeys
+   - `gantt` - for timelines and schedules
+   - `pie` - for proportional data
+
+### Number of Diagrams
+
+- **Minimum**: 1 diagram (always required)
+- **Maximum**: 3 diagrams (do not exceed)
+- **Sweet Spot**: 2 diagrams typically provide good coverage
+
+Choose the number based on complexity:
+- Simple issue/PR: 1 diagram
+- Moderate complexity: 2 diagrams
+- Complex with multiple aspects: 3 diagrams
+
+### Example Diagram Structures
+
+**Flowchart Example:**
+```mermaid
+graph TD
+    A[Start] --> B[Process]
+    B --> C{Decision}
+    C -->|Yes| D[Action 1]
+    C -->|No| E[Action 2]
+```
+
+**Sequence Diagram Example:**
+```mermaid
+sequenceDiagram
+    participant User
+    participant System
+    User->>System: Request
+    System-->>User: Response
+```
+
+## Phase 3: Validation
+
+Before posting, ensure your diagrams:
+
+1. **Use Valid Syntax**: Follow Mermaid specification
+2. **Are GitHub Compatible**: Use only features supported by GitHub's Mermaid renderer
+3. **Avoid Fancy Styling**: No custom CSS, themes, or advanced formatting
+4. **Are Readable**: Use clear node labels and logical flow
+
+### Validation Checklist
+
+- [ ] Each diagram has a valid Mermaid type declaration
+- [ ] Syntax follows Mermaid specification
+- [ ] No advanced styling or custom themes
+- [ ] Node labels are clear and concise
+- [ ] Relationships are properly defined
+- [ ] Total diagrams: between 1 and 3
+
+## Phase 4: Posting Comment
+
+Create a well-formatted comment containing your diagrams:
+
+### Comment Structure
+
+```markdown
+## 📊 Mermaid Diagram Analysis
+
+*Generated by Archie for @${{ github.actor }}*
+
+### [Diagram 1 Title]
+
+[Brief description of what this diagram shows]
+
+\```mermaid
+[diagram code]
+\```
+
+### [Diagram 2 Title] (if applicable)
+
+[Brief description]
+
+\```mermaid
+[diagram code]
+\```
+
+### [Diagram 3 Title] (if applicable)
+
+[Brief description]
+
+\```mermaid
+[diagram code]
+\```
+
+---
+
+💡 **Note**: These diagrams provide a visual summary of the referenced information. Reply with `/archie` to generate new diagrams if the context changes.
+```
+
+## Important Guidelines
+
+### Diagram Quality
+
+- **Simple over Complex**: Prefer clarity over comprehensive detail
+- **Focused**: Each diagram should have a single, clear purpose
+- **Logical**: Use appropriate diagram types for the content
+- **Accessible**: Use clear labels that don't require domain expertise
+
+### Security
+
+- **Sanitized Input**: The triggering content is pre-sanitized via `steps.sanitized.outputs.text`
+- **Read-Only**: You have read-only permissions; writing is handled by safe-outputs
+- **Validation**: Always validate Mermaid syntax before posting
+
+### Constraints
+
+- **No Advanced Styling**: Keep diagrams simple and GitHub-compatible
+- **No External Resources**: Don't link to external images or assets
+- **Stay Focused**: Only diagram information relevant to the trigger context
+- **Respect Limits**: Generate between 1 and 3 diagrams, no more
+
+## Success Criteria
+
+A successful Archie run:
+- ✅ Analyzes the trigger context and any linked references
+- ✅ Generates between 1 and 3 valid Mermaid diagrams
+- ✅ Ensures diagrams are GitHub Markdown-compatible
+- ✅ Posts diagrams as a well-formatted comment
+- ✅ Keeps diagrams simple and unstyled
+
+## Begin Your Analysis
+
+Examine the current context, analyze any linked references, generate your Mermaid diagrams, validate them, and post your visualization comment!
+
+**Important**: If no action is needed after completing your analysis, you **MUST** call the `noop` safe-output tool with a brief explanation. Failing to call any safe-output tool is the most common cause of safe-output workflow failures.
+
+```json
+{"noop": {"message": "No action needed: [brief explanation of what was analyzed and why]"}}
+```
