fix(cli): standardize --help flag descriptions and "agentic workflow" terminology (#20375)

Author: Copilot

cmd/gh-aw/help_flag_test.go

@@ -0,0 +1,33 @@
+//go:build !integration
+
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestHelpFlagConsistency verifies that all commands have consistent --help flag
+// descriptions starting with "Show help for gh aw" (matching the root command).
+func TestHelpFlagConsistency(t *testing.T) {
+	var checkCmd func(cmd *cobra.Command)
+	checkCmd = func(cmd *cobra.Command) {
+		t.Run("command "+cmd.CommandPath()+" has consistent help flag", func(t *testing.T) {
+			cmd.InitDefaultHelpFlag()
+			f := cmd.Flags().Lookup("help")
+			if f == nil {
+				t.Skip("Command has no help flag")
+			}
+			want := "Show help for gh aw"
+			if !strings.HasPrefix(f.Usage, want) {
+				t.Errorf("Command %q help flag Usage = %q, want prefix %q", cmd.CommandPath(), f.Usage, want)
+			}
+		})
+		for _, sub := range cmd.Commands() {
+			checkCmd(sub)
+		}
+	}
+	checkCmd(rootCmd)
+}

cmd/gh-aw/main.go

@@ -103,8 +103,8 @@ For detailed help on any command, use:
 
 var newCmd = &cobra.Command{
 	Use:   "new [workflow]",
-	Short: "Create a new workflow Markdown file with example configuration",
-	Long: `Create a new workflow Markdown file with commented examples and explanations of all available options.
+	Short: "Create a new agentic workflow file with example configuration",
+	Long: `Create a new agentic workflow file with commented examples and explanations of all available options.
 
 When called without a workflow name (or with --interactive flag), launches an interactive wizard
 to guide you through creating a workflow with custom settings.
@@ -162,7 +162,7 @@ Examples:
 var removeCmd = &cobra.Command{
 	Use:   "remove [pattern]",
 	Short: "Remove agentic workflow files matching the given name prefix",
-	Long: `Remove workflow files matching the given workflow-id pattern.
+	Long: `Remove agentic workflow files matching the given workflow-id pattern.
 
 The workflow-id is the basename of the Markdown file without the .md extension.
 You can provide a workflow-id prefix to remove multiple workflows, or a specific workflow-id.
@@ -224,7 +224,7 @@ Examples:
 
 var compileCmd = &cobra.Command{
 	Use:   "compile [workflow]...",
-	Short: "Compile workflow Markdown files (.md) into GitHub Actions workflows (.lock.yml)",
+	Short: "Compile agentic workflow files (.md) into GitHub Actions workflows (.lock.yml)",
 	Long: `Compile one or more agentic workflows to YAML workflows.
 
 If no workflows are specified, all Markdown files in .github/workflows will be compiled.
@@ -790,6 +790,30 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	rootCmd.AddCommand(completionCmd)
 	rootCmd.AddCommand(hashCmd)
 	rootCmd.AddCommand(projectCmd)
+
+	// Fix help flag descriptions for all subcommands to be consistent with the
+	// root command ("Show help for gh aw" vs the Cobra default "help for [cmd]").
+	var fixSubCmdHelpFlags func(cmd *cobra.Command)
+	fixSubCmdHelpFlags = func(cmd *cobra.Command) {
+		cmd.InitDefaultHelpFlag()
+		if f := cmd.Flags().Lookup("help"); f != nil {
+			cmdPath := cmd.CommandPath()
+			// CommandPath() uses Name() which returns the first word of Use
+			// ("gh" from "gh aw"), so subcommand paths look like "gh compile".
+			// Replace the leading "gh " prefix with "gh aw " to match the root
+			// command's display name.
+			if strings.HasPrefix(cmdPath, "gh ") && !strings.HasPrefix(cmdPath, "gh aw") {
+				cmdPath = "gh aw " + cmdPath[3:]
+			}
+			f.Usage = "Show help for " + cmdPath
+		}
+		for _, sub := range cmd.Commands() {
+			fixSubCmdHelpFlags(sub)
+		}
+	}
+	for _, sub := range rootCmd.Commands() {
+		fixSubCmdHelpFlags(sub)
+	}
 }
 
 func main() {

pkg/cli/add_command.go

@@ -48,7 +48,7 @@ func NewAddCommand(validateEngine func(string) error) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "add <workflow>...",
 		Short: "Add agentic workflows from repositories to .github/workflows",
-		Long: `Add one or more workflows from repositories to .github/workflows.
+		Long: `Add one or more agentic workflows from repositories to .github/workflows.
 
 This command adds workflows directly without interactive prompts. Use 'add-wizard'
 for a guided setup that configures secrets, creates a pull request, and more.

pkg/cli/fix_command.go

@@ -33,7 +33,7 @@ func NewFixCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "fix [workflow]...",
 		Short: "Apply automatic codemod-style fixes to agentic workflow files",
-		Long: `Apply automatic codemod-style fixes to agentic workflow Markdown files.
+		Long: `Apply automatic codemod-style fixes to agentic workflow files.
 
 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.