agent-team

A Claude Code agent team with structured orchestration, review, and git management.

Team structure

User (invokes via `claude --agent kevin`)
  └── Kevin (sonnet) ← PM and orchestrator
        ├── Grunt (haiku) ← trivial tasks (Tier 0)
        ├── Workers (sonnet) ← default implementers
        ├── Senior Workers (opus) ← complex/architectural tasks
        └── Karen (sonnet, background) ← independent reviewer, fact-checker

Agents

Agent	Model	Role
kevin	sonnet	PM — decomposes, delegates, validates, delivers. Never writes code.
worker	sonnet	Default implementer. Runs in isolated worktree.
senior-worker	opus	Escalation for architectural complexity or worker failures.
grunt	haiku	Lightweight worker for trivial one-liners.
karen	sonnet	Independent reviewer and fact-checker. Read-only, runs in background.

Skills

Skill	Used by	Purpose
conventions	All agents	Coding conventions, commit format, quality priorities
worker-protocol	Workers, Senior Workers	Output format, commit flow (RFR/LGTM/REVISE), feedback handling
qa-checklist	Workers, Senior Workers	Self-validation checklist before returning output
project	All agents	Instructs agents to check for and ingest .claude/skills/project.md if present

Project-specific context

To provide agents with project-specific instructions — architecture notes, domain conventions, tech stack details — create a .claude/skills/project.md file in your project repo. All agents will automatically check for and ingest it before starting work.

This file is yours to write and maintain. Commit it with the project so it's always present when the team is invoked.

Communication signals

Signal	Direction	Meaning
RFR	Worker → Kevin	Work complete, ready for review
LGTM	Kevin → Worker	Approved, commit now
REVISE	Kevin → Worker	Needs fixes (issues attached)
REVIEW	Kevin → Karen	New review request
RE-REVIEW	Kevin → Karen	Updated output after fixes
PASS / PASS WITH NOTES / FAIL	Karen → Kevin	Review verdict

Installation

# Clone the repo
git clone <repo-url> ~/Documents/projects/agent-team
cd ~/Documents/projects/agent-team

# Run the install script (creates symlinks to ~/.claude/)
./install.sh

The install script symlinks agents/ and skills/ into ~/.claude/. Works on Windows, Linux, and macOS.

Usage

claude --agent kevin

Kevin handles everything from there — task tiers, worker dispatch, review, git management, and delivery.