You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Analysis Date: 2025-12-09 Focus Area: Code Organization Strategy Type: Standard Category Custom Area: No - Selected from standard categories (not used in recent runs)
Executive Summary
The gh-aw repository demonstrates strong foundational architecture with clear package boundaries and good dependency flow (CLI → Workflow → Parser). However, the codebase shows signs of rapid growth stress with several organizational debt areas requiring attention.
Key Strengths: Clean 267-file Go codebase, excellent dependency direction (only 3 reverse imports), well-structured pkg/ organization with 11 focused packages, and strong encapsulation with 696 error wrapping patterns.
Critical Issues: 48 files exceed 500 lines (17% of codebase), workflow package has 82.5% public API surface (1,821 exported vs 386 unexported functions), 73 CLI files lack consistent _command.go naming, 8 packages missing package-level documentation, and several "god objects" with 25-41 functions each.
Full Analysis Report
Focus Area: Code Organization
Current State Assessment
The repository contains 267 non-test Go files organized across 11 packages under pkg/, with the bulk of complexity concentrated in two major packages:
375 global variables across the codebase (278 in workflow, 81 in cli, 16 in parser). While not critical, this indicates opportunities for better encapsulation.
🟢 Low: Limited Interface Usage
Only 5 interface definitions for a 267-file codebase suggests missed abstraction opportunities, particularly for testing and plugin systems.
pkg/workflow/compiler_jobs.go (1,374 LOC) - Separate job generation from step compilation
pkg/workflow/copilot_engine.go (1,368 LOC) - Split config from runtime setup
pkg/cli/update_command.go (1,331 LOC) - Extract tracking and error handling
🤖 Tasks for Copilot Agent
NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot agent execution. Please split these into individual work items for Claude to process.
Improvement Tasks
The following code regions and tasks should be processed by the Copilot agent. Each section is marked for easy identification by the planner agent.
Task 1: Split Oversized logs.go into Focused Modules
Priority: High Estimated Effort: Large Focus Area: Code Organization - File Size Reduction
Description:
The pkg/cli/logs.go file (1,620 LOC) handles multiple responsibilities: log downloading, log analysis, formatting, caching, and error reporting. It exhibits 10 levels of nesting indicating high cyclomatic complexity. Split this into separate, focused files following single responsibility principle.
Acceptance Criteria:
Create pkg/cli/logs_download.go for download orchestration logic
Create pkg/cli/logs_analysis.go for log parsing and error detection
Create pkg/cli/logs_cache.go for caching operations
Create pkg/cli/logs_format.go for output formatting
Retain pkg/cli/logs.go as thin orchestrator (<300 LOC)
No functionality regressions in gh aw logs command
Task 2: Introduce internal/ Package for Workflow Internals
Priority: High Estimated Effort: Large Focus Area: Code Organization - API Surface Reduction
Description:
The pkg/workflow package exports 82.5% of its functions (1,821 exported vs 386 unexported), creating an enormous public API surface. Move internal helper functions, validators, and utilities to pkg/workflow/internal/ subdirectories to clearly separate public API from implementation details.
Acceptance Criteria:
Create pkg/workflow/internal/ directory structure
Move unexported helpers to internal/helpers/
Move validation internals to internal/validation/
Move compilation helpers to internal/compiler/
Reduce exported function count by at least 400 functions (to ~75% or less)
Public API remains stable - no changes to pkg/cli import statements
All tests pass
godoc clearly distinguishes public vs internal APIs
Update package documentation to describe public API contract
Code Region:pkg/workflow/ (all files)
Refactor pkg/workflow to introduce internal/ subdirectories:
1. Analyze pkg/workflow exported functions (1,821 total):
- Identify which functions are called from pkg/cli (public API)
- Identify which functions are only used within pkg/workflow (internal)
- Identify validation helpers, formatters, converters (candidates for internal/)
2. Create internal/ structure:
pkg/workflow/internal/
├── helpers/ # String manipulation, formatting, conversion
├── validation/ # Internal validators not needed by CLI
├── compiler/ # Compiler-specific helpers
└── types/ # Internal-only type definitions
3. Move internal functions systematically:
- Start with clear helper functions (formatters, converters)
- Then move validation helpers not used by pkg/cli
- Finally move compiler-specific utilities
4. Update imports throughout pkg/workflow:
- Change internal references to new paths
- Verify pkg/cli imports remain unchanged (public API stable)
5. Document public API contract:
- Add package-level doc comments describing what pkg/cli should use
- Mark functions that must remain exported with documentation
- Add godoc examples for key public functions
Target: Reduce exported function percentage from 82.5% to ~75% (reduce by 400+ exports).
Task 3: Standardize CLI File Naming with _command.go Suffix
Priority: Medium Estimated Effort: Medium Focus Area: Code Organization - Naming Consistency
Description:
Currently only 10 of 83 CLI files follow the *_command.go naming pattern. Rename the 73 inconsistently named files to use the _command.go suffix for command implementations, and create separate *_support.go or *_types.go files for helpers and types.
Acceptance Criteria:
All command implementation files renamed to *_command.go
Helper functions moved to *_support.go files
Type definitions moved to *_types.go files
Update all import statements and references
All tests updated to reflect new file names
No functionality changes
Clear distinction between commands, helpers, and types
git history preserved with git mv commands
Code Region:pkg/cli/ (73 files without _command suffix)
Standardize CLI file naming conventions in pkg/cli/:
1. Identify current file categories:
- Command implementations (currently: audit.go, actions.go, logs.go, etc.)
- Helper functions
- Type definitions
- Shared utilities
2. Rename command files to *_command.go:
audit.go → audit_command.go
actions.go → actions_command.go
logs.go → logs_command.go (after Task 1 splits it)
mcp_inspect.go → mcp_inspect_command.go
etc. (70+ files total)
3. Extract helpers to *_support.go:
- If a command file has significant helper functions, create matching support file
- Example: logs_command.go → logs_support.go (for caching, formatting helpers)
4. Extract types to *_types.go:
- Move struct definitions to dedicated type files
- Example: audit_types.go for audit-related structs
5. Update all imports and references:
- Search for internal references
- Update test files
- Verify no broken imports
6. Use git mv for history preservation:
git mv pkg/cli/audit.go pkg/cli/audit_command.go
Target: 100% consistency with *_command.go naming for all command implementations.
Task 4: Split Compiler YAML and Jobs Files
Priority: Medium Estimated Effort: Large Focus Area: Code Organization - Component Decomposition
Description:
The files compiler_yaml.go (1,446 LOC, 29 functions) and compiler_jobs.go (1,374 LOC) are the largest non-command files in the codebase. Extract logical components into focused files: YAML formatters, job generators, step compilers, container config, and validation logic.
Acceptance Criteria:
compiler_yaml.go split into 3-4 files (≤500 LOC each)
compiler_jobs.go split into 3-4 files (≤500 LOC each)
Split the two largest workflow compiler files into focused components:
Part A: Split compiler_yaml.go (1,446 LOC, 29 functions)
1. Create compiler_yaml_generator.go:
- Main YAML structure generation
- Top-level workflow YAML assembly
- Metadata handling
-~400-500 LOC
2. Create compiler_yaml_formatters.go:
- YAML formatting helpers
- Indentation logic
- Comment generation
- String escaping
-~300-400 LOC
3. Create compiler_yaml_validation.go:
- YAML structure validation
- Schema compliance checking
- Error message generation
-~300-400 LOC
4. Retain compiler_yaml.go as orchestrator:
- Main entry point
- Coordination logic
-~300-400 LOC
Part B: Split compiler_jobs.go (1,374 LOC)
1. Create compiler_jobs_generator.go:
- Job structure creation
- Job metadata assembly
- Job ordering logic
-~400-500 LOC
2. Create compiler_jobs_steps.go:
- Step compilation logic
- Step ordering
- Step validation
-~300-400 LOC
3. Create compiler_jobs_container.go:
- Container configuration
- Image selection
- Volume mounting
- Network configuration
-~300-400 LOC
4. Retain compiler_jobs.go as orchestrator:
- Main entry point
- Job compilation coordination
-~300-400 LOC
Ensure all 32 compiler test files continue passing without modification.
Task 5: Add Package Documentation and Improve godoc
Priority: Medium Estimated Effort: Small Focus Area: Code Organization - Documentation
Description:
7 of 11 packages lack package-level documentation comments (console, constants, gateway, gitutil, logger, parser, testutil). Add package doc comments following Go conventions, either as doc.go files or as comments in the main package file.
Acceptance Criteria:
All 11 packages have package-level documentation
Each doc comment describes package purpose, primary types, and key functions
Documentation follows Go conventions (starts with "Package (name)")
Examples provided for key packages (parser, workflow)
Add package-level documentation to all pkg/ subdirectories:
1. Create or update package documentation for these 7 packages:
pkg/console/doc.go:
// Package console provides terminal formatting and rendering utilities for
// CLI output. It includes helpers for colorization, progress indicators,
// success/error messages, and structured output rendering.
//
// The primary types are Formatter and Renderer. Use FormatSuccessMessage,
// FormatErrorMessage, etc. for consistent CLI styling.
pkg/constants/doc.go:
// Package constants defines shared constants used across gh-aw, including
// version information, default values, timeout durations, and configuration
// keys. Import this package to access project-wide constant values.
pkg/gateway/doc.go:
// Package gateway implements API gateway logic for GitHub interactions,
// including request routing, authentication handling, and response processing.
pkg/gitutil/doc.go:
// Package gitutil provides Git operations helpers, including repository
// detection, branch management, and commit information retrieval.
pkg/logger/doc.go:
// Package logger implements debug logging with namespace-based filtering
// and zero-overhead when disabled. Use logger.New("namespace") to create
// loggers that only activate when DEBUG environment variable matches.
//
// Example: DEBUG=cli:* gh aw compile
pkg/parser/doc.go:
// Package parser handles markdown frontmatter parsing and schema validation
// for .aw workflow files. It extracts YAML frontmatter, validates against
// JSON schemas, and provides structured error messages.
//
// Primary functions: ParseFrontmatter, ValidateSchema, ExtractWorkflowConfig
pkg/testutil/doc.go:
// Package testutil provides test helpers and utilities for unit and
// integration tests, including temporary directory management, fixture
// loading, and assertion helpers.
2. Verify godoc generation:
go doc pkg/console
go doc pkg/parser
etc.
3. Add examples for key packages:
- Add Example functions in parser_test.go
- Add Example functions in workflow_test.go
- Demonstrate typical usage patterns
4. Update README.md to link to package documentation:
Add section: "## API Documentation" with godoc links
📊 Historical Context
Previous Focus Areas
Date
Focus Area
Type
Custom
Key Outcomes
2025-11-25
workflow-observability-debugging
Custom
Y
Analyzed logging infrastructure and debugging tools
2025-11-26
workflow-compilation-consistency
Custom
Y
.lock.yml freshness and compilation automation
2025-11-27
ci-cd
Standard
N
CI/CD pipeline efficiency and action versions
2025-11-28
mcp-integration-quality
Custom
Y
MCP server integration and documentation
2025-12-01
testing
Standard
N
222% test coverage, identified 90 untested files
2025-12-02
safe-output-system-reliability-validation
Custom
Y
Safe output validation and test coverage
2025-12-03
testing
Standard (Reused)
N
Test organization and maintainability deep-dive
2025-12-04
security
Standard
N
Comprehensive security audit with 99.9% pinned actions
2025-12-05
workflow-input-output-contract-validation
Custom
Y
Workflow contract definitions and type safety
2025-12-08
cli-resilience-self-healing-operations
Custom
Y
CLI batch operations and error recovery
Statistics: 10 total runs, 60% custom rate, 10% reuse rate, 9 unique areas explored
🎯 Recommendations
Immediate Actions (This Week)
Task 1: Split logs.go - Priority: High - Reduces most problematic file with 10-level nesting
Task 3: Rename CLI files - Priority: Medium - Quick win for consistency with low risk
Short-term Actions (This Month)
Task 2: Introduce workflow internal/ - Priority: High - Major API surface reduction
Task 4: Split compiler_yaml/jobs - Priority: Medium - Improves largest workflow files
Long-term Actions (This Quarter)
Task 5: Package documentation - Priority: Medium - Improves discoverability
Max file LOC: 1,620 → Target: 800 - largest file reduction
Files with 25+ functions: 10 → Target: 5 - responsibility distribution
Next Steps
Review and prioritize the tasks above - recommend starting with Task 1 (logs.go split) and Task 3 (CLI naming)
Assign tasks to Copilot agent via planner agent - all tasks are ready for autonomous execution
Track progress on improvement items using the success metrics above
Re-evaluate Code Organization in 2-3 months to measure improvement
Generated by Repository Quality Improvement Agent Next analysis: 2025-12-10 - Focus area will be selected based on diversity algorithm (60% custom, 30% standard, 10% reuse)
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
🎯 Repository Quality Improvement Report - Code Organization
Analysis Date: 2025-12-09
Focus Area: Code Organization
Strategy Type: Standard Category
Custom Area: No - Selected from standard categories (not used in recent runs)
Executive Summary
The gh-aw repository demonstrates strong foundational architecture with clear package boundaries and good dependency flow (CLI → Workflow → Parser). However, the codebase shows signs of rapid growth stress with several organizational debt areas requiring attention.
Key Strengths: Clean 267-file Go codebase, excellent dependency direction (only 3 reverse imports), well-structured pkg/ organization with 11 focused packages, and strong encapsulation with 696 error wrapping patterns.
Critical Issues: 48 files exceed 500 lines (17% of codebase), workflow package has 82.5% public API surface (1,821 exported vs 386 unexported functions), 73 CLI files lack consistent
_command.gonaming, 8 packages missing package-level documentation, and several "god objects" with 25-41 functions each.Full Analysis Report
Focus Area: Code Organization
Current State Assessment
The repository contains 267 non-test Go files organized across 11 packages under
pkg/, with the bulk of complexity concentrated in two major packages:Metrics Collected:
Findings
Strengths
Excellent Dependency Architecture: Clean unidirectional flow with only 3 reverse dependencies (workflow → cli). The intended hierarchy (CLI → Workflow → Parser → shared utilities) is well-maintained.
Strong Package Cohesion: 11 focused packages with clear responsibilities -
cli,workflow,parser,console,logger,testutil,timeutil,styles,gitutil,gateway,constants.Healthy File Size Distribution: 66% of files under 300 lines (80 small, 100 medium), indicating good modularization in most areas.
Consistent Error Handling: 696 instances of error wrapping with
fmt.Errorf("%w"), showing mature error propagation patterns.Minimal Initialization Complexity: Only 8
init()functions across the entire codebase - avoiding common Go anti-patterns.Good Test Organization: 69.6% test coverage ratio with consistent
*_test.gonaming and strong table-driven test patterns.Areas for Improvement
🔴 Critical: Large File Proliferation
48 files exceed 500 lines (17% of codebase), with several massive files handling too many responsibilities:
pkg/cli/logs.gopkg/workflow/compiler_yaml.gopkg/workflow/compiler_jobs.gopkg/workflow/copilot_engine.gopkg/cli/update_command.goImpact: Decreased maintainability, increased cognitive load, harder to test individual responsibilities, higher merge conflict risk.
🔴 Critical: Over-Exposed Workflow Package API
The
pkg/workflowpackage exports 82.5% of its functions (1,821 exported vs 386 unexported), creating an enormous public API surface:Problems:
internal/subdirectories despite large package size🟡 High: Inconsistent Naming Conventions
73 CLI files (88% of CLI package) don't follow the
*_command.gonaming pattern:This makes it difficult to distinguish between command implementations, helpers, types, and utilities.
🟡 High: Missing Package Documentation
7 of 11 packages lack package-level documentation comments:
Go convention requires package comments for godoc generation and IDE tooling.
🟡 High: God Objects with Too Many Responsibilities
Several files contain 25-41 functions, indicating potential Single Responsibility Principle violations:
🟡 Medium: Deep Nesting Complexity
Several files exhibit 5-10 levels of nesting, indicating high cyclomatic complexity:
🟡 Medium: Long Parameter Lists
Functions with 9-18 parameters indicate missing abstraction or need for config structs:
🟢 Low: Moderate Global State
375 global variables across the codebase (278 in workflow, 81 in cli, 16 in parser). While not critical, this indicates opportunities for better encapsulation.
🟢 Low: Limited Interface Usage
Only 5 interface definitions for a 267-file codebase suggests missed abstraction opportunities, particularly for testing and plugin systems.
Detailed Analysis
Package Structure & Responsibilities
Core Packages (Large, Well-Defined):
pkg/workflow(552 files, 159K LOC): Workflow compilation, engine configuration, MCP integration, safe outputspkg/cli(232 files, 73K LOC): All CLI commands, GitHub API integration, user interfacepkg/parser(42 files, 17K LOC): Markdown frontmatter parsing, schema validationUtility Packages (Small, Focused):
pkg/console(13 files, 3K LOC): Terminal formatting and renderingpkg/logger(5 files, 883 LOC): Debug logging infrastructurepkg/testutil(2 files, 220 LOC): Test helperspkg/timeutil(2 files, 193 LOC): Time formatting utilitiespkg/styles(2 files, 508 LOC): Style definitionspkg/gitutil(2 files, 313 LOC): Git operationspkg/gateway(2 files, 834 LOC): API gateway logicpkg/constants(2 files, 708 LOC): 49 exported constantsDependency Flow Analysis
Healthy Dependencies (Expected Flow):
Architectural Concerns (Reverse Flow):
The 3 reverse dependencies from workflow → cli should be investigated - these suggest potential circular dependency risks.
Compiler Component Organization
The workflow compiler is split across 32 files but concentrated in 3 large files:
Recommendation: Split
compiler_yaml.goandcompiler_jobs.gointo smaller, responsibility-focused files.File Size Distribution Detail
Biggest Refactoring Candidates:
pkg/cli/logs.go(1,620 LOC, 10-level nesting) - Split into logs_download, logs_analysis, logs_cachepkg/workflow/compiler_yaml.go(1,446 LOC, 29 functions) - Extract YAML formatterspkg/workflow/compiler_jobs.go(1,374 LOC) - Separate job generation from step compilationpkg/workflow/copilot_engine.go(1,368 LOC) - Split config from runtime setuppkg/cli/update_command.go(1,331 LOC) - Extract tracking and error handling🤖 Tasks for Copilot Agent
NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot agent execution. Please split these into individual work items for Claude to process.
Improvement Tasks
The following code regions and tasks should be processed by the Copilot agent. Each section is marked for easy identification by the planner agent.
Task 1: Split Oversized logs.go into Focused Modules
Priority: High
Estimated Effort: Large
Focus Area: Code Organization - File Size Reduction
Description:
The
pkg/cli/logs.gofile (1,620 LOC) handles multiple responsibilities: log downloading, log analysis, formatting, caching, and error reporting. It exhibits 10 levels of nesting indicating high cyclomatic complexity. Split this into separate, focused files following single responsibility principle.Acceptance Criteria:
pkg/cli/logs_download.gofor download orchestration logicpkg/cli/logs_analysis.gofor log parsing and error detectionpkg/cli/logs_cache.gofor caching operationspkg/cli/logs_format.gofor output formattingpkg/cli/logs.goas thin orchestrator (<300 LOC)gh aw logscommandCode Region:
pkg/cli/logs.goTask 2: Introduce internal/ Package for Workflow Internals
Priority: High
Estimated Effort: Large
Focus Area: Code Organization - API Surface Reduction
Description:
The
pkg/workflowpackage exports 82.5% of its functions (1,821 exported vs 386 unexported), creating an enormous public API surface. Move internal helper functions, validators, and utilities topkg/workflow/internal/subdirectories to clearly separate public API from implementation details.Acceptance Criteria:
pkg/workflow/internal/directory structureinternal/helpers/internal/validation/internal/compiler/Code Region:
pkg/workflow/(all files)Task 3: Standardize CLI File Naming with _command.go Suffix
Priority: Medium
Estimated Effort: Medium
Focus Area: Code Organization - Naming Consistency
Description:
Currently only 10 of 83 CLI files follow the
*_command.gonaming pattern. Rename the 73 inconsistently named files to use the_command.gosuffix for command implementations, and create separate*_support.goor*_types.gofiles for helpers and types.Acceptance Criteria:
*_command.go*_support.gofiles*_types.gofilesgit mvcommandsCode Region:
pkg/cli/(73 files without _command suffix)Task 4: Split Compiler YAML and Jobs Files
Priority: Medium
Estimated Effort: Large
Focus Area: Code Organization - Component Decomposition
Description:
The files
compiler_yaml.go(1,446 LOC, 29 functions) andcompiler_jobs.go(1,374 LOC) are the largest non-command files in the codebase. Extract logical components into focused files: YAML formatters, job generators, step compilers, container config, and validation logic.Acceptance Criteria:
compiler_yaml.gosplit into 3-4 files (≤500 LOC each)compiler_jobs.gosplit into 3-4 files (≤500 LOC each)Code Region:
pkg/workflow/compiler_yaml.go,pkg/workflow/compiler_jobs.goTask 5: Add Package Documentation and Improve godoc
Priority: Medium
Estimated Effort: Small
Focus Area: Code Organization - Documentation
Description:
7 of 11 packages lack package-level documentation comments (console, constants, gateway, gitutil, logger, parser, testutil). Add package doc comments following Go conventions, either as doc.go files or as comments in the main package file.
Acceptance Criteria:
Code Region:
pkg/console/,pkg/constants/,pkg/gateway/,pkg/gitutil/,pkg/logger/,pkg/parser/,pkg/testutil/📊 Historical Context
Previous Focus Areas
Statistics: 10 total runs, 60% custom rate, 10% reuse rate, 9 unique areas explored
🎯 Recommendations
Immediate Actions (This Week)
Short-term Actions (This Month)
Long-term Actions (This Quarter)
📈 Success Metrics
Track these metrics to measure improvement in Code Organization:
Next Steps
Generated by Repository Quality Improvement Agent
Next analysis: 2025-12-10 - Focus area will be selected based on diversity algorithm (60% custom, 30% standard, 10% reuse)
Beta Was this translation helpful? Give feedback.
All reactions