System Architecture

Multi-agent system architecture and technical implementation

Multi-Agent System Architecture

Deep dive into the technical architecture of Portfolio OS's multi-agent development system.

Architecture Overview

Core Components

1. Git Worktrees

Git worktrees are the foundation of the multi-agent system:

# Worktree structure
portfolio-os/.git/                  # Shared Git database
portfolio-os/worktrees/
  ├── agent-1-chris/               # Agent 1 workspace
  │   ├── apps/
  │   ├── packages/
  │   └── scripts/
  └── agent-2-jason/               # Agent 2 workspace
      ├── apps/
      ├── packages/
      └── scripts/

Key Features:

  • All worktrees share the same .git database
  • Each worktree has its own working directory
  • Each worktree tracks a different branch
  • No duplication of Git history

2. Coordination Scripts

PowerShell scripts orchestrate agent workflows:

Agent Management Scripts

ScriptPurpose
setup-agent-development.ps1Initialize new agent worktree
manage-multi-agent-system.ps1Start/stop/status of agents
start-multi-agent-e2e-unified.ps1Complete workflow automation
update-agent-status.ps1Update agent work status

Configuration Files

agent-assignment-config.json

{
  "agents": [
    {
      "name": "agent-1",
      "displayName": "Chris",
      "role": "Frontend Specialist",
      "worktreePath": "worktrees/agent-1-chris",
      "branch": "chris-automation-frontend",
      "tasks": [
        {"id": 266, "title": "Create Issue Implementation System"},
        {"id": 268, "title": "Create Advanced Analytics"}
      ],
      "status": "in-progress"
    }
  ]
}

worktree-state.json

{
  "worktrees": [
    {
      "path": "worktrees/agent-1-chris",
      "branch": "chris-automation-frontend",
      "lastSync": "2025-10-08T10:30:00Z",
      "uncommittedChanges": false,
      "behindDevelop": 2
    }
  ]
}

3. Task Assignment System

Tasks are assigned based on agent roles:

Frontend Specialist Tasks:

  • UI components
  • User workflows
  • Client-side logic
  • Analytics dashboards
  • User experience features

4. State Management

The system tracks multiple state dimensions:

Agent State:

  • Current branch
  • Assigned tasks
  • Work progress
  • Dependencies

Worktree State:

  • Last sync with develop
  • Uncommitted changes
  • Commits ahead/behind develop

Task State:

  • Not started
  • In progress
  • In review
  • Completed
  • Blocked

Workflow Automation

Complete E2E Flow

1

Initialization

.\scripts\agent-management\start-multi-agent-e2e-unified.ps1 `
  -NumAgents 2 `
  -Tasks "Feature A", "Feature B"

Creates worktrees, assigns tasks, sets up branches.

2

Development

Agents work in parallel in their isolated worktrees.

State is tracked in configuration files.

3

Status Updates

.\scripts\agent-management\update-agent-status.ps1 `
  -AgentName "agent-1" `
  -Status "in-progress"
4

PR Creation

Automated PR creation when agent completes work:

.\scripts\pr-management\automate-pr-unified.ps1 `
  -Title "feat(agent-1): implement feature A" `
  -AgentName "agent-1"
5

Integration

PRs are reviewed, approved, and merged to develop.

Agent worktree can then be synced or reassigned.

Technical Implementation

Worktree Creation

# Create worktree
git worktree add -b $BranchName $WorktreePath develop

# Configure worktree
cd $WorktreePath
git config --local user.name "Agent Name"
git config --local user.email "agent@example.com"

# Install dependencies
pnpm install

State Synchronization

# Sync worktree with develop
cd $WorktreePath
git fetch origin develop
git rebase develop

# Update state file
$state = Get-Content worktree-state.json | ConvertFrom-Json
$state.lastSync = Get-Date
$state | ConvertTo-Json | Set-Content worktree-state.json

Conflict Resolution

When conflicts occur:

  1. Detection: Script detects uncommitted changes
  2. Notification: Alert agent or human operator
  3. Resolution: Manual intervention or automated strategies
  4. Verification: Tests pass before proceeding

Performance Considerations

Disk Space

Each worktree requires:

  • Working directory: ~100MB
  • Node modules: ~500MB
  • Build artifacts: ~50MB

Total per agent: ~650MB

CPU/Memory

  • Each agent can run dev server: ~500MB RAM
  • Build processes: 1-2 CPU cores per agent
  • Recommended: 8GB RAM for 2-3 active agents

Network

  • Minimal network overhead
  • Git operations share local .git database
  • Only PRs and pushes use network

Security Considerations

Note:

Security Best Practices:

  1. Isolation: Each agent works in separate worktree
  2. Permissions: Limit agent access to assigned files
  3. Validation: Run tests before merging
  4. Code Review: Always review agent PRs
  5. Secrets: Don't commit secrets in worktrees

Monitoring & Observability

Track agent system health:

# View all agent status
.\scripts\agent-management\manage-multi-agent-system.ps1 -Action status

# Check worktree health
.\scripts\monitoring\performance-analyzer.ps1 -Target worktrees

# Generate metrics
.\scripts\monitoring\automation-metrics.ps1

Limitations & Constraints

Current Limitations

  • Max agents: 3-4 recommended (disk/resource limits)
  • Coordination: Manual task assignment
  • Conflict resolution: Requires human intervention
  • Cleanup: Worktrees must be manually removed

Future Improvements

  • Automatic task assignment based on agent specialization
  • AI-powered conflict resolution
  • Dynamic agent scaling
  • Cloud-based worktree storage

Next Steps