# Conversation 002 — Research Review + Design Doc

**Date:** 2026-02-09
**Phase:** Design Doc with Mermaid Diagrams
**Participants:** Josh, Claude (Sonnet 4.5)

---

## What Happened

### 1. Research Review (5 parallel agents)
Reviewed all research materials that hadn't been incorporated yet:

- **Pydantic AI POC** — Validated provider abstraction pattern. Generic `AgentProvider` interface with Pydantic v2 models works across all target providers. Adopted as foundation.
- **Opus Agent Roles** — 12 specialist roles, 10-phase lifecycle, 3-tier delegation (solo ~1x / subagent ~2x / team ~5x), 5 reusable skills. Informed coordination model.
- **Hooks & Quality Control** — Pre-commit lint, post-edit format, post-failure autofix. stdin JSON protocol. Circuit breaker via stateful retry. Adopted for Critique/Review Pass 1.
- **Early Research Skills/Schemas** — 25 PIV-Swarm skills, schema-driven decisions (70% question reduction), progressive context loading, fresh context per task. Core patterns adopted.
- **Current AI Setup** — Josh's battle-tested PIV-Swarm workflow. Smart defaults, 3-tier testing, helper scripts. Mapped existing skills to TeamBuild modules.

### 2. Code Reviewer Research (added mid-session)
Josh pointed to `research/code-review/ai-reviewer.mjs` — a GitHub Actions AI reviewer he built. Key concepts adopted:

- **`agentPrompt` field** — AI-to-AI handoff. Each review issue includes a prompt a coding agent can pick up directly to verify and fix. Turns review into a pipeline.
- **False positive prevention** — mandatory 5-point self-check, banned speculative language, "zero issues = ideal outcome."
- **Priority-based truncation** — file priority weights for context budget allocation.
- **Stale comment resolution** — auto-minimize resolved issues.
- **Two-pass review architecture** — automated hooks (Pass 1) + AI deep review (Pass 2).

### 3. Design Doc Created
Created `design-doc.md` with Mermaid diagrams covering:

- High-level system architecture
- Module dependency graph
- Provider Abstraction interface (validated by POC)
- Context Window Manager (atomic indexes, progressive disclosure, budget tracking)
- Metrics collection points (6 annotated collection points)
- Interview Agent internal architecture (detailed enough to build from)
- PM Integration data flow (adapter pattern, scope markers, stale resolution)
- Coding Agent lifecycle (3-tier delegation, fresh context per task, self-validation)
- Critique/Review two-pass architecture (hooks + AI review, agentPrompt, circuit breaker)
- Cost/Performance Metrics (full tracking taxonomy, JSONL/SQLite storage)
- Package structure for the full project
- Build sequence for Module 1

### 4. HANDOFF.md Updated
- All research items moved to "Reviewed and Incorporated into Design Doc"
- `research/code-review/` added to inventory
- Open questions resolved with decisions
- Next task updated: Build Module 1 (Interview Agent)
- Project structure updated

---

## Decisions Made

| Decision | Choice | Rationale |
|----------|--------|-----------|
| PM abstraction | Adapter pattern | Mirrors AgentProvider pattern, PlaneAdapter + LinearAdapter |
| Agent coordination | PM-driven + file ownership | PM as single source of truth, no file conflicts |
| Metrics storage | JSONL → SQLite (same ABC) | Simple first, query-able later, seamless switch |
| Module interfaces | Python packages + Pydantic models | Type-safe, validated, clear contracts |
| Atomic indexes | `.index.md` per directory | Lightweight, human-readable, auto-maintained |
| Context budgeting | Token % thresholds | 70% warn, 85% degrade, 95% stop |
| Critique architecture | Two-pass (hooks + AI) | Fast automated checks first, expensive AI review second |
| Review → fix pipeline | agentPrompt field | AI-to-AI handoff, no human translation needed |

---

## Artifacts Produced

- `design-doc.md` — full system design with Mermaid diagrams
- `conversation-logs/002-design-doc.md` — this file
- Updated `HANDOFF.md` — reflects current state

---

## Josh's Feedback Pass

Josh reviewed the design doc and provided feedback (`feedback-design-docs.md`). Changes made:

1. **Context Window Manager** — Flat index scanning replaced with hierarchical navigation. Root index routes to 2-3 relevant module indexes based on ticket scope markers. Cross-references between related modules.
2. **Context budget tracking** — Added research note: investigate Claude Code's `/context` command and Pydantic AI's built-in usage tracking before building custom. Don't reinvent the wheel.
3. **Coding Agent coordination** — File ownership by convention isn't enough. Added git worktrees for file isolation. Added research item: deep dive into Claude's agent team coordination.
4. **Self-validation gates** — Made language-agnostic. Validation categories (test/lint/type/format/security) resolved per-language at runtime via project config detection.
5. **Metrics storage** — Added DuckDB as candidate alongside SQLite. Added research item: DuckDB vs SQLite for analytics workloads.
6. **Package structure** — Replaced separate tests/ dir with monorepo + import-linter enforced layers. Tests colocated with modules. Every module independently runnable and replaceable. Layer 0 (foundation) → Layer 1 (core agents) → Layer 2 (coordination).
7. **Modularity** — Reinforced: everything must be replaceable by new tech. Clean `__init__.py` public APIs.
8. **Research backlog** — Added: Beads framework, Plane API, Linear API, Claude agent teams, git worktrees, DuckDB vs SQLite, Claude /context, Pydantic AI tracking.

