Skip to content

Commit 4ee2ca4

Browse files
dsymedsyme
committed
2 parents 30e4979 + e9d6082 commit 4ee2ca4

7 files changed

Lines changed: 791 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com
2929
- [📰 Daily Repository Chronicle](docs/daily-repo-chronicle.md) - Transform daily repository activity into an engaging newspaper-style narrative with trend charts
3030
- [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination
3131
- [🔍 Discussion Task Miner](docs/discussion-task-miner.md) - Extract actionable improvement tasks from GitHub Discussions and create tracked issues
32+
- [🗺️ Weekly Repository Map](docs/weekly-repo-map.md) - Visualize repository file structure and size distribution with a weekly ASCII tree map
3233

3334
### Dependency Management Workflows
3435

@@ -39,6 +40,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com
3940

4041
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.
4142

43+
- [📊 Archie](docs/archie.md) - Generate Mermaid diagrams to visualize issue and pull request relationships with /archie command
4244
- [📋 Plan Command](docs/plan.md) - Break down issues into actionable sub-tasks with /plan command
4345
- [🏥 PR Fix](docs/pr-fix.md) - Analyze failing CI checks and implement fixes for pull requests
4446
- [🔍 Repo Ask](docs/repo-ask.md) - Intelligent research assistant for repository questions and analysis
@@ -68,6 +70,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
6870
- [🧪 Daily Test Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas
6971
- [⚡ Daily Perf Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization
7072
- [📊 Repository Quality Improver](docs/repository-quality-improver.md) - Daily rotating analysis of repository quality across code, documentation, testing, security, and custom dimensions
73+
- [📝 Markdown Linter](docs/markdown-linter.md) - Run Markdown quality checks on all documentation files and get a prioritized issue report of violations
7174

7275
## Security Workflows
7376

‎docs/archie.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# 📊 Archie - Mermaid Diagram Generator
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**On-demand Mermaid diagram generation for issues and pull requests**
6+
7+
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.
8+
9+
## Installation
10+
11+
```bash
12+
# Install the 'gh aw' extension
13+
gh extension install github/gh-aw
14+
15+
# Add the workflow to your repository
16+
gh aw add-wizard githubnext/agentics/archie
17+
```
18+
19+
This walks you through adding the workflow to your repository.
20+
21+
## How It Works
22+
23+
```mermaid
24+
graph LR
25+
A[/archie command] --> B[Fetch issue or PR details]
26+
B --> C[Extract relationships and concepts]
27+
C --> D[Select diagram types]
28+
D --> E[Generate 1-3 Mermaid diagrams]
29+
E --> F[Validate syntax]
30+
F --> G[Post comment with diagrams]
31+
```
32+
33+
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.
34+
35+
## Usage
36+
37+
Comment on any issue or pull request:
38+
39+
```
40+
/archie
41+
```
42+
43+
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.
44+
45+
### Configuration
46+
47+
The workflow runs with sensible defaults:
48+
- **Max diagrams**: 3 per invocation
49+
- **Timeout**: 10 minutes
50+
- **Trigger**: `/archie` command in issues, issue comments, PRs, or PR comments
51+
52+
After editing, run `gh aw compile` to update the workflow and commit all changes to the default branch.
53+
54+
### Human in the Loop
55+
56+
- Archie generates diagrams but never modifies your issue or PR content
57+
- Regenerate diagrams at any time by commenting `/archie` again as the issue evolves
58+
- The diagrams are advisory — they summarize and visualize, not prescribe
59+
60+
## What It Visualizes
61+
62+
Archie selects the best diagram type based on the content:
63+
64+
| Content Type | Diagram Type |
65+
|---|---|
66+
| Process flows, dependencies, steps | `graph` / `flowchart` |
67+
| Interactions between components or users | `sequenceDiagram` |
68+
| Data structures, relationships | `classDiagram` |
69+
| Branch strategies, merges | `gitGraph` |
70+
| Timelines, milestones | `gantt` |
71+
| Proportional data | `pie` |
72+
73+
## Example Output
74+
75+
For a feature issue describing an authentication flow, Archie might generate:
76+
77+
```mermaid
78+
sequenceDiagram
79+
participant User
80+
participant App
81+
participant Auth
82+
User->>App: Login request
83+
App->>Auth: Validate credentials
84+
Auth-->>App: Token
85+
App-->>User: Session established
86+
```
87+
88+
## Notes
89+
90+
- Diagrams are kept simple and use only GitHub-compatible Mermaid syntax (no custom styling or themes)
91+
- On very simple issues with no identifiable structure, Archie generates a single summary diagram
92+
- The `/archie` command is role-gated: only users with write access or above can trigger it

‎docs/markdown-linter.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# 📝 Markdown Linter
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Run Markdown quality checks across all documentation files and get a prioritized issue report of violations**
6+
7+
The [Markdown Linter workflow](../workflows/markdown-linter.md?plain=1) runs the [Super Linter](https://github.com/super-linter/super-linter) tool on every Markdown file in your repository, then uses an AI agent to analyze the results and create a detailed GitHub issue listing each violation with suggested fixes. Only Markdown files are checked — other file types are unaffected.
8+
9+
## Installation
10+
11+
```bash
12+
# Install the 'gh aw' extension
13+
gh extension install github/gh-aw
14+
15+
# Add the workflow to your repository
16+
gh aw add-wizard githubnext/agentics/markdown-linter
17+
```
18+
19+
This walks you through adding the workflow to your repository.
20+
21+
## How It Works
22+
23+
```mermaid
24+
graph LR
25+
A[Scheduled Trigger] --> B[Run Super Linter]
26+
B --> C[Check Markdown Files]
27+
C --> D{Violations Found?}
28+
D -->|Yes| E[AI Analyzes Results]
29+
E --> F[Create Issue Report]
30+
D -->|No| G[Noop: All Clear]
31+
```
32+
33+
The workflow runs in two jobs. The first job runs Super Linter to lint all Markdown files and uploads the log as an artifact. The second job (the AI agent) downloads that log, categorizes violations by severity, and creates a prioritized GitHub issue with recommended fixes. Previous issues expire after 2 days to avoid accumulation.
34+
35+
## Usage
36+
37+
The workflow runs on weekdays at 2 PM UTC and can also be triggered manually via `workflow_dispatch`.
38+
39+
### Configuration
40+
41+
After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
42+
43+
### Customizing What Gets Linted
44+
45+
By default only Markdown files are validated (`VALIDATE_MARKDOWN: "true"`, `VALIDATE_ALL_CODEBASE: "false"`). To extend validation to other file types, add the appropriate `VALIDATE_*` environment variables to the Super Linter step. See the [Super Linter documentation](https://github.com/super-linter/super-linter#environment-variables) for a full list.

‎docs/weekly-repo-map.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 🗺️ Weekly Repository Map
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Visualize your repository's file structure and size distribution with a weekly ASCII tree map**
6+
7+
The [Weekly Repository Map workflow](../workflows/weekly-repo-map.md?plain=1) analyzes your repository's structure every week using standard bash tools, then creates a GitHub issue containing an ASCII tree map visualization showing directory hierarchy, file sizes, and key statistics.
8+
9+
## Installation
10+
11+
Add the workflow to your repository:
12+
13+
```bash
14+
gh aw add https://github.com/githubnext/agentics/blob/main/workflows/weekly-repo-map.md
15+
```
16+
17+
Then compile:
18+
19+
```bash
20+
gh aw compile
21+
```
22+
23+
> **Note**: This workflow creates GitHub Issues with the `documentation` label.
24+
25+
## What It Does
26+
27+
The Weekly Repository Map runs every Monday and:
28+
29+
1. **Collects Repository Statistics** — Counts files, measures sizes, and maps the directory structure using standard bash tools
30+
2. **Generates ASCII Tree Map** — Creates a visual representation of the repository hierarchy with proportional size bars
31+
3. **Summarizes Key Metrics** — Reports file type distribution, largest files, and directory sizes
32+
4. **Creates an Issue** — Posts the complete visualization as a GitHub issue, closing the previous week's issue
33+
34+
## How It Works
35+
36+
````mermaid
37+
graph LR
38+
A[Collect File Statistics] --> B[Compute Sizes & Counts]
39+
B --> C[Generate ASCII Tree Map]
40+
C --> D[Compute Key Statistics]
41+
D --> E[Create Issue Report]
42+
````
43+
44+
### Output: GitHub Issues
45+
46+
Each run produces one issue containing:
47+
48+
- **Repository Overview** — Brief summary of the repository's structure and size
49+
- **ASCII Tree Map** — Visual directory hierarchy with size bars using box-drawing characters
50+
- **File Type Breakdown** — Count of files by extension
51+
- **Largest Files** — Top 10 files by size
52+
- **Directory Sizes** — Top directories ranked by total size
53+
54+
Example excerpt from an issue:
55+
56+
```
57+
Repository Tree Map
58+
===================
59+
60+
/ [1234 files, 45.2 MB]
61+
│
62+
├─ src/ [456 files, 28.5 MB] ██████████████████░░
63+
│ ├─ core/ [78 files, 5.2 MB] ████░░
64+
│ └─ utils/ [34 files, 3.1 MB] ███░░
65+
│
66+
├─ docs/ [234 files, 8.7 MB] ██████░░
67+
│
68+
└─ tests/ [78 files, 3.5 MB] ███░░
69+
```
70+
71+
## Configuration
72+
73+
The workflow uses these default settings:
74+
75+
| Setting | Default | Description |
76+
|---------|---------|-------------|
77+
| Schedule | Weekly on Monday | When to run the analysis |
78+
| Issue label | `documentation` | Label applied to created issues |
79+
| Max issues per run | 1 | Prevents duplicate reports |
80+
| Issue expiry | 7 days | Older issues are closed when a new one is posted |
81+
| Timeout | 10 minutes | Per-run time limit |
82+
83+
## Customization
84+
85+
```bash
86+
gh aw edit weekly-repo-map
87+
```
88+
89+
Common customizations:
90+
- **Change issue labels** — Set the `labels` field in `safe-outputs.create-issue` to labels that exist in your repository
91+
- **Adjust the schedule** — Change to run more or less frequently (e.g., daily or monthly)
92+
- **Customize exclusions** — Update the bash commands to exclude additional directories (e.g., `vendor/`, `dist/`)
93+
- **Adjust tree depth** — Edit the prompt to change how deep the tree visualization goes (default max is 3–4 levels)
94+
95+
## Related Workflows
96+
97+
- [Repository Quality Improver](repository-quality-improver.md) — Daily analysis of quality dimensions across your repository
98+
- [Daily File Diet](daily-file-diet.md) — Monitor for oversized source files and create targeted refactoring issues
99+
- [Weekly Issue Summary](weekly-issue-summary.md) — Weekly issue activity report with trend charts

0 commit comments

Comments
 (0)