[Code Quality] Restructure CLI Help Text with Progressive Disclosure

[github-actions]

Description

The compile command (most frequently used) has comprehensive help text but presents a wall of text mixing basic usage with advanced options. This reduces clarity for the 80% use case.

Current Problem

Compile one or more agentic workflows to YAML workflows.

If no workflows are specified, all Markdown files in .github/workflows will be compiled.

The workflow-id is the basename of the Markdown file without the .md extension.

The --dependabot flag generates dependency manifests when dependencies are detected:
  - For npm: Creates package.json and package-lock.json (requires npm in PATH)
  - For Python: Creates requirements.txt for pip packages
...
[Long paragraph continues with mixed basic and advanced info]

User confusion: Basic users overwhelmed by advanced options; advanced users can't quickly find specialized flags

Suggested Solution

Restructure with clear visual sections separating common from advanced usage:

Compile agentic workflow markdown files (.md) into executable GitHub Actions workflows (.lock.yml).

BASIC USAGE:
  gh aw compile              # Compile all workflows in .github/workflows
  gh aw compile my-workflow  # Compile specific workflow (without .md extension)

IMPORTANT: Changes to .md files only take effect after compilation. The .lock.yml files are what GitHub Actions executes.

COMMON OPTIONS:
  -w, --watch               Watch for changes and auto-recompile
  --strict                  Enforce strict mode (action pinning, safe-outputs)
  --validate                Enable schema and security validation
  -j, --json                Output results in JSON format

ADVANCED OPTIONS:
  --dependabot              Generate dependency manifests and Dependabot config
  --trial                   Compile for trial mode (requires --logical-repo)
  --zizmor                  Run zizmor security scanner
  --poutine                 Run poutine security scanner
  --actionlint              Run actionlint linter
  --fix                     Apply automatic codemod fixes before compiling

Files Affected

• pkg/cli/compile_command.go - Restructure Long description

Success Criteria

• Help text restructured with BASIC USAGE, COMMON OPTIONS, ADVANCED OPTIONS sections
• Core workflow emphasized at top
• Important note about .md vs .lock.yml prominently displayed
• Advanced options clearly separated
• Maintain comprehensive examples
• Testing with users confirms improved clarity

Impact

Severity: Medium
Frequency: Affects most-used command
Benefit: Reduced cognitive load, faster learning curve, improved efficiency

Source

Extracted from User Experience Analysis #13053 - Opportunity #2

Priority

High - High-impact, low-effort improvement to most-used command

Estimated Effort

Small (1-2 hours) - Single file change with clear structure

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 15, 2026, 1:20 PM UTC