[repository-quality] Repository Quality: CLI Command Definition Inconsistency (2026-04-16)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — CLI Command Definition Inconsistency

Analysis Date: 2026-04-16
Focus Area: CLI Command Definition Inconsistency
Strategy Type: Custom (first run — no prior history)
Custom Area: Yes — This focus area was chosen after observing that cmd/gh-aw/main.go mixes two architecturally incompatible patterns for defining CLI commands, creating a growing inconsistency that impedes testability, discoverability, and contribution experience.

---

Executive Summary

The gh-aw CLI entry point (cmd/gh-aw/main.go, 895 lines) currently defines five commands inline (new, compile, run, remove, enable, disable, version) while all other commands follow the established pattern of being implemented in pkg/cli/ and simply instantiated in main.go. The largest inline command, compileCmd, spans ~126 lines with significant business logic directly in the cobra RunE closure, making it untestable via standard package-level tests.

This inconsistency has concrete downstream costs: inline commands cannot be unit tested, adding new features requires editing the 895-line main.go, and contributors looking for command logic in pkg/cli/ will miss critical behavior implemented elsewhere. The init() function alone is ~403 lines registering all commands, which further adds to the cognitive load of understanding the entry point.

The fix is straightforward: move each inline command to a dedicated *_command.go file in pkg/cli/, following the existing NewXCommand() / RunX() pattern already used by 25+ other commands in the codebase.

---

Full Analysis Report

Focus Area: CLI Command Definition Inconsistency

Current State Assessment

Metrics Collected:

Metric	Value	Status
main.go total lines	895	⚠️ Very large for an entry point
init() function lines	~403	⚠️ Monolithic
Inline command definitions	5 (new, compile, run, remove/enable/disable, version)	❌ Inconsistent
Commands in pkg/cli/	25+	✅ Proper pattern
compileCmd inline lines	126	❌ Untestable logic
runCmd inline lines	85	❌ Untestable logic
newCmd inline lines	57	⚠️ Small but still inconsistent

Findings

Strengths

• The pkg/cli/ pattern with NewXCommand() and RunX() functions is well-established and followed consistently by 25+ commands
• Commands in pkg/cli/ are testable and follow the *_command.go naming convention
• The overall command surface is rich and well-organized within pkg/cli/

Areas for Improvement

• [High] compileCmd (126 lines inline in main.go) — contains real logic in a cobra closure that cannot be unit tested
• [High] runCmd (85 lines inline in main.go) — same issue; run workflow logic is a core user path
• [Medium] newCmd, removeCmd, enableCmd, disableCmd, versionCmd — smaller but create the same discoverability and testing gap
• [Low] The init() function (~403 lines) could be broken into smaller registration helpers

Detailed Analysis

Searching for all inline var *Cmd = &cobra.Command{...} definitions in cmd/gh-aw/main.go reveals:

var newCmd     = &cobra.Command{...}   // L108–L165  (~57 lines)
var removeCmd  = &cobra.Command{...}   // L166–L192  (~26 lines)
var enableCmd  = &cobra.Command{...}   // L193–L211  (~18 lines)
var disableCmd = &cobra.Command{...}   // L212–L232  (~20 lines)
var compileCmd = &cobra.Command{...}   // L233–L359  (~126 lines)
var runCmd     = &cobra.Command{...}   // L360–L445  (~85 lines)
var versionCmd = &cobra.Command{...}   // L446–L458  (~12 lines)

Every other command (add, logs, audit, mcp, health, checks, pr, secrets, fix, upgrade, validate, hash, domains, project, status, list, etc.) is implemented in pkg/cli/ with the proper NewXCommand() factory function and is directly testable.

The pattern to follow is already well documented in AGENTS.md under "CLI Command Patterns":

• File named *_command.go in pkg/cli/
• Logger: logger.New("cli:command_name")
• NewXCommand() and RunX() functions defined
• Test file *_command_test.go

---

🤖 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 Claude to process.

Improvement Tasks

---

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

Priority: High
Estimated Effort: Medium
Focus Area: CLI Command Definition Inconsistency

