Multi-Agent System

Parallel development with multiple AI agents

Multi-Agent System

Portfolio OS includes a sophisticated multi-agent development system that enables parallel development by multiple AI agents working simultaneously on different features.

Overview

The multi-agent system uses Git worktrees to create isolated development environments where each agent can work independently without conflicts. This dramatically accelerates development by allowing multiple features to be built in parallel.

Key Benefits

  • Parallel Development: Multiple agents work simultaneously on different features
  • Zero Conflicts: Each agent has its own isolated workspace
  • Easy Integration: Merge completed work through standard PR process
  • State Management: Track agent status and task assignments
  • Coordination: PowerShell scripts orchestrate agent workflows

How It Works

Core Components

1. Git Worktrees

Git worktrees create separate working directories that share the same repository:

# Main repo
portfolio-os/

# Agent worktrees
worktrees/agent-1-chris/
worktrees/agent-2-jason/
worktrees/agent-3-alex/

Each worktree is a full working copy with its own branch.

2. Agent Coordination Scripts

PowerShell scripts in scripts/agent-management/:

  • setup-agent-development.ps1 - Create new agent worktree
  • manage-multi-agent-system.ps1 - Coordinate multiple agents
  • start-multi-agent-e2e-unified.ps1 - Run complete workflows
  • update-agent-status.ps1 - Track agent progress

3. Task Assignment

Agents are assigned specific tasks with clear boundaries:

{
  "agent-1": {
    "name": "Chris",
    "role": "Frontend Specialist",
    "tasks": ["Issue #266", "Issue #268"],
    "branch": "chris-automation-frontend"
  },
  "agent-2": {
    "name": "Jason", 
    "role": "Backend Specialist",
    "tasks": ["Issue #264", "Issue #265"],
    "branch": "jason-automation-backend"
  }
}

4. State Synchronization

Configuration file tracks agent state:

  • Current branch
  • Assigned tasks
  • Work status (pending, in-progress, review, completed)
  • Dependencies

Typical Workflow

1

Create Agent Worktrees

.\scripts\agent-management\setup-agent-development.ps1 -AgentName "agent-1"
.\scripts\agent-management\setup-agent-development.ps1 -AgentName "agent-2"
2

Assign Tasks to Agents

Each agent receives specific issues or features to implement.

Tasks are tracked in scripts/configuration/agent-assignment-config.json

3

Agents Work in Parallel

Each agent:

  • Works in their isolated worktree
  • Makes commits on their feature branch
  • Has no conflicts with other agents
4

Create Pull Requests

# Agent 1 completes work
.\scripts\pr-management\automate-pr-unified.ps1 -Title "feat: implement feature A"

# Agent 2 completes work
.\scripts\pr-management\automate-pr-unified.ps1 -Title "feat: implement feature B"
5

Review and Merge

PRs are reviewed and merged to develop branch independently.

Use Cases

Parallel Feature Development

Two agents implement different features simultaneously:

  • Agent 1: User authentication system
  • Agent 2: Dashboard analytics

Bug Fixes + Features

Mix urgent fixes with feature work:

  • Agent 1: Critical security patch
  • Agent 2: New feature development

Experimentation

Try different approaches in parallel:

  • Agent 1: Implement solution A
  • Agent 2: Implement solution B
  • Compare and choose the best approach

Getting Started

Ready to use the multi-agent system?

Quick Start Guide

Set up your first multi-agent workflow

System Architecture

Deep dive into how it works

Agent Scripts

Available automation scripts

Best Practices

Note:

Tips for Effective Multi-Agent Development:

  1. Clear task boundaries - Minimize overlap between agents
  2. Regular syncing - Keep worktrees updated with develop
  3. Status tracking - Update agent status regularly
  4. Communication - Document decisions in PRs
  5. Small PRs - Easier to review and merge

Limitations

Note:

Be aware of these constraints:

  • Disk space: Each worktree is a full copy (~100MB each)
  • Coordination overhead: More agents = more coordination needed
  • Merge conflicts: Can still occur if agents touch same files
  • Resource usage: Multiple Node processes if running dev servers

Next Steps