Ai Team Orchestration

AI Team Orchestration

When to Use

• Starting a new project that needs planning, development, testing, and deployment
• Setting up parallel AI agent teams (dev, QA, DevOps)
• Writing brainstorm prompts that produce real debate (not generic output)
• Creating sprint plans with cross-chat context survival
• Recovering from context overflow mid-sprint

Team Roles

Customize names and roles for your project. Not every project needs all roles.

Chat Architecture

The human (CEO) is the message bus between parallel chats:

┌────────────────────────────────────────┐
│  @ai-team-producer — Plans, merges     │
│  NEVER writes code                     │
└────────────────┬───────────────────────┘
                 │ Human carries messages
      ┌──────────┼──────────┐
      ▼          ▼          ▼
┌──────────┐ ┌────────┐ ┌────────┐
│@ai-team  │ │@ai-team│ │DevOps  │
│-dev      │ │-qa     │ │(on     │
│          │ │        │ │demand) │
│ Nova     │ │ Ivy    │ │        │
│ Sage     │ │        │ │        │
│ Milo     │ │        │ │        │
│          │ │feature/│ │feature/│
│ feature/ │ │qa-N    │ │devops-N│
│ sprint-N │ └────────┘ └────────┘
└──────────┘

Each team works in a separate VS Code window with its own clone:

git clone <repo> project-dev    # Dev team
git clone <repo> project-qa     # QA
git clone <repo> project-devops # DevOps (only when needed)

Project Bootstrap

1. Create PROJECT_BRIEF.md

The single source of truth across all chats. See the project brief template.

Required sections (do not abbreviate): 1. Project Overview 2. Concept / Product Description 3. Tech Stack 4. Architecture (ASCII diagram) 5. Key Files Map 6. Team Roles 7. Sprint Status (updated every sprint) 8. Current State (rewritten every sprint) 9. Security Rules 10. How to Run Locally 11. How to Deploy 12. Cross-Chat Handoff Protocol — how context survives between chats 13. Bug & Fix Tracking — GitHub Issues as single source of truth 14. Multi-Repo Setup — separate clones, branch strategy, merge rules

2. Run a Brainstorm

See the brainstorm format. Key: name each agent explicitly with distinct personality and perspective. Require at least 2 genuine disagreements to prevent groupthink.

3. Create Sprint Plans

See the sprint plan template. Every sprint gets:

• docs/sprint-N/plan.md — prioritized tasks, success criteria
• docs/sprint-N/progress.md — live tracker, enables recovery
• docs/sprint-N/done.md — handoff doc written at sprint end

4. Execute Sprints

Read PROJECT_BRIEF.md, then read docs/sprint-N/plan.md. Execute Sprint N.

First: git pull origin main && git checkout -b feature/sprint-N

Close GitHub Issues in commits: "fix: description (Fixes #NN)"
Update docs/sprint-N/progress.md after each phase.
When done, push and create PR: git push origin feature/sprint-N
Follow Sections 12-14 of PROJECT_BRIEF.md.

5. QA Sign-off

After dev merges, QA does a full playthrough:

Read PROJECT_BRIEF.md. You are Ivy (QA).
Sprint N is merged to main. Do full playthrough.
File bugs as GitHub Issues. Write docs/qa/sprint-N-signoff.md.

Context Recovery

When a chat gets long (>100 messages), save state and start fresh:

Before closing: 1. Update docs/sprint-N/progress.md with current status 2. Update PROJECT_BRIEF.md sections 7+8 3. Write docs/sprint-N/done.md

Cold start prompt:

Read PROJECT_BRIEF.md and docs/sprint-N/progress.md.
Continue from where it left off.

Anti-Patterns

See anti-patterns reference for the full list. Top 5:

Tips for Better Results

• "Take your time, do it right" in prompts produces better output than rushing
• Test before merge — you playtest, file issues, dev fixes, then merge
• Run team consiliums before major sprints — each agent reviews the plan from their perspective
• Save lessons to memory after every milestone

Anti-Patterns

Lessons learned from real multi-agent projects. Each anti-pattern was encountered at least once and caused real problems.

Git & Branching

Team Roles

Sprint Management

Testing & QA

Context & Communication

Brainstorm Format

Use this format to produce real creative debate — not generic "the team agrees" output. The key is naming each agent explicitly with a distinct personality and perspective.

Prompt Template

You are orchestrating a brainstorm with the [PROJECT NAME] team.
Each member has a DISTINCT voice, perspective, and expertise.
They should DEBATE, build on each other's ideas, and CHALLENGE weak concepts.
This is a creative session — no idea is too wild in Phase 1.

### Kira (Product Designer)
- Thinks about: user delight, accessibility, "would this be fun?"
- Tendency: pushes for features that spark joy, pushes back on anything that feels like homework

### Milo (Art/Visual Director)
- Thinks about: visual identity, cohesion, "does this look and feel right?"
- Tendency: wants everything beautiful, sometimes at odds with engineering feasibility

### Nova (Frontend Engineer)
- Thinks about: component architecture, state management, "can we actually build this?"
- Tendency: pragmatic, flags scope risks, suggests simpler alternatives

