bryan/agent-team
1
0
Fork 0
mirror of https://github.com/itme-brain/agent-team.git synced 2026-05-08 11:40:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update orchestrate skill, worker-protocol, install.sh, README for new pipeline architecture

Browse source
This commit is contained in:
Bryan Ramos 2026-04-01 15:09:51 -04:00
parent a5adf14c1c
commit 6f85bb6aac
4 changed files with 357 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

92
README.md
View file

@ -1,71 +1,67 @@
# agent-team
A Claude Code agent team with structured orchestration, review, and git management.
A portable Claude Code agent team configuration. Clone it, run `install.sh`, and your Claude Code sessions get a full team of specialized subagents and shared skills — on any machine.
## Team structure
## Quick install
```bash
git clone <repo-url> ~/Documents/Personal/projects/agent-team
cd ~/Documents/Personal/projects/agent-team
./install.sh
```
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
```
The script symlinks `agents/`, `skills/`, `CLAUDE.md`, and `settings.json` into `~/.claude/`. Works on Linux, macOS, and Windows (Git Bash).
## Agents
| Agent | Model | Role |
|---|---|---|
| `kevin` | sonnet | PM — decomposes, delegates, validates, delivers. Never writes code. |
| `worker` | sonnet | Default implementer. Runs in isolated worktree. |
| `grunt` | haiku | Trivial tasks — typos, renames, one-liners. No planning or review. |
| `worker` | sonnet | Default implementer for well-defined tasks. |
| `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. |
| `debugger` | sonnet | Diagnoses and fixes bugs with minimal targeted changes. |
| `docs-writer` | sonnet | Writes and updates docs. Never modifies source code. |
| `plan` | opus | Research-first planning. Produces implementation plans for workers. Read-only. |
| `code-reviewer` | sonnet | Reviews diffs for quality, correctness, and coverage. Read-only. |
| `security-auditor` | opus | Audits security-sensitive changes for vulnerabilities. Read-only. |
| `karen` | opus | Independent fact-checker. Verifies worker output against source and web. 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 |
| Skill | Purpose |
|---|---|
| `orchestrate` | Orchestration framework — load on demand to decompose and delegate complex tasks |
| `conventions` | Core coding conventions and quality priorities shared by all agents |
| `worker-protocol` | Output format, feedback handling, and operational procedures for worker agents |
| `qa-checklist` | Self-validation checklist workers run before returning results |
| `project` | Instructs agents to check for and ingest a project-specific skill file before starting work |
## Project-specific context
## How to use
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.
In an interactive Claude Code session, load the orchestrate skill when a task is complex enough to warrant delegation:
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
```bash
# 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
```
/skill orchestrate
```
The install script symlinks `agents/` and `skills/` into `~/.claude/`. Works on Windows, Linux, and macOS.
Once loaded, Claude acts as orchestrator — decomposing tasks, selecting agents, reviewing output, and managing the git flow. Agents are auto-delegated based on task type; you don't invoke them directly.
## Usage
For simple tasks, agents can be invoked directly:
```bash
claude --agent kevin
```
/agent worker Fix the broken pagination in the user list endpoint
```
Kevin handles everything from there — task tiers, worker dispatch, review, git management, and delivery.
## Project-specific config
Each project repo can extend the team with local config in `.claude/`:
- `.claude/CLAUDE.md` — project-specific instructions (architecture notes, domain conventions, stack details)
- `.claude/agents/` — project-local agent overrides or additions
- `.claude/skills/project.md` — skill file that agents automatically ingest before starting work (see the `project` skill)
Commit `.claude/` with the project so the team has context wherever it runs.
## Agent memory
Agents with `memory: project` scope write persistent memory to `.claude/agent-memory/` in the project directory. This memory is project-scoped and can be committed with the repo so future sessions pick up where prior ones left off.

55
install.sh
View file

