name: wolf-scripts-agents
description: Agent coordination, orchestration, and multi-agent workflow management scripts
version: 1.1.0
category: agent-coordination
triggers:
- agent orchestration
- workflow coordination
- multi-agent
- agent execution
- agent validation
dependencies:
- wolf-roles
- wolf-archetypes
- wolf-governance
size: large

Wolf Scripts - Agent Coordination

Agent coordination patterns that power Wolf's multi-agent orchestration system. These scripts manage agent lifecycles, workflow handoffs, and cross-agent collaboration.

Overview

This skill captures agent coordination and orchestration patterns:

1. Agent Executor - Unified interface for invoking agent binaries
2. Workflow Orchestrator - Multi-phase, multi-agent workflow management
3. Agent Change Validator - Enforces agent file scope boundaries
4. Mailbox System - Async inter-agent communication
5. Work Claimer - Agent work assignment and claim management

🤖 Agent Executor Pattern

Purpose

Provides unified interface for invoking real agent binaries (codex, claude-code, custom) with structured output parsing and timeout management.

Features

• Multi-backend Support: codex, claude-code, custom binaries
• Non-interactive Execution: --cwd and --prompt-file for automation
• Structured Signal Parsing: AGENT_RESPONSE_ID, AGENT_CREATED_ISSUE_URL, etc.
• Timeout Management: Configurable execution timeouts
• Error Handling: Robust error capture and reporting

Configuration

const executor = new AgentExecutor({
  agentBinary: 'codex',          // or 'claude-code', '/path/to/custom'
  timeout: 300000,                // 5 minutes default
  captureOutput: true,            // Capture stdout/stderr
  parseSignals: true,             // Parse structured signals
  env: { ... },                   // Custom environment variables
  executionDir: '/path/to/repo', // Working directory
  verbose: false,                 // Logging verbosity
  logPrefix: '[agent-executor]'  // Log message prefix
});

Execution Parameters

const result = await executor.executeAgent({
  cwd: '/path/to/repo',          // Working directory for agent
  promptFile: '/path/to/prompt.md', // Prompt file path
  command: 'run',                 // Agent command (run, create-issue, etc.)
  args: { ... },                  // Additional command arguments
  id: 'unique-request-id'         // Request ID for tracking
});

Structured Signals

Agent output is parsed for special signals:
- AGENT_RESPONSE_ID: Unique response identifier
- AGENT_CREATED_ISSUE_URL: URL of created issue
- AGENT_CREATED_PR_URL: URL of created PR
- AGENT_STATUS: Execution status (success, failure, partial)
- AGENT_NEXT_ACTION: Suggested next step
- AGENT_HANDOFF_TO: Next agent in workflow

Return Value

{
  success: true,
  stdout: '...',
  stderr: '...',
  exitCode: 0,
  signals: {
    responseId: '...',
    createdIssueUrl: '...',
    status: 'success',
    nextAction: '...',
    handoffTo: '...'
  },
  executionTime: 45.2, // seconds
  timeout: false
}

Usage Pattern

import { AgentExecutor } from './agent-executor.mjs';

// Initialize executor
const executor = new AgentExecutor({
  agentBinary: 'claude-code',
  timeout: 600000  // 10 minutes
});

// Execute agent with prompt
const result = await executor.executeAgent({
  cwd: '/workspace/project',
  promptFile: '/tmp/prompt.md',
  command: 'run',
  id: 'workflow-123-phase-1'
});

// Check for success
if (result.success) {
  console.log(`Agent completed successfully`);
  console.log(`Response ID: ${result.signals.responseId}`);

  // Handle handoff if specified
  if (result.signals.handoffTo) {
    console.log(`Handing off to: ${result.signals.handoffTo}`);
  }
} else {
  console.error(`Agent failed: ${result.stderr}`);
}

When to Use

• Automating agent invocation from workflows
• Building multi-agent pipelines
• Testing agent behavior programmatically
• Capturing structured agent outputs

