[cli-consistency] Inconsistent terminology: workflow-id vs workflow-file in command arguments

[github-actions]

Issue Description

Type: Terminology inconsistency
Priority: Low
Area: CLI command argument naming

Current Behavior

Commands use inconsistent terminology for workflow arguments:

Commands using workflow-id:

• gh aw enable [workflow-id]...
• gh aw disable [workflow-id]...
• gh aw run (workflow-id)...
• gh aw logs [workflow-id]
• gh aw update [workflow-id]...

Commands using workflow-file:

• gh aw mcp add [workflow-file] [mcp-server-name]
• gh aw mcp inspect [workflow-file]
• gh aw mcp list [workflow-file]
• gh aw mcp list-tools (mcp_server) [workflow-file]

Analysis

The inconsistency creates confusion about what users should provide:

1. workflow-id: Suggests the basename without .md extension (e.g., ci-doctor)
2. workflow-file: Suggests a file path (e.g., ci-doctor.md or .github/workflows/ci-doctor.md)

According to the root command's Long description:

Note: A workflow-id is the basename of the markdown file without the .md extension.
For example, for 'weekly-research.md', the workflow-id is 'weekly-research'.

Recommendation

Option 1 (Preferred): Standardize on workflow-id everywhere

• Use [workflow-id] for all commands that accept workflow identifiers
• Update MCP commands to use workflow-id instead of workflow-file
• This aligns with the documentation and is more concise

Option 2: Clarify when to use each term

• Use workflow-file when the command accepts file paths
• Use workflow-id when the command only accepts basenames
• Add clear documentation explaining the distinction

Suggested Changes

If choosing Option 1, update these command definitions in pkg/cli/mcp*.go:

// Before:
Use: "add [workflow-file] [mcp-server-name]"

// After:
Use: "add [workflow-id] [mcp-server-name]"

And similarly for inspect, list, and list-tools commands.

Impact

• Low user impact: Commands currently work with both formats in practice
• Documentation clarity: Would improve consistency in help text and documentation
• Learning curve: Makes it easier for users to understand the expected input format

Additional Context

The term "workflow-id" is well-established in the CLI:

• Documented in root command help
• Used by most major commands
• Matches the conceptual model (identifier vs file path)

AI generated by CLI Consistency Checker

[pelikhan]

Use workflow-id-or-file everywhere and make sure the commands resolve the workflow from the id/file using the same helper.