1. Inconsistent description for mcp add within gh aw mcp --help

Command Affected: gh aw mcp
Priority: Medium
Type: Inconsistent terminology

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

Available subcommands:
  • list       - List MCP servers defined in agentic workflows
  • list-tools - List available tools for a specific MCP server
  • inspect    - Inspect MCP servers and list available tools, resources, and roots
  • add        - Add an MCP tool to an agentic workflow    ← says "tool"

...

Available Commands:
  add        Add an MCP server to an agentic workflow    ← says "server"

Issue: Within the same --help output, the add subcommand is described as "Add an MCP tool" in the bullet list but "Add an MCP server" in the Cobra-generated command table. An MCP server and an MCP tool are different concepts. The correct term is server (which is what mcp add actually adds), as confirmed by ./gh-aw mcp add --help which says Add an MCP server to an agentic workflow.

Source: pkg/cli/mcp.go line 26 uses "tool"; pkg/cli/mcp_add.go uses "server".

Suggested Fix: Change the bullet in pkg/cli/mcp.go from:

• add        - Add an MCP tool to an agentic workflow

to:

• add        - Add an MCP server to an agentic workflow

2. Argument ordering inconsistency between mcp list-tools and mcp inspect

Commands Affected: gh aw mcp list-tools, gh aw mcp inspect
Priority: Medium
Type: Inconsistent UX pattern

mcp list-tools current output (from ./gh-aw mcp list-tools --help):

Usage:
  gh aw mcp list-tools <server> [workflow] [flags]

Examples:
  gh aw mcp list-tools github                    # Find workflows with 'github' MCP server
  gh aw mcp list-tools github weekly-research    # List tools for 'github' server in weekly-research.md

mcp inspect current output (from ./gh-aw mcp inspect --help):

Usage:
  gh aw mcp inspect [workflow] [flags]

Examples:
  gh aw mcp inspect weekly-research                              # Inspect all servers
  gh aw mcp inspect daily-news --server tavily                   # Inspect only the tavily server

Issue: The two related commands use inconsistent patterns for specifying the server:

• list-tools uses <server> as a required positional argument, with [workflow] as optional second argument
• inspect uses [workflow] as the first positional argument, with --server as an optional flag

This forces users to remember two different argument orderings for related commands. Users coming from mcp inspect would naturally try gh aw mcp list-tools weekly-research github (workflow first) but the correct invocation is gh aw mcp list-tools github weekly-research (server first).

Suggested Fix: Either:

• Add --server flag to mcp list-tools and deprecate the positional <server> argument to match mcp inspect's pattern
• Or update both commands to use the same argument ordering convention

3. Inconsistent wording in gh aw logs cache eviction examples

Command Affected: gh aw logs
Priority: Low
Type: Minor wording inconsistency

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

  # Cache maintenance
  gh aw logs --after -1w                # Delete cached run folders older than 1 week
  gh aw logs --after -30d               # Delete cached run folders older than 30 days
  gh aw logs --after -1mo               # Delete cached run folders older than 1 month
  gh aw logs --after 2024-01-01         # Delete cached run folders from before 2024-01-01

Issue: The first three comments use "older than" (e.g., "older than 1 week") but the absolute date comment uses "from before" (e.g., "from before 2024-01-01"). These phrases describe the same concept but with different wording.

Suggested Fix: Use consistent phrasing throughout:

  gh aw logs --after -1w                # Delete cached run folders older than 1 week
  gh aw logs --after -30d               # Delete cached run folders older than 30 days
  gh aw logs --after -1mo               # Delete cached run folders older than 1 month
  gh aw logs --after 2024-01-01         # Delete cached run folders older than 2024-01-01

4. gh aw init --codespaces flag shows Cobra implementation detail

Command Affected: gh aw init
Priority: Low
Type: Implementation detail exposed in UX

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

      --codespaces string[=" "]   Create devcontainer.json for GitHub Codespaces...

Issue: The string[=" "] in the flag type shows Cobra's internal representation for an optional string flag with a space character (" ") as the default sentinel value. This is an implementation detail that may confuse users who see string[=" "] in the help output instead of something more intuitive.

Suggested Fix: This is a known Cobra limitation for optional string flags. Consider either:

• Documenting in the flag description that the flag can be used with or without a value
• Wrapping the flag description to be clearer about its optional-value nature