Script Location: /agents/shared/scripts/agent-executor.mjs

🎯 Workflow Orchestrator Pattern

Purpose

Coordinates multi-phase, multi-agent workflows with automatic handoffs, lens integration, and state management.

Available Workflows

const WORKFLOWS = {
  'issue-to-release': {
    name: 'Issue to Release Pipeline',
    description: 'Complete journey from issue creation to deployment',
    phases: [
      { agent: 'intake-agent', action: 'triage' },
      { agent: 'pm-agent', action: 'curate' },
      { agent: 'coder-agent', action: 'implement' },
      { agent: 'reviewer-agent', action: 'review' },
      { agent: 'qa-agent', action: 'test' },
      { agent: 'release-agent', action: 'deploy' }
    ]
  },
  'pr-review-cycle': {
    name: 'PR Review Cycle',
    description: 'Automated PR review and feedback loop',
    phases: [
      { agent: 'reviewer-agent', action: 'initial-review' },
      { agent: 'coder-agent', action: 'address-feedback' },
      { agent: 'reviewer-agent', action: 'final-review' }
    ]
  },
  'ci-failure-recovery': {
    name: 'CI Failure Recovery',
    description: 'Automatic diagnosis and fix of CI failures',
    phases: [
      { agent: 'devops-agent', action: 'diagnose' },
      { agent: 'coder-agent', action: 'fix' },
      { agent: 'qa-agent', action: 'verify' }
    ]
  }
};

WorkflowOrchestrator Class

class WorkflowOrchestrator {
  constructor() {
    this.currentWorkflow = null;
    this.currentPhase = 0;
    this.workflowState = {};
  }

  // List all available workflows
  async listWorkflows() {
    // Display workflow catalog
  }

  // Start a workflow
  async startWorkflow(workflowName, options = {}) {
    // Initialize workflow state
    // Integrate lens selection if issue provided
    // Execute workflow phases
  }

  // Execute workflow phases sequentially
  async executeWorkflow() {
    // For each phase:
    //   1. Prepare agent context
    //   2. Execute agent action
    //   3. Capture results
    //   4. Determine handoff
    //   5. Update state
  }

  // Execute a single phase
  async executePhase(phase, context) {
    // Run agent action with context
    // Parse output signals
    // Return phase result
  }

  // Save workflow state for resume
  saveWorkflowState() {
    // Persist state to disk/database
  }

  // Resume incomplete workflow
  async resumeWorkflow(workflowId) {
    // Load state
    // Continue from last phase
  }
}

Lens Integration

Workflows automatically integrate with the lens system:

// Lens selection happens at workflow start
const lensIntegration = await integrateLensWithOrchestration(
  workflowName,
  issueNumber,
  repository
);

// Lenses modify workflow phases
this.currentWorkflowDefinition = lensIntegration.applyToWorkflow(baseWorkflow);

// Example modifications:
// - Performance lens adds benchmark phase
// - Security lens adds security review phase
// - Accessibility lens adds a11y validation phase

Workflow State

{
  workflowName: 'issue-to-release',
  startTime: '2025-10-20T12:00:00Z',
  currentPhase: 3,
  phases: [
    {
      phase: 0,
      agent: 'intake-agent',
      action: 'triage',
      startTime: '2025-10-20T12:00:00Z',
      endTime: '2025-10-20T12:02:30Z',
      status: 'completed',
      output: { ... },
      signals: { ... }
    },
    { ... } // More phases
  ],
  lenses: ['performance', 'security'],
  metadata: { issueNumber: 123, prNumber: 456 }
}

Command Line Usage

# List all workflows
node orchestrate-workflow.mjs --list-workflows

# Start issue-to-release workflow
node orchestrate-workflow.mjs --workflow=issue-to-release --issue=123

# Start PR review cycle
node orchestrate-workflow.mjs --workflow=pr-review-cycle --pr=456

