diff --git a/cmd/gh-aw/main.go b/cmd/gh-aw/main.go index e8576e3307d..66da3c83643 100644 --- a/cmd/gh-aw/main.go +++ b/cmd/gh-aw/main.go @@ -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`, RunE: func(cmd *cobra.Command, args []string) error { engineOverride, _ := cmd.Flags().GetString("engine") actionMode, _ := cmd.Flags().GetString("action-mode") diff --git a/pkg/cli/add_command.go b/pkg/cli/add_command.go index 04f1f0c925d..6254cabf7a4 100644 --- a/pkg/cli/add_command.go +++ b/pkg/cli/add_command.go @@ -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 + + # 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) diff --git a/pkg/cli/fix_command.go b/pkg/cli/fix_command.go index 274447bfd3c..db4e7d137ac 100644 --- a/pkg/cli/fix_command.go +++ b/pkg/cli/fix_command.go @@ -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`, RunE: func(cmd *cobra.Command, args []string) error { listCodemods, _ := cmd.Flags().GetBool("list-codemods") write, _ := cmd.Flags().GetBool("write") diff --git a/pkg/cli/trial_command.go b/pkg/cli/trial_command.go index 9af4af65677..4e00f8fca5a 100644 --- a/pkg/cli/trial_command.go +++ b/pkg/cli/trial_command.go @@ -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 + + # 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) @@ -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 diff --git a/pkg/cli/update_command.go b/pkg/cli/update_command.go index a46d3382333..374000aea22 100644 --- a/pkg/cli/update_command.go +++ b/pkg/cli/update_command.go @@ -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 + +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")