@william9527/virtual-team

AI-driven virtual team framework — automate software development with PM and Coder agents powered by Claude CLI.

What is this?

Virtual Team is an orchestration framework that runs two AI agents in a loop:

• PM (Project Manager) — reads a task list (GOALS.md), selects the next task, writes a detailed specification
• Coder (Software Engineer) — reads the specification, implements the code, runs tests, and reports back

The loop continues automatically until all tasks are complete, with safety mechanisms for stuck detection, truncation recovery, and human intervention requests.

Prerequisites

• Node.js >= 18
• Git
• Claude CLI (claude) installed and authenticated

Quick Start

# Install
npm install -g @william9527/virtual-team

# Initialise in your project
cd my-project
virtual-team init

# Define your tasks
vim .virtual-team/GOALS.md

# Start the development loop
virtual-team start

CLI Commands

virtual-team init [--force]

Creates the .virtual-team/ directory with:

• prompts/pm.txt — PM system prompt
• prompts/coder.txt — Coder system prompt
• PLAYBOOK.md — Framework documentation
• GOALS_TEMPLATE.md — Template for creating task lists
• INTENT_SPEC_TEMPLATE.md — Template for task specifications
• GOALS.md — Empty task list for you to fill in
• config.json — Configuration file

virtual-team start [options]

Starts the PM ↔ Coder development loop.

Option	Description
--dry-run	Log actions without executing agents
--max-cycles <n>	Limit PM→Coder cycles
--sleep <seconds>	Override cooldown time (default: 600)
--project <path>	Specify project root (default: cwd)

virtual-team status

Shows current task progress (TODO / IN PROGRESS / DONE counts).

Configuration

Edit .virtual-team/config.json:

{
  "sleepTime": 600,
  "errorSleepTime": 300,
  "stuckLimit": 3,
  "pmMaxTurns": 45,
  "coderMaxTurns": 65,
  "pmModel": "sonnet"
}

Key	Default	Description
sleepTime	600	Cooldown seconds between PM and Coder phases
errorSleepTime	300	Retry wait after API errors
stuckLimit	3	Consecutive no-change cycles before force exit
pmMaxTurns	45	Max conversation turns for PM
coderMaxTurns	65	Max conversation turns for Coder
pmModel	"sonnet"	Model for PM agent

Programmatic API

import { loadConfig, startLoop, initVirtualTeam } from '@william9527/virtual-team';

// Initialise
initVirtualTeam('/path/to/project');

// Run the loop
const config = loadConfig('/path/to/project');
const result = await startLoop(config, { maxCycles: 5 });
console.log(result.status); // 'all_done' | 'human_needed' | 'stuck' | 'max_cycles_reached'

Safety Mechanisms

Mechanism	Description
Task completion detection	Loop ends when no [TODO] or [IN PROGRESS] in GOALS.md
Truncation detection	Missing signal file → rollback and retry
Stuck detection	N consecutive no-change cycles → force exit
Human intervention	HUMAN_NEEDED.md pauses the loop
API error tolerance	Retry with backoff on API/network errors

GOALS.md Format

## Epic 1: Infrastructure

### Feature 1.1: Project Setup

- [ ] `[TODO]` Task 1.1.1: Initialise Node.js project
  - Goal: Set up package.json, TypeScript, and build tooling
  - Output: package.json, tsconfig.json, working `npm run build`

Task statuses: [TODO] → [IN PROGRESS] → [DONE]

License

MIT