This directory contains design specifications and implementation documentation for key features of GitHub Agentic Workflows.
| Document | Status | Implementation |
|---|---|---|
| Code Organization Patterns | ✅ Documented | Code organization guidelines and patterns |
| Validation Architecture | ✅ Documented | pkg/workflow/validation.go and domain-specific files |
| Go Type Patterns and Best Practices | ✅ Documented | pkg/constants/constants.go, pkg/workflow/permissions_validator.go, pkg/parser/frontmatter.go |
| Styles Guide | ✅ Documented | pkg/styles/theme.go - Adaptive color palette and terminal styling |
| Campaign Files Architecture | ✅ Documented | pkg/campaign/, actions/setup/js/campaign_discovery.cjs - Campaign discovery, compilation, and execution |
| Document | Status | Implementation |
|---|---|---|
| Safe Outputs System Specification | ✅ Documented | W3C-style formal specification for safe outputs architecture, security, and operations |
| Capitalization Guidelines | ✅ Documented | cmd/gh-aw/capitalization_test.go |
| Safe Output Messages Design System | ✅ Implemented | pkg/workflow/safe_outputs.go |
| Safe Output Environment Variables Reference | ✅ Documented | Environment variable requirements for safe output jobs |
| MCP Logs Guardrail | ✅ Implemented | pkg/cli/mcp_logs_guardrail.go |
| YAML Version Compatibility | ✅ Documented | pkg/workflow/compiler.go |
| Schema Validation | ✅ Documented | pkg/parser/schemas/ |
| GitHub Actions Security Best Practices | ✅ Documented | Workflow security guidelines and patterns |
| End-to-End Feature Testing | ✅ Documented | .github/workflows/dev.md, .github/workflows/dev-hawk.md |
| Document | Date | Status |
|---|---|---|
| Template Injection Security Review | 2025-11-11 | ✅ No vulnerabilities found |
| Document | Status | Description |
|---|---|---|
| mdflow Syntax Comparison | ✅ Documented | Detailed comparison of mdflow and gh-aw syntax covering 17 aspects: file naming, frontmatter design, templates, imports, security models, execution patterns, and more |
| Gastown Multi-Agent Orchestration | ✅ Documented | Detailed analysis of Gastown's multi-agent coordination patterns and mapping to gh-aw concepts: persistent state, workflow composition, crash recovery, agent communication, and implementation recommendations |
| Document | Date | Description |
|---|---|---|
| Serena Tools Usage Analysis | 2026-02-01 | ✅ Complete deep-dive statistical analysis of Serena MCP server tool usage in workflow run 21560089409 |
| Serena Tools Quick Reference | 2026-02-01 | ✅ At-a-glance summary of Serena tool usage metrics and insights |
| Serena Tools Raw Data | 2026-02-01 | ✅ JSON dataset with complete statistics for programmatic access |
For user-facing documentation, see docs/.
When adding new specifications:
- Document implementation details with file paths
- Mark status with standard icons: ✅ Implemented, 🚧 In Progress, or 📋 Planned
- Provide code samples and usage patterns
- Link to test files
- Update this README's table
Last Updated: 2026-01-20