[repository-quality] 🎯 Repository Quality Improvement Report - Code Organization (2026-08-07)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Code Organization

Analysis Date: 2026-08-07
Focus Area: Code Organization
Strategy Type: Standard
Custom Area: No

Executive Summary

pkg/workflow (1,272 Go files, effectively a single flat package with no internal sub-packages besides asset/data folders) and pkg/cli (857 Go files, flat except workflows/ and data/) dominate the codebase and contain 15 of the top files exceeding 1,000 lines each — with pkg/workflow/awf_helpers.go (1,148 lines) and pkg/cli/update_actions.go (1,144 lines) as the largest. These files mix multiple concerns (AWF command construction, version-gate feature checks, action-update logic, skill-ref rewriting, git-based release resolution) in single files, which increases review friction and cognitive load for both human and Copilot contributors.

The repository otherwise has a healthy test ratio (520K test LOC vs 268K source LOC, ~1.9:1) and a modest TODO/FIXME backlog (41), so this run focuses purely on structural organization rather than correctness or coverage. Splitting the largest, clearly-separable files by responsibility (e.g., AWF version-gating helpers vs. command builders; action-update fetch/parse vs. workflow-file rewriting) would reduce file sizes below the 1,000-line threshold without behavior changes, aligning with the repo's own developer-code-organization skill guidance.

Recommended actions below target the four largest offending files with concrete split boundaries, plus one directory-level suggestion to introduce sub-packages under pkg/workflow for asset-adjacent logic, mirroring the existing pkg/cli/workflows pattern.

Full Analysis Report

Focus Area: Code Organization

Current State Assessment

Metrics Collected:

Metric	Value	Status
Go files >1000 lines	15	⚠️
Total non-test Go files	1,191	✅
Avg lines/file (non-test)	225	✅
pkg/workflow file count	1,272 (flat, no logic sub-packages)	⚠️
pkg/cli file count	857 (flat, only workflows/, data/ subdirs)	⚠️
Test/Source LOC ratio	520,129 / 268,300 (~1.94)	✅
TODO/FIXME count	41	✅
Largest file	pkg/workflow/awf_helpers.go (1,148 LOC, 29 top-level funcs)	⚠️

Findings

Strengths

• Strong test-to-source LOC ratio (~1.9:1) indicates disciplined testing culture.
• Low TODO/FIXME count (41) shows the team resolves technical debt markers promptly.
• Most files (average 225 LOC) are appropriately sized; oversized files are a minority (15 of 1,191).

Areas for Improvement

• ⚠️ Medium: pkg/workflow and pkg/cli are both very large flat packages (1,272 and 857 files respectively) with almost no logical sub-packaging, unlike smaller packages such as pkg/linters, pkg/parser, pkg/console which stay focused.
• ⚠️ Medium: pkg/workflow/awf_helpers.go (1,148 LOC) mixes AWF command/arg builders (BuildAWFCommand, BuildAWFArgs, GetAWFCommandPrefix), image digest lookup, environment exclusion logic, and ~15 awfSupports* version-gate predicates in one file.
• ⚠️ Medium: pkg/cli/update_actions.go (1,144 LOC) combines action-cache-dependency wiring, GitHub release/tag resolution (both API and git-based), cooldown logic, skill-ref rewriting, and workflow-file rewriting — five distinct responsibilities.
• ⚠️ Low: pkg/workflow/compiler_custom_jobs.go (1,142 LOC) and pkg/cli/audit.go (1,073 LOC) similarly bundle multiple pipeline stages (audit command registration, single/multi-run resolution, permission-error classification, run summary rendering) that could be split along natural seams already visible in function naming (runAuditSingle vs runAuditMulti vs renderCachedAuditIfAvailable).

Detailed Analysis

The four files below account for 4,507 combined lines and are the most impactful targets:

1. pkg/workflow/awf_helpers.go — 29 top-level functions. Natural split: awf_command_builder.go (BuildAWFCommand/BuildAWFArgs/GetAWFCommandPrefix/WrapCommandInShell), awf_version_gates.go (all awfSupports* predicates + awfVersionAtLeast), awf_env.go (ComputeAWFExcludeEnvVarNames/addCliProxyGHTokenToEnv/applyDefaultMaxAICreditsEnvToMap).
2. pkg/cli/update_actions.go — 18 top-level functions. Natural split: action_release_resolver.go (getLatestActionRelease*/getActionSHAForTag/parseActionTagRefs/findCooledDownActionVersion), skill_ref_updater.go (updateSkillRefsInContent*/updateSkillRefValue), keep update_actions.go for the orchestration entry points (UpdateActions, UpdateActionsInWorkflowFiles).
3. pkg/workflow/compiler_custom_jobs.go (1,142 LOC) — worth a follow-up file-level function inventory before splitting; flagged for task assignment.
4. pkg/cli/audit.go (1,073 LOC) — split single-run path (runAuditSingle, AuditWorkflowRun, newAuditRunConfig) from multi-run path (runAuditMulti) into audit_single.go / audit_multi.go, keeping command registration in audit.go.

