# Conversation 001 — Initial Interview

**Date:** 2026-02-08
**Participants:** Josh (Product Owner / Power User), Claude Opus 4.6 (Interviewer)
**Phase:** Idea → Interview
**Purpose:** Establish v0.1 requirements, build order, and key constraints for the TeamBuild AI workflow system

---

## Session Metrics

| Metric | Value |
|--------|-------|
| Model | Claude Opus 4.6 |
| Session Type | Interactive Interview (10 questions) |
| Conversation Turns | ~22 (11 questions/prompts, 11 responses) |
| Estimated Input Tokens | ~12,000–15,000 (includes system context, CLAUDE.md, base-plan.md, initial-build-ticket-idea.md) |
| Estimated Output Tokens | ~4,000–5,000 |
| Estimated Total Tokens | ~16,000–20,000 |
| Estimated Cost | ~$0.90–$1.20 (Opus pricing) |
| Duration | ~30 minutes |
| Artifacts Produced | This conversation log, interview summary |

> **Note:** Token counts are estimates. Exact tracking is not yet available — building the Cost/Performance Metrics module (item 5 in the build order) will solve this. These rough numbers establish a baseline for what an interview session costs.

### Observations for Future Metrics Module
- System context (CLAUDE.md + referenced files) consumed a significant portion of input tokens (~5,000–7,000). This is a fixed cost per session that could be optimized.
- The adaptive interview format (next question based on last answer) required sequential turns — not parallelizable. This is inherent to interviews.
- Most value was extracted in questions 1-6. Questions 7-10 were confirmatory/refinement. A smarter interview agent could detect when it's hitting diminishing returns.
- The interview produced a clear, prioritized build order in ~10 questions. This is a good benchmark for the Interview Agent to target.

---

## Interview Transcript

### Q1 — The Vision Check
**Q:** When you imagine this system working well enough that you're actually using it daily on real projects, what does that minimum version look like?

**A:** The interview agent, coding agents and agent teams functioning in general, the critique agent, and code review agents are the very first things that need to get done. Connecting this all with project management software like Plane and Linear is also an early priority to keep track of everything being built.

**Insight:** PM integration is not an afterthought — it's core infrastructure for coordination.

---

### Q2 — Current Workflow Pain
**Q:** Walk me through how you're currently working on a project from idea to shipped code. Where do you lose the most time, context, or quality?

**A:** The biggest limiter is not knowing what to build ahead of time. Having a base general goal but not a plan for execution. As long as inputs and expected outputs are defined, anything can be built. The problem is not laying those out well ahead of time. That's why the interview process needs to be right — to get all the information out of power users up front.

**Insight:** The bottleneck is clarity before coding, not coding itself. The Interview Agent is the highest-leverage piece.

---

### Q3 — The Interview Agent's Job
**Q:** When you picture a great interview session, what comes out the other end? And is the interviewer always talking to you?

**A:** Sometimes talking to Josh, but often talking to his boss or a project manager. Two modes: (1) Direct interview about a plan that isn't finalized, working through actual specs. (2) Interpreting what stakeholders give and figuring out what's missing — where is the data, what does it look like, what do you want outputs to look like, what should v1 look like, is this a day build or a year build.

**Insight:** Interview Agent needs two modes — direct interview and gap analysis on existing specs. Core framework: data source, data shape, desired outputs, scope/timeline.

---

### Q4 — Agent Teams and Autonomy
**Q:** How do you see yourself interacting with the agent teams day-to-day?

**A:** Give them as much control as possible, with the understanding that human oversight is needed because you can never give AI all the information in your head. Wants to be able to easily step in when things go off the rails. Agents should take features from nothing to app spec to build plan to PR tickets. Agent team runs through and builds as much of v1 as possible. Comes back as a checkpoint. Must do its own validation before involving a human — TDD with a true flow where "done" means actually done.