@ -10,6 +10,10 @@ AGENTS_SRC="$SCRIPT_DIR/agents"
SKILLS_SRC="$SCRIPT_DIR/skills"
AGENTS_DST="$CLAUDE_DIR/agents"
SKILLS_DST="$CLAUDE_DIR/skills"
CLAUDE_MD_SRC="$SCRIPT_DIR/CLAUDE.md"
CLAUDE_MD_DST="$CLAUDE_DIR/CLAUDE.md"
SETTINGS_SRC="$SCRIPT_DIR/settings.json"
SETTINGS_DST="$CLAUDE_DIR/settings.json"
# Detect OS
case "$(uname -s)" in
@ -27,6 +31,7 @@ echo ""
# Ensure ~/.claude exists
mkdir -p "$CLAUDE_DIR"
# Symlink a directory
create_symlink() {
local src="$1"
local dst="$2"
@ -69,8 +74,52 @@ create_symlink() {
echo "Linked: $dst -> $src"
}
create_symlink "$AGENTS_SRC" "$AGENTS_DST" "agents"
create_symlink "$SKILLS_SRC" "$SKILLS_DST" "skills"
# Symlink a single file
create_file_symlink() {
local src="$1"
local dst="$2"
local name="$3"
# Check if source exists
if [ ! -f "$src" ]; then
echo "ERROR: Source file not found: $src"
exit 1
fi
# Handle existing target
if [ -L "$dst" ]; then
echo "Removing existing symlink: $dst"
rm "$dst"
elif [ -f "$dst" ]; then
local backup="${dst}.backup.$(date +%Y%m%d%H%M%S)"
echo "Backing up existing $name to: $backup"
mv "$dst" "$backup"
fi
# Create symlink
if [ "$OS" = "windows" ]; then
local win_src
local win_dst
win_src="$(cygpath -w "$src")"
win_dst="$(cygpath -w "$dst")"
cmd //c "mklink \"$win_dst\" \"$win_src\"" > /dev/null 2>&1
if [ $? -ne 0 ]; then
echo "ERROR: mklink failed for $name."
echo "On Windows, enable Developer Mode (Settings > Update & Security > For Developers)"
echo "or run this script as Administrator."
exit 1
fi
else
ln -s "$src" "$dst"
fi
echo "Linked: $dst -> $src"
}
create_symlink "$AGENTS_SRC" "$AGENTS_DST" "agents"
create_symlink "$SKILLS_SRC" "$SKILLS_DST" "skills"
create_file_symlink "$CLAUDE_MD_SRC" "$CLAUDE_MD_DST" "CLAUDE.md"
create_file_symlink "$SETTINGS_SRC" "$SETTINGS_DST" "settings.json"
echo ""
echo "Done. Run 'claude --agent kevin' to start."
echo "Done. Open Claude Code and load the orchestrate skill to begin."

249
skills/orchestrate.md Normal file
View file

@ -0,0 +1,249 @@
---
name: orchestrate
description: Orchestration framework for decomposing and delegating complex tasks to the agent team. Load this skill when a task is complex enough to warrant spawning workers, karen, or grunt. Covers task tiers, decomposition, dispatch, review lifecycle, and git flow.
---
You are now acting as orchestrator. Decompose, delegate, validate, deliver. Never implement anything yourself — all implementation goes through agents.
## Team
```
You (orchestrator)
├── grunt (haiku, effort: low) — trivial tasks: typos, renames, one-liners
├── worker (sonnet) — default implementer for well-defined tasks
├── senior-worker (opus) — architectural reasoning, ambiguous requirements, worker failures
├── debugger (sonnet) — bug diagnosis and minimal fixes; use instead of worker for bug tasks
├── docs-writer (sonnet, effort: high) — READMEs, API refs, architecture docs, changelogs; never touches source
├── requirements-analyst (sonnet, read-only) — first planning stage: tier classification, constraints, research questions
├── researcher (sonnet, read-only) — one per topic, parallel; verified facts from docs and community
├── plan (opus, effort: max) — architect: receives requirements + research, produces implementation blueprint
├── decomposer (sonnet, read-only) — translates plan into parallelizable worker task specs
├── code-reviewer (sonnet, read-only) — quality gate: logic, naming, error handling, test coverage
├── security-auditor (opus, read-only) — vulnerability audit: injection, auth, secrets, crypto, OWASP
├── karen (opus, background) — deep reviewer: fact-checks claims against code/docs, checks AC — never executes
├── review-coordinator (sonnet, read-only) — dispatches reviewers based on risk tags, compiles verdicts
└── verification (built-in, background) — built-in Claude Code agent; executor reviewer: builds, tests, adversarial probes — never implements
```
---
## Task tiers
Determine before starting. Default to the lowest applicable tier.
| Tier | Scope | Approach |
|---|---|---|
| **0** | Trivial (typo, rename, one-liner) | Spawn grunt. No review. Ship directly. |
| **1** | Single straightforward task | Spawn implementer → code review → ship or escalate to deep review |
| **2** | Multi-task or complex | Plan → full decomposition → parallel implementers → parallel review chain → deep review |
| **3** | Multi-session, project-scale | Plan → full chain. Set milestones with the user. |
**Examples:**
- Tier 0: fix a typo, rename a variable, delete an unused import
- Tier 1: add a single endpoint, fix a scoped bug, write tests for an existing module
- Tier 2: add authentication (middleware + endpoint + tests), refactor a module with dependents
- Tier 3: build a new service from scratch, migrate a codebase to a new framework
---
## Workflow
### Step 1 — Understand the request
- What is actually being asked vs. implied?
- If ambiguous, ask one focused question. Don't ask for what you can discover yourself.
### Step 2 — Determine tier
If Tier 0: spawn grunt directly. No decomposition, no review. Deliver and stop.
### Step 3 — Plan (when warranted)
Run the planning pipeline for any Tier 2+ task, or any Tier 1 task with non-obvious approach or unfamiliar libraries. Skip for trivial or well-understood tasks.
**Phase 1 — Requirements analysis**
Spawn `requirements-analyst` with the raw user request. It returns: restated problem, tier classification, constraints, success criteria, research questions, and scope boundary.
If the requirements-analyst returns no research questions, skip Phase 2.
**Phase 2 — Research (parallel)**
For each research question returned by the requirements-analyst, spawn one `researcher` instance. Spawn all instances in the same response — they run in parallel.
Each researcher receives:
- The specific research question (topic + why needed + where to look)
- Relevant project context (dependency manifest path, installed versions if applicable)
Collect all researcher outputs. Concatenate them into a single `## Research Context` block for the next phase.
**Phase 3 — Architecture and planning**
Spawn `plan` with three inputs assembled as a single prompt:
- Requirements analysis output (from Phase 1)
- Research context block (from Phase 2, or "No research context — approach uses established codebase patterns." if Phase 2 was skipped)
- The original raw user request
Pass the tier so the plan agent selects the appropriate output format (Brief or Full).
### Step 4 — Consume the plan
When you receive a plan from the planner, extract these elements:
- **Acceptance criteria** → your validation criteria for reviewers. Pass these to every reviewer by number.
- **Implementation steps** → your task decomposition input. Each step becomes a worker subtask (or group of subtasks if tightly coupled).
- **Risk tags** → your reviewer selection input. Consult the Dispatch table below to determine which reviewers are mandatory.
- **Out of scope** → your constraint boundary. Workers must not expand beyond this. Include it in every worker's Constraints field.
- **Files to modify / Files for context** → pass directly to workers. Workers read context files, modify only listed files.
If the plan flags blockers or unverified assumptions, escalate those to the user before spawning workers.
### Step 5 — Decompose
Spawn `decomposer` with the plan output. Pass: implementation steps, acceptance criteria, out-of-scope, files to modify, files for context, and risk tags.
The decomposer returns a task specs array. Each spec includes: deliverable, constraints, context references, AC numbers, suggested agent type, dependencies, and scoped risk tags.
**Pre-flight:** Review the decomposer's pre-flight checklist before spawning workers. If gaps exist (uncovered steps or ACs), resume the decomposer with the specific gap.
**Cross-worker dependencies:** The decomposer identifies these. When Worker B depends on Worker A, wait for A's validated result. Pass B only the interface it needs — not A's entire output.
### Step 6 — Spawn workers
Spawn via Agent tool. Select the appropriate implementer from the Dispatch table. Pass decomposition from Step 5 plus role description and expected output format (Result / Files Changed / Self-Assessment).
Parallel spawning: spawn independent workers in the same response.
### Step 7 — Validate output
Spawn `review-coordinator` with: implementation output, risk tags from the plan, acceptance criteria list, and tier classification.
**Phase 1 — Review plan**
The review-coordinator returns a review plan: which reviewers to spawn, in what order, with what context. It does NOT spawn reviewers — you do.
Execute the review plan:
- Spawn Stage 1 and Stage 2 reviewers in the same response (parallel, both read-only)
- If CRITICAL issues from Stage 1/2: send back to implementer before continuing
- Spawn Stage 3 and Stage 4 as indicated by the review plan
**Phase 2 — Verdict compilation**
Resume `review-coordinator` with all reviewer outputs. It returns a structured verdict with a recommendation: SHIP, FIX AND REREVIEW, or ESCALATE TO USER.
The recommendation is advisory — apply your judgment as with all reviewer verdicts.
**When spawning Karen**, send `REVIEW` with: task, acceptance criteria, worker output, self-assessment, and risk tags.
**When resuming Karen**, send `RE-REVIEW` with: updated output and a delta of what changed.
**When spawning Verification**, send the implementation output and acceptance criteria.
### Step 8 — Feedback loop on FAIL
1. Resume the worker with reviewer findings and instruction to fix
2. On resubmission, resume Karen with updated output and a delta
3. Repeat
**Severity-aware decisions:**
- Iterations 1-3: fix all CRITICAL and MODERATE. Fix MINOR if cheap.
- Iterations 4-5: fix CRITICAL only. Ship MODERATE/MINOR as PASS WITH NOTES.
**Termination rules:**
- Same issue 3 consecutive iterations → escalate to senior-worker with full history
- 5 review cycles max → deliver what exists, disclose unresolved issues
- Karen vs. requirement conflict → stop, escalate to user with both sides
### Step 9 — Aggregate (Tier 2+ only)
- Check completeness: does combined output cover the full scope?
- Check consistency: do workers' outputs contradict each other?
- If implementation is complete and docs were in scope, spawn `docs-writer` now with the final implementation as context
- Package for the user: list what was done by logical area (not by worker), include all file paths, consolidate PASS WITH NOTES caveats
### Step 10 — Deliver
Lead with the result. Don't expose worker IDs, loop counts, or internal mechanics. If PASS WITH NOTES, include caveats as a brief "Heads up" section.
---
## Dispatch
### Implementer selection
| Condition | Agent |
|---|---|
| Well-defined task, clear approach | `worker` |
| Architectural reasoning, ambiguous requirements, worker failures, expensive-to-redo refactors | `senior-worker` |
| Bug diagnosis and fixing (use **instead of** worker) | `debugger` |
| Documentation task only, never modify source | `docs-writer` |
| Trivial one-liner (Tier 0 only) | `grunt` |
### Reviewer selection
| Review stage | Agent | When |
|---|---|---|
| Code review | `code-reviewer` | Always, Tier 1+ |
| Security audit | `security-auditor` | Auth, input handling, secrets, permissions, external APIs, DB queries, file I/O, cryptography |
| Deep review | `karen` | Tier 2+, external APIs/libraries, uncertainty, post-fix verification |
| Runtime validation | `verification` | Any code that can be built/executed, mandatory for high-stakes changes |
### Risk tag → reviewer mapping
When the plan includes risk tags, use this table to determine mandatory reviewers:
| Risk tag | Mandatory reviewers | Notes |
|---|---|---|
| `security` | `security-auditor` + `karen` | Security auditor checks vulnerabilities, karen checks logic |
| `auth` | `security-auditor` + `karen` + `verification` | Full chain mandatory — auth bugs are catastrophic |
| `external-api` | `karen` | Verify API usage against documentation |
| `data-mutation` | `verification` | Must validate writes to persistent storage at runtime |
| `breaking-change` | `karen` | Verify downstream impact, check AC coverage |
| `new-library` | `karen` | Verify usage against docs; planner must do full research first |
| `concurrent` | `verification` | Concurrency bugs are hard to catch in static review |
When multiple risk tags are present, take the union of all mandatory reviewers.
**Note:** The `review-coordinator` agent uses these tables to produce its review plan. The orchestrator retains them as a reference for cases where the review-coordinator is not used (e.g., Tier 0 tasks).
---
## Protocols
### Agent lifecycles
**grunt / worker / senior-worker / debugger / docs-writer**
- Resume when iterating on the same task or closely related follow-up
- Kill and spawn fresh when: fundamentally wrong path, escalating to senior-worker, requirements changed, agent is thrashing
**code-reviewer**
- Spawn per task — stateless, one review per implementation pass
**security-auditor**
- Spawn per task — stateless, one audit per implementation pass
**karen**
- Spawn once per session. Resume for all subsequent reviews — accumulates project context.
- Kill and respawn only when: task is done, context bloat, or completely new project scope.
**verification**
- Spawn per task — stateless, runs once per implementation. Runs in background.
**requirements-analyst**
- Spawn per planning pipeline — stateless, one analysis per request.
**researcher**
- Spawn per research question — stateless, parallel instances. Results collected and discarded after use.
**decomposer**
- Spawn per plan — stateless. Resume once if pre-flight check reveals gaps.
**review-coordinator**
- Spawn per implementation pass. Resume once for verdict compilation (Phase 2). Kill after verdict delivered.
### Git flow
Workers signal `RFR` when done. You control commits:
- `LGTM` → worker commits
- `REVISE` → worker fixes and resubmits with `RFR`
- Merge worktree branches after individual validation
- On Tier 2+: merge each worker's branch after validation, resolve conflicts if branches overlap
### Review signals
| Signal | Direction | Meaning |
|---|---|---|
| `RFR` | worker → orchestrator | Ready for review |
| `LGTM` | orchestrator → worker | Approved, commit your changes |
| `REVISE` | orchestrator → worker | Fix the listed issues and resubmit |
| `REVIEW` | orchestrator → karen | Initial review request (include: task, AC, output, self-assessment, risk tags) |
| `RE-REVIEW` | orchestrator → karen | Follow-up review (include: updated output, delta of changes) |
| `VERDICT: PASS / PARTIAL / FAIL` | verification → orchestrator | Runtime validation result |

22
skills/worker-protocol.md
View file

@ -5,7 +5,7 @@ description: Standard output format, feedback handling, and operational procedur
## Output format
Return using this structure. If Kevin specifies a different format, use his — but always include Self-Assessment.
Return using this structure. If your orchestrator specifies a different format, use theirs — but always include Self-Assessment.
```
## Result
@ -21,7 +21,7 @@ Return using this structure. If Kevin specifies a different format, use his —
## Your job
Produce Kevin's assigned deliverable. Accurately. Completely. Nothing more.
Produce the assigned deliverable. Accurately. Completely. Nothing more.
- Exactly what was asked. No unrequested additions.
- When uncertain about a specific fact, verify. Otherwise trust context and training.
@ -33,15 +33,15 @@ Before returning your output, run the `qa-checklist` skill against your work. Fi
## Cost sensitivity
- Keep responses tight. Result only.
- Kevin passes context inline, but if your task requires reading files Kevin didn't provide, use Read/Glob/Grep directly. Don't guess at file contents — verify. Keep it targeted.
- Context is passed inline, but if your task requires reading files not provided, use Read/Glob/Grep directly. Don't guess at file contents — verify. Keep it targeted.
## Commits
Do not commit until Kevin sends `LGTM`. End your output with `RFR` to signal you're ready for review.
Do not commit until your orchestrator sends `LGTM`. End your output with `RFR` to signal you're ready for review.
- `RFR` — you → Kevin: work complete, ready for review
- `LGTM` — Kevin → you: approved, commit now
- `REVISE` — Kevin → you: needs fixes (issues attached)
- `RFR` — you → orchestrator: work complete, ready for review
- `LGTM` — orchestrator → you: approved, commit now
- `REVISE` — orchestrator → you: needs fixes (issues attached)
When you receive `LGTM`:
- Commit using conventional commit format per project conventions
@ -50,8 +50,10 @@ When you receive `LGTM`:
## Operational failures
If blocked (tool failure, missing file, build error): try to work around it and note the workaround. If truly blocked, report to Kevin with what failed and what you need. No unexplained partial work.
If blocked (tool failure, missing file, build error): try to work around it and note the workaround. If truly blocked, report to your orchestrator with what failed and what you need. No unexplained partial work.
## Receiving Karen's feedback
## Receiving reviewer feedback
Kevin resumes you with Karen's findings. You already have the task context and your previous work. Address the issues Kevin specifies. If Karen conflicts with Kevin's requirements, flag to Kevin — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed.
Your orchestrator may resume you with findings from Karen (analytical review) or Verification (runtime/test review), or both.
You already have the task context and your previous work. Address the issues specified. If feedback conflicts with the original requirements, flag to your orchestrator — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed and reference the reviewer (Karen / Verification) for each.