No behavior changes are needed — these are pure file-organization refactors (moving functions between files within the same package), so risk is low and can be validated with go build ./... and existing unit tests.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Split pkg/workflow/awf_helpers.go by responsibility

Priority: Medium
Estimated Effort: Medium
Focus Area: Code Organization

Description: pkg/workflow/awf_helpers.go (1,148 LOC, 29 functions) mixes AWF command/argument construction, container-digest lookup, environment-variable exclusion logic, and ~15 awfSupports* version-gate predicates. Split into awf_command_builder.go, awf_version_gates.go, and awf_env.go within the same pkg/workflow package. No functional changes — pure file reorganization.

Acceptance Criteria:

• BuildAWFCommand, BuildAWFArgs, GetAWFCommandPrefix, WrapCommandInShell, digest-lookup helpers moved to awf_command_builder.go
• All awfSupports* functions and awfVersionAtLeast moved to awf_version_gates.go
• ComputeAWFExcludeEnvVarNames, addCliProxyGHTokenToEnv, applyDefaultMaxAICreditsEnvToMap, injectMaxAICreditsExpression moved to awf_env.go
• go build ./... and make test-unit pass unchanged
• No public API/behavior changes; only file locations change

Code Region: pkg/workflow/awf_helpers.go

Split the file `pkg/workflow/awf_helpers.go` (currently ~1148 lines) in the gh-aw repository into three files within the same `pkg/workflow` package, moving functions only (no behavior changes):

1. `pkg/workflow/awf_command_builder.go`: BuildAWFCommand, BuildAWFArgs, GetAWFCommandPrefix, WrapCommandInShell, buildAWFImageTagWithDigests, lookupContainerDigest, buildModelsJSONPathExportScript, rewriteArcDindPath, rewriteArcDindEngineCommand, buildArcDindChrootConfigPatchBody, buildArcDindChrootConfigPatchBodyBash, buildWorkflowCallNetworkAllowedUpdateScript, shouldUseWorkflowCallNetworkAllowedInput
2. `pkg/workflow/awf_version_gates.go`: awfVersionAtLeast and every function prefixed `awfSupports*`
3. `pkg/workflow/awf_env.go`: ComputeAWFExcludeEnvVarNames, addCliProxyGHTokenToEnv, applyDefaultMaxAICreditsEnvToMap, injectMaxAICreditsExpression

Keep the original `pkg/workflow/awf_helpers.go` for any remaining glue code, or remove it if empty. Preserve all existing doc comments and function signatures exactly. Run `go build ./...` and `make fmt` after the split, then run `make test-unit` (or the impacted-only variant) to confirm no regressions. Do not alter any function bodies, only their file location.

---

Task 2: Split pkg/cli/update_actions.go into release-resolver and skill-ref-updater files

Priority: Medium
Estimated Effort: Medium
Focus Area: Code Organization

Description: pkg/cli/update_actions.go (1,144 LOC, 18 functions) combines GitHub Action release/tag resolution (both API and git-based), cooldown checking, skill-reference rewriting, and workflow-file rewriting orchestration. Separate these concerns into dedicated files for maintainability.

Acceptance Criteria:

• getLatestActionRelease, getLatestActionReleaseWithDeps, getLatestActionReleaseViaGit, getActionSHAForTag, parseActionTagRefs, findCooledDownActionVersion moved to pkg/cli/action_release_resolver.go
• updateSkillRefsInContent, updateSkillRefsInContentWithResolver, updateSkillRefValue moved to pkg/cli/skill_ref_updater.go
• update_actions.go retains only orchestration entry points (UpdateActions, updateActions, UpdateActionsInWorkflowFiles, updateActionsInWorkflowFiles, updateActionRefsInContentWithDeps) and shared types/helpers (isCoreAction, isGhAwNativeAction, newCachedActionUpdateDeps, defaultActionUpdateDeps)
• go build ./... passes and existing update_actions unit tests pass unchanged

Code Region: pkg/cli/update_actions.go

Split the file `pkg/cli/update_actions.go` (currently ~1144 lines) in the gh-aw repository into two additional files within the same `pkg/cli` package, moving functions only (no behavior changes):

1. `pkg/cli/action_release_resolver.go`: getLatestActionRelease, getLatestActionReleaseWithDeps, getLatestActionReleaseViaGit, getActionSHAForTag, parseActionTagRefs, findCooledDownActionVersion
2. `pkg/cli/skill_ref_updater.go`: updateSkillRefsInContent, updateSkillRefsInContentWithResolver, updateSkillRefValue

Leave `pkg/cli/update_actions.go` with the orchestration functions (UpdateActions, updateActions, UpdateActionsInWorkflowFiles, updateActionsInWorkflowFiles, updateActionRefsInContentWithDeps) and shared helper/type declarations (isCoreAction, isGhAwNativeAction, newCachedActionUpdateDeps, defaultActionUpdateDeps, actionUpdateDeps type). Preserve all doc comments and signatures exactly — only relocate function bodies. Run `go build ./...`, `make fmt`, and the existing tests in `pkg/cli/update_actions_test.go` (or equivalent) to confirm no regressions.