# Dry run mode
DRY_RUN=true node orchestrate-workflow.mjs --workflow=ci-failure-recovery --issue=78

When to Use

• Multi-agent collaboration required
• Sequential phase execution needed
• Automatic handoffs between agents
• State persistence for long-running workflows
• Lens-aware workflow modification

Script Location: /agents/shared/scripts/orchestrate-workflow.mjs

🛡️ Agent Change Validator Pattern

Purpose

Enforces agent file scope boundaries to prevent cross-cutting changes that could interfere with other agents.

Role File Patterns

Each agent role has explicitly defined allowed file patterns:

const ROLE_FILE_PATTERNS = {
  'pm-agent': {
    allowed: [
      'agents/roles/pm-agent/**/*',
      'agents/shared/templates/pm-*',
      '.github/ISSUE_TEMPLATE/**/*',
      'docs/**/*.md',
      'README.md',
      'CONTRIBUTING.md'
    ],
    description: 'PM templates, documentation, issue templates'
  },

  'coder-agent': {
    allowed: [
      'src/**/*',
      'lib/**/*',
      'components/**/*',
      'test/**/*',
      '*.test.*',
      '*.spec.*',
      'package.json',
      'tsconfig.json',
      '*.config.js'
    ],
    description: 'Source code, tests, build configs, dependencies'
  },

  'qa-agent': {
    allowed: [
      'test/**/*',
      'e2e/**/*',
      '*.test.*',
      '*.spec.*',
      '.github/workflows/*test*',
      'playwright.config.*',
      'jest.config.*'
    ],
    description: 'Test files, CI test workflows, testing configs'
  },

  'reviewer-agent': {
    allowed: [
      'agents/roles/reviewer-agent/**/*',
      '.eslintrc*',
      '.prettierrc*',
      '.github/workflows/*review*',
      '.github/workflows/*lint*',
      '.gitignore'
    ],
    description: 'Code standards, linting configs, review templates'
  }

  // ... more agent patterns
};

Validation Algorithm

function validateAgentChanges(agentRole, changedFiles) {
  const rolePatterns = ROLE_FILE_PATTERNS[agentRole];

  if (!rolePatterns) {
    throw new Error(`Unknown agent role: ${agentRole}`);
  }

  const violations = [];

  for (const file of changedFiles) {
    const isAllowed = rolePatterns.allowed.some(pattern =>
      minimatch(file, pattern)
    );

    if (!isAllowed) {
      violations.push({
        file,
        agent: agentRole,
        reason: `File outside agent scope. Allowed patterns: ${rolePatterns.description}`
      });
    }
  }

  return {
    valid: violations.length === 0,
    violations,
    totalFiles: changedFiles.length,
    allowedFiles: changedFiles.length - violations.length
  };
}

Command Line Usage

# Validate from file list
node validate-agent-changes.mjs --agent=pm-agent --files=changed-files.txt

# Validate from git diff
node validate-agent-changes.mjs --agent=coder-agent --git-diff

# Validate specific PR
node validate-agent-changes.mjs --agent=qa-agent --pr=456

# Check without failing (report only)
node validate-agent-changes.mjs --agent=reviewer-agent --git-diff --no-fail

Integration with CI

# .github/workflows/agent-scope-validation.yml
- name: Validate Agent File Scope
  run: |
    AGENT=$(gh pr view ${{ github.event.pull_request.number }} --json labels --jq '.labels[].name' | grep 'agent:' | sed 's/agent://')
    node agents/shared/scripts/validate-agent-changes.mjs --agent=$AGENT --git-diff

When to Use

• PR validation gates
• Pre-commit hooks for agent work
• Preventing scope creep
• Enforcing separation of concerns
• CI/CD validation

Script Location: /agents/shared/scripts/validate-agent-changes.mjs

📬 Mailbox System Pattern

Purpose

Asynchronous inter-agent communication using file-based mailboxes.

