Repository Tree Map - December 2024

[github-actions[bot]]

🗺️ GitHub Agentic Workflows Repository Tree Map

Generated: December 2024
Repository: githubnext/gh-aw
Purpose: Visual overview of repository structure and file distribution

---

📊 Repository Overview

┌─────────────────────────────────────────────────────────────┐
│  Total Files: 665                                           │
│  Primary Language: Go (52% of files)                        │
│  Documentation: 178 Markdown files                          │
│  Test Coverage: Extensive (integrated in source)            │
└─────────────────────────────────────────────────────────────┘

---

🌳 ASCII Tree Map

gh-aw/ [665 files]
│
├─ 📁 pkg/ [~450 files, 68%] ████████████████████████████████████████░░░░
│  │
│  ├─ 🔧 workflow/ [~280 files] ████████████████████████░░
│  │  │  Core workflow compilation and engine implementation
│  │  │
│  │  ├─ Engine Implementations
│  │  │  ├─ claude_engine.go ⚡ Claude AI integration
│  │  │  ├─ codex_engine.go ⚡ Codex integration  
│  │  │  ├─ copilot_engine.go ⚡ GitHub Copilot CLI
│  │  │  └─ custom_engine.go ⚡ Custom engine support
│  │  │
│  │  ├─ Compilation Pipeline
│  │  │  ├─ compiler.go 🏗️ Main compiler logic
│  │  │  ├─ jobs.go 📋 Job generation
│  │  │  ├─ template.go 📝 Template rendering
│  │  │  └─ yaml.go 📄 YAML output
│  │  │
│  │  ├─ Safe Outputs System
│  │  │  ├─ safe_outputs.go 🛡️ Safe output orchestration
│  │  │  ├─ create_issue.go 📋 Issue creation
│  │  │  ├─ create_pull_request.go 🔀 PR creation
│  │  │  ├─ add_comment.go 💬 Comment handling
│  │  │  └─ create_pr_review_comment.go 👁️ Review comments
│  │  │
│  │  ├─ Network & Security
│  │  │  ├─ network.go 🌐 Network permissions
│  │  │  ├─ threat_detection.go 🔒 Security scanning
│  │  │  ├─ xpia.go 🛡️ Cross-prompt injection protection
│  │  │  └─ redact_secrets.go 🔐 Secret redaction
│  │  │
│  │  ├─ MCP Integration
│  │  │  ├─ mcp-config.go 🔌 MCP server config
│  │  │  ├─ mcps.go 🔌 MCP orchestration
│  │  │  └─ nodejs.go 📦 Node.js tooling
│  │  │
│  │  ├─ 📁 js/ [~50 files] JavaScript/TypeScript tools
│  │  │  ├─ parse_copilot_log.cjs 📊 Log parsing
│  │  │  ├─ validate_errors.cjs ✅ Error validation
│  │  │  └─ [test files] 🧪
│  │  │
│  │  ├─ 📁 schemas/ JSON schemas for validation
│  │  ├─ 📁 templates/ Workflow templates
│  │  ├─ 📁 test_data/ Test fixtures
│  │  └─ 📁 config/ Configuration files
│  │
│  ├─ 🎯 cli/ [~120 files] ██████████░░
│  │  │  Command-line interface implementation
│  │  │
│  │  ├─ Commands
│  │  │  ├─ compile_command.go 🔨 Compile workflows
│  │  │  ├─ logs.go 📜 Log analysis
│  │  │  ├─ audit.go 🔍 Workflow auditing
│  │  │  ├─ run_command.go ▶️ Local execution
│  │  │  └─ init.go 🎬 Repository initialization
│  │  │
│  │  ├─ MCP Commands
│  │  │  ├─ mcp_add.go ➕ Add MCP servers
│  │  │  ├─ mcp_inspect.go 🔬 Inspect servers
│  │  │  ├─ mcp_list.go 📋 List servers
│  │  │  ├─ mcp_list_tools.go 🔧 Tool discovery
│  │  │  └─ mcp_registry.go 📚 Registry integration
│  │  │
│  │  ├─ Workflow Management
│  │  │  ├─ add_command.go ➕ Add workflows
│  │  │  ├─ remove_command.go ➖ Remove workflows
│  │  │  ├─ list_command.go 📋 List workflows
│  │  │  ├─ status_command.go 📊 Status checking
│  │  │  └─ update_command.go 🔄 Update workflows
│  │  │
│  │  └─ 📁 workflows/ [~30 files] Built-in workflow templates
│  │
│  ├─ 📖 parser/ [~25 files] ████░░
│  │  │  Frontmatter and schema validation
│  │  │
│  │  ├─ frontmatter.go YAML frontmatter parsing
│  │  ├─ schema.go JSON schema validation
│  │  ├─ mcp.go MCP configuration parsing
│  │  ├─ json_path_locator.go Error location
│  │  └─ 📁 schemas/ Embedded JSON schemas
│  │
│  ├─ 💬 console/ [~8 files] ██░░
│  │  │  Terminal output formatting
│  │  │  
│  │  ├─ Message formatting (colors, icons)
│  │  └─ Progress indicators
│  │
│  └─ ⚙️ constants/ [~5 files] █░░
│     Global constants and configuration
│
├─ 📚 docs/ [~130 files, 20%] ████████████████░░░░
│  │  Astro Starlight documentation site
│  │
│  ├─ 📁 src/ [~120 files]
│  │  │
│  │  ├─ 📁 content/docs/ [~100 files] Documentation pages
│  │  │  │  Organized using Diátaxis framework
│  │  │  │
│  │  │  ├─ 📖 tutorials/ Getting started guides
│  │  │  ├─ 🎯 how-to/ Task-oriented guides  
│  │  │  ├─ 📚 reference/ Technical reference
│  │  │  └─ 💡 concepts/ Explanatory content
│  │  │
│  │  └─ 📁 assets/ Images and media
│  │
│  ├─ 📁 public/ Static assets
│  ├─ package.json Node.js dependencies
│  └─ astro.config.mjs Astro configuration
│
├─ 🔧 .github/ [~100 files, 15%] ████████████░░░░
│  │  GitHub configuration and workflows
│  │
│  ├─ 📁 workflows/ [~75 files]
│  │  │
│  │  ├─ Agentic Workflows (.md files)
│  │  │  ├─ issue-classifier.md 🏷️ Auto-label issues
│  │  │  ├─ security-fix-pr.md 🔒 Security automation
│  │  │  ├─ ci-doctor.md 🩺 CI diagnostics
│  │  │  ├─ changeset-generator.md 📝 Release notes
│  │  │  ├─ daily-news.md 📰 News aggregation
│  │  │  ├─ scout.md 🔍 Repository analysis
│  │  │  ├─ technical-doc-writer.md ✍️ Documentation
│  │  │  └─ [20+ more workflows]
│  │  │
│  │  ├─ Compiled Workflows (.lock.yml files)
│  │  │  └─ Auto-generated from .md files
│  │  │
│  │  ├─ Traditional Workflows (.yml files)
│  │  │  ├─ ci.yml ✅ Continuous integration
│  │  │  ├─ release.yml 🚀 Release automation
│  │  │  ├─ docs.yml 📚 Documentation deployment
│  │  │  └─ integration-agentics.yml 🧪 Testing
│  │  │
│  │  └─ 📁 shared/ Reusable workflow components
│  │
│  ├─ 📁 instructions/ [~5 files] Agent-specific rules
│  │  ├─ github-script.instructions.md
│  │  ├─ github-agentic-workflows.instructions.md
│  │  ├─ documentation.instructions.md
│  │  ├─ copilot-cli.instructions.md
│  │  └─ error-pattern-safety.instructions.md
│  │
│  └─ 📁 prompts/ System prompts
│
├─ 🚀 cmd/ [~5 files, 1%] ██░░
│  │  Main application entry point
│  │
│  └─ 📁 gh-aw/
│     └─ main.go CLI bootstrapping
│
├─ 📋 schemas/ [~1 file] █░░
│  │  JSON schema definitions
│  │
│  └─ agent-output.json Safe outputs schema
│
├─ 🔧 scripts/ [~10 files] ██░░
│  │  Build and utility scripts
│  │
│  ├─ Build automation
│  ├─ Release management
│  └─ Development helpers
│
└─ 📄 Root Files [~20 files] ████░░
   │  Project configuration and documentation
   │
   ├─ 📖 Documentation
   │  ├─ README.md Project overview
   │  ├─ AGENTS.md 🤖 AI agent instructions
   │  ├─ DEVGUIDE.md Development guide
   │  ├─ TESTING.md Testing guidelines
   │  ├─ CONTRIBUTING.md Contribution guide
   │  ├─ CHANGELOG.md Version history
   │  └─ SECURITY.md Security policy
   │
   ├─ ⚙️ Configuration
   │  ├─ go.mod Go module definition
   │  ├─ go.sum Dependency checksums
   │  ├─ Makefile Build automation
   │  ├─ .golangci.yml Linter config
   │  └─ .prettierrc.json JS formatter
   │
   └─ 🔐 Repository Config
      ├─ CODEOWNERS Code ownership
      ├─ CODE_OF_CONDUCT.md Community standards
      └─ LICENSE MIT license