---

Task 3: Split pkg/cli/audit.go into single-run and multi-run audit files

Priority: Low
Estimated Effort: Small
Focus Area: Code Organization

Description: pkg/cli/audit.go (1,073 LOC) bundles command registration, single-run audit execution, multi-run audit execution, and permission-error classification. The function names already reveal a clean split boundary between single-run and multi-run code paths.

Acceptance Criteria:

• runAuditSingle, AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, announceAuditRun, renderCachedAuditIfAvailable, processedRunFromSummary moved to pkg/cli/audit_single.go
• runAuditMulti and its direct helpers moved to pkg/cli/audit_multi.go
• audit.go retains NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs, applyAuditRepoFlag, isPermissionErrorStr, isPermissionError
• go build ./... and existing audit tests pass unchanged

Code Region: pkg/cli/audit.go

Split the file `pkg/cli/audit.go` (currently ~1073 lines) in the gh-aw repository into two additional files within the same `pkg/cli` package, moving functions only (no behavior changes):

1. `pkg/cli/audit_single.go`: runAuditSingle, AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, announceAuditRun, renderCachedAuditIfAvailable, processedRunFromSummary, and the auditRunConfig type plus its jobOptions()/auditOptions() methods
2. `pkg/cli/audit_multi.go`: runAuditMulti and any private helpers used only by it

Leave `pkg/cli/audit.go` with command registration and shared/dispatch logic: NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs, applyAuditRepoFlag, isPermissionErrorStr, isPermissionError. Preserve doc comments and signatures exactly. Run `go build ./...`, `make fmt`, and existing tests referencing `pkg/cli/audit*_test.go` to confirm no regressions.

---

Task 4: Introduce logical sub-packages or naming conventions for pkg/workflow's AWF-related files

Priority: Low
Estimated Effort: Large
Focus Area: Code Organization

Description: pkg/workflow has grown to 1,272 files as a single flat package (aside from data/asset directories like js/, sh/, schemas/). Several files share an awf_* naming prefix (awf_helpers.go, awf_config.go, plus the newly split files from Task 1), suggesting a coherent sub-domain. Evaluate consolidating AWF-firewall-related Go logic into a dedicated internal sub-package (e.g., pkg/workflow/awf) to reduce the flat package's file count and clarify ownership boundaries, following the precedent of pkg/cli/workflows.

Acceptance Criteria:

• Inventory all awf_*.go files in pkg/workflow and assess exported vs. unexported API surface
• Produce a migration plan (this task) or, if scoped small enough, perform the move into pkg/workflow/awf/ with adjusted import paths
• Confirm no circular import issues are introduced between pkg/workflow and the new sub-package
• go build ./... and make test-unit pass after any structural change

Code Region: pkg/workflow/awf_*.go

In the gh-aw repository, investigate whether the `awf_*.go` files under `pkg/workflow` (e.g., awf_helpers.go, awf_config.go, and any awf_command_builder.go/awf_version_gates.go/awf_env.go created by prior refactors) can be moved into a new internal sub-package `pkg/workflow/awf` to reduce pkg/workflow's flat file count (currently 1,272 files) and clarify module boundaries, mirroring the existing pkg/cli/workflows sub-package pattern.

First produce an inventory of all awf_*.go files and their exported symbols used from outside pkg/workflow (search the whole pkg/ tree for cross-package references). If the exported surface is small and no import cycles would result, perform the move: create pkg/workflow/awf/, relocate the files, update package declarations, and fix all call sites/imports across the repo. If the exported surface is large or import cycles are likely, instead produce a written migration plan added as a comment at the top of pkg/workflow/awf_helpers.go describing the proposed package boundary and blocking issues, without moving any code.

Validate with `go build ./...`, `make fmt`, and `make test-unit` (impacted-first). Do not change any function behavior — this is a structural/organizational task only.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-06	Error Message & Diagnostics Quality	Custom	Y	Found 257 generic error wrappers and 215 bare "invalid" messages lacking guidance, concentrated in pkg/cli
2026-08-07	Code Organization	Standard	N	Identified 15 files >1000 LOC; proposed splits for awf_helpers.go, update_actions.go, audit.go; flagged pkg/workflow/pkg/cli as oversized flat packages

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split pkg/workflow/awf_helpers.go into command-builder, version-gates, and env-helper files — Priority: Medium

Short-term Actions (This Month)

1. Split pkg/cli/update_actions.go into release-resolver and skill-ref-updater files — Priority: Medium
2. Split pkg/cli/audit.go into single-run and multi-run files — Priority: Low

Long-term Actions (This Quarter)

1. Evaluate introducing pkg/workflow/awf sub-package to reduce pkg/workflow's flat file count — Priority: Low

---

📈 Success Metrics

• Files >1000 LOC: 15 → 10 or fewer
• Largest file size: 1,148 LOC → under 700 LOC

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 1 quarter

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-08-08 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · auto · 27.6 AIC · ⌖ 11.1 AIC · ⊞ 9.5K · ◷

• expires on Aug 8, 2026, 5:19 AM UTC-08:00