Mailbox Structure

agents/shared/mailbox/
├── intake/           # intake-agent mailbox
│   ├── inbox/
│   ├── outbox/
│   └── archive/
├── pm/               # pm-agent mailbox
│   ├── inbox/
│   ├── outbox/
│   └── archive/
└── coder/            # coder-agent mailbox
    ├── inbox/
    ├── outbox/
    └── archive/

Message Format

{
  "id": "msg-2025-10-20-001",
  "from": "pm-agent",
  "to": "coder-agent",
  "subject": "Implementation request for issue #123",
  "timestamp": "2025-10-20T12:00:00Z",
  "priority": "normal",
  "payload": {
    "issueNumber": 123,
    "archetype": "product-implementer",
    "acceptanceCriteria": [ ... ],
    "technicalContext": { ... }
  },
  "metadata": {
    "workflowId": "workflow-456",
    "phaseNumber": 2
  }
}

Mailbox API

class MailboxClient {
  constructor(agentName) {
    this.agentName = agentName;
    this.inboxPath = `agents/shared/mailbox/${agentName}/inbox`;
    this.outboxPath = `agents/shared/mailbox/${agentName}/outbox`;
  }

  // Send message to another agent
  async sendMessage(toAgent, subject, payload) {
    const message = {
      id: this.generateMessageId(),
      from: this.agentName,
      to: toAgent,
      subject,
      timestamp: new Date().toISOString(),
      payload
    };

    // Write to outbox and recipient's inbox
    await this.writeMessage(this.outboxPath, message);
    await this.writeMessage(`agents/shared/mailbox/${toAgent}/inbox`, message);

    return message.id;
  }

  // Check inbox for new messages
  async checkInbox() {
    const messages = await this.readMessages(this.inboxPath);
    return messages.filter(msg => !msg.read);
  }

  // Mark message as read
  async markAsRead(messageId) {
    // Update message metadata
  }

  // Archive message
  async archiveMessage(messageId) {
    // Move to archive folder
  }
}

Usage Pattern

// PM agent sends work to coder agent
const pmMailbox = new MailboxClient('pm');
const messageId = await pmMailbox.sendMessage('coder', 'Implement feature #123', {
  issueNumber: 123,
  archetype: 'product-implementer',
  acceptanceCriteria: [ ... ]
});

// Coder agent checks inbox
const coderMailbox = new MailboxClient('coder');
const newMessages = await coderMailbox.checkInbox();

for (const msg of newMessages) {
  console.log(`New work from ${msg.from}: ${msg.subject}`);

  // Process message
  await processWork(msg.payload);

  // Mark as read
  await coderMailbox.markAsRead(msg.id);

  // Send completion notification
  await coderMailbox.sendMessage(msg.from, `Completed: ${msg.subject}`, {
    prUrl: '...',
    completionTime: '...'
  });
}

When to Use

• Async agent communication
• Work queue management
• Handoff tracking
• Audit trails
• Decoupled agent coordination

Integration Patterns

Complete Workflow Example

// 1. Start orchestrated workflow
const orchestrator = new WorkflowOrchestrator();

await orchestrator.startWorkflow('issue-to-release', {
  issue: 123,
  repository: 'org/repo'
});

// 2. Workflow internally uses agent executor
const executor = new AgentExecutor({ agentBinary: 'claude-code' });

for (const phase of workflow.phases) {
  // 3. Execute agent with validation
  const changedFiles = await getChangedFiles();
  const validation = validateAgentChanges(phase.agent, changedFiles);

  if (!validation.valid) {
    throw new Error(`Agent scope violation: ${validation.violations}`);
  }

  // 4. Run agent
  const result = await executor.executeAgent({
    cwd: '/workspace',
    promptFile: `/tmp/phase-${phase.number}-prompt.md`,
    command: phase.action
  });

  // 5. Use mailbox for async communication if needed
  if (phase.requiresHandoff) {
    const mailbox = new MailboxClient(phase.agent);
    await mailbox.sendMessage(phase.nextAgent, 'Work ready for review', {
      prUrl: result.signals.createdPrUrl
    });
  }

  // 6. Save state
  orchestrator.saveWorkflowState();
}