---

📈 File Type Distribution

Extension    Count   Percentage  Visual
────────────────────────────────────────────────────────────
.go          346     52.0%       ████████████████████████████████████████████████████
.md          178     26.8%       ███████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░
.cjs          50      7.5%       ███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
.yml/.yaml    35      5.3%       █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
.json         21      3.2%       ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
.sh           12      1.8%       ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
.ts            4      0.6%       █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
other         19      2.9%       ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

---

🔍 Key Directories Explained

🏗️ Core Architecture

pkg/workflow/ - The heart of the system

• Compiles Markdown workflows to GitHub Actions YAML
• Implements multiple AI engine integrations (Claude, Codex, Copilot)
• Provides safe output processing for secure GitHub API operations
• Handles network permissions, security scanning, and threat detection
• Contains ~280 files including extensive test coverage

pkg/cli/ - Command-line interface

• Main user interaction point for the gh-aw extension
• Implements commands: compile, logs, audit, mcp, run, init
• MCP server management and registry integration
• Workflow lifecycle management (add, remove, update, list)
• Contains ~120 files with comprehensive CLI logic

pkg/parser/ - Configuration parsing

• YAML frontmatter parsing with JSON schema validation
• MCP configuration processing
• Error location and helpful diagnostic messages
• Embedded schema validation for workflow definitions

