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:

•Agent Executor - Unified interface for invoking agent binaries
•Workflow Orchestrator - Multi-phase, multi-agent workflow management
•Agent Change Validator - Enforces agent file scope boundaries
•Mailbox System - Async inter-agent communication
•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

javascript

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

javascript

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

javascript

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

Usage Pattern

javascript

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

javascript

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

javascript

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:

javascript

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

javascript

{
  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

bash

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

javascript

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

javascript

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

bash

# 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

yaml

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

code

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

json

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

javascript

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

javascript

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

javascript

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

code

Integration with Wolf role-based system

•
REQUIRED SKILL: Use wolf-roles to understand agent boundaries
- •Why: Coordination scripts enforce role boundaries. Must understand role definitions to use orchestration properly.
- •When: Before using orchestrate-workflow.mjs or validate-agent-changes.mjs
- •Tool: Use Skill tool to load wolf-roles
- •Example: Before orchestrating pm-agent → coder-agent → reviewer-agent workflow, load each role's responsibilities
•
RECOMMENDED SKILL: Use wolf-governance for workflow quality gates
- •Why: Workflows must enforce governance at each phase. Understanding gates ensures compliance.
- •When: When designing custom workflows or modifying existing workflow definitions
- •Tool: Use Skill tool to load wolf-governance
•
DURING WORK: Coordination scripts enable multi-agent collaboration
- •Scripts orchestrate agent interactions throughout complex workflows
- •Use scripts at handoff points and phase transitions
- •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

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

Script Execution:

bash

$ 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 </Good>

<Bad> **Task**: Same feature implementation #123

Manual Approach: "I'll just coordinate manually"

Actions:

code

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

Example 2: Agent Scope Validation

<Good> **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:

bash

$ 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. </Good>

<Bad> **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:

bash

$ 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 </Bad>

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