Description:
The compileCmd variable in cmd/gh-aw/main.go (lines ~233–359, ~126 lines) defines the compile command inline with real business logic in the cobra RunE closure. This prevents unit testing and violates the pkg/cli command pattern.

Move it to pkg/cli/compile_command.go following the exact same structure as other commands like pkg/cli/audit_command.go or pkg/cli/logs_command.go.

Acceptance Criteria:

• New file pkg/cli/compile_command.go contains NewCompileCommand() factory and RunCompile() testable function
• cmd/gh-aw/main.go replaces the inline var compileCmd = &cobra.Command{...} with compileCmd := cli.NewCompileCommand(validateEngine)
• All existing flags (--engine, --output, --force, --approve, etc.) preserved with identical behavior
• New file pkg/cli/compile_command_test.go with at least 3 test cases (valid input, missing file, invalid engine)
• make agent-finish passes with no errors

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

In the gh-aw repository, the `compile` command is defined inline in `cmd/gh-aw/main.go` (search for `var compileCmd = &cobra.Command`) but should follow the established `pkg/cli` pattern used by all other commands.

Extract the `compileCmd` definition from `cmd/gh-aw/main.go` into a new file `pkg/cli/compile_command.go`:
1. Create `pkg/cli/compile_command.go` with a `NewCompileCommand(validateEngine func(string) error) *cobra.Command` factory function
2. Extract the `RunE` logic into a testable `RunCompileWorkflows(config CompileConfig) error` function
3. Define a `CompileConfig` struct with all needed fields
4. Update `cmd/gh-aw/main.go` to use `compileCmd := cli.NewCompileCommand(validateEngine)` in the `init()` function
5. Add `//go:build !integration` build tag at the top of the test file
6. Create `pkg/cli/compile_command_test.go` with table-driven tests
7. Run `make agent-finish` to verify no regressions

Follow the AGENTS.md CLI Command Patterns guidelines: use `logger.New("cli:compile")`, console formatting with `os.Stderr`, and proper error wrapping with `%w`.

---

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

Priority: High
Estimated Effort: Medium
Focus Area: CLI Command Definition Inconsistency

Description:
The runCmd variable in cmd/gh-aw/main.go (lines ~360–445, ~85 lines) defines the run command with execution logic inline. This is a critical user path (running workflows) that deserves proper isolation, testing, and documentation in pkg/cli/.

Acceptance Criteria:

• New file pkg/cli/run_command.go with NewRunCommand() and RunWorkflow() functions
• cmd/gh-aw/main.go uses runCmd := cli.NewRunCommand(validateEngine) (if engine validation needed) or cli.NewRunCommand()
• All existing flags preserved (e.g., --ref, --engine, --push, --dry-run, etc.)
• New pkg/cli/run_command_test.go with at least 3 test cases
• make agent-finish passes with no errors

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

In the gh-aw repository, the `run` command is defined inline in `cmd/gh-aw/main.go` (search for `var runCmd = &cobra.Command`) but should follow the established `pkg/cli` pattern.

Extract the `runCmd` definition into `pkg/cli/run_command.go`:
1. Create `NewRunCommand(validateEngine func(string) error) *cobra.Command` in `pkg/cli/run_command.go`
2. Extract business logic into a `RunWorkflow(config RunWorkflowConfig) error` testable function
3. Define a `RunWorkflowConfig` struct with all needed fields
4. Update `cmd/gh-aw/main.go` to remove the inline `var runCmd` and use `runCmd := cli.NewRunCommand(validateEngine)` in `init()`
5. Add `//go:build !integration` build tag to any new test file
6. Create `pkg/cli/run_command_test.go` with table-driven tests covering: valid run, invalid workflow name, missing workflow file
7. Run `make agent-finish` to verify

Follow the AGENTS.md CLI Command Patterns guidelines.

---

Task 3: Extract newCmd, removeCmd, enableCmd, disableCmd into pkg/cli/

Priority: Medium
Estimated Effort: Small
Focus Area: CLI Command Definition Inconsistency

