Skip to content

Add workflow guidance and cross-references to CLI help text #14268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 2 commits into from
Closed

Add workflow guidance and cross-references to CLI help text #14268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
147f039
Initial plan
Copilot Feb 7, 2026
0cc0234
Add Common Workflows and cross-references to CLI help text
Copilot Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion cmd/gh-aw/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,30 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` compile --watch ci-doctor # Watch and auto-compile
` + string(constants.CLIExtensionPrefix) + ` compile --trial --logical-repo owner/repo # Compile for trial mode
` + string(constants.CLIExtensionPrefix) + ` compile --dependabot # Generate Dependabot manifests
` + string(constants.CLIExtensionPrefix) + ` compile --dependabot --force # Force overwrite existing dependabot.yml`,
` + string(constants.CLIExtensionPrefix) + ` compile --dependabot --force # Force overwrite existing dependabot.yml

Common Workflows:
# Check for errors before compiling
` + string(constants.CLIExtensionPrefix) + ` fix # Dry-run to check for deprecated fields
` + string(constants.CLIExtensionPrefix) + ` fix --write # Fix issues automatically

# Compile and validate a new workflow
` + string(constants.CLIExtensionPrefix) + ` compile my-workflow
` + string(constants.CLIExtensionPrefix) + ` compile my-workflow --validate # With schema validation

# If compilation fails, debug with hash command
` + string(constants.CLIExtensionPrefix) + ` hash my-workflow # Check frontmatter rendering

# After deployment, monitor execution
` + string(constants.CLIExtensionPrefix) + ` run my-workflow # Test run the workflow
` + string(constants.CLIExtensionPrefix) + ` logs my-workflow # Check recent execution logs
` + string(constants.CLIExtensionPrefix) + ` health my-workflow # View success rates

Related Commands:
` + string(constants.CLIExtensionPrefix) + ` fix Apply automatic fixes before compiling
` + string(constants.CLIExtensionPrefix) + ` hash Debug frontmatter and expression issues
` + string(constants.CLIExtensionPrefix) + ` logs View workflow execution logs after running
` + string(constants.CLIExtensionPrefix) + ` health Check workflow success rates and trends`,
Comment on lines +210 to +222
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The help text references gh aw hash, but the actual command name is hash-frontmatter (see pkg/cli/hash_command.go). Also, hash-frontmatter expects a workflow file path (e.g., my-workflow.md), not a workflow id. Update the example and the related-commands entry accordingly.

Copilot uses AI. Check for mistakes.
RunE: func(cmd *cobra.Command, args []string) error {
engineOverride, _ := cmd.Flags().GetString("engine")
actionMode, _ := cmd.Flags().GetString("action-mode")
Expand Down
22 changes: 22 additions & 0 deletions pkg/cli/add_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,28 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/*@v1.0.0
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --dir shared # Add to .github/workflows/shared/

Common Workflows:
# Add and immediately run a workflow
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/daily-plan
` + string(constants.CLIExtensionPrefix) + ` run daily-plan # Test the workflow

# Add workflow and create PR for review
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --pr
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example uses --pr, but the add command intentionally hides --pr from help output (MarkHidden("pr")). To avoid advertising a hidden/back-compat flag, use the documented flag name (--create-pull-request) in the workflow example instead.

Suggested change
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --pr
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --create-pull-request

Copilot uses AI. Check for mistakes.

# Add multiple workflows from a repository
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics # List available workflows
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/* # Add all workflows

# Keep workflows up-to-date
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/my-workflow
` + string(constants.CLIExtensionPrefix) + ` update my-workflow # Update to latest version

Related Commands:
` + string(constants.CLIExtensionPrefix) + ` update Keep workflows current with source repositories
` + string(constants.CLIExtensionPrefix) + ` compile Compile workflows after adding
` + string(constants.CLIExtensionPrefix) + ` run Test newly added workflows
` + string(constants.CLIExtensionPrefix) + ` status View all installed workflows

Workflow specifications:
- Two parts: "owner/repo[@version]" (lists available workflows in the repository)
- Three parts: "owner/repo/workflow-name[@version]" (implicitly looks in workflows/ directory)
Expand Down
23 changes: 22 additions & 1 deletion pkg/cli/fix_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,28 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` fix my-workflow # Check specific workflow
` + string(constants.CLIExtensionPrefix) + ` fix my-workflow --write # Fix specific workflow
` + string(constants.CLIExtensionPrefix) + ` fix --dir custom/workflows # Fix workflows in custom directory
` + string(constants.CLIExtensionPrefix) + ` fix --list-codemods # List available codemods`,
` + string(constants.CLIExtensionPrefix) + ` fix --list-codemods # List available codemods

Common Workflows:
# Check for issues before compiling
` + string(constants.CLIExtensionPrefix) + ` fix # Dry-run to see what needs fixing
` + string(constants.CLIExtensionPrefix) + ` fix --write # Apply all fixes

# Fix and compile workflow
` + string(constants.CLIExtensionPrefix) + ` fix my-workflow --write
` + string(constants.CLIExtensionPrefix) + ` compile my-workflow # Recompile after fixing

# Quick fix-compile-test cycle
` + string(constants.CLIExtensionPrefix) + ` compile --fix my-workflow # Fix and compile in one step
` + string(constants.CLIExtensionPrefix) + ` run my-workflow # Test the fixed workflow

# Discover available fixes
` + string(constants.CLIExtensionPrefix) + ` fix --list-codemods # See all available codemods