pkg/console/ - Terminal UX

• Colored output formatting for different message types
• Progress indicators and status displays
• Consistent CLI user experience

📚 Documentation

docs/ - Full documentation site

• Built with Astro Starlight framework
• Follows Diátaxis documentation framework
• ~130 files including tutorials, how-tos, reference, and concepts
• Deployed automatically via GitHub Actions

🤖 Agentic Workflows

.github/workflows/ - Example workflows

• 25+ agentic workflow examples (.md files)
• Compiled workflows (.lock.yml files)
• Traditional CI/CD workflows (.yml files)
• Shared components for reuse
• Live examples of the framework in action

🔌 Integration Points

schemas/ - JSON schema definitions

• Safe outputs schema for validation
• Referenced by parser for frontmatter validation

scripts/ - Build automation

• Compilation helpers
• Release management
• Development utilities

---

💡 Repository Insights

Architecture Highlights

1. 🎯 Separation of Concerns

   • Clean boundaries between CLI, parsing, and workflow compilation
   • Each package has focused responsibility
   • Extensive test coverage integrated alongside source

2. 🔒 Security First

   • Multi-layered security: XPIA protection, secret redaction, threat detection
   • Safe outputs system isolates write operations
   • Network permission management with ecosystem-based controls

3. 🧪 Test Coverage

   • Tests co-located with source files (_test.go pattern)
   • Integration tests for critical paths
   • Both unit and integration testing strategies

4. 📖 Documentation Excellence

   • Extensive inline documentation
   • Separate documentation site with 100+ pages
   • Agent-specific instruction files for AI development
   • Following industry-standard Diátaxis framework

5. 🔌 Extensibility

   • Multiple AI engine support (Claude, Codex, Copilot, Custom)
   • MCP server integration for tool extensibility
   • Template system for workflow reuse
   • Registry integration for discovering MCP servers

Technology Stack

• Language: Go (primary), JavaScript/TypeScript (tooling)
• Documentation: Astro + Starlight (MDX)
• CI/CD: GitHub Actions
• AI Integration: Claude Code, GitHub Copilot, OpenAI Codex
• Protocol: Model Context Protocol (MCP)
• Testing: Go testing framework, integration tests

Development Patterns

• Make-based workflow: make build, make test, make agent-finish
• Compiled workflows: .md → .lock.yml compilation
• Schema-driven validation: JSON schemas for frontmatter
• Console formatting: Consistent terminal output
• Agent instructions: Special .github/instructions/ for AI development

---

📊 Statistics Summary

Metric	Value
Total Files	665
Go Files	346 (52%)
Markdown Files	178 (27%)
Test Files	~200+ (integrated)
Agentic Workflows	25+ examples
Documentation Pages	100+
Main Packages	5 (workflow, cli, parser, console, constants)
Supported AI Engines	4 (Claude, Codex, Copilot, Custom)

---

🎯 Usage Patterns

The repository structure reflects its dual nature:

1. CLI Tool (pkg/cli/, cmd/) - User-facing extension for gh CLI
2. Workflow Framework (pkg/workflow/, pkg/parser/) - Backend compilation engine
3. Living Examples (.github/workflows/) - Dogfooding the framework
4. Developer Resources (docs/, .github/instructions/) - Comprehensive guidance

This architecture enables both immediate use (via CLI) and deep customization (via code), while maintaining security and extensibility as core principles.

---

Tree map generated by analyzing repository structure and file distribution. Visual bars represent relative sizes and counts.

AI generated by Repository Tree Map Generator