### Sage (Backend Engineer)
- Thinks about: data model, API design, security, "where do secrets live?"
- Tendency: security-first, sometimes over-engineers, good at spotting edge cases

### Remy (Producer)
- Thinks about: timeline, scope, "will this ship?"
- Tendency: cuts scope aggressively, keeps the team focused on deliverables

### Ivy (QA Engineer)
- Thinks about: testability, edge cases, "what breaks when the user does X?"
- Tendency: pessimistic about reliability, asks uncomfortable "what if" questions

Phase 1 — Free Ideation:
Each agent pitches 2-3 raw ideas from their perspective.
Wild ideas welcome. No filtering.

Phase 2 — Discussion & Refinement:
Agents debate, combine, and critique ideas.
They reference each other by name: "Kira, that's great but..."
They push back on weak points.
At least 2 genuine disagreements.

Phase 3 — Final Pitches:
3-5 polished concepts.
Each concept includes: name, description, pros, cons, estimated effort.
Team vote with brief justification from each voter.

Output all phases as separate files:
- docs/brainstorm/01-free-ideation.md
- docs/brainstorm/02-discussion.md
- docs/brainstorm/03-concept-[A/B/C...].md (one per concept)
- docs/brainstorm/04-team-vote.md
- docs/brainstorm/05-summary.md

Tips

• Name each agent — "you are the full team" produces bland consensus
• Define tendencies — gives the LLM permission to disagree
• Require disagreements — "at least 2 genuine disagreements" prevents groupthink
• Separate files — forces structured output, makes it reviewable
• Customize personas — adjust for your domain (e.g., replace Kira with a Data Scientist for ML projects)

Mini-Brainstorm (Quick Version)

For smaller decisions:

Run a team brainstorm about [TOPIC].
Each agent speaks separately with their own perspective.
They should debate and disagree.
Write results to docs/[topic]-design.md.

Team Consilium

Before major sprints, validate the plan:

Run a team consilium on the Sprint N plan.
Each agent reviews from their perspective:
- Kira: Is it fun / useful? Missing features?
- Nova: Technically feasible? Scope risks?
- Sage: Security concerns? API design issues?
- Milo: Visual consistency? Design system gaps?
- Ivy: Testable? Edge cases?
- Remy: Timeline realistic? What to cut?

Flag issues and suggest fixes.

PROJECT_BRIEF.md Template

Copy this template to your project root and fill in every section. Do not abbreviate sections 12-14 — they are critical for cross-chat context survival.

---

# PROJECT_BRIEF.md — [Project Name]

> Last updated: [date] | Sprint [N] | Status: [In Progress / Complete]

## 1. Project Overview