Description:
Four smaller commands (new, remove, enable, disable) are still defined inline in main.go. While individually smaller, they contribute to the inconsistency. Consolidate them into pkg/cli/ to complete the migration.

Acceptance Criteria:

• pkg/cli/new_command.go contains NewNewCommand() factory
• pkg/cli/workflow_lifecycle_commands.go (or separate files) contains NewRemoveCommand(), NewEnableCommand(), NewDisableCommand()
• main.go shrinks by ~120 lines from removing these inline definitions
• All commands behave identically to before
• make agent-finish passes

Code Region: cmd/gh-aw/main.go:108–232, new files in pkg/cli/

In the gh-aw repository, four small commands (`new`, `remove`, `enable`, `disable`) are still defined inline in `cmd/gh-aw/main.go` starting at lines ~108–232. Extract these into `pkg/cli/`:

1. Create `pkg/cli/new_command.go` with `NewNewCommand() *cobra.Command`
2. Create `pkg/cli/workflow_lifecycle_commands.go` (or individual files) with `NewRemoveCommand()`, `NewEnableCommand()`, `NewDisableCommand()`
3. Update `cmd/gh-aw/main.go` `init()` to use these new factories
4. Ensure all flags and behavior are preserved
5. Run `make agent-finish` to verify no regressions

These commands have simpler logic but should still follow the standard pattern for consistency.

---

Task 4: Refactor init() in main.go into focused registration helpers

Priority: Low
Estimated Effort: Small
Focus Area: CLI Command Definition Inconsistency

Description:
After extracting inline commands (Tasks 1–3), the init() function will still be long due to many rootCmd.AddCommand(...) calls and persistent flag setup. Organize this into two or three focused helper functions to make the command registration clear and scannable.

Acceptance Criteria:

• init() is reduced to ~50 lines by delegating to helpers like registerCommands(rootCmd) and registerPersistentFlags(rootCmd)
• No behavior changes — all commands and flags still registered
• make agent-finish passes

Code Region: cmd/gh-aw/main.go:459–862

After extracting inline commands from `cmd/gh-aw/main.go` (the `compile`, `run`, `new`, `remove`, `enable`, `disable` commands), refactor the remaining `init()` function (currently ~403 lines at L459):

1. Extract command registrations into a `registerCommands(root *cobra.Command)` private function
2. Extract persistent flag setup into a `registerPersistentFlags(root *cobra.Command)` private function
3. Keep `init()` as a thin orchestrator calling these two functions
4. Verify all commands still appear in `gh aw --help` output
5. Run `make agent-finish` to verify no regressions

Goal: `init()` should be ~20–30 lines and serve as a clear table of contents for the CLI structure.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-16	CLI Command Definition Inconsistency	Custom	Yes	First run — established baseline

---

🎯 Recommendations

Immediate Actions (This Week)

1. Extract compileCmd — Task 1 above — Priority: High (core user path, large inline block)
2. Extract runCmd — Task 2 above — Priority: High (core user path, currently untestable)

Short-term Actions (This Month)

1. Extract newCmd/removeCmd/enableCmd/disableCmd — Task 3 — Priority: Medium

Long-term Actions (This Quarter)

1. Refactor init() — Task 4 — Priority: Low (cleanup after Tasks 1–3 shrink main.go)

---

📈 Success Metrics

Track these metrics to measure improvement in CLI Command Definition Inconsistency:

• main.go line count: 895 → ≤ 300 lines
• Inline command definitions: 5 → 0
• init() function lines: ~403 → ≤ 50
• Commands testable via pkg/cli/ package tests: 25 → 30+ (all commands)

---

Next Steps

1. Review and prioritize the tasks above
2. Assign Tasks 1 and 2 to Copilot coding agent via planner agent
3. Track progress — main.go line count is the easiest health metric
4. Re-evaluate this focus area in 2 weeks to confirm migration complete

---

References:

• §24512301027

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

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

• expires on Apr 17, 2026, 1:24 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #26871.