# Conversation 003 — Integration Model & Identity Resolution

**Date:** 2026-02-10
**Phase:** Design finalization
**Outcome:** TeamBuild identity resolved as workflow framework. Design doc finalized with integration model, three-layer project understanding, validation runner, and managed executor sections.

---

## What Happened

### 1. Josh's Feedback: Agent Agnosticism

Josh raised a critical concern: the integration model from conversation 002 was too tightly coupled to Claude Code. It depended on `.claude/` directory structure, Claude Code skills, and hooks — the opposite of the project's core principle of being agent-agnostic.

Key quote: "This plan depends a lot on .claude and how it functions currently... We really want to build this so that it still works in six months when all of this stuff changes."

Josh also noted preference for config in `pyproject.toml` (standard Python convention) rather than a separate config file.

### 2. Linus Critique of the Adapter Pattern

Initial response proposed an `AgentRuntimeAdapter` ABC (ClaudeCodeAdapter, CursorAdapter, etc.) with `teambuild sync <runtime>` commands. Linus critique tore this apart:

- **Moving targets:** Claude Code, Cursor, Aider don't have stable plugin APIs. Writing adapters against moving targets with no contracts is a maintenance nightmare.
- **Sync is a lie:** `teambuild sync` implies bidirectional state that needs merge strategies when users manually edit agent config. That's a config synchronization engine, not a feature.
- **Adapters aren't symmetric:** Claude Code has skills/hooks/CLAUDE.md. Cursor has a rules file. These aren't the same thing — the ABC would either be useless or full of special cases.
- **Cart before horse:** Haven't built anything yet. Don't know what the actual integration surface is in practice.
- **Config file is same critique:** `teambuild.yaml` at project root is the `.teambuild/` critique wearing a different hat.

### 3. Identity Resolution — The Breakthrough

Linus identified the fundamental problem: **TeamBuild didn't know what it was.** The design doc was simultaneously:
- Identity A: TeamBuild IS the agent runtime (Interview Agent runs its own agent)
- Identity B: TeamBuild is a plugin for other runtimes (generates .claude/ config)

These are incompatible. The resolution:

**Identity C: TeamBuild is the WORKFLOW layer. Agent runtimes are the EXECUTION layer.**

TeamBuild owns the *what* and the *when*. The agent runtime owns the *how*. Like CI/CD — Jenkins doesn't care if you compile with gcc or clang.

### 4. Component Mapping Under New Identity

| Component | Role |
|-----------|------|
| Interview Agent | TeamBuild runs directly (conversation, not code execution) |
| PM Integration | TeamBuild owns entirely (creates tickets, tracks status) |
| Planning/Spec | TeamBuild produces handoff document (spec + acceptance criteria) |
| Coding Agent | **NOT TeamBuild's job.** Any agent reads the spec, writes code. |
| Validation | `teambuild check` — standalone CLI, works regardless of who wrote code |
| Review | `teambuild review` — AI review producing fix prompts any agent can pick up |
| Metrics | TeamBuild collects from all sources |

### 5. Managed Executor — Josh's Addition

Josh agreed with Identity C but added: MetrIQ's team also wants to own the coding step for consistency. This led to the **managed executor** — an optional wrapper (`teambuild code <ticket>`) that:
- Wraps any coding agent (Claude Code today) with standardized rules
- Monitors token usage, cost, time
- Runs `teambuild check` automatically
- Ensures everyone on the team has the same experience

This doesn't violate agnosticism because:
- It's optional (Layer 2, built last)
- The core workflow works without it
- The spec format, validation, and review don't change
- It uses the same handoff document any external agent would receive

### 6. Final Integration Model

Instead of adapters, the integration is three universal mechanisms:

1. **Git-native `.index.md` files** — just markdown, any tool reads them
2. **Config in `[tool.teambuild]`** — standard pyproject.toml convention
3. **Standalone CLI** — `teambuild` commands work independently

Optional thin generators (`teambuild setup claude/cursor/generic`) write a one-shot config file pointing at indexes. Not adapters — 50-100 lines of string formatting each.

---

## Design Doc Updates Made

### New Sections Added
- **Section 3: Integration Model** — CLI + git-native files, no agent dependency, `[tool.teambuild]` config, CLI surface, agent runtime independence
- **Section 4: Three-Layer Project Understanding** — L1 static analysis (free), L2 tree-sitter AST (free), L3 lazy AI summarization, bootstrap flow, agent file-finding flow
- **Section 8: Validation Runner** — standalone `teambuild check`, language-agnostic gates, auto-detection
- **Section 9: Managed Executor** — optional `teambuild code`, CodingExecutor ABC, execution flow, built last

### Sections Reframed
- **Section 1 (System Overview)** — rewritten with workflow framework identity, architecture diagram shows coding agent as dashed pluggable box
- **Module Dependency Graph** — updated with new modules, executor shown as optional
- **Section 13 (Package Structure)** — added `cli/`, `validation/`, `executor/` modules, renamed layers

### Sections Removed/Replaced
- Old "Coding Agent Team" section (was section 6) — replaced by Validation Runner (section 8) and Managed Executor (section 9)
- Old self-validation gates moved from coding agent into standalone Validation Runner

### Other Updates
- All section numbers fixed (1-14, sequential)
- Build order references updated across all module sections
- Resolved Design Decisions table expanded with 6 new decisions
- Research backlog reprioritized (tree-sitter and Pydantic AI tracking moved to high priority)
- Build sequence expanded from 5 steps to 11

---

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| TeamBuild identity | Workflow framework | Survives agent runtime churn. Doesn't compete with Claude Code/Cursor. |
| Integration mechanism | CLI + git-native files | Universal, no runtime dependency, standard conventions. |
| Config location | `[tool.teambuild]` in pyproject.toml | Standard Python convention. No separate config file. |
| Agent runtime setup | Thin generators, not adapters | No ABC, no sync, no drift. 50-100 lines each, disposable. |
| Managed executor | Optional, built last | Convenience layer, not core. Dogfood before automating. |
| Validation | Standalone CLI | Agent-agnostic. Works in git hooks, CI, or manually. |

---

## Files Modified
- `design-doc.md` — Major rewrite (new sections 3, 4, 8, 9; reframed sections 1, 12, 13, 14)
- `HANDOFF.md` — Updated current state, added conversation 003, new decisions, build sequence
- `memory/MEMORY.md` — Updated identity, phase, decisions, research backlog

## Next Steps
1. Josh reviews finalized design doc
2. Begin build: Project scaffolding (Step 1 in §14)
3. Provider Abstraction (Step 2)
4. Metrics Collection (Step 3)
5. Interview Agent (Step 4)
