githubnext · github-actions · Feb 22, 2026
diff --git a/README.md b/README.md
@@ -8,6 +8,10 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com
 
 - [🏷️ Issue Triage](docs/issue-triage.md) - Triage issues and pull requests
 
+### Issue Management Workflows
+
+- [🌳 Issue Arborist](docs/issue-arborist.md) - Automatically organize issues by linking related issues as parent-child sub-issues
+
 ### Fault Analysis Workflows
 
 - [🏥 CI Doctor](docs/ci-doctor.md) - Monitor CI workflows and investigate failures automatically

diff --git a/docs/daily-malicious-code-scan.md b/docs/daily-malicious-code-scan.md
@@ -1,6 +1,8 @@
 # 🔍 Daily Malicious Code Scan
 
-The **Daily Malicious Code Scan** workflow automatically reviews recent code changes for suspicious patterns that could indicate malicious activity, supply chain attacks, or unintended security regressions.
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The [Daily Malicious Code Scan workflow](../workflows/daily-malicious-code-scan.md?plain=1) automatically reviews recent code changes for suspicious patterns that could indicate malicious activity, supply chain attacks, or unintended security regressions.
 
 ## What It Does
 

diff --git a/docs/duplicate-code-detector.md b/docs/duplicate-code-detector.md
@@ -1,6 +1,8 @@
 # 🔍 Duplicate Code Detector
 
-The **Duplicate Code Detector** workflow automatically identifies duplicate code patterns across your codebase and suggests refactoring opportunities to improve maintainability.
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The [Duplicate Code Detector workflow](../workflows/duplicate-code-detector.md?plain=1) automatically identifies duplicate code patterns across your codebase and suggests refactoring opportunities to improve maintainability.
 
 ## What It Does
 

