.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
```bash
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
```bash
gh pr review "$pr_number" --approve --body "..."
```

### Auto-merge
```bash
gh pr merge "$pr_number" --squash --auto --delete-branch
```

## Usage

### Manual Trigger
```bash
# 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:
```bash
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

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

## Story Points Total

- Block 4: 50 points
- Block 5: 32 points
- Block 6: 28 points
- **Total: 110 points**