[repository-quality] Repository Quality Improvement — main.go Modularization (2026-04-17)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — main.go Modularization

Analysis Date: 2026-04-17
Focus Area: main.go Modularization
Strategy Type: Custom
Custom Area: Yes — This focus area was selected because cmd/gh-aw/main.go has grown to 895 lines and contains inline cobra.Command definitions for 9 commands — in stark contrast to the 29 commands that have already been properly extracted to pkg/cli/. This creates a maintenance inconsistency and makes the entry point unnecessarily large.

Executive Summary

cmd/gh-aw/main.go is 895 lines long and acts as both an application entry point and a command definition file for several core commands: compile, run, new, remove, enable, disable, and version. These commands contain full cobra.Command structs with Long descriptions, RunE handlers, and 103 inline flag registrations scattered throughout a large init() function spanning lines ~460–861.

This contrasts with 29 other commands (e.g., audit, add, fix, validate, logs, mcp, checks) that have been cleanly extracted to pkg/cli/*_command.go files following the project's established patterns. Notably, compile_command.go and run_command.go even contain explicit comments acknowledging they are "compatibility bridges" — meaning the extraction intent exists but the cobra.Command definitions and flag setup remain in main.go.

Completing the extraction would reduce main.go to a clean entry point (~200 lines), improve discoverability of command implementations, and align all commands with the NewXCommand() pattern used throughout the codebase.

Full Analysis Report

Focus Area: main.go Modularization

Current State Assessment

Metrics Collected:

Metric	Value	Status
main.go total lines	895	❌ (guideline: prefer smaller files)
Inline cobra.Command definitions in main.go	9	⚠️
Inline flag registrations in main.go	103	❌
Commands extracted to pkg/cli/	29	✅
compileCmd flags	32	❌ (belongs in compile command file)
runCmd flags	11	⚠️
init() function span	lines 460–861 (~400 lines)	❌

Findings

Strengths

• 29 commands already follow the NewXCommand(...) extraction pattern
• compile_command.go and run_command.go contain explicit comments acknowledging the split — the intent is clear
• Business logic for compile is already split across 6 dedicated files (compile_config.go, compile_helpers.go, compile_validation.go, compile_watch.go, compile_campaign.go, compile_orchestrator.go)
• Business logic for run has been moved to run_workflow_tracking.go and related files
• Root command, command groups, and global flags (verbose, banner) belong in main.go and are well-structured

Areas for Improvement

• [High] compileCmd (127 lines + 32 flags) is the largest inline command and has the most flags — its extraction is explicitly hinted by the existing compile_command.go comment
• [High] runCmd (86 lines + 11 flags) similarly has run_command.go marked as a "compatibility bridge"
• [Medium] newCmd (58 lines) defines interactive workflow creation inline with no extracted counterpart
• [Medium] enableCmd (19 lines) and disableCmd (21 lines) are small but inconsistently placed
• [Low] removeCmd (27 lines) and versionCmd (small) could be extracted for completeness

Detailed Analysis

The project already has a clear pattern for command organization:

pkg/cli/
  add_command.go        → NewAddCommand(validateEngine)
  audit.go              → NewAuditCommand()
  fix_command.go        → NewFixCommand()
  validate_command.go   → NewValidateCommand()
  ...

The init() function in main.go wires these up:

addCmd := cli.NewAddCommand(validateEngine)
...
rootCmd.AddCommand(addCmd)

The same pattern should be applied to compileCmd, runCmd, newCmd, enableCmd, disableCmd, and removeCmd. The validateEngine function (already used by NewAddCommand) can be passed as a parameter to commands that need it.

The massive init() would then shrink to just:

1. Command group definitions (~15 lines)
2. Global flag setup (~10 lines)
3. Root command configuration (SilenceUsage, SetOut, etc.) (~20 lines)
4. Custom usage/help setup (~80 lines, already complex but necessary)
5. Wiring extracted commands (~30 lines)

Estimated main.go reduction: ~500 lines → ~300 lines.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot coding agent execution. Please split these into individual work items for the coding agent to process sequentially (later tasks may depend on earlier ones).

Improvement Tasks

Task 1: Extract compileCmd from main.go to pkg/cli/compile_command.go

Priority: High
Estimated Effort: Medium
Focus Area: main.go Modularization

Description:
cmd/gh-aw/main.go defines var compileCmd = &cobra.Command{...} inline (127 lines) along with 32 flag registrations in init(). The file pkg/cli/compile_command.go currently contains only a comment saying "The compile functionality has been split into: ...". The task is to move the cobra.Command definition and all its flag registrations into a NewCompileCommand(validateEngine func(string) error) *cobra.Command function in pkg/cli/compile_command.go, then update main.go to call cli.NewCompileCommand(validateEngine).

Acceptance Criteria:

• NewCompileCommand(validateEngine func(string) error) *cobra.Command is defined in pkg/cli/compile_command.go
• All 32 flag definitions (--engine, --action-mode, --validate, --watch, --dir, --no-emit, --purge, --strict, --dependabot, etc.) are moved to the new function
• The Long description, Use, Short, Args, and RunE are preserved exactly
• main.go replaces compileCmd var definition with compileCmd := cli.NewCompileCommand(validateEngine)
• All flag mutual exclusion and deprecation declarations are preserved
• make build && make test-unit pass with no regressions

Code Region: cmd/gh-aw/main.go:233–359 and pkg/cli/compile_command.go

In the repository github/gh-aw, extract the `compileCmd` cobra.Command definition from `cmd/gh-aw/main.go` into a proper `NewCompileCommand(validateEngine func(string) error) *cobra.Command` function in `pkg/cli/compile_command.go`.

The cobra.Command definition starts at line 233 in main.go and the flag registrations are in the `init()` function (look for all lines containing `compileCmd.Flags()`). 

Steps:
1. Open `pkg/cli/compile_command.go` — it currently has only a comment. Add a `NewCompileCommand` function that:
   - Creates and returns the `*cobra.Command` with the same `Use`, `Short`, `Long`, `Args`, and `RunE` currently in `main.go`
   - Registers all flags currently set via `compileCmd.Flags().*` in `init()` directly inside the function (before returning)
   - Calls `cli.RegisterEngineFlagCompletion(cmd)` if needed
2. Update `cmd/gh-aw/main.go`:
   - Remove the `var compileCmd = &cobra.Command{...}` definition
   - Replace the compileCmd flag registrations in `init()` with `compileCmd := cli.NewCompileCommand(validateEngine)`
   - Ensure `rootCmd.AddCommand(compileCmd)` still works
3. Run `make build && make test-unit` and fix any issues
4. Run `make fmt` to format the code

---

Task 2: Extract runCmd from main.go to pkg/cli/run_command.go

Priority: High
Estimated Effort: Medium
Focus Area: main.go Modularization

Description:
cmd/gh-aw/main.go defines var runCmd = &cobra.Command{...} inline (86 lines) with 11 flag registrations. The file pkg/cli/run_command.go currently says "This file now serves as a compatibility bridge." Move the cobra.Command definition to NewRunCommand(validateEngine func(string) error) *cobra.Command in pkg/cli/run_command.go.

Acceptance Criteria:

• NewRunCommand(validateEngine func(string) error) *cobra.Command is defined in pkg/cli/run_command.go
• All 11 flag definitions (--repeat, --enable-if-needed, --engine, --repo, --ref, --auto-merge-prs, --raw-field, --push, --dry-run, --json, --approve) are moved
• Interactive mode and CI environment check are preserved in RunE
• main.go replaces the runCmd var with runCmd := cli.NewRunCommand(validateEngine)
• make build && make test-unit pass with no regressions

Code Region: cmd/gh-aw/main.go:360–445 and pkg/cli/run_command.go

In the repository github/gh-aw, extract the `runCmd` cobra.Command definition from `cmd/gh-aw/main.go` into `NewRunCommand(validateEngine func(string) error) *cobra.Command` in `pkg/cli/run_command.go`.

The file `pkg/cli/run_command.go` currently says "This file now serves as a compatibility bridge" — this task completes the bridge by moving the cobra definition into it.

Steps:
1. Find `var runCmd = &cobra.Command{` in `cmd/gh-aw/main.go` (around line 360) and all `runCmd.Flags().*` lines in the `init()` function
2. Create `NewRunCommand(validateEngine func(string) error) *cobra.Command` in `pkg/cli/run_command.go` with:
   - Same `Use`, `Short`, `Long`, `Args`, `RunE` as the current inline definition
   - All flag registrations inside the function
3. Update `main.go`:
   - Remove `var runCmd = &cobra.Command{...}`
   - Replace runCmd flag lines in `init()` with `runCmd := cli.NewRunCommand(validateEngine)`
4. Run `make build && make test-unit` and fix any issues
5. Run `make fmt`

---

Task 3: Extract newCmd from main.go to pkg/cli/new_command.go

Priority: Medium
Estimated Effort: Small
Focus Area: main.go Modularization

Description:
cmd/gh-aw/main.go defines var newCmd = &cobra.Command{...} inline (58 lines) with 3 flags. There is no existing pkg/cli/new_command.go. Create this file with NewNewCommand(validateEngine func(string) error) *cobra.Command following the existing patterns.

Acceptance Criteria:

• pkg/cli/new_command.go is created with NewNewCommand(validateEngine func(string) error) *cobra.Command
• The file has a //go:build !integration build tag at the very top
• All 3 flags (--force, --interactive, --engine) are registered inside the function
• main.go replaces var newCmd with newCmd := cli.NewNewCommand(validateEngine)
• make build && make test-unit pass

Code Region: cmd/gh-aw/main.go:108–165 → new file pkg/cli/new_command.go

In the repository github/gh-aw, extract `var newCmd = &cobra.Command{...}` from `cmd/gh-aw/main.go` into a new file `pkg/cli/new_command.go`.

Steps:
1. Create `pkg/cli/new_command.go` with:
   - Build tag `//go:build !integration` as the very first line
   - Package declaration `package cli`
   - Required imports
   - `NewNewCommand(validateEngine func(string) error) *cobra.Command` function containing:
     * The `*cobra.Command` struct with `Use: "new [workflow]"`, `Short`, `Long`, `Args`, `RunE` from current main.go
     * The 3 flags: --force, --interactive, --engine
     * Call to `RegisterEngineFlagCompletion(cmd)` 
2. Update `cmd/gh-aw/main.go`:
   - Remove `var newCmd = &cobra.Command{...}` block
   - In `init()`, remove the 3 `newCmd.Flags().*` lines and `cli.RegisterEngineFlagCompletion(newCmd)`
   - Add `newCmd := cli.NewNewCommand(validateEngine)` before `rootCmd.AddCommand(newCmd)`
3. Run `make build && make fmt && make test-unit`

---

Task 4: Extract enableCmd and disableCmd from main.go

Priority: Medium
Estimated Effort: Small
Focus Area: main.go Modularization

Description:
cmd/gh-aw/main.go defines var enableCmd (19 lines) and var disableCmd (21 lines) with 1 flag each (--repo). Extract both to pkg/cli/enable_disable_command.go or separate files.

Acceptance Criteria:

• NewEnableCommand() *cobra.Command and NewDisableCommand() *cobra.Command are created in pkg/cli/ (single file or separate files per project convention)
• Each file has //go:build !integration build tag at top
• The --repo flag is registered inside each command function
• main.go is updated to use the new constructors
• make build && make test-unit pass

Code Region: cmd/gh-aw/main.go:193–232 → pkg/cli/enable_command.go and pkg/cli/disable_command.go

In the repository github/gh-aw, extract `enableCmd` and `disableCmd` from `cmd/gh-aw/main.go` into dedicated command files in `pkg/cli/`.

Look at existing small command files like `pkg/cli/hash_command.go` for the correct pattern.

Steps:
1. Create `pkg/cli/enable_command.go` with build tag `//go:build !integration`, containing `NewEnableCommand() *cobra.Command` that includes the --repo flag registration
2. Create `pkg/cli/disable_command.go` with build tag `//go:build !integration`, containing `NewDisableCommand() *cobra.Command` that includes the --repo flag registration  
3. Update `cmd/gh-aw/main.go`:
   - Remove `var enableCmd` and `var disableCmd` block definitions
   - Remove `enableCmd.Flags().*` and `disableCmd.Flags().*` in `init()`
   - Add `enableCmd := cli.NewEnableCommand()` and `disableCmd := cli.NewDisableCommand()` before `rootCmd.AddCommand` calls
4. Run `make build && make fmt && make test-unit`

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-17	main.go Modularization	Custom	Yes	First run — 4 extraction tasks identified

---

🎯 Recommendations

Immediate Actions (This Week)

1. Extract compileCmd — Priority: High — Biggest impact, most flags, clear extraction path
2. Extract runCmd — Priority: High — Second largest, marked as "compatibility bridge"

Short-term Actions (This Month)

1. Extract newCmd — Priority: Medium — Small effort, completes the interactive commands extraction
2. Extract enableCmd/disableCmd — Priority: Medium — Quick wins for consistency

Long-term Actions (This Quarter)

1. Extract removeCmd and versionCmd — Priority: Low — Small files, complete the extraction
2. Add tests for extracted commands — Ensure each New*Command() function has a corresponding test verifying flag registration and basic invocation

---

📈 Success Metrics

Track these metrics to measure improvement in main.go Modularization:

• main.go line count: 895 → target ≤ 300 lines
• Inline cobra.Command definitions: 9 → target ≤ 2 (only rootCmd + custom help)
• Inline flag registrations in init(): 103 → target ≤ 10 (only global persistent flags)
• Commands following New*Command() pattern: 29 → target 35+ (after all extractions)

---

Next Steps

1. Review and prioritize the 4 tasks above
2. Assign Task 1 (compileCmd extraction) to Copilot coding agent first — it is self-contained and highest impact
3. Tasks should be executed sequentially as later tasks follow the same pattern
4. After all tasks, verify main.go line count is below 350

---

References:

• §24566938428

Generated by Repository Quality Improvement Agent · ● 1.7M · ◷

• expires on Apr 18, 2026, 1:23 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-18T13:23:42.486Z.

Closed by Workflow