[3-4 sentences describing what the project is, who it's for, and the core goal.]

## 2. Concept / Product Description

[Detailed description of the product — user flows, key features, narrative if applicable.]

## 3. Tech Stack

- **Frontend:** [framework, language, key libraries]
- **Backend:** [runtime, framework, database]
- **Hosting:** [platform, CDN, storage]
- **Testing:** [test framework, E2E tool]
- **CI/CD:** [pipeline tool]

## 4. Architecture

┌─────────────────────────────────────────┐ │ Frontend │ │ [Main Component] → [Sub Components] │ └──────────────┬──────────────────────────┘ │ HTTPS ┌──────────────▼──────────────────────────┐ │ Backend API │ │ [Endpoints and their purpose] │ └──────────────┬──────────────────────────┘ │ ┌──────────────▼──────────────────────────┐ │ Storage / Database │ │ [Tables, collections, env vars] │ └─────────────────────────────────────────┘

## 5. Key Files Map

| Area | Path | Contents |
|------|------|----------|
| Entry point | `src/main.tsx` | App bootstrap |
| API | `api/src/` | Server-side logic |
| Config | `api/src/config/` | Server-only configuration |
| Tests | `tests/` | E2E and API tests |
| Sprint docs | `docs/sprint-N/` | Plans, progress, done |

## 6. Team Roles

| Agent | Name | Role |
|-------|------|------|
| Producer | Remy | Sprint plans, coordination, merging |
| Frontend | Nova | UI components, state, client logic |
| Backend | Sage | API, auth, database, security |
| Art/CSS | Milo | Visual design, animations, polish |
| QA | Ivy | Testing, bug filing, sign-off |
| Product | Kira | UX design, mechanics, feature specs |
| DevOps | Dash | CI/CD, deployment, infrastructure |

## 7. Sprint Status

| Sprint | Name | Status | Scope |
|--------|------|--------|-------|
| 0 | Architecture | ✅ Done | Tech stack, project structure, design guide |
| 1 | Core Features | 🔨 In Progress | [scope description] |

## 8. Current State (rewrite every sprint)

**What works:**
- [List of working features]

**What doesn't work yet:**
- [Known issues]

**What's next:**
- [Next sprint goals]

## 9. Security Rules

1. Secrets live in environment variables only — never in code or git.
2. [Auth approach]
3. [Additional security rules]

## 10. How to Run Locally

npm install cd api && npm install cp api/local.settings.json.example api/local.settings.json npm run dev:all

## 11. How to Deploy

[Pipeline description, env var locations, deployment steps]

## 12. Cross-Chat Handoff Protocol

Every sprint chat must do these before finishing:

1. Write `docs/sprint-N/done.md` — what was built, what's not done, what needs manual setup, files changed/created
2. Update PROJECT_BRIEF.md: Section 7 (mark sprint done) + Section 8 (rewrite current state)
3. Commit all changes with descriptive message: `sprint-N: <summary>`

This is how context survives across chats. If skipped, the next chat starts blind and may overwrite or duplicate work. The repo is the shared memory — keep it accurate.

## 13. Bug & Fix Tracking

Bugs are tracked as GitHub Issues on the repo. Single source of truth for all teams.

**For QA:** File bugs as GitHub Issues with labels (`bug`, `severity:blocker/major/minor`). Include: component, steps to reproduce, expected vs actual. When no blockers found: write `docs/qa/sprint-N-signoff.md` with test count, pass rate, explicit "no blockers" statement.

**For Dev Team:** Check GitHub Issues before starting work. Fix blockers and majors before polish. Use GitHub closing keywords in commits: `fix: description (Fixes #42)`. For reference-only, use `Refs #42`.

**For DevOps:** File infrastructure issues with label `infra`.

**For feature ideas:** add to `docs/ideas-backlog.md`.

## 14. Multi-Repo Setup

Each team works in their own separate clone of the repo. No worktrees. Everyone works on their own branch, pushes to origin, creates PRs.

**Teams:**
- Producer on `main` (coordination hub)
- Dev Team on `feature/sprint-N`
- QA on `feature/qa-N`
- DevOps on `feature/devops-N` (only when needed)

**Setup:**

git clone <repo> <folder-name> cd <folder-name> git checkout -b <branch-name> npm install

**Branch strategy:** Feature branches → PR → regular merge to main. Never push directly to main. Never squash. Never rebase feature branches (causes commit loss).

Sprint Plan Template

Plan File

Save as docs/sprint-N/plan.md:

# Sprint N — [Name]

> Sprint Goal: [one sentence describing the deliverable]
> Branch: feature/sprint-N
> Estimated effort: [time estimate]

## Prioritized Task List

| # | Task | Owner | Est | Description |
|---|------|-------|-----|-------------|
| 1 | [task] | Nova | 1h | [what to build] |
| 2 | [task] | Sage | 2h | [what to build] |
| 3 | [task] | Milo | 1h | [what to style] |

## Work Schedule

### Phase 1: [Name] (tasks 1-3)
- Build [component]
- Checkpoint commit after phase

### Phase 2: [Name] (tasks 4-6)
- Build [component]
- Checkpoint commit after phase

### Phase 3: Polish & Integration
- Integration testing
- Bug fixes
- Final commit

## Success Criteria

- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]
- [ ] All tests pass
- [ ] No console errors

## What's NOT in This Sprint

| Feature | Reason |
|---------|--------|
| [cut feature] | [why — scope, complexity, not needed yet] |

## Agent Prompt

> Read PROJECT_BRIEF.md, then read docs/sprint-N/plan.md. Execute Sprint N.
>
> First: git pull origin main && git checkout -b feature/sprint-N
>
> Close GitHub Issues in commits: "fix: description (Fixes #NN)"
> Update docs/sprint-N/progress.md after each phase.
> When done, push and create PR: git push origin feature/sprint-N
> Follow Sections 12-14 of PROJECT_BRIEF.md.

Progress Tracker

Create docs/sprint-N/progress.md at sprint start:

# Sprint N — Progress Tracker

> If context overflows, start a new chat:
> "Read PROJECT_BRIEF.md and docs/sprint-N/progress.md.
>  Continue from where it left off."

## Task Status

| # | Task | Status | Notes |
|---|------|--------|-------|
| 1 | [task] | ⬜ Not started | |
| 2 | [task] | 🔨 In progress | |
| 3 | [task] | ✅ Done | |
| 4 | [task] | ❌ Blocked | [reason] |

## Bugs Found

| # | Description | Severity | Status | Fix |
|---|-------------|----------|--------|-----|
| 1 | [bug] | blocker/major/minor | open/fixed | [commit or PR] |

## Notes

[Free-form notes about decisions, issues, or context for recovery]

Done File

Write docs/sprint-N/done.md at sprint end:

# Sprint N — Done

## What Was Built
- [Feature 1]
- [Feature 2]

## What's NOT Done
- [Deferred item — why]

## Files Changed/Created
- `src/components/NewComponent.tsx` — [purpose]
- `api/src/functions/newEndpoint.ts` — [purpose]

## Manual Setup Required
- [Any env vars, config, or manual steps needed]

## Known Issues
- [Issue — tracked as GitHub Issue #NN]

QA Sign-off Template

# QA Sprint N Sign-Off

Date: [date]
Tester: Ivy (QA)

## Test Results
- Tests run: X
- Tests passed: X
- Tests failed: 0

## Blockers
NONE

## Issues Filed
- #NN — [description] (severity: minor)

## Result
✅ PASS — No blockers. Sprint N is ready to merge.