# BUILDPRINT: Personal Agent Chat

This is the canonical starting point and execution contract for the blueprint. Do not start from generated prompts or secondary files. Your first action must be reading this file; do not inventory, glob, or enumerate packet files before this read order is established.

## Product brief

- Product: Personal Agent Chat
- Primary outcome: Mapper OS phase-flow packet for building a clean-room, self-hosted personal agent chat workbench with streaming chat, provider routing, tools, skills, MCP, memory, subagents, telemetry, and WebUI/API workbench surfaces.
- Primary users: operators or developers implementing the mapped product workflow.
- Main surfaces: BUILDPRINT.md canonical entry; 01-questions.md setup questions; 02-project-setup.md architecture and operating contract; blueprint.yaml machine contract
- What this packet must not become: a generic local MVP, static demo, source clone, source-code port, or single-file product shell.

## Final product at a glance

**Golden path** - A self-hosted operator configures providers and storage, opens a streaming personal agent chat workbench, routes messages through tools, skills and MCP policy, reviews memory/subagent telemetry, enforces safety boundaries, and uses a WebUI/API surface that keeps state and traces durable.

**Surfaces**

- Contracts and storage - define persistence, schemas and core records - Phase 1
- Provider streaming runtime - stream chat through provider adapters - Phase 2
- Tools, skills and MCP policy - run governed tool and skill calls - Phase 3
- Memory, subagents and telemetry - manage memory, coordination and token traces - Phase 4
- Safety and claim boundaries - enforce permissions, denials and claim limits - Phase 5
- WebUI/API workbench - expose the agent through usable browser/API surfaces - Phase 6

**Done looks like**

- Conversation, memory, tool traces, settings and telemetry persist and can be inspected.
- The WebUI is a real agent workbench with streaming states, not a static chat mock or local MVP.
- Provider, MCP, tool and safety claims upgrade only from matching proof rows.

## Required read order

1. Read this `BUILDPRINT.md` first, before listing or opening other packet files.
2. Read `01-questions.md`.
3. Read and complete `02-project-setup.md`.
4. Read `blueprint.yaml` as the machine-readable mirror.
5. Read `03-phases/phase-index.yaml`.
6. Read `03-phases/phase-flow.md`.
7. Read only the role contracts under `06-contracts/` required by the active phase `requires_roles`.
8. Read only the current active phase file. For a fresh run, use `active_phase` from `03-phases/phase-index.yaml`; for a targeted or resumed run, use the assignment or `.buildprint` state override after confirming the phase exists in `03-phases/phase-index.yaml`.
9. Read `04-evaluation.md`.
10. Treat `05-evidence/evidence-ledger.jsonl` as the immutable packet seed; append implementation proof or blocker rows only to `.buildprint/evidence/evidence-ledger.jsonl`.

Read these files sequentially. Do not batch, parallelize, or reorder the initial context reads, even when using multi-command tooling.

## Project setup gate

Do not start `03-phases/*` until `02-project-setup.md` has enough explicit architecture, team rules, quality gates, safety rules, and `AGENTS.md` plan to prevent agents from inventing project structure.

Blank answers in `01-questions.md` are not blockers. They authorize AI best-fit decisions unless the choice is irreversible, expensive, credentialed, destructive, or product-defining.

## Implementation loop

Every phase must repeat this loop until the proof gate passes or a real blocker is recorded:

1. Observe: inspect existing project files, nearest `AGENTS.md`, current behavior, and constraints.
2. Plan: state the smallest coherent change, likely files, and verification gate.
3. Execute: make scoped changes without silently expanding architecture.
4. Verify: run the planned test/build/browser/runtime gate and inspect output.
5. Reflect: compare results against the phase proof gate.
6. Record: append evidence or blocker rows before claiming progress.

A phase cannot be marked done from code edits alone.

## Repair routing

If verification fails, route back before editing again:

- test/build/runtime/UI/proof failure -> current phase file
- architecture contradiction -> `02-project-setup.md`
- missing human preference that affects product identity/cost/secrets/destructive action -> `01-questions.md`
- missing dependency -> required prior phase
- external blocker -> `.buildprint/evidence/evidence-ledger.jsonl`

Do not mark a phase complete while its verification failure is unresolved.

## Phase discipline

Every phase starts through `03-phases/phase-flow.md`. Do not collapse phase entry into immediate implementation: create `.buildprint/phase-runs/<phase-id>/plan.md`, `.buildprint/phase-runs/<phase-id>/team-gates.md`, bounded handoffs for every role in `requires_roles`, and return files for every role. Use subagents or delegated workers when available; when unavailable, self-simulate each role through the same handoff/return artifacts. Collect returns/reviews/proof, and only then append runtime evidence.

A phase is a proof-gated product slice, not a waterfall task bucket. Each phase must define product outcome, mapped product obligations, implementation scope, interfaces touched, state/runtime touched, UX/UI requirements, safety/security constraints, quality gates, proof gate, and repair routing.