Related Skills

• wolf-roles: Agent role definitions and responsibilities
• wolf-archetypes: Behavioral profiles
• wolf-workflows-ci: GitHub Actions integration
• wolf-governance: Quality gates and policies

File Locations

All agent coordination scripts in /agents/shared/scripts/:
- agent-executor.mjs - Unified agent execution interface
- orchestrate-workflow.mjs - Multi-agent workflow orchestration
- validate-agent-changes.mjs - Agent scope enforcement
- intake-agent-with-mailbox.mjs - Mailbox-integrated intake agent
- work-claimer.mjs - Work assignment and claim management

Best Practices

Agent Execution

• ✅ Always set reasonable timeouts
• ✅ Parse structured signals for automation
• ✅ Capture both stdout and stderr
• ✅ Use unique request IDs for tracking
• ❌ Don't run agents without timeout limits
• ❌ Don't ignore exit codes

Workflow Orchestration

• ✅ Save state after each phase for resume capability
• ✅ Integrate lens modifications early
• ✅ Use dry-run mode for testing
• ✅ Log all phase transitions
• ❌ Don't skip error handling
• ❌ Don't hardcode workflow definitions

Agent Scope Validation

• ✅ Validate file changes in CI
• ✅ Provide clear violation messages
• ✅ Keep role patterns up to date
• ✅ Document allowed patterns clearly
• ❌ Don't allow broad wildcards
• ❌ Don't skip validation for "small" changes

Mailbox Communication

• ✅ Use structured message formats
• ✅ Archive read messages
• ✅ Set message priorities
• ✅ Include workflow context in metadata
• ❌ Don't leave inbox unprocessed
• ❌ Don't lose message delivery confirmation

Red Flags - STOP

If you catch yourself thinking:

• ❌ "I can coordinate agents manually without scripts" - STOP. Manual coordination doesn't scale and loses state. Use workflow orchestrator for multi-agent work.
• ❌ "Scripts are overkill for simple workflows" - NO. Even "simple" multi-agent workflows have handoffs, state, and failures. Scripts provide resilience.
• ❌ "Automation can wait until later" - FORBIDDEN. "Later" means never. Set up orchestration from the start or face coordination chaos.
• ❌ "Agent scope validation is too restrictive" - Wrong. Scope boundaries prevent interference and maintain separation of concerns. Violating scope = breaking governance.
• ❌ "Mailbox system is unnecessary overhead" - False. Async communication enables decoupled agents and audit trails. Direct coordination breaks under load.
• ❌ "One agent can do multiple roles to save time" - FORBIDDEN. Role mixing violates governance. Use orchestrator to coordinate multiple agents properly.

STOP. Use the appropriate coordination script BEFORE proceeding.

After Using This Skill

REQUIRED NEXT STEPS:

Integration with Wolf role-based system

1. REQUIRED SKILL: Use wolf-roles to understand agent boundaries
2. Why: Coordination scripts enforce role boundaries. Must understand role definitions to use orchestration properly.
3. When: Before using orchestrate-workflow.mjs or validate-agent-changes.mjs
4. Tool: Use Skill tool to load wolf-roles

5. Example: Before orchestrating pm-agent → coder-agent → reviewer-agent workflow, load each role's responsibilities

6. RECOMMENDED SKILL: Use wolf-governance for workflow quality gates

7. Why: Workflows must enforce governance at each phase. Understanding gates ensures compliance.
8. When: When designing custom workflows or modifying existing workflow definitions

9. Tool: Use Skill tool to load wolf-governance

10. DURING WORK: Coordination scripts enable multi-agent collaboration

