.github/workflows/README-AGENTS.md

Multi-Agent Workflow System

Overview

This directory contains 4 GitHub Actions workflows implementing a multi-agent development cascade:

• Block 4: DatabaseMaster (50 points)
• Block 5: QASpecialist (32 points)
• Block 6: SecurityCompliance (28 points)
• HansPedder Orchestrator

Workflow Cascade

Block 3 (APISpecialist)
    |
    v
Block 4 (DatabaseMaster) - 50 points
    |
    v
Block 5 (QASpecialist) - 32 points
    |
    v
Block 6 (SecurityCompliance) - 28 points
    |
    v
HansPedder Orchestrator -> Auto-merge

Trigger Chain

• Block 4: Triggered by Block 3 completion OR manual dispatch
• Block 5: Triggered by Block 4 completion OR manual dispatch
• Block 6: Triggered by Block 5 completion OR manual dispatch
• Orchestrator: Triggered by PR open/sync, every 15 mins, OR manual dispatch

Key Features

Agent Workflows

• NO emoji characters in step names (GitHub Actions compatible)
• Proper conditional execution: if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
• Structured commit messages with Agent, Block, and Points fields
• PR creation with parseable body format
• Realistic implementations (models, tests, security configs)
• 8-10 steps per workflow

HansPedder Orchestrator

• Discovers all agent PRs automatically
• Validates PR format and extracts metadata
• Auto-approves PRs with proper format
• Auto-merges approved PRs (squash merge)
• Updates kanban board with comments
• Generates validation and merge reports
• Runs every 15 minutes via cron

Block Implementations

Block 4: DatabaseMaster (50 points)

Creates:

• Sequelize User and Widget models
• PostgreSQL migration scripts
• Database configuration for all environments
• Demo seed data
• Directory: database/models/, database/migrations/, database/seeds/

Block 5: QASpecialist (32 points)

Creates:

• Jest configuration with 80% coverage threshold
• Database test helpers
• API test helpers with authentication
• Unit tests for models
• Integration tests for APIs
• E2E tests with Playwright
• Directory: tests/unit/, tests/integration/, tests/e2e/

Block 6: SecurityCompliance (28 points)

Creates:

• SECURITY.md policy
• CodeQL scanning workflow
• Dependency scanning workflow
• Security headers middleware (Helmet)
• Rate limiting middleware
• Input validation and sanitization
• CSRF protection
• Security audit scripts
• Directory: security/policies/, security/scans/, .github/workflows/security/

Orchestrator Logic

PR Discovery

gh pr list --state open --json number,title,body,author,headRefName
# Filter for PRs containing "Agent:" in body

PR Validation

Extracts and validates:

• Agent name (required)
• Block number (required)
• Story points (required, 1-100)

Auto-approval

gh pr review "$pr_number" --approve --body "..."

Auto-merge

gh pr merge "$pr_number" --squash --auto --delete-branch

Usage

Manual Trigger

# Trigger specific block
gh workflow run agent-block-4-foundation.yml

# Trigger orchestrator
gh workflow run hanspedder-orchestrator.yml

Automatic Cascade

Just merge Block 3 to main, and Blocks 4-6 will cascade automatically.

Monitor Orchestrator

Check workflow runs:

gh run list --workflow=hanspedder-orchestrator.yml

File Locations

• agent-block-4-foundation.yml - DatabaseMaster workflow
• agent-block-5-testing.yml - QASpecialist workflow
• agent-block-6-security.yml - SecurityCompliance workflow
• hanspedder-orchestrator.yml - Orchestrator workflow

Validation Checklist

• No emoji in step names
• Proper workflow_run triggers
• Conditional execution with success check
• Structured commit messages
• Parseable PR body format
• Valid YAML syntax
• Executable agent implementations
• Orchestrator discovery logic
• Auto-approval mechanism
• Auto-merge capability

Story Points Total

• Block 4: 50 points
• Block 5: 32 points
• Block 6: 28 points
• Total: 110 points