Multi-Agent Quick Start

Get started with multi-agent development in 15 minutes

Multi-Agent Quick Start

Set up and run your first multi-agent workflow in just 15 minutes.

Prerequisites

Before starting, ensure you have:

  • Portfolio OS installed and working
  • PowerShell 7+ installed
  • Git worktree feature available (Git 2.5+)
  • At least 2GB free disk space

Quick Setup

1

Create Your First Agent

cd portfolio-os
.\scripts\agent-management\setup-agent-development.ps1 -AgentName "agent-1"

This creates a new worktree at worktrees/agent-1/

2

Verify Agent Created

# List all worktrees
git worktree list

# Check agent directory
ls worktrees/

You should see the new agent worktree listed.

3

Assign a Task

Edit scripts/configuration/agent-assignment-config.json:

{
  "agents": [{
    "name": "agent-1",
    "tasks": ["Implement dark mode toggle"],
    "branch": "feature/dark-mode",
    "status": "in-progress"
  }]
}
4

Agent Starts Working

The agent now works in their isolated worktree:

cd worktrees/agent-1
pnpm dev
# Make changes, commit, create PR

Multi-Agent Workflow

Now let's run multiple agents in parallel:

1

Create Multiple Agents

.\scripts\agent-management\start-multi-agent-e2e-unified.ps1 `
  -NumAgents 2 `
  -Tasks "Add authentication", "Create admin dashboard"
2

Monitor Agent Status

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

Shows current status of all agents.

3

Agents Work in Parallel

  • Agent 1 implements authentication in worktrees/agent-1/
  • Agent 2 builds admin dashboard in worktrees/agent-2/
  • No conflicts because they're in separate worktrees!
4

Create PRs

# Agent 1 completes work
cd worktrees/agent-1
.\scripts\pr-management\automate-pr-unified.ps1 `
  -Title "feat: add user authentication" `
  -Body "Implements JWT-based auth"

# Agent 2 completes work
cd worktrees/agent-2
.\scripts\pr-management\automate-pr-unified.ps1 `
  -Title "feat: create admin dashboard" `
  -Body "Adds admin UI with analytics"

Example: Parallel Feature Development

Let's walk through a real example:

Scenario

Build two features simultaneously:

  • Feature A: Blog comment system (Agent 1)
  • Feature B: Newsletter subscription (Agent 2)

Implementation

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

# Agent 1: Comment System
cd worktrees/agent-1
git checkout -b feature/comments
# Implement comment system
git add .
git commit -m "feat: add blog comments"
git push origin feature/comments

# Agent 2: Newsletter
cd worktrees/agent-2
git checkout -b feature/newsletter
# Implement newsletter
git add .
git commit -m "feat: add newsletter subscription"
git push origin feature/newsletter

# Create PRs (both at the same time!)

Both features developed in parallel, zero conflicts!

Common Commands

CommandPurpose
setup-agent-development.ps1Create new agent
manage-multi-agent-system.ps1 -Action statusCheck all agents
update-agent-status.ps1Update agent progress
git worktree listList all worktrees
git worktree remove <path>Delete worktree

Troubleshooting

Worktree Creation Fails

# Error: worktree already exists
Solution: Remove existing worktree first
git worktree remove worktrees/agent-1

# Error: branch already exists
Solution: Use different branch name
git checkout -b feature/different-name

Agent Can't Push

# Error: permission denied
Solution: Ensure Git credentials are configured
git config --global credential.helper store

Port Conflicts

# Error: port 3000 in use
Solution: Each agent should use different port
# In worktrees/agent-1/apps/site/next.config.js
module.exports = {
  devServer: { port: 3001 }
}

Best Practices

Note:

Tips for Success:

  1. Clear boundaries: Assign non-overlapping features
  2. Small tasks: Each agent works on focused features
  3. Regular syncs: Rebase on develop frequently
  4. Status updates: Keep agent status current
  5. Clean up: Remove unused worktrees

Next Steps

Now that you've created your first multi-agent workflow:

Note:

Questions? Check the Troubleshooting Guide or see Multi-Agent Architecture for deep dive.