Skip to content

Overview

This document describes a reusable multi-agent framework for optimization software development. The framework organizes agents into four teams---Research, Dev, KB, and QA---plus a shadow validation mode, all coordinated by a manager who owns the kanban and co-plans with the user.

Key Point

The framework is project-agnostic. Install it using the base+override layer architecture: core framework in .claude/teamdev/ (safe to overwrite on upgrade), project customizations in .claude/project/ (never overwritten). Configure project-config.md with project-specific paths and settings.

Design Principles

  1. Atomic tasks. Each agent executes one small task at a time. The user decomposes and directs.
  2. Developer/reviewer pairs. Every artifact is created by a developer and challenged by a reviewer (red team).
  3. Execution-grounded verification. Reviewers run code and tests, not just inspect.
  4. Adversarial defense. Reviewer has veto on high-severity findings.
  5. Explicit handoffs. Cross-team communication uses defined bridge mechanisms, not implicit assumptions.
  6. Shadow validation. KB quality is tested by reimplementation: if the docs are good enough, a fresh agent can rebuild the system without seeing the source.
  7. Tree-structured knowledge. All information is organized as a navigable tree: an index points to cards (or categories of cards when the collection grows). Agents retrieve knowledge the way a researcher uses a library---consult the index first, then pull the relevant material. This keeps lookup cost proportional to what is needed, not to the total size of the knowledge base.
  8. Base + override layers. Core framework and project customizations are cleanly separated. Upgrading the framework is a single copy operation that preserves all project-specific changes.

Installation

  1. Copy the template into your project: 
    mkdir -p .claude/teamdev .claude/project/{docs,skills,scripts}
cp -r claude_teamdev/{README.md,TODO.md,VERSION.md,MIGRATION.md,docs,skills,scripts} .claude/teamdev/
cp claude_teamdev/skills/general/project-config.md .claude/project/project-config.md
  2. Edit .claude/project/project-config.md with project-specific paths, language, build commands, and benchmark configuration.
  3. Start working: load the manager skill, ask it to decompose your request, then direct individual agents.

Resource Map — Integrating Existing Project Content

Most projects already have test scripts, benchmark suites, example folders, or data directories. The resource map in project-config.md tells agents where these live so they use them instead of reinventing them.

resources:
  - path: "quicktest/"
    role: "quick-validation"
    description: "Quick smoke test on small problem subset"
    run_cmd: "bash quicktest/run.sh"
    notes: "quicktest/README.md"

Agents consult the resource map before running tests, benchmarks, or looking for examples. The resource map lives in .claude/project/ so it survives framework upgrades.

See Upgrade Guide for full details on the base+override architecture.

Single Source of Truth

The docs/ directory contains both operational guidelines and documentation. There is no separate guidelines/ directory. Agents read protocols from docs/; MkDocs renders the same files as a website. One file, two audiences.