**Insight:** High autonomy with quality gates. Human is the exception handler, not the primary reviewer. TDD is the mechanism that makes "done" meaningful.

---

### Q5 — The Critique and Review Loop
**Q:** What does a good review look like to you?

**A:** If there are errors, it goes back to coding agents immediately. The server should run without errors, inputs should produce correct outputs. "All of the above" for review quality — code quality, bugs, security, spec compliance. Critique also applies to the plan up front, not just code. Different skills or agents for each concern (security, code quality, bugs, pytest, ruff, etc.) for all possible languages.

**Addition:** There must be a limited number of loops (3-5 attempts) before escalating to the human with a notification. Prevents infinite loops and wasted tokens.

**Insight:** Critique is a layer, not a single agent. It applies at every phase. Circuit breaker pattern is a hard requirement.

---

### Q6 — PM Integration and Tracking
**Q:** What do you actually need the PM integration to do in v1?

**A:** Single source of truth. Has researched Beads format for managing projects and tokens with multiple agents. PM software is where thinking and working happens, ensuring coordination so agents don't grab the same problem, produce conflicting solutions, and push conflicting PRs. Testing v1 with Plane (personal account) but Linear must be accessible (work uses it).

**Insight:** PM tool is the coordination layer that prevents duplicate/conflicting work. Must be abstract enough to support both Plane and Linear. Research Beads format.

---

### Q7 — Cost and Performance Tracking
**Q:** What do you actually want to see when you look at performance data?

**A:** Critical for projects where AI builds as much as possible. Need to measure effectiveness vs. paying a human. Cost per ticket, startup costs of learning a codebase, context window health (smart vs. dumb window), all important triggers. Want metrics everywhere — tool, dashboard, CLI, PM reports, project reviews, estimations. Building real data around effectiveness. Can also measure how well developers are utilizing the tools based on instruction quality.

**Insight:** Metrics aren't just cost control — they're a feedback loop for the entire system, including human effectiveness. Must be visible on every surface.

---

### Q8 — Tech Stack and Provider Agnosticism
**Q:** How hard of a line is provider agnosticism? Is Pydantic AI a firm choice?

**A:** Get as agnostic as possible, as early as possible. Can start with Claude for first iteration but wants this to be a true build of the actual system. Pydantic AI is the leading candidate but should be validated with research and critiquing.

**Insight:** Abstraction layer from day one, not a refactor. Pydantic AI needs validation before committing.

---

### Q9 — v0.1 Build Order Confirmation
**Q:** [Presented prioritized build order for confirmation]

**A:** Confirmed the order is correct. Highlighted that items 1-4 should be used to build item 5 (Cost/Performance Metrics), creating a dogfooding loop that tests the system while building it.

**Insight:** The system builds itself. This is the primary testing strategy for early iterations.

---

### Q10 — Working Style and Notifications
**Q:** How do you primarily work? Where do you want notifications?

**A:** Primarily IDE, but terminal-based Claude Code for AI work (open to experimenting). Notifications via desktop notifications and PM tool for v1. Communication app integrations (Slack, Teams, Discord) are later — not first pass.

**Insight:** Terminal-first, IDE when coding. Two notification channels for v1. Keep it simple.

---

## Requirements Summary

### Core Problem
Lack of clarity before coding starts. Inputs and expected outputs aren't well-defined, leading to wasted effort and rework.

### v0.1 Build Order
1. **Interview Agent** — Two modes: direct interview and gap analysis on existing specs. Core output: clear inputs, outputs, data sources, scope/timeline
2. **PM Integration** — Plane first, Linear-ready. Single source of truth. Agent coordination, ticket management, status tracking
3. **Coding Agent Team** — High autonomy, TDD, self-validating (tests pass, server runs, linting clean). Spec → PR pipeline
4. **Critique/Review Layer** — Applies at every phase (plan, code, security, quality). Auto-loops on failure. Circuit breaker at 3-5 attempts → escalate with context
5. **Cost/Performance Metrics** — Built BY items 1-4 as dogfooding test. Per-agent, per-ticket, per-project. Visible in CLI, PM, dashboards, reviews. Tracks estimate accuracy and context window health
6. **Provider Abstraction** — Model-agnostic from day one. Validate Pydantic AI in research phase