11. Scripts orchestrate agent interactions throughout complex workflows
12. Use scripts at handoff points and phase transitions
13. Continuous state management for long-running workflows

Verification Checklist

Before claiming multi-agent coordination complete:

• [ ] Used workflow orchestrator for multi-agent coordination (not manual coordination)
• [ ] Validated agent file scope boundaries before allowing changes (validate-agent-changes.mjs)
• [ ] Set up mailbox communication for async handoffs (if workflow requires it)
• [ ] Documented workflow state and phases (saved state after each phase)
• [ ] All agents stayed within their defined file scopes (no role boundary violations)
• [ ] Workflow resumable from any phase (state persistence working)

Can't check all boxes? Coordination incomplete. Return to this skill.

Good/Bad Examples: Multi-Agent Coordination

Example 1: Proper Workflow Orchestration

Task: Implement feature #123 through complete pipeline (intake → PM curation → implementation → review → QA → release)

Script Execution:

$ node orchestrate-workflow.mjs --workflow=issue-to-release --issue=123

Starting workflow: issue-to-release
Issue: #123 - Add user authentication
Lenses detected: security, observability

Phase 1: intake-agent (triage)
  ✅ Issue triaged successfully
  ✅ Labels applied: feature, security
  ✅ Archetype recommended: product-implementer
  ✅ State saved

