# Deep Dive: wshobson/agents (Verified Against Source)

**Date**: 2026-03-04 (updated with source verification)
**Source**: https://github.com/wshobson/agents
**Stars**: 30.2k | **License**: MIT (Conductor: Apache-2.0)
**Scale**: 72 plugins, 112 agents, 146 skills, 79 tools, 24 categories
**Version**: 1.5.5

---

## Table of Contents

1. [Plugin Architecture](#1-plugin-architecture)
2. [Agent Frontmatter](#2-agent-frontmatter)
3. [Skill Progressive Disclosure](#3-skill-progressive-disclosure)
4. [3-Tier Model Strategy](#4-3-tier-model-strategy)
5. [TDD Workflows Plugin](#5-tdd-workflows-plugin)
6. [Conductor Pattern](#6-conductor-pattern)
7. [Agent Teams](#7-agent-teams)
8. [Command Format](#8-command-format)
9. [Verdict Summary](#9-verdict-summary)

---

## 1. Plugin Architecture

### 1.1 Directory Structure (verified)

Each plugin is an isolated directory under `plugins/` with a **mandatory** `.claude-plugin/` config dir:

```
plugins/python-development/
  .claude-plugin/
    plugin.json                   # Per-plugin manifest (REQUIRED)
  agents/
    python-pro.md                 # Agent .md with YAML frontmatter
    django-pro.md
    fastapi-pro.md
    temporal-python-pro.md
  commands/
    python-scaffold.md            # Slash command (invoked as /python-development:python-scaffold)
  skills/
    async-python-patterns/
      SKILL.md                    # Progressive disclosure skill
    python-testing-patterns/
      SKILL.md
    python-packaging/
      SKILL.md
    python-performance-optimization/
      SKILL.md
    uv-package-manager/
      SKILL.md
```

Four component types:
- **`.claude-plugin/plugin.json`** -- per-plugin manifest (required)
- **`agents/`** -- domain-expert agent .md files (optional, loaded when plugin installs)
- **`commands/`** -- slash command .md files (optional, `/plugin:command` syntax)
- **`skills/`** -- modular knowledge packages with progressive disclosure (optional)

### 1.2 Per-Plugin Manifest (verified from source)

**File**: `.claude-plugin/plugin.json`

Verified examples from real source:

```json
// plugins/python-development/.claude-plugin/plugin.json
{
  "name": "python-development",
  "version": "1.2.1",
  "description": "Modern Python development with Python 3.12+, Django, FastAPI, async patterns, and production best practices",
  "author": {
    "name": "Seth Hobson",
    "email": "seth@major7apps.com"
  },
  "license": "MIT"
}
```

```json
// plugins/conductor/.claude-plugin/plugin.json
{
  "name": "conductor",
  "version": "1.2.1",
  "description": "Context-Driven Development plugin that transforms Claude Code into a project management tool with structured workflow: Context -> Spec & Plan -> Implement",
  "author": {
    "name": "Seth Hobson",
    "email": "seth@major7apps.com"
  },
  "license": "Apache-2.0"
}
```

**Per-plugin manifest schema:**

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | Yes | string | kebab-case, matches directory name |
| `version` | Yes | string | semver |
| `description` | Yes | string | one-line summary |
| `author` | Yes | object | `{ name, email? }` |
| `license` | Yes | string | MIT or Apache-2.0 |

**Important**: No `category`, `homepage`, or `source` fields in the per-plugin manifest. Those are only in the root-level marketplace catalog.

### 1.3 Root Marketplace Catalog (verified)

**File**: `.claude-plugin/marketplace.json` (at repository root)

This is the aggregated catalog with **additional fields** not present in per-plugin manifests:

```json
{
  "name": "kubernetes-operations",
  "source": "plugins/kubernetes-operations",
  "description": "K8s architect, tools, 4 skills",
  "version": "1.3.0",
  "author": { "name": "Seth Hobson" },
  "homepage": "https://github.com/wshobson/agents",
  "license": "MIT",
  "category": "infrastructure"
}
```

Additional catalog-only fields: `source` (relative path), `homepage`, `category`.

### 1.4 Two-Level Discovery

**Level 1 -- Marketplace**: Root `.claude-plugin/marketplace.json` is the browsable catalog.
**Level 2 -- Plugin**: Each plugin's `.claude-plugin/plugin.json` is the authoritative manifest.

Content within the plugin (agents, commands, skills) is discovered by **directory convention**, not listed in any manifest.

### 1.5 Installation/Removal

```bash
# Step 1: Add marketplace (makes all 72 plugins discoverable)
/plugin marketplace add wshobson/agents

# Step 2: Install individual plugins
/plugin install python-development
/plugin install kubernetes-operations

# Step 3: Browse without loading
/plugin marketplace list

# Step 4: Use via slash commands or natural language
/tdd-workflows:tdd-cycle <feature description>
# or: "Use python-pro to optimize this function"
```

Installed plugins tracked in `~/.claude/plugins/installed_plugins.json`.
Cache at `~/.claude/plugins/cache/claude-code-workflows/`.

### 1.6 Plugin Dependencies

**There is no explicit inter-plugin dependency mechanism.** Plugins are fully independent by design. Each plugin "does one thing well" (Unix philosophy). Complex workflows are achieved by installing multiple plugins, not by declaring plugin-to-plugin dependencies.

Cross-plugin orchestration happens through Claude Code's natural language routing (e.g., "use backend-architect to design the API, then test-automator to create tests").

### 1.7 Minimum Requirements

- `.claude-plugin/plugin.json` manifest
- At least one agent OR one command
- Clear, focused purpose

### iEvo Verdict: ADAPT

**What to adopt:**
- Plugin = isolated directory with `.claude-plugin/` + `agents/` + `commands/` + `skills/` convention
- Two-level discovery: per-plugin manifest + root catalog
- "Install what you need" -- selective loading over monolithic install
- Convention-based content discovery (scan dirs, don't list files in manifest)

**What to change for iEvo:**
- iEvo already has `registry.yaml` (YAML, not JSON). Extend it with plugin grouping
- iEvo needs agent dependencies (spec-writer -> architect -> coder pipeline). Add `dependencies` at plugin level -- wshobson deliberately skips this but iEvo's pipeline is sequential
- iEvo uses Python (pluggy) for plugin mechanics. wshobson is pure Claude Code `/plugin`. iEvo plugins can be both: .md bundles for content + Python hooks for behavior
- Use `plugin.yaml` (not JSON) per-plugin for consistency with iEvo's YAML preference

**Proposed iEvo plugin.yaml per-plugin:**
```yaml
name: sdd-pipeline
version: 0.2.0
description: "Spec-driven development pipeline"
category: core
author: iEvo
license: Apache-2.0
# agents, commands, skills discovered by directory convention (not listed here)
dependencies:
  - evolution  # iEvo addition: pipeline needs evolution agent
```

---

## 2. Agent Frontmatter

### 2.1 Exact Fields (verified from source)

Every agent .md was fetched and verified. Here are the **actual** frontmatter fields:

**Example 1 -- python-pro.md (verified):**
```yaml
---
name: python-pro
description: Master Python 3.12+ with modern features, async programming, performance optimization, and production-ready practices. Expert in the latest Python ecosystem including uv, ruff, pydantic, and FastAPI. Use PROACTIVELY for Python development, optimization, or advanced Python patterns.
model: opus
---
```

**Example 2 -- conductor-validator.md (verified):**
```yaml
---
name: conductor-validator
description: Validates Conductor project artifacts for completeness, consistency, and correctness. Use after setup, when diagnosing issues, or before implementation to verify project context.
tools: Read, Glob, Grep, Bash
model: opus
color: cyan
---
```

**Example 3 -- tdd-orchestrator.md (verified):**
```yaml
---
name: tdd-orchestrator
description: Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices. Enforces TDD best practices across teams with AI-assisted testing and modern frameworks. Use PROACTIVELY for TDD implementation and governance.
model: opus
---
```

**Example 4 -- team-lead.md (verified):**
```yaml
---
name: team-lead
description: Team orchestrator that decomposes work into parallel tasks with file ownership boundaries, manages team lifecycle, and synthesizes results. Use when coordinating multi-agent teams, decomposing complex tasks, or managing parallel workstreams.
tools: Read, Glob, Grep, Bash
model: opus
color: blue
---
```

### 2.2 Complete Field Reference (verified)

| Field | Required | Values | Notes |
|-------|----------|--------|-------|
| `name` | Yes | kebab-case string | Same as filename minus `.md` |
| `description` | Yes | String, <1024 chars | Includes "Use when..." or "Use PROACTIVELY for..." activation triggers |
| `model` | Yes | `opus` / `sonnet` / `haiku` | Direct Anthropic model names |
| `tools` | No | Comma-separated string | `Read, Glob, Grep, Bash, Write, Edit` -- only on agents that need restriction |
| `color` | No | CSS/terminal color name | `cyan`, `blue` -- visual distinction in TUI |

**NOT present in any wshobson agent (verified):**
- No `tier` field -- model names hardcoded directly
- No `skills` field -- skill activation is proximity-based within plugin
- No `hooks` field
- No `memory` field
- No `version` field on agents (only on plugins in plugin.json)
- No `category` field on agents

### 2.3 Key Pattern: "Use PROACTIVELY" / "Use when"

The `description` field doubles as an **activation trigger** for Claude's native agent routing. Two observed patterns:

1. **"Use PROACTIVELY for..."** -- tells Claude to auto-delegate without being asked:
   > "Use PROACTIVELY for Python development, optimization, or advanced Python patterns."

2. **"Use when..."** / **"Use after..."** -- conditional activation:
   > "Use after setup, when diagnosing issues, or before implementation to verify project context."

This is the **primary routing mechanism**. Claude Code reads all agent descriptions and matches user requests against them. No custom routing code exists.

**iEvo comparison**: iEvo's spec-writer already uses "ALWAYS invoke this agent FIRST when the user describes a new feature". Same pattern, slightly different phrasing.

### 2.4 Comparison with iEvo Agent Frontmatter

iEvo's current spec-writer.md (verified from source):
```yaml
---
name: spec-writer
description: >
  Requirements analyst for the iEvo SDD pipeline. ALWAYS invoke this agent FIRST
  when the user describes a new feature, asks to add functionality, requests a change,
  or says anything like "I want", "add", "build", "change", "update", "implement", or
  "we need". Do NOT jump to planning or coding -- decompose requirements first.
  Produces atomic, testable REQ-xxx specs in .ievo/spec/requirements/.
  Also handles change requests (CR-xxx) when the user asks to modify existing behaviour.
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
memory: user
skills:
  - evo
---
```

**iEvo has more fields than wshobson:**
- `tools` as YAML list (vs comma-separated string in wshobson)
- `memory: user` -- persistent cross-project learning (wshobson has nothing equivalent)
- `skills` -- explicit skill binding (wshobson uses proximity-based activation)

### iEvo Verdict: KEEP CURRENT + ADD TWO FIELDS

iEvo's frontmatter is already richer. Add:

1. **`tier: 1|2|3`** -- abstract model tier for multi-provider mapping
   - `tier: 1` = critical (maps to Opus/GPT-4o/etc per provider)
   - `tier: 2` = complex (maps to Sonnet/GPT-4.1/etc)
   - `tier: 3` = fast (maps to Haiku/GPT-4.1-mini/etc)
   - Keep `model` as optional override (backward compat)

2. **`color`** -- nice-to-have for TUI visualization (agents table, pipeline view)

**Do NOT adopt:**
- wshobson's comma-separated tools format (iEvo's YAML list is better)
- Dropping `memory` and `skills` fields (iEvo needs explicit binding for multi-provider support)
- Proximity-based skill activation (works for Claude-only; iEvo needs explicit binding for multi-provider)

---

## 3. Skill Progressive Disclosure

### 3.1 Three-Tier Architecture (verified from source)

```
plugins/{plugin-name}/skills/{skill-name}/SKILL.md
```

All three tiers live in a **single SKILL.md file**. There are no separate files for tiers.

**Tier 1 -- Metadata (always in context):**
YAML frontmatter with `name`, `description`, and optional `version`.

**Verified from context-driven-development/SKILL.md:**
```yaml
---
name: context-driven-development
description: >-
  Creates and maintains project context artifacts (product.md, tech-stack.md, workflow.md, tracks.md)
  in a `conductor/` directory. Scaffolds new projects from scratch, extracts context from existing
  codebases, validates artifact consistency before implementation, and synchronizes documents as the
  project evolves. Use when setting up a project, creating or updating product docs, managing a tech
  stack file, defining development workflows, tracking work units, onboarding to an existing codebase,
  or running project scaffolding.
version: 1.0.0
---
```

**Verified from async-python-patterns/SKILL.md:**
```yaml
---
name: async-python-patterns
description: Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.
---
```

**Tier 2 -- Instructions (loaded when skill is activated):**
The markdown body below the frontmatter. Claude loads this when the skill's description matches the user's request.

**Tier 3 -- Resources (implicit, loaded on demand):**
Code examples, templates, and supplementary materials within the body. Claude reads these lazily -- only the sections relevant to the current task. This is NOT a separate file or directory; it's structural within the same SKILL.md.

### 3.2 Skill Frontmatter Fields (verified)

| Field | Required | Notes |
|-------|----------|-------|
| `name` | Yes | kebab-case |
| `description` | Yes | Includes "Use when..." activation trigger |
| `version` | No | Semver (present in some skills, absent in others) |

### 3.3 Activation Mechanism (verified)

Skills activate via **Claude's native skill detection** based on the `description` field's "Use when" clause. No custom routing code.

When a user request matches the skill's description pattern:
1. Claude loads the SKILL.md body (Tier 2)
2. Claude selectively reads relevant sections (Tier 3 effect)

### 3.4 Skill Content Structure -- async-python-patterns (verified section headings)

Progressive disclosure within the SKILL.md body itself:

```
# Async Python Patterns
# When to Use This Skill                    <-- Decision framework
# Sync vs Async Decision Guide              <-- Quick reference table
# Core Concepts                             <-- Fundamentals
  ## Event Loop
  ## Coroutines
  ## Tasks
  ## Futures
  ## Async Context Managers
  ## Async Iterators
# Quick Start                               <-- Onboarding
# Fundamental Patterns                      <-- Level 2
  ## Pattern 1: Basic Async/Await
  ## Pattern 2: Concurrent Execution with gather()
  ## Pattern 3: Task Creation and Management
  ## Pattern 4: Error Handling in Async Code
  ## Pattern 5: Timeout Handling
# Advanced Patterns                         <-- Level 3
  ## Pattern 6: Async Context Managers
  ## Pattern 7: Async Iterators and Generators
  ## Pattern 8: Producer-Consumer Pattern
  ## Pattern 9: Semaphore for Rate Limiting
  ## Pattern 10: Async Locks and Synchronization
# Real-World Applications                   <-- Level 4
  ## Web Scraping with aiohttp
  ## Async Database Operations
  ## WebSocket Server
# Performance Best Practices                <-- Level 5
# Common Pitfalls
# Testing Async Code
# Resources
# Best Practices Summary
```

Five levels of graduated complexity:
1. **Decision framework**: When to use this? (quick assessment)
2. **Core concepts**: What are the building blocks?
3. **Fundamental patterns**: 5 basic patterns (enough for most tasks)
4. **Advanced patterns**: 5 advanced patterns (for complex scenarios)
5. **Production**: Performance, pitfalls, testing (for deployment)

Claude naturally discloses progressively -- it does not dump all 5 levels at once.

### 3.5 Skill Content Structure -- context-driven-development (verified section headings)

```
# Context-Driven Development
## When to Use This Skill
## Core Philosophy
## The Workflow
## Artifact Relationships
## Context Maintenance Principles
## Greenfield vs Brownfield Handling
## Benefits
## Directory Structure
## Context Lifecycle
## Context Validation Checklist
## Common Anti-Patterns
## Integration with Development Tools
## Session Continuity
## Best Practices
```

Different structure from async-python-patterns: organized by **workflow** rather than by **complexity level**. Both patterns work -- the structure should match the skill's nature.

### iEvo Verdict: ADAPT

**What to adopt:**
- SKILL.md format with frontmatter (name, description, version) -- iEvo already uses this
- "Use when..." activation triggers in description -- iEvo already does this for `/evo`
- Graduated complexity within skill body (decision framework -> fundamentals -> advanced -> production)
- Pattern: all tiers in one file (not separate files per tier)

**What iEvo already has (keep):**
- iEvo's `/evo` skill already has SKILL.md format with frontmatter -- correct
- iEvo's `/backlog` skill lacks frontmatter -- needs migration

**What to add for iEvo:**
- Convert `/backlog` to include YAML frontmatter with `name`, `description`, "Use when..." trigger
- For complex skills (e.g., a future `/tdd` skill), use the graduated 5-level structure
- Consider adding `resources/` subdirectory per skill for templates (Tier 3 as separate files)

**Proposed iEvo skill migration:**
```yaml
# skills/backlog/SKILL.md -- CURRENT (no frontmatter)
# /backlog -- Quick Idea Capture

# skills/backlog/SKILL.md -- PROPOSED (add frontmatter)
---
name: backlog
description: >-
  Quick idea capture into .ievo/backlog/. Use when you have a raw idea,
  improvement suggestion, or quick note that should be saved for later review.
  Not for formal proposals -- just fast capture.
---
# /backlog -- Quick Idea Capture
...
```

---

## 4. 3-Tier Model Strategy

### 4.1 Tier Distribution (verified from docs/agents.md)

The README mentions 4 tiers (including "Inherit") but the actual `model` field in agent files uses only **3 values**: `opus`, `sonnet`, `haiku`.

**IMPORTANT DISCREPANCY**: The README categorizes `python-pro` as Sonnet (Tier 2), but the actual `python-pro.md` file has `model: opus`. This means the README's tier counts may not match reality. The actual frontmatter is the source of truth.

| Model | README Count | Docs Count | Purpose |
|-------|-------------|------------|---------|
| Opus | 42 | 42 | Critical architecture, security, ALL code review, AI/ML, production coding |
| Sonnet | 39-51 | 39 | Complex tasks, language expertise, testing, debugging |
| Haiku | 18 | 18 | Fast operations, SEO, simple docs, content generation |

The "Inherit" tier (42 agents) mentioned in the README appears to be a display artifact -- these agents have a concrete `model` value in their frontmatter.

### 4.2 Which Agents Get Which Tier and WHY (verified)

**Opus -- Critical decisions and security:**
- ALL architects: backend-architect, graphql-architect, cloud-architect, kubernetes-architect, database-architect, service-mesh-expert, event-sourcing-architect, monorepo-architect, docs-architect, hybrid-cloud-architect, design-system-architect
- ALL security: security-auditor, backend-security-coder, frontend-security-coder, mobile-security-coder, threat-modeling-expert
- ALL code review: code-reviewer, architect-reviewer, conductor-validator
- ALL AI/ML: ai-engineer, ml-engineer, mlops-engineer, prompt-engineer, vector-database-engineer
- ALL UI/UX design: ui-designer, accessibility-expert
- Business critical: hr-pro, legal-advisor, quant-analyst, data-scientist
- Operations critical: incident-responder, performance-engineer, observability-engineer
- Team: team-lead, team-reviewer, team-debugger, team-implementer
- Language pros (some): python-pro (verified `model: opus`)

**Key insight**: wshobson uses Opus for ANY agent that makes decisions with expensive consequences if wrong. "The higher per-token cost is offset by fewer tokens needed" -- Opus gets complex tasks right in fewer iterations.

**Sonnet -- Complex reasoning, not security-critical:**
- Most language pros: typescript-pro, rust-pro, golang-pro, java-pro, c-pro, cpp-pro, etc.
- Testing: test-automator, tdd-orchestrator
- Debugging: debugger, error-detective, devops-troubleshooter
- Frontend: frontend-developer, mobile-developer, ios-developer, flutter-expert
- Infrastructure: deployment-engineer, terraform-specialist, network-engineer
- Documentation: api-documenter, tutorial-engineer, mermaid-expert, c4-component, c4-container, c4-context
- Business: business-analyst, content-marketer, customer-support, risk-manager
- Some SEO: seo-content-auditor, seo-authority-builder, seo-content-writer

**Haiku -- Fast, templated, repetitive:**
- SEO bulk operations: seo-meta-optimizer, seo-keyword-strategist, seo-structure-architect, seo-snippet-hunter, seo-content-refresher, seo-cannibalization-detector, seo-content-planner
- Simple documentation: reference-builder, c4-code
- Operations: search-specialist, context-manager, sales-automator

### 4.3 Model Override

The `model` field is **hardcoded** in each agent's YAML frontmatter. There is no per-project override mechanism in wshobson's system.

Users can override by running Claude with `--model opus` which promotes all agents to Opus, but there is no selective per-agent override.

### 4.4 Token Savings Logic

1. **Opus efficiency**: Complex tasks take ~65% fewer tokens because Opus gets it right in fewer iterations
2. **Haiku for bulk work**: 18 agents use the cheapest model for repetitive/templated work (SEO, simple docs)
3. **Hybrid pipeline**: Planning (Opus) -> Execution (Sonnet) -> Fast ops (Haiku)

### 4.5 Mapping to iEvo's Agents (verified against iEvo registry.yaml)

| iEvo Agent | Current Model | wshobson Logic | Recommended | Change? |
|------------|---------------|----------------|-------------|---------|
| spec-writer | sonnet | Complex reasoning | Tier 2 (Sonnet) | No change |
| architect | opus | Architecture = critical | Tier 1 (Opus) | No change |
| coder | sonnet | Implementation = complex | Tier 2 (Sonnet) | No change |
| code-reviewer | **sonnet** | Code review = ALWAYS Opus in wshobson | **Tier 1 (Opus)** | **UPGRADE** |
| qa | sonnet | Testing = complex | Tier 2 (Sonnet) | No change |
| acceptance | **sonnet** | Quality gate = critical decision | **Tier 1 (Opus)** | **UPGRADE** |
| docs | haiku | Simple documentation | Tier 3 (Haiku) | No change |
| evolution | sonnet | Pattern analysis = complex | Tier 2 (Sonnet) | No change |
| researcher | opus | Research = critical decisions | Tier 1 (Opus) | No change |
| defrag | haiku | Fast consistency scan | Tier 3 (Haiku) | No change |
| tech-lead | sonnet | Infrastructure = complex | Tier 2 (Sonnet) | No change |
| debugger | sonnet | Debug = complex reasoning | Tier 2 (Sonnet) | No change |
| hr | sonnet | Agent management = complex | Tier 2 (Sonnet) | No change |

**Key changes**: Upgrade `code-reviewer` and `acceptance` to Opus. In wshobson, ALL code review agents use Opus -- no exceptions. The logic: code review is a quality gate where missing a bug is more expensive than the extra cost of Opus.

### iEvo Verdict: ADAPT

**What to adopt:**
- The logic of WHY each tier: critical decisions = Opus, complex reasoning = Sonnet, fast ops = Haiku
- Upgrade code-reviewer and acceptance to Opus (both are quality gates)
- Hybrid orchestration: Opus (architecture/review) -> Sonnet (implementation) -> Haiku (docs)

**What to change for iEvo:**
- Use abstract `tier: 1|2|3` in frontmatter, not model names directly
- Tier-to-model mapping in manifest.yaml (per-project configurable):
  ```yaml
  model_tiers:
    1: opus      # Claude provider
    2: sonnet
    3: haiku
  ```
- This is iEvo's multi-provider advantage: `tier: 1` maps to Opus on Claude, GPT-4o on OpenAI, etc.

---

## 5. TDD Workflows Plugin

### 5.1 Plugin Structure (verified)

```
plugins/tdd-workflows/
  .claude-plugin/
    plugin.json                 # {"name":"tdd-workflows","version":"1.3.0","license":"MIT"}
  agents/
    code-reviewer.md            # Code review agent (model: opus)
    tdd-orchestrator.md         # TDD master (model: opus)
  commands/
    tdd-cycle.md                # Full red-green-refactor cycle (12 steps, 6 phases)
    tdd-red.md                  # Write failing tests only
    tdd-green.md                # Implement to pass tests
    tdd-refactor.md             # Refactor with passing tests
```

### 5.2 TDD Cycle Command (verified from source)

The `/tdd-workflows:tdd-cycle` command implements a **12-step, 6-phase** process with **4 user checkpoints**.

**Phase 1 -- Test Specification & Design (Steps 1-2)**
1. Requirements analysis -> `.tdd-cycle/01-requirements.md`
   - Subagent analyzes acceptance criteria
   - Identifies edge cases: null/empty values, boundaries, error states, concurrency
   - Creates test scenario matrix
2. Test architecture design -> `.tdd-cycle/02-test-architecture.md`
   - Test structure, fixture strategy, mock/stub approach
   - Execution ordering
- **CHECKPOINT 1**: User reviews and approves specifications

**Phase 2 -- RED (Steps 3-4)**
3. Write failing unit tests -> `.tdd-cycle/03-failing-tests.md`
   - Arrange-Act-Assert pattern
   - Naming: `should_X_when_Y`
   - Tests deliberately fail due to missing implementation
4. Verify all tests fail correctly -> `.tdd-cycle/04-failure-verification.md`
   - Code-reviewer agent confirms tests fail appropriately
   - No false positives (accidental passes)
- **CHECKPOINT 2**: User approves failing tests

**Phase 3 -- GREEN (Steps 5-6)**
5. Minimal implementation -> `.tdd-cycle/05-implementation.md`
   - Only code necessary to pass tests
   - No optimization, no feature creep
   - Documents shortcuts for refactor phase
6. Verify all tests pass + coverage -> `.tdd-cycle/06-green-verification.md`
   - Must achieve 100% pass rate
   - Coverage meets thresholds
- **CHECKPOINT 3**: User approves green tests

**Phase 4 -- REFACTOR (Steps 7-8)**
7. Code refactoring (SOLID) -> `.tdd-cycle/07-refactored-code.md`
   - Triggers: cyclomatic complexity >10, method >20 lines, class >200 lines, duplication >3 lines
   - Tests must remain green throughout
8. Test refactoring -> `.tdd-cycle/08-refactored-tests.md`
   - Extract common fixtures
   - Improve test names for documentation value
- **CHECKPOINT 4**: User approves refactored code/tests

**Phase 5 -- Integration & Extended Testing (Steps 9-11)**
9. Integration tests (RED) -> `.tdd-cycle/09-integration-tests.md`
10. Integration implementation -> `.tdd-cycle/10-integration-impl.md`
11. Performance & edge cases -> `.tdd-cycle/11-extended-tests.md`

**Phase 6 -- Final Review (Step 12)**
12. Comprehensive code review -> `.tdd-cycle/12-final-review.md`

### 5.3 State Management (verified)

`.tdd-cycle/state.json` tracks:
- Feature name and execution mode (incremental/suite)
- Coverage target (default 80% line, 75% branch, 100% critical path)
- Current step and completed steps log
- Session timestamps

Pre-flight validation: detects existing sessions (resume/fresh/archive).

### 5.4 Modes (verified)

- **Full mode** (default): Write all tests, then implement all
- **Incremental mode** (`--incremental`): Write ONE failing test -> make it pass -> refactor -> next test

### 5.5 Anti-Pattern Detection (verified)

The system explicitly rejects:
- Implementation before tests
- Tests already passing at RED phase
- Skipping refactor phase
- Modifying tests to make them pass
- Multi-feature development without test coverage

**Failure recovery protocol**:
1. Stop execution immediately
2. Identify violated phase
3. Rollback to last valid state
4. Resume from correct phase checkpoint
5. Document lesson in state.json

### 5.6 Coverage Targets (verified)

- Line coverage: configurable via `--coverage N` (default 80%)
- Branch coverage: 75% minimum
- Critical path: 100% (no exceptions)

### 5.7 Enforcement Rules (verified)

1. Sequential execution -- no skipping, reordering, or merging steps
2. File-based state -- each step outputs to `.tdd-cycle/` and reads prior outputs (avoids context window dependency)
3. Mandatory checkpoints -- 4 user approval gates
4. Failure halting -- any step failure triggers immediate stop
5. Local agents only -- uses bundled agents, no cross-plugin dependencies
6. No autonomous planning -- executes predefined workflow, rejects `EnterPlanMode` requests

### 5.8 Comparison with iEvo

| Feature | wshobson TDD Cycle | iEvo Coder |
|---------|-------------------|------------|
| Test-first | Enforced (RED before GREEN) | CLAUDE.md rule (100% coverage) |
| Checkpoints | 4 user approval gates | No formal checkpoints |
| State tracking | `.tdd-cycle/state.json` | Session journal in memory/ |
| Step artifacts | 12 separate .md files | Single session log |
| Coverage targets | Configurable (80%/75%/100%) | Hard 100% in CLAUDE.md |
| Incremental mode | `--incremental` flag | Not available |
| Refactor phase | Explicit separate phase | Implicit in coding |
| Integration tests | Explicit Phase 5 | Mixed into single phase |
| Anti-pattern detection | Explicit enforcement | No detection |
| Failure recovery | Rollback to last valid state | Manual recovery |

### iEvo Verdict: ADAPT (as a skill, not plugin replacement)

**What to adopt:**
- The 6-phase structure (spec -> RED -> GREEN -> REFACTOR -> integration -> review)
- User checkpoints at phase transitions
- `.tdd-cycle/state.json` for resumable TDD sessions
- Anti-pattern detection (tests passing before implementation = wrong)
- Step artifacts for audit trail
- Refactor triggers (cyclomatic complexity >10, method >20 lines, class >200 lines)

**What NOT to adopt:**
- Replacing iEvo's Coder agent (the Coder does more than TDD)
- The code-reviewer in this plugin (iEvo already has its own)
- The full 12-step ceremony for every change (overkill for small fixes)
- The 80% coverage default (iEvo enforces 100%)

**Proposed integration:**
- Create a `/tdd` skill in iEvo marketplace that iEvo's Coder agent can activate
- The skill teaches the Coder the 6-phase discipline
- For large features (REQ-xxx), Coder activates the skill; for small fixes, direct implementation
- State tracking in `.ievo/tdd-sessions/` instead of `.tdd-cycle/`
- Override coverage to 100% (iEvo's standard)

---

## 6. Conductor Pattern

### 6.1 What is Conductor? (verified)

A **context-driven development** system. License: Apache-2.0 (not MIT like other plugins).

Core philosophy: **Context -> Spec & Plan -> Implement**

Plugin manifest (verified):
```json
{
  "name": "conductor",
  "version": "1.2.1",
  "description": "Context-Driven Development plugin that transforms Claude Code into a project management tool with structured workflow: Context -> Spec & Plan -> Implement",
  "author": { "name": "Seth Hobson", "email": "seth@major7apps.com" },
  "license": "Apache-2.0"
}
```

### 6.2 Directory Structure (verified)

```
conductor/
  index.md                  # Navigation hub with quick links
  product.md                # Product vision & goals
  product-guidelines.md     # Voice, tone, design principles
  tech-stack.md             # Languages, frameworks, databases, infra
  workflow.md               # TDD policy, commit conventions, review rules
  tracks.md                 # Master track registry (table format)
  setup_state.json          # Resumable setup state
  code_styleguides/         # Language-specific style guides
    python.md
    typescript.md
  tracks/
    _archive/               # Archived tracks
    user-auth_20250115/     # Track directory
      spec.md               # Requirements specification
      plan.md               # Phased task breakdown
      metadata.json         # Track metadata (type, dates, status, commits)
      index.md              # Track navigation
```

### 6.3 Track/Phase/Task Hierarchy (verified)

**Track** = a feature, bug, chore, or refactor. Named `{shortname}_{YYYYMMDD}`.

**Phase** = a logical grouping of tasks within a track's plan.md.

**Task** = an individual work item. Status in plan.md:
- `[ ]` -- pending
- `[~]` -- in progress
- `[x]` -- complete

Status tracked in both plan.md (checkboxes) and metadata.json (counters, commit history).

### 6.4 Track Implementation with TDD (verified)

When TDD is enabled in `conductor/workflow.md`, each task follows:
1. **Red**: Write failing tests
2. **Green**: Implement minimal passing code
3. **Refactor**: Clean up while maintaining test success

**Critical**: "Wait for explicit user approval before proceeding to next phase." Mandatory verification gates between phases.

**State persistence**: All state in `conductor/tracks/{trackId}/metadata.json`:
- Current phase and task position
- Completion counts
- Commit history for rollback
- Timestamps for resumption

**Resume behavior**: Reconstructs state from metadata, offers user: continue / restart / review.

### 6.5 Semantic Revert (verified from source)

The `/conductor:revert` command implements git-aware undo by logical work unit.

**Command frontmatter (verified):**
```yaml
---
description: "Git-aware undo by logical work unit (track, phase, or task)"
argument-hint: "[track-id | track-id:phase | track-id:task]"
---
```

**Usage:**
```bash
# Revert entire track
/conductor:revert auth_20250115

# Revert from phase 2 onwards
/conductor:revert auth_20250115:phase2

# Revert a single task
/conductor:revert auth_20250115:task2.3
```

**Execution flow (verified):**
1. Pre-flight: check `conductor/tracks.md` exists, check git status, warn on uncommitted changes/active merge/rebase
2. Target selection: guided menu if no argument provided
3. Discover commits: grep git log for track ID + task/phase identifiers
4. Display execution plan: affected commits, modified files, task status changes
5. Require exact "YES" confirmation (not 'y', not Enter)
6. Execute `git revert --no-edit` in reverse chronological order
7. Update plan.md markers from `[x]` back to `[ ]`
8. Update metadata.json counters

**Safety rules (verified):**
- NEVER `git reset --hard`
- NEVER force push
- NEVER auto-resolve merge conflicts -- halt immediately
- Always preserve history via revert commits
- Immediate halt on any error

### 6.6 Setup Flow (verified)

`/conductor:setup` creates project context through structured Q&A with state persistence.

**Five phases:**
1. Product Definition (5 questions max): name, description, problem, users, goals
2. Product Guidelines (3 questions max): voice/tone, design principles
3. Tech Stack (5 questions max): languages, frameworks, databases, infra
4. Workflow Preferences (4 questions max): TDD enforcement, commits, reviews, checkpoints
5. Code Style Guides (2 questions max): which languages, existing linting

**Rules (verified):**
- One question per turn
- 2-3 suggested answers + custom option
- State saved after each step in `setup_state.json`
- Resumable across sessions
- Brownfield detection: scans existing configs to pre-populate choices

### 6.7 Track Lifecycle

```
/conductor:new-track   -->  pending       (spec.md + plan.md created)
/conductor:implement   -->  in-progress   (TDD phases with checkpoints)
/conductor:status      -->  monitoring    (progress tracking)
/conductor:manage      -->  archive / restore / delete / rename / cleanup
/conductor:revert      -->  undo by logical unit
```

### 6.8 Comparison with iEvo SDD Pipeline

| Feature | Conductor | iEvo SDD |
|---------|-----------|----------|
| Project context | conductor/ with product.md, tech-stack.md, workflow.md | .ievo/ with manifest.yaml, CONTEXT.md, VOCABULARY.md |
| Work units | Tracks (feature/bug/chore/refactor) | REQ-xxx requirements |
| Planning | Interactive Q&A -> spec.md + plan.md per track | Spec Writer -> Architect -> PLAN-REQ-xxx.md |
| Implementation | /conductor:implement with TDD phases | Coder agent follows PLAN |
| Status tracking | plan.md checkboxes + metadata.json | SPEC_INDEX.md status column |
| Revert | Semantic revert by track/phase/task | **Gap: manual git operations** |
| State persistence | setup_state.json, metadata.json | Session journal in memory/ |
| Pipeline enforcement | workflow.md rules | CLAUDE.md + agent instructions |
| Archive | /conductor:manage archive | **Gap: not implemented** |
| Validation | conductor-validator agent | defrag agent (partial) |
| Resume | State-based resume across sessions | Session-based resume |

### iEvo Verdict: ADOPT SELECTIVELY

**Adopt:**

1. **Semantic revert** -- Major gap in iEvo. Ability to revert by REQ-xxx or task using `git revert` (not reset) is powerful and safe. Propose as `/revert` skill.

2. **Per-REQ metadata** -- iEvo's SPEC_INDEX.md is a flat table. Adding per-REQ metadata (type, dates, phase counts, commit history) in a structured YAML/JSON file would enable: resume, revert, progress tracking, archival.

3. **Track archival** -- Completed REQs pile up in SPEC_INDEX.md. An archive mechanism (`status: archived` + move to `.ievo/spec/archive/`) would reduce noise.

4. **Validation report format** -- conductor-validator uses structured severity (CRITICAL/WARNING/INFO). iEvo's defrag agent should adopt this.

5. **Resumable state** -- Conductor's state.json pattern for resuming across sessions. Apply to iEvo's init and TDD flows.

**Skip:**
- Conductor's project context model (product.md, tech-stack.md) -- iEvo has its own
- Interactive Q&A setup -- iEvo init is fast and non-interactive by design
- Replacing REQ-xxx with "tracks" -- iEvo's spec-driven approach is more structured

---

## 7. Agent Teams

### 7.1 Requirements (verified)

```bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

Uses Claude Code's experimental `Teammate` tool for spawning parallel agents.

Display modes:
- `tmux` (recommended) -- separate terminal panes per agent
- `iterm2` -- iTerm2 tabs
- `in-process` -- shared process (default)

### 7.2 Team Agents (verified frontmatter)

```yaml
# team-lead.md (verified)
---
name: team-lead
description: Team orchestrator that decomposes work into parallel tasks with file ownership boundaries, manages team lifecycle, and synthesizes results. Use when coordinating multi-agent teams, decomposing complex tasks, or managing parallel workstreams.
tools: Read, Glob, Grep, Bash
model: opus
color: blue
---
```

4 specialized team agents, ALL Opus:

| Agent | Model | Tools | Purpose |
|-------|-------|-------|---------|
| team-lead | Opus | Read, Glob, Grep, Bash | Decomposes tasks, assigns file ownership, synthesizes results |
| team-reviewer | Opus | (default) | Multi-dimensional code analysis |
| team-debugger | Opus | (default) | Hypothesis-driven investigation (ACH) |
| team-implementer | Opus | (default) | Builds features within file ownership boundaries |

### 7.3 Presets (7 configurations, verified)

| Preset | Agents | Purpose |
|--------|--------|---------|
| review | 3 | Parallel security + performance + architecture analysis |
| debug | 3 | Competing hypothesis investigation (ACH method) |
| feature | 1 lead + 2 implementers | Parallel development with file ownership |
| fullstack | 4+ | Frontend + backend + testing + coordination |
| research | 3 | Codebase exploration from different angles |
| security | 4 | OWASP + auth + dependencies + secrets audits |
| migration | 1 lead + 2 implementers + 1 reviewer | Coordinated codebase transformation |

### 7.4 File Ownership Model (verified)

**Verified from team-lead.md body**: "One owner per file -- Never assign the same file to multiple teammates."

Each teammate receives exclusive control over assigned files/directories. When boundaries require coordination, teammates establish **interface contracts** beforehand rather than sharing files directly.

### 7.5 Team Feature Development (verified from team-feature.md)

**Command frontmatter (verified):**
```yaml
---
description: "Develop features in parallel with multiple agents using file ownership boundaries and dependency management"
argument-hint: "<feature-description> [--team-size N] [--branch feature/name] [--plan-first]"
---
```

**7-phase execution flow (verified):**
1. **Analysis**: Codebase exploration for scope and patterns
2. **Decomposition**: Feature broken into non-overlapping work streams with interface contracts
3. **Team spawn**: Git branch creation + `Teammate` tool with `operation: "spawnTeam"` + agents
4. **Task creation**: `TaskCreate` with owned files + requirements + acceptance criteria
5. **Monitoring**: Progress tracking + `TaskUpdate` with `blockedBy` dependencies + issue detection
6. **Verification**: Build + test execution + issue resolution
7. **Cleanup**: Summary + `shutdown_request` to all teammates

### 7.6 ACH Debugging (verified from team-debug.md)

**Command frontmatter (verified):**
```yaml
---
description: "Debug issues using competing hypotheses with parallel investigation by multiple agents"
argument-hint: "<error-description-or-file> [--hypotheses N] [--scope files|module|project]"
---
```

**6-phase ACH protocol (verified):**
1. **Triage**: Analyze error, identify failure symptoms, gather context (recent changes, related tests)
2. **Hypothesis generation**: Create N hypotheses across 6 failure categories:
   - Logic errors
   - Data issues
   - State problems
   - Integration failures
   - Resource issues
   - Environmental factors
3. **Investigation**: Spawn parallel investigator agents via `Teammate`, each assigned a hypothesis with scope boundaries
4. **Evidence collection**: Monitor task completion, track supporting/contradicting evidence
5. **Arbitration**: Rank hypotheses by confidence, causal strength, evidence quality, absence of contradictions. Present structured root cause analysis
6. **Cleanup**: Shutdown all investigators

### 7.7 Team Communication Protocol (verified from team-lead.md)

Three-tier communication:
- **`message`** (direct) -- routine teammate coordination
- **`broadcast`** (team-wide) -- critical alerts only (expensive, use sparingly)
- **`shutdown_request`** -- graceful termination

Anti-patterns: broadcasting routine updates, sending JSON status blobs, micromanaging ("checks in at milestones, not every step").

### iEvo Verdict: TRACK (Phase 2)

**Adopt when ready:**
- File ownership model (prevent conflicts in parallel execution)
- 7 preset team configurations
- ACH hypothesis-driven debugging (can work sequentially even without parallel agents)
- Three-tier communication protocol

**Near-term quick win (before Phase 2):**
- Port ACH debugging as a skill for iEvo's existing `debugger` agent
- The debugger tests hypotheses sequentially: generate N hypotheses -> investigate each -> rank by evidence

**Skip:**
- Direct dependency on `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` (Claude-specific)
- tmux/iterm2 display modes (iEvo has its own TUI)

---

## 8. Command Format

### 8.1 Slash Command .md Files (verified)

Commands are .md files in `plugins/{name}/commands/` with **minimal frontmatter** and a prompt body.

**Verified command frontmatter fields:**

| Field | Required | Notes |
|-------|----------|-------|
| `description` | Yes | One-line summary of what the command does |
| `argument-hint` | No | Template showing expected arguments |

No `name` field -- the filename IS the command name.

**Examples (verified from source):**

```yaml
# tdd-red.md
---
description: "Write comprehensive failing tests following TDD red phase principles"
argument-hint: "<feature or component to write tests for>"
---
```

```yaml
# new-track.md
---
description: "Create a new track with specification and phased implementation plan"
argument-hint: "<feature|bug|chore|refactor> <name>"
---
```

```yaml
# revert.md
---
description: "Git-aware undo by logical work unit (track, phase, or task)"
argument-hint: "[track-id | track-id:phase | track-id:task]"
---
```

### 8.2 Command Invocation

```bash
/plugin-name:command-name [arguments]

# Examples:
/tdd-workflows:tdd-cycle implement user authentication --incremental
/tdd-workflows:tdd-red user login form
/conductor:new-track feature payment-processing
/conductor:revert auth_20250115:phase2
```

### 8.3 Command Body

The body is a **parameterized instruction template** with `$ARGUMENTS` placeholder for user input. Not a code file -- it's a prompt that Claude executes.

### iEvo Verdict: ADAPT

iEvo's current skills (`/evo`, `/backlog`) are already similar to wshobson commands -- .md files with instructions. The key difference is iEvo uses skills (loaded into agent context) while wshobson uses commands (invoked as slash commands).

**What to adopt:**
- The `argument-hint` field -- useful for `/tdd <feature>`, `/revert <REQ-xxx>`, etc.
- The `$ARGUMENTS` pattern for parameterized skills

**Proposed iEvo skill frontmatter extension:**
```yaml
---
name: tdd
description: >-
  Enforce 6-phase TDD discipline on the current task.
  Use when implementing a REQ-xxx with test-first methodology.
argument-hint: "<REQ-xxx or feature description> [--incremental]"
---
```

---

## 9. Verdict Summary

### Adopt As-Is (low effort, high impact)

| Pattern | Source | iEvo Action | Effort |
|---------|--------|-------------|--------|
| "Use PROACTIVELY" in descriptions | Agent frontmatter | Audit all 13 agent descriptions for activation triggers | Low |
| Upgrade code-reviewer to Opus | Model strategy | Change `model: opus` in frontmatter + registry | Trivial |
| Upgrade acceptance to Opus | Model strategy | Change `model: opus` in frontmatter + registry | Trivial |
| Add frontmatter to /backlog skill | Skill format | Add `name` + `description` with "Use when" trigger | Trivial |
| Validation severity format | Conductor validator | Adopt CRITICAL/WARNING/INFO in defrag agent | Low |

### Adapt (medium effort, high impact)

| Pattern | Source | iEvo Action | Effort |
|---------|--------|-------------|--------|
| Abstract tier field | Model strategy | Add `tier: 1\|2\|3` to frontmatter + mapping in manifest | Medium |
| Plugin directory convention | Plugin architecture | Reorganize marketplace into plugin dirs with plugin.yaml | Medium |
| Graduated skill content | Progressive disclosure | Restructure complex skill .md files with levels | Medium |
| `/tdd` skill with 6 phases | TDD workflows | Create TDD skill for Coder agent with state.json | Medium |
| `/revert` semantic revert | Conductor | Create revert skill for REQ-level undo via git revert | Medium |
| ACH debugging skill | Agent teams | Create debugging skill with 6-category hypothesis framework | Medium |
| `argument-hint` in skill frontmatter | Command format | Add argument templates to skills | Low |
| `color` field in agent frontmatter | Agent format | Add color for TUI visualization | Low |

### Track for Phase 2+ (high effort, high impact)

| Pattern | Source | iEvo Action | Effort |
|---------|--------|-------------|--------|
| Parallel agent teams | Agent teams | Requires PTY bridge + process isolation | High |
| File ownership model | Agent teams | Requires parallel execution first | High |
| 7 team presets | Agent teams | Configurations for review/debug/feature/etc | Medium |
| Per-REQ metadata.json | Conductor | Structured metadata per requirement | Medium |
| REQ archival | Conductor manage | Archive completed REQs to reduce noise | Low |
| Setup resumability | Conductor | State.json for resumable ievo init | Medium |

### Skip (low applicability or already covered)

| Pattern | Reason |
|---------|--------|
| marketplace.json format (JSON) | iEvo already has registry.yaml (YAML preferred) |
| Conductor setup Q&A | iEvo init is deliberately fast/non-interactive |
| Full Conductor project context model | iEvo has its own (manifest, CONTEXT.md, VOCABULARY.md) |
| Comma-separated tools in frontmatter | iEvo's YAML list is better |
| Dropping memory/skills fields | iEvo needs explicit binding for multi-provider |
| Proximity-based skill activation | Works for Claude-only; iEvo needs explicit binding |

---

## Appendix A: Verified Source Files

All files verified via raw fetch from `https://github.com/wshobson/agents/`:

| File | What was verified |
|------|-------------------|
| `README.md` | Project overview, counts, tier table |
| `.claude-plugin/marketplace.json` | Root catalog schema (72 entries) |
| `plugins/python-development/.claude-plugin/plugin.json` | Per-plugin manifest schema |
| `plugins/tdd-workflows/.claude-plugin/plugin.json` | TDD plugin manifest |
| `plugins/conductor/.claude-plugin/plugin.json` | Conductor manifest (Apache-2.0) |
| `plugins/python-development/agents/python-pro.md` | Agent frontmatter (`model: opus`, no tier/skills/memory) |
| `plugins/tdd-workflows/agents/tdd-orchestrator.md` | TDD agent frontmatter |
| `plugins/conductor/agents/conductor-validator.md` | Agent with `tools` and `color` fields |
| `plugins/agent-teams/agents/team-lead.md` | Team agent with `tools` and `color` |
| `plugins/conductor/skills/context-driven-development/SKILL.md` | Skill frontmatter with `version` |
| `plugins/python-development/skills/async-python-patterns/SKILL.md` | Skill frontmatter without `version` |
| `plugins/tdd-workflows/commands/tdd-cycle.md` | TDD cycle (12 steps, 6 phases, verified) |
| `plugins/tdd-workflows/commands/tdd-red.md` | Command frontmatter (`description` + `argument-hint`) |
| `plugins/conductor/commands/revert.md` | Semantic revert (safety rules verified) |
| `plugins/conductor/commands/new-track.md` | Track creation frontmatter |
| `plugins/conductor/commands/setup.md` | Setup Q&A with state persistence |
| `plugins/conductor/commands/implement.md` | Track implementation with TDD |
| `plugins/agent-teams/commands/team-feature.md` | File ownership + 7-phase flow |
| `plugins/agent-teams/commands/team-debug.md` | ACH 6-phase debugging protocol |
| `docs/architecture.md` | Design principles, model strategy |
| `docs/plugins.md` | Plugin catalog (72 plugins, 21 categories) |
| `docs/agents.md` | Full agent reference with model assignments |
| `docs/agent-skills.md` | 129 skills across 27 plugins |
| `docs/usage.md` | Plugin installation and usage patterns |

## Appendix B: Discrepancies Found

1. **python-pro model**: README/docs categorize it as Sonnet. Actual file has `model: opus`. Source of truth = the .md file.
2. **Skill count**: README says 146, docs/agent-skills.md says 129, architecture.md says 107. The count appears to have changed between documentation versions.
3. **Tier count**: README mentions 4 tiers (including "Inherit"). Architecture docs say 3. Actual agent files use only 3 values: opus/sonnet/haiku.
4. **Orchestrator count**: README says 16, architecture says 15. Minor discrepancy.