### Key Constraints
- Python for orchestration, TS for web, best tool otherwise
- TDD, strict linting, modular design
- **Modular components** — plug and play, leave behind what you don't need, adaptable per project or per user
- Open source first, self-hosted where possible
- Terminal-first workflow, desktop + PM notifications for v1
- Circuit breaker pattern on all agent loops (3-5 attempts)
- Track everything — tokens, costs, accuracy, context window usage
- Beads format research for project/token management

### What Success Looks Like
Hand off a feature spec → agents build through PR with real validation → human only steps in when genuinely stuck or for final approval. PM tool shows exactly what's happening at all times. Cost and quality metrics prove the system is effective.

---

## Post-Interview Addition — Context Window Management (Critical)

After the formal interview, Josh raised the single biggest technical pain point: **context window management during agent handoffs and codebase onboarding.**

**The problem:** Previous "prime" functions loaded full codebase understanding into context, consuming the smart window before agents could do real work. On large codebases, the priming was so expensive that execution quality degraded.

**The requirement:** Targeted, lazy context loading. Agents fetch only what's relevant to their specific task. Navigation via atomic index notes (Zettelkasten-inspired). Context budget tracking with degradation warnings. Shared knowledge layer in external storage, not in the context window.

**This was elevated to a first-class architectural constraint** — it affects every module's design and is documented as a dedicated section in requirements.md.

Josh also re-emphasized that **modularity is critical** — every component must be plug-and-play, usable independently depending on the project or user setup.

---

## Handoff Documents Created

After the interview, we identified that the project lacked clean handoff documents for agent continuity. Created:

1. **CLAUDE.md** (updated) — entry point for any agent, points to HANDOFF.md and requirements.md
2. **HANDOFF.md** — current state, decisions made, next task with explicit inputs/outputs, full research inventory
3. **requirements.md** — standalone requirements spec extracted from interview, including the Context Window Management architectural constraint

---

## Post-Session: Interview Agent Synthesis (2026-02-09)

After the initial interview session, Josh's colleague shared their `clarity-interviewer` skill, which uses Teresa Torres story-based methodology and Dylan Davis' "Don't Prompt AI. Let It Prompt You" approach.

**Synthesis work completed:**
1. Analyzed clarity-interviewer approach (story-based questioning, ONE question at a time, completeness tracking, domain libraries, explorer mindset)
2. Compared to our interview 001 approach (structured, deliverable-focused, technical depth)
3. Created `interview-agent-synthesis.md` — full comparison and hybrid approach recommendation
4. **Updated Interview Agent spec in requirements.md** to merge both approaches:
   - Story-based questioning mechanics (specific situations, not generalizations)
   - Dynamic question generation (multiple candidates, select best)
   - Completeness tracking (1-10 scale with clear criteria)
   - Internal note-taking after each response
   - Profile building (working style, values, priorities)
   - Explorer mindset (follow valuable tangents)
   - Domain libraries that grow over time
   - Natural conclusion when completeness reaches 9-10
   - Structured outputs always (requirements docs, not just insights)

The hybrid Interview Agent combines clarity-interviewer's discovery power with TeamBuild's deliverable focus.

---

## Next Steps
- Move to **Design Doc Phase** — Mermaid diagrams showing system architecture, agent relationships, data flow, and module boundaries
- Research: Beads format, Pydantic AI validation, Plane API, Linear API
- Define the modular component boundaries so pieces can be used independently
- Design the context navigation layer (atomic indexes, progressive disclosure, context budgeting)
- Create initial domain libraries for Interview Agent (software-requirements.md, feature-specs.md, architecture-decisions.md)