Related Commands:
` + string(constants.CLIExtensionPrefix) + ` compile Use --fix flag for automatic fixing before compile
` + string(constants.CLIExtensionPrefix) + ` update Automatically applies fixes after updating workflows
` + string(constants.CLIExtensionPrefix) + ` hash Debug frontmatter issues after fixing`,
Comment on lines +90 to +92
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hash is not an actual CLI command here; the command is hash-frontmatter, and it expects a workflow file path. Update this related-command reference so it matches the real command users can run.

Suggested change
` + string(constants.CLIExtensionPrefix) + ` compile Use --fix flag for automatic fixing before compile
` + string(constants.CLIExtensionPrefix) + ` update Automatically applies fixes after updating workflows
` + string(constants.CLIExtensionPrefix) + ` hash Debug frontmatter issues after fixing`,
` + string(constants.CLIExtensionPrefix) + ` compile Use --fix flag for automatic fixing before compile
` + string(constants.CLIExtensionPrefix) + ` update Automatically applies fixes after updating workflows
` + string(constants.CLIExtensionPrefix) + ` hash-frontmatter my-workflow.yml Debug frontmatter issues after fixing`,

Copilot uses AI. Check for mistakes.
RunE: func(cmd *cobra.Command, args []string) error {
listCodemods, _ := cmd.Flags().GetBool("list-codemods")
write, _ := cmd.Flags().GetBool("write")
Expand Down
24 changes: 23 additions & 1 deletion pkg/cli/trial_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,23 @@ Advanced examples:
` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --host-repo . # Use current repo as host
` + string(constants.CLIExtensionPrefix) + ` trial ./local-workflow.md --clone-repo upstream/repo --repeat 2

Common Workflows:
# Quick trial of a new workflow
` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow
` + string(constants.CLIExtensionPrefix) + ` logs --trial # View trial results

Comment on lines +107 to +111
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The help text uses gh aw logs --trial, but the logs command does not define a --trial flag. Update these workflow examples to use a valid invocation (e.g., gh aw logs --repo <trial-host-repo> <workflow> or direct users to gh aw audit <run-id> based on what trial outputs).

This issue also appears in the following locations of the same file:

  • line 116
  • line 120

Copilot uses AI. Check for mistakes.
# Test workflow before adding to production
` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --logical-repo myorg/myrepo
` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/my-workflow # Add after successful trial

# Compare multiple workflow versions
` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/workflow@v1.0 githubnext/agentics/workflow@v2.0
` + string(constants.CLIExtensionPrefix) + ` logs --trial # Compare results

# Debug workflow issues in isolation
` + string(constants.CLIExtensionPrefix) + ` trial ./my-workflow.md --clone-repo myorg/myrepo --repeat 3
` + string(constants.CLIExtensionPrefix) + ` logs --trial # Analyze trial logs

Repository modes:
- Default mode (no flags): Creates a temporary trial repository and simulates execution as if running against the current repository (github.repository context points to current repo)
- --logical-repo REPO: Simulates execution against a specified repository (github.repository context points to REPO while actually running in a temporary trial repository)
Expand All @@ -112,7 +129,12 @@ Repository modes:

All workflows must support workflow_dispatch trigger to be used in trial mode.
The host repository will be created as private and kept by default unless --delete-host-repo-after is specified.
Trial results are saved both locally (in trials/ directory) and in the host repository for future reference.`,
Trial results are saved both locally (in trials/ directory) and in the host repository for future reference.

Related Commands:
` + string(constants.CLIExtensionPrefix) + ` logs View trial execution logs and outputs
` + string(constants.CLIExtensionPrefix) + ` add Add workflow to production after successful trial
` + string(constants.CLIExtensionPrefix) + ` audit Debug workflow execution with detailed analysis`,
Args: cobra.MinimumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
workflowSpecs := args
Expand Down
24 changes: 23 additions & 1 deletion pkg/cli/update_command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,29 @@ Examples:
` + string(constants.CLIExtensionPrefix) + ` update --force # Force update even if no changes
` + string(constants.CLIExtensionPrefix) + ` update --dir custom/workflows # Update workflows in custom directory
` + string(constants.CLIExtensionPrefix) + ` update --audit # Check dependency health without updating
` + string(constants.CLIExtensionPrefix) + ` update --dry-run # Show what would be updated without making changes`,
` + string(constants.CLIExtensionPrefix) + ` update --dry-run # Show what would be updated without making changes

Comment on lines 62 to +64
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The help text suggests using --dry-run, but the command currently returns an error (--dry-run mode not yet implemented for workflow updates). This is misleading for users; either remove the --dry-run example/mention from help text for now, or implement --dry-run behavior before advertising it.

Copilot uses AI. Check for mistakes.
Common Workflows:
# Regular update and sync workflow
` + string(constants.CLIExtensionPrefix) + ` update # Update all workflows and actions
` + string(constants.CLIExtensionPrefix) + ` compile # Recompile after updates

# Update with PR for review
` + string(constants.CLIExtensionPrefix) + ` update --pr # Create PR with all updates

# Check for updates without applying
` + string(constants.CLIExtensionPrefix) + ` update --audit # View dependency health report

# Update and test specific workflow
` + string(constants.CLIExtensionPrefix) + ` update my-workflow
` + string(constants.CLIExtensionPrefix) + ` compile my-workflow
` + string(constants.CLIExtensionPrefix) + ` run my-workflow # Test the updated workflow

Related Commands:
` + string(constants.CLIExtensionPrefix) + ` compile Recompile workflows after updating
` + string(constants.CLIExtensionPrefix) + ` fix Apply automatic fixes to updated workflows
` + string(constants.CLIExtensionPrefix) + ` logs Check workflow logs after updating
` + string(constants.CLIExtensionPrefix) + ` health Monitor workflow health post-update`,
RunE: func(cmd *cobra.Command, args []string) error {
majorFlag, _ := cmd.Flags().GetBool("major")
forceFlag, _ := cmd.Flags().GetBool("force")
Expand Down
Loading