### Package Structure Decision
Evaluated independent packages vs monorepo. Chose **monorepo with import-linter enforcement** — zero packaging overhead, real enforcement in CI, tests colocated with modules, trivial to split later if needed.

## Agent Workflow Contract Added

Josh flagged that index maintenance is the #1 risk — if agents don't update indexes, the whole context management system collapses. Can't rely on agents to "remember." Added **Section 2: Agent Workflow Contract** to design-doc.md:

- **8-step mandatory lifecycle**: PICKUP → LOAD → BUDGET → WORK → MONITOR → VALIDATE → HOUSEKEEP → DONE
- **Steps 1-3 and 7-8 are framework-level** — the agent doesn't choose to do them, the system forces them
- **Reserved context budget**: Work budget = smart window (~120K). Housekeeping reserve = 30K. Hard ceiling ~150K.
- **Never compact, always hand off** — compaction loses context, structured handoff to fresh agent preserves it
- **Hook enforcement**: Post-edit hook blocks commits if indexes are stale. Pre-handoff hook blocks if PM ticket not updated. Pre-compaction hook requires handoff state.
- **HandoffState model**: Structured output with files_modified, remaining_work, key_decisions, gotchas, context_needed
- **Budget thresholds configurable per model** — current reality is ~120K smart window, will increase

## Integration Model Discussion (IN PROGRESS)

Discussed how TeamBuild gets used inside other projects (not building TeamBuild itself).

### Initial Proposal: `.teambuild/` config directory
- TeamBuild installed globally, bootstraps per-project config
- `.teambuild/` holds config, indexes, metrics, state
- Generates `.claude/` skills and hooks
- Developer uses Claude Code normally with TeamBuild-powered slash commands

### Linus Critique of Initial Proposal
- Yet another dot-directory — projects already have too many
- `config.yaml` will grow into an unmaintainable monster
- Chicken-and-egg: `teambuild init` needs to understand the project to generate indexes, but understanding requires reading code, which is the problem we're solving
- Two source-of-truth problem: `.teambuild/` generates `.claude/`, now they can drift
- "Zero coupling" is a lie — losing `.teambuild/` loses all accumulated knowledge

### Three Alternatives Discussed
1. **Just a CLAUDE.md generator** — one-shot setup, no runtime, Claude Code is the runtime. Too thin for persistent state.
2. **Git-native** — indexes are committed `.index.md` files, version-controlled, reviewable in PRs. Metrics gitignored. No hidden state.
3. **Background daemon** — file watcher, live indexes, LSP-like. Too heavy for v0.1.

### Emerging Consensus: Git-native + CLAUDE.md generation
- Indexes are committed `.index.md` files (visible, reviewable, versioned)
- TeamBuild manages `.claude/` config (one directory, not two)
- Project settings in `.claude/teambuild.yaml`
- No `.teambuild/` directory

### Project Structure Understanding — Three-Layer Approach
Discussed how TeamBuild actually understands a large project. Key insight: **80% of understanding costs 0 AI tokens**.

**Layer 1 (free):** Static analysis — git ls-files, directory structure, file sizes, package manifests, git log change frequency, co-change patterns, entry points.

**Layer 2 (free):** AST parsing via tree-sitter — exports, imports, function/class signatures, import graph, public API surface. Zero AI tokens.

**Layer 3 (expensive, targeted):** AI-powered summarization — "what does this module do in business terms?" Only needed for business-level understanding. Done lazily, once per module, on first access.

**Bootstrapping flow:** `teambuild init` runs Layers 1-2 (free), generates root .index.md with one cheap AI call. Module indexes generated lazily when agents first work in that area.

**Agent file-finding flow:** Root index → module index → import graph → git history → read 2-3 targeted files (out of 500).

### STILL NEEDS TO BE ADDED TO DESIGN DOC
The integration model discussion and three-layer project understanding approach need to be formalized in the design doc. This was discussed but not yet written into design-doc.md.

## Next Steps

1. **Add integration model to design-doc.md** — how TeamBuild plugs into other projects (git-native indexes, `.claude/` config, `teambuild init` bootstrapping)
2. **Add three-layer project understanding to design-doc.md** — static analysis, AST parsing, lazy AI summarization
3. Josh does deep review of complete design doc
4. Set up project scaffolding (pyproject.toml with import-linter, ruff, mypy, pytest)
5. Build Provider Abstraction (Layer 0)
6. Build Metrics Collection (Layer 0, lightweight)
7. Build Interview Agent (Layer 1)
