agentic-workflow-development

name	agentic-workflow-development
description	gh-aw CLI usage, compilation, testing, debugging, add-wizard, and CI/CD practices for GitHub Agentic Workflows
license	Apache-2.0

🛠️ 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

# 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

# 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

# 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

# .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

---
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

# 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

#!/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

#!/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

# 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 - Secure development lifecycle
• Change Management Policy - Workflow change management
• Information Security Policy - Overall security framework

Related Skills

• GitHub Agentic Workflows - Core workflow fundamentals
• Agentic Workflow Security - Security best practices
• Agentic Workflow Orchestration - Multi-workflow coordination
• GitHub Actions CI/CD - CI/CD integration
• Testing Strategy - Testing approaches

Related Documentation

• gh-aw Quick Start
• Creating Workflows
• gh-aw CLI Reference
• GitHub CLI Documentation

Compliance Mapping

ISO 27001:2022

• A.8.25 Secure development life cycle
• A.8.32 Change management
• A.5.37 Documented operating procedures

NIST Cybersecurity Framework 2.0

• PR.IP-02: System development lifecycle
• PR.MA-01: Maintenance is performed
• DE.CM-08: Vulnerability scans are performed

CIS Controls v8.1

• Control 16: Application Software Security
  • 16.1 Secure Application Development Process
  • 16.3 Maintain Separate Development Environments

Enforcement

Development practice violations:

• Critical: Committing without compilation, exposed secrets - Block deployment
• High: Missing tests, no code review - Require remediation
• Medium: Incomplete documentation, style issues - Create improvement tickets
• Low: Minor optimization opportunities - Optional improvements

Version History

• 2026-04-02: Updated with add-wizard sharing, latest CLI commands, and Agent Factory learnings
• 2026-02-11: Initial skill creation