Phase 2: pm-agent (curate)
  ✅ Acceptance criteria defined
  ✅ Incremental shards created (#123-1, #123-2)
  ✅ Technical context documented
  ✅ State saved

Phase 3: coder-agent (implement)
  ✅ Implementation complete
  ✅ PR created: #456
  ✅ Security lens requirements met (threat model, security tests)
  ✅ File scope validated: all changes in src/**/* (allowed for coder-agent)
  ✅ State saved

Phase 4: reviewer-agent (review)
  ✅ Code review complete
  ✅ Governance checks passed (DoD complete)
  ✅ Security lens validated
  ✅ Approved
  ✅ State saved

Phase 5: qa-agent (test)
  ✅ E2E tests passing
  ✅ Security scans clean
  ✅ Observability lens validated (metrics, monitoring)
  ✅ State saved

Phase 6: release-agent (deploy)
  ✅ Deployed to staging
  ✅ Smoke tests passing
  ✅ Production deployment complete
  ✅ Workflow complete ✅

Total time: 2.5 hours
All phases completed successfully

Why this is correct:
- Used workflow orchestrator instead of manual coordination
- Each agent stayed within scope (validated at each phase)
- Lenses (security, observability) automatically integrated
- State saved after each phase (workflow resumable)
- Complete audit trail of all agent actions
- Handoffs automatic and documented

Benefits:
- No dropped work between agents
- No scope violations
- Governance enforced at each phase
- Resumable if any phase fails
- Complete traceability

Task: Same feature implementation #123

Manual Approach: "I'll just coordinate manually"

Actions:

Developer: "Let me implement this feature myself across all phases"

1. Manual triage: Skipped (assumed feature type)
2. Manual PM work: Wrote quick acceptance criteria in memory
3. Implementation:
   ❌ Modified files in agents/roles/pm-agent/templates/ (scope violation - coder touching PM files)
   ❌ Modified .github/workflows/review.yml (scope violation - coder touching reviewer config)
   ❌ Modified test/ and src/ together (mixed coder + qa concerns)
4. Self-review: "Looks good to me" (governance violation - no separation)
5. Manual deploy: Pushed directly to main

Result:
❌ No archetype selection (wrong behavioral profile)
❌ No lens integration (security requirements missed)
❌ Scope violations broke PM templates (PM agent now fails)
❌ Scope violations broke review workflows (all PRs now fail review)
❌ No governance enforcement (DoD skipped)
❌ No state tracking (no resume capability)
❌ No audit trail (can't determine what broke)
❌ Self-approval violates governance
❌ Direct to main bypasses all gates

Outcome: 3 other agents broke, 2 days debugging, emergency rollback, team demoralized

What Should Have Been Done:
Used orchestrate-workflow.mjs which would have:
- ✅ Enforced agent scope boundaries
- ✅ Prevented PM template modifications by coder
- ✅ Prevented review workflow modifications by coder
- ✅ Required separate qa-agent for testing
- ✅ Required separate reviewer-agent for approval
- ✅ Integrated security lens automatically
- ✅ Saved state for resume
- ✅ Created audit trail
- ✅ Enforced governance at each phase

Example 2: Agent Scope Validation

PR #456 from coder-agent
Files changed:

src/auth/login.ts
src/auth/logout.ts
src/auth/session.ts
test/auth/login.test.ts
test/auth/session.test.ts
package.json

Validation:

$ node validate-agent-changes.mjs --agent=coder-agent --pr=456

Validating changes for coder-agent...
Allowed patterns: src/**/* lib/**/* components/**/* test/**/* *.test.* *.spec.* package.json tsconfig.json *.config.js

Checking files:
  ✅ src/auth/login.ts (matches: src/***)
  ✅ src/auth/logout.ts (matches: src/***)
  ✅ src/auth/session.ts (matches: src/***)
  ✅ test/auth/login.test.ts (matches: test/**/* AND *.test.*)
  ✅ test/auth/session.test.ts (matches: test/**/* AND *.test.*)
  ✅ package.json (matches: package.json)

Validation passed ✅
6/6 files within coder-agent scope

Result: PR allowed to proceed. No scope violations.

PR #457 from coder-agent
Files changed:

src/auth/login.ts
agents/roles/pm-agent/templates/feature-template.md
.github/workflows/review.yml
docs/GOVERNANCE.md
README.md

Validation:

$ node validate-agent-changes.mjs --agent=coder-agent --pr=457

Validating changes for coder-agent...
Allowed patterns: src/**/* lib/**/* components/**/* test/**/* *.test.* *.spec.* package.json tsconfig.json *.config.js

Checking files:
  ✅ src/auth/login.ts (matches: src/***)
  ❌ agents/roles/pm-agent/templates/feature-template.md
     Violation: File outside coder-agent scope
     This file belongs to: pm-agent
     Reason: PM templates are PM agent's responsibility
  ❌ .github/workflows/review.yml
     Violation: File outside coder-agent scope
     This file belongs to: reviewer-agent
     Reason: Review workflows are reviewer agent's responsibility
  ❌ docs/GOVERNANCE.md
     Violation: File outside coder-agent scope
     This file belongs to: pm-agent
     Reason: Governance docs are PM agent's responsibility
  ❌ README.md
     Violation: File outside coder-agent scope
     This file belongs to: pm-agent (or documentation-agent)
     Reason: Top-level docs are PM/docs agent's responsibility

Validation failed ❌
1/5 files within scope
4/5 files violate scope boundaries

BLOCKING: This PR cannot be merged until scope violations are resolved.

Recommended actions:
1. Remove changes to PM templates, review workflows, and docs
2. OR: Create separate PRs from appropriate agents:
   - pm-agent PR for template and governance doc changes
   - reviewer-agent PR for review workflow changes
   - documentation-agent PR for README changes

Result: PR blocked. Developer must split changes across appropriate agent roles.

Why this is correct:
- Scope validation caught cross-cutting changes
- Prevented coder from modifying PM agent's files
- Prevented coder from modifying reviewer agent's files
- Enforced separation of concerns
- Provided clear remediation guidance

If validation had been skipped:
- PM templates would have been modified by non-PM agent
- Review workflow would have been broken by non-reviewer agent
- Governance docs would have been modified without proper review
- Future agent work would have failed due to broken templates/workflows

Last Updated: 2025-11-14
Phase: Superpowers Skill-Chaining Enhancement v2.0.0
Maintainer: Wolf Orchestration Team