agentic-workflow-development

# 🛠️ Agentic Workflow Development Skill ## Purpose Development lifecycle guidance for GitHub Agentic Workflows: CLI setup, compilation, testing, debugging, sharing workflows via `add-wizard`, version control, and CI/CD integration. ## When to Use Apply this skill when: - Setting up gh-aw development environment - Creating, testing, and debugging workflows - Sharing workflows via `gh aw add-wizard` - Implementing CI/CD for workflow deployment - Troubleshooting workflow execution issues ## Rules ### CLI Setup and Usage **MUST:** - Install GitHub CLI: `gh --version` to verify - Install gh-aw extension: `gh extension install github/gh-aw` - Keep gh-aw updated: `gh extension upgrade gh-aw` - Initialize repositories: `gh aw init` for new projects - Use CLI for all workflow operations (not manual file editing of `.lock.yml`) **MUST NOT:** - Manually edit `.lock.yml` files - Use outdated gh-aw versions - Skip repository initialization - Bypass CLI for workflow management ### Development Workflow **MUST:** - Create workflow `.md` files in `.github/workflows/` - Use descriptive workflow names (kebab-case) - Compile after every edit: `gh aw compile` - Test workflows before committing: `gh aw run <workflow-name>` - Review compilation output for warnings - Commit both `.md` and `.lock.yml` files together - Write meaningful commit messages **MUST NOT:** - Edit workflows without compiling - Commit `.md` without `.lock.yml` - Skip testing before merge - Use generic commit messages ### Rapid Iteration with Watch Mode **MUST:** - Use `gh aw compile --watch` for active development - Keep watch mode running in dedicated terminal - Review compilation errors immediately - Test changes incrementally - Save frequently to trigger recompilation **MUST NOT:** - Ignore watch mode error messages - Make multiple changes without testing - Disable automatic compilation during development ### Testing Strategies **MUST:** - Test with `workflow_dispatch` trigger first - Use `gh aw run <workflow-name>` for manual testing - Test with real repository data - Verify safe-outputs work as expected - Test error conditions and edge cases - Review GitHub Actions logs after each test run - Test permission boundaries **MUST NOT:** - Test only happy path scenarios - Skip permission testing - Test in production without staging - Ignore test failures ### Debugging Techniques **MUST:** - Use `gh aw logs` to review execution logs - Check GitHub Actions workflow run details - Review compilation output for syntax errors - Add debug logging to workflow instructions - Test workflows in isolation - Use `gh aw status` to check workflow health - Reproduce issues locally when possible **MUST NOT:** - Debug only by editing production workflows - Ignore error messages - Skip log review - Make blind fixes without understanding root cause ### Version Control Practices **MUST:** - Use feature branches for workflow changes - Write descriptive pull request descriptions - Include workflow testing results in PRs - Review workflow changes carefully (both `.md` and `.lock.yml`) - Tag workflow versions for major changes - Maintain changelog for workflow evolution - Document breaking changes **MUST NOT:** - Commit directly to main branch - Merge without review - Skip documentation updates - Delete workflow history ### Code Review for Workflows **MUST:** - Review natural language instructions for clarity - Verify security settings (permissions, tools, network) - Check safe-outputs configuration - Validate trigger appropriateness - Confirm secret usage is correct - Test workflow before approving PR - Verify compilation produces expected `.lock.yml` **MUST NOT:** - Approve without testing - Skip security review - Ignore compilation warnings - Rubber-stamp workflow changes ### Workflow Organization **MUST:** - Group related workflows in subdirectories (if supported) - Use consistent naming conventions - Document workflow purpose in file header - Create README for complex workflow systems - Link related workflows explicitly - Maintain workflow dependency documentation **MUST NOT:** - Create monolithic workflows (split into orchestrator-worker) - Use unclear or cryptic names - Leave workflows undocumented - Create hidden dependencies ### Performance Optimization **MUST:** - Profile workflow execution time - Optimize AI prompts for clarity and brevity - Batch operations when possible - Cache results to avoid redundant work - Use appropriate trigger frequencies - Monitor resource usage and costs **MUST NOT:** - Over-trigger workflows - Create unnecessarily complex instructions - Ignore performance warnings - Skip cost monitoring ### Maintenance and Upgrades **MUST:** - Regularly update gh-aw CLI: `gh extension upgrade gh-aw` - Upgrade workflow dependencies: `gh aw upgrade` - Review and apply workflow template updates - Monitor for deprecated features - Test upgrades in non-production first - Document upgrade procedures - Maintain backward compatibility when possible **MUST NOT:** - Let workflows become outdated - Skip testing after upgrades - Apply breaking changes without notice - Ignore deprecation warnings ## Examples ### Example 1: Complete Development Workflow ```bash # 1. Initialize new repository for agentic workflows cd my-repo gh aw init # 2. Create new workflow file cat > .github/workflows/issue-triage.md << 'EOF' --- on: issues permissions: read-all tools: github: safe-outputs: create-comment: max: 1 --- # Issue Triage Analyze new issues and provide triage information. EOF # 3. Start watch mode for development gh aw compile --watch & # 4. Edit workflow, save, watch auto-compiles # (Make changes to issue-triage.md) # 5. Test workflow manually gh aw run issue-triage # 6. Check logs gh aw logs issue-triage # 7. Commit both files git add .github/workflows/issue-triage.md git add .github/workflows/issue-triage.lock.yml git commit -m "Add issue triage workflow" # 8. Push and create PR git push origin feature/issue-triage gh pr create --title "Add issue triage workflow" \ --body "Implements automated issue triage with AI" ``` ### Example 2: Debugging Workflow Issues ```bash # Check workflow status gh aw status # Review recent logs for specific workflow gh aw logs my-workflow --tail 100 # Check compilation for errors gh aw compile --verbose # Test workflow with debug output gh aw run my-workflow --debug # Check GitHub Actions workflow runs gh run list --workflow=my-workflow.lock.yml # View specific run logs gh run view <run-id> --log # Check for common issues gh aw doctor ``` ### Example 3: Testing Workflow Changes ```bash # Create test branch git checkout -b test/workflow-improvements # Make changes to workflow vim .github/workflows/pr-reviewer.md # Compile and check for errors gh aw compile if [ $? -ne 0 ]; then echo "Compilation failed" exit 1 fi # Test workflow (requires PR or issue depending on trigger) gh aw run pr-reviewer # Wait and check results sleep 30 gh aw logs pr-reviewer --tail 50 # If successful, commit git add .github/workflows/pr-reviewer.md git add .github/workflows/pr-reviewer.lock.yml git commit -m "Improve PR reviewer workflow logic" git push origin test/workflow-improvements ``` ### Example 4: Workflow CI/CD Pipeline ```yaml # .github/workflows/workflow-ci.yml name: Workflow CI on: pull_request: paths: - '.github/workflows/*.md' jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup GitHub CLI run: gh --version - name: Install gh-aw run: gh extension install github/gh-aw - name: Compile workflows run: gh aw compile --check - name: Validate workflow structure run: | for workflow in .github/workflows/*.md; do echo "Validating $workflow" gh aw validate "$workflow" done - name: Check for security issues run: gh aw security-check - name: Verify lock files are up to date run: | gh aw compile if [ -n "$(git status --porcelain .github/workflows/*.lock.yml)" ]; then echo "Lock files out of date. Run: gh aw compile" exit 1 fi ``` ### Example 5: Workflow with Debug Logging ```markdown --- on: workflow_dispatch permissions: read-all tools: github: safe-outputs: create-comment: max: 1 --- # Debug Example Workflow **DEBUG MODE ENABLED** Log all steps for debugging: 1. List repository details - Log: Repository name, owner, default branch 2. Check issue count - Log: Total open issues, closed issues 3. Analyze most recent issue - Log: Issue number, title, author - Log: Label count, comment count 4. Generate report - Include all logged data - Post as comment on issue #1 Use verbose output for all operations. ``` ### Example 6: Workflow Upgrade Process ```bash # Check current gh-aw version gh extension list # Upgrade gh-aw extension gh extension upgrade gh-aw # Check for workflow upgrades gh aw check-updates # Upgrade workflows to latest patterns gh aw upgrade --dry-run # See what would change gh aw upgrade # Apply upgrades # Recompile all workflows gh aw compile # Test critical workflows gh aw run critical-workflow-1 gh aw run critical-workflow-2 # If tests pass, commit git add .github/workflows/ git commit -m "Upgrade workflows to gh-aw v2.0" ``` ### Example 7: Local Development Setup Script ```bash #!/bin/bash # setup-aw-dev.sh - Set up local environment for agentic workflows set -e echo "Setting up Agentic Workflows development environment..." # Install/update GitHub CLI if ! command -v gh &> /dev/null; then echo "Installing GitHub CLI..." # Installation varies by OS brew install gh # macOS fi # Install gh-aw extension echo "Installing gh-aw extension..." gh extension install github/gh-aw || gh extension upgrade gh-aw # Initialize repository echo "Initializing repository..." gh aw init # Set up git hooks for workflow compilation cat > .git/hooks/pre-commit << 'EOF' #!/bin/bash # Pre-commit hook: Compile workflows if git diff --cached --name-only | grep -q ".github/workflows/.*\.md"; then echo "Compiling workflows..." gh aw compile || exit 1 # Stage updated lock files git add .github/workflows/*.lock.yml fi EOF chmod +x .git/hooks/pre-commit echo "Setup complete! Development environment ready." echo "- gh-aw version: $(gh aw version)" echo "- Pre-commit hook installed" ``` ### Example 8: Workflow Testing Framework ```bash #!/bin/bash # test-workflows.sh - Test all workflows set -e echo "Testing all agentic workflows..." WORKFLOWS=$(ls .github/workflows/*.md | xargs -n1 basename -s .md) for workflow in $WORKFLOWS; do echo "Testing: $workflow" # Compile gh aw compile "$workflow" || { echo "❌ Compilation failed: $workflow" exit 1 } # Validate structure gh aw validate "$workflow" || { echo "❌ Validation failed: $workflow" exit 1 } # Security check gh aw security-check "$workflow" || { echo "❌ Security check failed: $workflow" exit 1 } echo "✅ $workflow passed all checks" done echo "All workflows tested successfully!" ``` ## CLI Command Reference ```bash # Setup gh extension install github/gh-aw # Install gh extension upgrade gh-aw # Update gh aw init # Initialize repository # Development gh aw compile # Compile all workflows gh aw compile <name> # Compile specific workflow gh aw compile --watch # Watch mode (auto-recompile) gh aw compile --check # Validate only (CI) # Execution gh aw run <name> # Run workflow manually gh aw run <name> --debug # Run with debug output # Monitoring gh aw logs # All recent logs gh aw logs <name> # Specific workflow logs gh aw logs <name> --tail 100 # Last 100 lines gh aw status # Workflow health # Sharing gh aw add <url> # Add workflow from URL gh aw add-wizard <url> # Add with guided setup # Diagnostics gh aw doctor # Diagnose issues gh aw validate <name> # Validate structure gh aw security-check # Security audit # Upgrades gh aw upgrade # Upgrade workflows gh aw check-updates # Check for updates ``` ## Best Practices Checklist ### Development - [ ] Repository initialized with `gh aw init` - [ ] Watch mode used for active development - [ ] Workflows tested before committing - [ ] Both `.md` and `.lock.yml` committed together - [ ] Meaningful commit messages written ### Testing - [ ] Manual testing with `gh aw run` - [ ] Logs reviewed with `gh aw logs` - [ ] Edge cases tested - [ ] Permission boundaries validated - [ ] Error handling verified ### Security - [ ] Security check passed: `gh aw security-check` - [ ] Minimal permissions configured - [ ] Safe-outputs used for write operations - [ ] Secrets properly configured - [ ] Network access restricted ### Collaboration - [ ] Feature branch workflow used - [ ] Pull requests reviewed by team - [ ] Documentation updated - [ ] Breaking changes documented - [ ] Changelog maintained ### Maintenance - [ ] gh-aw CLI kept up to date - [ ] Workflows upgraded regularly - [ ] Performance monitored - [ ] Costs tracked - [ ] Deprecated features replaced ## Troubleshooting Guide ### Compilation Errors **Symptom**: `gh aw compile` fails **Solutions**: - Check YAML frontmatter syntax - Verify all required fields present - Review error message carefully - Check for unclosed quotes or brackets - Validate indentation ### Workflow Won't Trigger **Symptom**: Workflow doesn't run on expected events **Solutions**: - Verify `.lock.yml` is committed - Check trigger configuration in frontmatter - Review GitHub Actions logs - Ensure workflow name is correct - Check repository workflow permissions ### Permission Denied Errors **Symptom**: Workflow fails with permission errors **Solutions**: - Review `permissions:` in frontmatter - Check if safe-outputs needed - Verify secrets configured correctly - Ensure token has required scopes - Check repository Actions permissions ### Slow or Hanging Workflows **Symptom**: Workflows take too long or never complete **Solutions**: - Add explicit timeouts - Simplify workflow instructions - Check for infinite loops - Review tool usage (disable unused tools) - Monitor GitHub Actions queue ### Unexpected AI Behavior **Symptom**: AI doesn't follow instructions **Solutions**: - Make instructions more specific - Add examples to workflow - Break complex tasks into steps - Use imperative language - Consider different engine ## Related ISMS Policies This skill aligns with: - **[Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)** - Secure development lifecycle - **[Change Management Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Change_Management_Policy.md)** - Workflow change management - **[Information Security Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Information_Security_Policy.md)** - Overall security framework ## Related Skills - **[GitHub Agentic Workflows](../github-agentic-workflows/SKILL.md)** - Core workflow fundamentals - **[Agentic Workflow Security](../agentic-workflow-security/SKILL.md)** - Security best practices