Fix CLI help text consistency: codemods list, --repeat semantics, disable behavior, project new formatting

[Copilot]

Five CLI help text inconsistencies identified by automated inspection: outdated hardcoded codemod list in fix, ambiguous --repeat semantics in run/trial, mismatch between disable short/long descriptions, and mixed whitespace in project new.

Changes

• fix command: Replaced stale hardcoded list of 8 codemods (out of ~25 registered) with a reference to --list-codemods, which dynamically reflects the actual registry
• --repeat flag (run + trial): Clarified that the value is additional runs, not total — --repeat 3 executes 4 times (1 initial + 3 repeats). Updated both the flag description and the inline example comments which incorrectly said "Run 3 times total"
• disable Long description: Added cancellation note ("Any in-progress runs will be cancelled before disabling") to match the Short description, which already advertised this behavior
• project new Long description: Normalized indentation in the "Project Setup:" bullet list from mixed tabs/spaces to consistent spaces

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] CLI Consistency Issues - 2026-03-02</issue_title>
<issue_description>### Summary

Automated CLI consistency inspection found 5 inconsistencies across command help text that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 1 (Outdated information breaks user expectations)
• Medium: 3 (Inconsistent terminology or missing behavior descriptions)
• Low: 1 (Minor omission)

Inspection Details

• Total Commands Inspected: 30 (--help run for every command and subcommand)
• Commands with Issues: 5
• Date: 2026-03-02
• Method: Executed all CLI commands with --help flags, ran --list-codemods, and compared with documentation in docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Global flags consistency (-v, -h, --banner present everywhere)
• Flag naming conventions (consistent across similar commands)
• Example formatting and accuracy
• Documentation URLs (confirmed github.github.com is the intentional docs domain per astro.config.mjs)
• mcp, pr, secrets, project subcommand structures
• add, compile, run, logs, audit, status, health, update, upgrade core commands

⚠️ Issues found:

• fix help has severely outdated hardcoded codemod list
• --repeat flag description is ambiguous in run and trial
• disable summary description and detailed help disagree on behavior
• project new help has mixed whitespace formatting

Detailed Findings

1. fix --help "Available codemods" section is severely outdated

Commands Affected: fix
Priority: High
Type: Outdated information

Current Output (from ./gh-aw fix --help):

Available codemods:
  • timeout-minutes-migration: Replaces 'timeout_minutes' with 'timeout-minutes'
  • network-firewall-migration: Removes deprecated 'network.firewall' field
  • sandbox-false-to-agent-false: Converts 'sandbox: false' to 'sandbox.agent: false'
  • safe-inputs-mode-removal: Removes deprecated 'safe-inputs.mode' field
  • schedule-at-to-around-migration: Converts 'daily at TIME' to 'daily around TIME'
  • delete-schema-file: Deletes deprecated .github/aw/schemas/agentic-workflow.json
  • delete-old-agents: Deletes old workflow-specific .agent.md files from .github/agents/
  • delete-old-templates: Removes old template files from pkg/cli/templates/
```

**Issue**: The hardcoded list in help text lists only 8 codemods, but `./gh-aw fix --list-codemods` shows **24 codemods**. Additionally, two entries in the help text (`delete-old-agents`, `delete-old-templates`) do not appear in the actual codemod registry at all — they were apparently removed but the help text was never updated. Missing from help text (among others): `command-to-slash-command-migration`, `expires-integer-to-string`, `serena-local-to-docker`, `roles-to-on-roles`, `bots-to-on-bots`, `playwright-allowed-domains-migration`, and 16 more.

**Source**: `pkg/cli/fix_command.go` lines 41–49

**Suggested Fix**: Remove the hardcoded "Available codemods" section from the `Long` help text in `fix_command.go` entirely, and replace it with a pointer to `--list-codemods`:

```
This command applies a registry of codemods that automatically update deprecated fields
and migrate to new syntax. Codemods preserve formatting and comments as much as possible.

Use --list-codemods to see all available codemods with descriptions.
```

---

#### 2. `--repeat` flag description is ambiguous (run, trial)

**Commands Affected**: `run`, `trial`
**Priority**: Medium
**Type**: Inconsistent/ambiguous description

**Current Output** (from `./gh-aw run --help` and `./gh-aw trial --help`):
```
      --repeat int              Number of times to repeat running workflows (0 = run once)
```

**With example**:
```
gh aw run daily-perf-improver --repeat 3  # Run 3 times total

Issue: The flag name repeat and phrase "Number of times to repeat" implies additional runs after the first (so --repeat 3 = run once + 3 repeats = 4 total). However, the example --repeat 3 # Run 3 times total indicates it means total count (3 total). The parenthetical (0 = run once) further suggests the default=0 maps to 1 total run, compounding the confusion for new users.

Suggested Fix: Clarify the description to remove ambiguity:

cmd.Flags().Int("repeat", 0, "Total number of times to run the workflow (default: 1 when set to 0)")
```

Or keep the current semantics but update the example comment:
```
gh aw run daily-perf-improver --repeat 3  # Run a total of 3 times
```

And update `trial_command.go:97` similarly.

---

#### 3. `disable` summary description mentions behavior not in detailed help

**Commands Affected**: `disable`
**Priority**: Medium
**Type**: Inconsistency between summary and detailed h...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes github/gh-aw#19222

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

[Copilot]

Pull request overview

This PR fixes 5 CLI help text consistency issues identified by automated inspection, addressing problems with outdated information, ambiguous descriptions, behavioral inconsistencies, and formatting irregularities.

Changes:

• Replaced the stale hardcoded codemod list in fix help with a pointer to --list-codemods
• Clarified --repeat flag semantics in both run (main.go) and trial commands — the value is additional runs, so --repeat 3 results in 4 total executions
• Added the cancellation behavior note to the disable command's long description to match its short description
• Normalized indentation in project new long description from mixed tabs/spaces to consistent 2-space indentation

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
pkg/cli/fix_command.go	Removes hardcoded (outdated) codemod list and replaces it with a --list-codemods pointer
pkg/cli/trial_command.go	Updates --repeat flag description and example comment to clarify "additional runs" semantics
pkg/cli/project_command.go	Normalizes indentation in "Project Setup:" block from tabs to 2-space indentation
cmd/gh-aw/main.go	Adds cancellation note to disable Long description; updates run --repeat flag description and example comment

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The "Any in-progress runs will be cancelled before disabling." line is immediately followed by the WorkflowIDExplanation block with no blank line separator. Comparing with the enableCmd Long description (which has a blank line before WorkflowIDExplanation), and other commands like fix, health, logs, and validate (all of which wrap WorkflowIDExplanation with blank lines on both sides), the disableCmd description is missing a blank line between the cancellation note and the workflow ID explanation. This inconsistency will cause the two sections to visually run together in the help output.

Suggested change

	Any in-progress runs will be cancelled before disabling.
	Any in-progress runs will be cancelled before disabling.