diff --git a/docs/issue-arborist.md b/docs/issue-arborist.md
@@ -0,0 +1,91 @@
+# 🌳 Issue Arborist
+
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The [Issue Arborist workflow](../workflows/issue-arborist.md?plain=1) automatically organizes your issue tracker by identifying related issues and linking them as parent-child sub-issues. It keeps your issue garden tidy by building structured hierarchies from unorganized issue clusters.
+
+## What It Does
+
+This workflow runs daily to analyze open issues and create meaningful organization:
+
+- **Fetches Open Issues**: Downloads the last 100 open issues that don't already have a parent
+- **Identifies Relationships**: Finds natural parent-child relationships between issues through semantic analysis
+- **Links Sub-Issues**: Creates parent-child links for clearly related issue pairs
+- **Creates Parent Issues**: When it finds clusters of 5+ related orphan issues, it creates a new parent issue to group them
+- **Reports Findings**: Creates a daily discussion report summarizing what was analyzed and linked
+
+## Why It's Valuable
+
+Issue trackers tend to grow organically and become hard to navigate. Related issues accumulate without structure, making it difficult to understand the overall scope of work. The Issue Arborist helps by:
+
+- **Building structure automatically** — links related issues without requiring manual triage
+- **Grouping orphan clusters** — identifies themes across unrelated-looking issues and creates parent issues for cohesive groupings
+- **Improving traceability** — makes it easier to see which issues are part of broader efforts
+- **Being conservative** — only links when the relationship is clear and unambiguous, avoiding false positives
+
+## How It Works
+
+````mermaid
+graph LR
+    A[Fetch Open Issues] --> B[Analyze Relationships]
+    B --> C{Orphan Cluster?}
+    C -->|5+ related| D[Create Parent Issue]
+    D --> E[Link as Sub-Issues]
+    C -->|Clear hierarchy| F[Link Existing Issues]
+    E --> G[Report]
+    F --> G
+    B --> H{Nothing clear?}
+    H --> I[Noop Report]
+````
+
+1. **Daily Schedule**: Runs automatically every day
+2. **Issue Fetch**: Downloads up to 100 open issues (excluding those already linked as sub-issues)
+3. **Relationship Analysis**: Examines issue titles, descriptions, and labels to find:
+   - Feature requests with related implementation tasks
+   - Epics with component issues
+   - Bug symptoms related to a common root cause
+   - Tracking issues covering multiple work items
+   - Clusters of semantically related issues without a parent
+4. **Linking**: Creates parent-child links for confirmed relationships (max 50 per run)
+5. **Parent Creation**: For clusters of 5+ related orphans, creates a new "[Parent]" issue (max 5 per run)
+6. **Discussion Report**: Publishes a daily summary with all links created and potential relationships for manual review
+
+## Example Output
+
+When the workflow finds and links related issues, it creates a discussion like:
+
+```markdown
+## 🌳 Issue Arborist Daily Report
+
+**Date**: 2026-02-22
+**Issues Analyzed**: 87
+
+### Parent Issues Created
+
+| Parent Issue | Title | Related Issues | Reasoning |
+|--------------|-------|----------------|-----------|
+| #234 | [Parent] Authentication Improvements | #189, #201, #215, #222, #228 | All 5 issues relate to auth flows |
+
+### Links Created
+
+| Parent Issue | Sub-Issue | Reasoning |
+|-------------|-----------|-----------|
+| #120: Epic: Docs Overhaul | #183: Update CLI docs | Clear sub-task of the epic |
+
+### Potential Relationships (For Manual Review)
+
+- #95 and #167 may be related (both about performance), but not confident enough to link
+```
+
+## Getting Started
+
+This workflow works out of the box with any GitHub repository that uses issues. No configuration is required.
+
+The workflow uses only standard GitHub CLI tools and JSON processing, making it language-agnostic and applicable to any project type.
+
+> **Note**: For the discussion report to appear, your repository needs a GitHub Discussions category named "audits". You can update the `category` field in the workflow frontmatter to use any existing discussion category in your repository.
+
+## Learn More
+
+- [GitHub Agentic Workflows Documentation](https://github.github.io/gh-aw/)
+- [Blog: Issue & PR Management Workflows](https://github.github.io/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/)
diff --git a/docs/link-checker.md b/docs/link-checker.md
@@ -1,6 +1,8 @@
 # 🔗 Link Checker
 
-**Workflow file:** [`.github/workflows/link-checker.md`](../.github/workflows/link-checker.md)
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The [Link Checker workflow](../workflows/link-checker.md?plain=1) is an automated agentic workflow that scans documentation for broken links and fixes them automatically.
 
 ## What It Does
 

diff --git a/docs/plan.md b/docs/plan.md
@@ -1,5 +1,7 @@
 # 📋 Plan Command
 
+> For an overview of all available workflows, see the [main README](../README.md).
+
 The Plan Command is an agentic workflow that helps break down complex issues or discussions into manageable, actionable sub-tasks for GitHub Copilot agents.
 
 > [!WARNING]

diff --git a/workflows/issue-arborist.md b/workflows/issue-arborist.md
@@ -0,0 +1,186 @@
+---
+description: Daily workflow that analyzes open issues and links related issues as sub-issues to improve issue tracker organization
+name: Issue Arborist
+on:
+  schedule: daily
+  workflow_dispatch:
+permissions:
+  contents: read
+  issues: read
+engine: codex
+strict: true
+network:
+  allowed:
+    - defaults
+    - github
+tools:
+  github:
+    lockdown: true
+    toolsets:
+      - issues
+  bash:
+    - "cat *"
+    - "jq *"
+steps:
+  - name: Fetch issues data
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    run: |
+      mkdir -p /tmp/issues-data
+
+      echo "⬇ Downloading the last 100 open issues (excluding sub-issues)..."
+
+      gh issue list --repo ${{ github.repository }} \
+        --search "-parent-issue:*" \
+        --state open \
+        --json number,title,author,createdAt,state,url,body,labels,updatedAt,closedAt,milestone,assignees \
+        --limit 100 \
+        > /tmp/issues-data/issues.json
+
+      echo "✓ Issues data saved to /tmp/issues-data/issues.json"
+      echo "Total issues fetched: $(jq 'length' /tmp/issues-data/issues.json)"
+safe-outputs:
+  create-issue:
+    expires: 2d
+    title-prefix: "[Parent] "
+    max: 5
+    group: true
+  link-sub-issue:
+    max: 50
+  create-discussion:
+    title-prefix: "[Issue Arborist] "
+    category: "audits"
+    close-older-discussions: true
+timeout-minutes: 15
+---
+
+# Issue Arborist 🌳
+
+You are the Issue Arborist - an intelligent agent that cultivates the issue garden by identifying and linking related issues as parent-child relationships.
+
+## Task
+
+Analyze the last 100 open issues in repository ${{ github.repository }} and identify opportunities to link related issues as sub-issues.
+
+## Pre-Downloaded Data
+
+The issue data has been pre-downloaded and is available at:
+- **Issues data**: `/tmp/issues-data/issues.json` - Contains the last 100 open issues (excluding those that are already sub-issues)
+
+Use `cat /tmp/issues-data/issues.json | jq ...` to query and analyze the issues.
+
+## Process
+
+### Step 1: Load and Analyze Issues
+
+Read the pre-downloaded issues data from `/tmp/issues-data/issues.json`. The data includes:
+- Issue number, title, body/description
+- Labels, state, author, assignees, milestone, timestamps
+
+Use `jq` to filter and analyze the data. Example queries:
+```bash
+# Get count of issues
+jq 'length' /tmp/issues-data/issues.json
+
+# Get issues with specific label
+jq '[.[] | select(.labels | any(.name == "bug"))]' /tmp/issues-data/issues.json
+```
+
+### Step 2: Analyze Relationships
+
+Examine the issues to identify potential parent-child relationships. Look for:
+
+1. **Feature with Tasks**: A high-level feature request (parent) with specific implementation tasks (sub-issues)
+2. **Epic Patterns**: Issues with "[Epic]", "[Parent]" or similar prefixes that encompass smaller work items
+3. **Bug with Root Cause**: A symptom bug (sub-issue) that relates to a root cause issue (parent)
+4. **Tracking Issues**: Issues that track multiple related work items
+5. **Semantic Similarity**: Issues with highly related titles, labels, or content that suggest hierarchy
+6. **Orphan Clusters**: Groups of 5 or more related issues that share a common theme but lack a parent issue
+
+### Step 3: Make Linking Decisions
+
+For each potential relationship, evaluate:
+- Is there a clear parent-child hierarchy? (parent should be broader/higher-level)
+- Are both issues in a state where linking makes sense?
+- Would linking improve organization and traceability?
+- Is the relationship strong enough to warrant a permanent link?
+
+**Creating Parent Issues for Orphan Clusters:**
+- If you identify a cluster of **5 or more related issues** that lack a parent issue, you may create a new parent issue
+- The parent issue should have a clear, descriptive title that captures the common theme (prefixed with "[Parent] " automatically)
+- Include a body that explains the cluster and references all related issues
+- Use temporary IDs (format: `aw_` + 3-8 alphanumeric characters) for newly created parent issues
+- After creating the parent, link all related issues as sub-issues using the temporary ID
+
+**Constraints:**
+- Maximum 5 parent issues created per run
+- Maximum 50 sub-issue links per run
+- Only create a parent issue if there are 5+ strongly related issues without a parent
+- Only link if you are absolutely sure of the relationship - when in doubt, don't link
+- Prefer linking open issues
+- Parent issue should be broader in scope than sub-issue
+
+### Step 4: Create Parent Issues and Execute Links
+
+**For orphan clusters (5+ related issues without a parent):**
+1. Create a parent issue using the `create_issue` tool with a temporary ID
+   - Format: `{"type": "create_issue", "temporary_id": "aw_XXXXXXXX", "title": "Theme Description", "body": "Description with references to related issues"}`
+   - Temporary ID must be `aw_` followed by 3-8 alphanumeric characters (e.g., `aw_abc123`, `aw_Test123`)
+2. Link each related issue to the parent using `link_sub_issue` tool with the temporary ID
+   - Format: `{"type": "link_sub_issue", "parent_issue_number": "aw_XXXXXXXX", "sub_issue_number": 123}`
+
+**For existing parent-child relationships:**
+- Use the `link_sub_issue` tool with actual issue numbers to create the parent-child relationship
+
+### Step 5: Report
+
+Create a discussion summarizing your analysis with:
+- Number of issues analyzed
+- Parent issues created for orphan clusters (with reasoning)
+- Relationships identified (even if not linked)
+- Links created with reasoning
+- Recommendations for manual review (relationships you noticed but weren't confident enough to link)
+
+## Output Format
+
+Your discussion should include:
+
+```markdown
+## 🌳 Issue Arborist Daily Report
+
+**Date**: [Current Date]
+**Issues Analyzed**: [count]
+
+### Parent Issues Created
+
+| Parent Issue | Title | Related Issues | Reasoning |
+|--------------|-------|----------------|-----------|
+| #X: [title] | [Parent] Feature X | #A, #B, #C, #D, #E | [brief explanation of cluster theme] |
+
+### Links Created
+
+| Parent Issue | Sub-Issue | Reasoning |
+|-------------|-----------|-----------|
+| #X: [title] | #Y: [title] | [brief explanation] |
+
+### Potential Relationships (For Manual Review)
+
+[List any relationships you identified but didn't link, with confidence level]
+
+### Observations
+
+[Brief notes on issue organization patterns, suggestions for maintainers]
+```
+
+## Important Notes
+
+- Only link issues when you are absolutely certain of the parent-child relationship
+- Be conservative with linking - only link when the relationship is clear and unambiguous
+- Prefer precision over recall (better to miss a link than create a wrong one)
+- Consider that unlinking is a manual process, so be confident before linking
+- **Create parent issues only for clusters of 5+ related issues** that clearly share a common theme
+- Use temporary IDs (format: `aw_` + 3-8 alphanumeric characters) when creating parent issues
+- When creating parent issues, include references to all related sub-issues in the body
+- Link all related issues as sub-issues immediately after creating the parent issue
+- If there are no clear relationships to link and no clusters to parent, call `noop` with a summary of what you analyzed