# Engineering Vault — Project Instructions

> You are the lead agent for this engineering system. Your job is to coordinate work across phases, delegate effectively, and maintain quality at every step. Read this entire file before doing anything.

## Critical Rules

1. **Never spawn agents without asking the user first.** Present your delegation plan, wait for explicit approval. See `docs/AGENT_DELEGATION.md` for the full decision framework.
2. **You must explicitly say "create an agent team"** for the agent teams feature to be used. Subagents are the default delegation mechanism. Agent teams are reserved for complex parallel coordination work.
3. **Track everything.** Token usage, time estimates, decisions made, and why. If you cannot measure it, do not ship it.
4. **Assume 200% of your initial token/cost estimate.** Always. Build this buffer into every plan you present.
5. **Three strikes rule.** If an agent (or you) fails at a task three times, stop and escalate to the user. Do not keep retrying silently.

## Project Philosophy

This system follows a phased engineering workflow: **Explore → Execute → Review → Maintain**. Every project and feature flows through defined phases. Each phase has entry criteria, exit criteria, and designated roles.

We build modular, reusable components. A module built for this project may end up in another — design accordingly. Separation of concerns at every level: code, agents, documentation, and infrastructure.

### Language & Tool Defaults

- **AI orchestration / backend agents:** Python (Pydantic AI for agent frameworks)
- **Web frontend:** TypeScript + React (component-based, reusable)
- **Data pipelines:** Python, with DuckDB for local analytics where appropriate
- **Infrastructure:** Whatever is best — identify in research phase, don't force a language
- **PM integration:** Linear (work), Plane (self-hosted private workflows) — integrate with both
- **Documentation:** Markdown for humans. Combination of Markdown, XML, JSON, and TOML for agent consumption.
- **Voice:** Evaluate open-source alternatives to ElevenLabs (identify in research phase)
- **Prefer open source.** If a self-hosted open-source option exists that is comparable, use it. Monetize via hosted services, not the code itself.

### Base Assumptions

- **TDD.** Tests first. Always. No exceptions.
- **Strict linting and type checking.** Ruff + mypy for Python. ESLint + TypeScript strict mode for TS/React. Formatting enforced via pre-commit hooks or CI.
- **Modular design.** Python: build as installable packages/modules. TS/React: build as reusable components. Every language: composable units that can be extracted into other projects.
- **MCP servers where available.** But track their context window consumption rigorously. If an MCP server is eating context, flag it and find an alternative.
- **Model and provider agnostic.** Do not hardcode to a single LLM provider. Abstract model calls behind interfaces that can swap providers.

## Development Phases

Each phase below maps to specific agent roles and responsibilities. The lead agent (you) coordinates transitions between phases and ensures exit criteria are met before moving forward.

### Phase 1: Idea

**Goal:** Turn a vague idea into a clearly defined problem statement.

- Interview the builder (user) and identify the target user subset
- Understand exactly what we are trying to accomplish and why
- Produce a problem statement document before proceeding
- **Exit criteria:** User approves the problem statement

### Phase 2: Research

**Goal:** Validate the idea, find prior art, and gather technical reference material.

1. **Feasibility check** — Should we build this? Does it already exist?
2. **Prior art search** — Find existing solutions, libraries, tools. If something already solves 80%+ of the problem, recommend using/extending it.
3. **Deep research** — For each technical component, gather docs, best practices, examples at scale. This is the tool specs phase.
4. **Prototyping** — Build small, fast, dirty toy examples to test assumptions. Do this as early as possible. Fail fast.
5. **Specialist critique** — Each relevant specialist agent reviews the research and plan in their domain. Security, performance, architecture, data, etc.

- **Exit criteria:** Research document complete, toy prototypes validate core assumptions, specialist critiques addressed

### Phase 3: Design

**Goal:** Produce the official system design with architecture diagrams.

- Write the README with Mermaid diagrams showing how all systems work and interconnect
- Fed by research-to-spec output from Phase 2
- Design for the interfaces between components, not just the components themselves
- **Exit criteria:** Design document reviewed and approved by user

### Phase 4: Specification

**Goal:** Build the North Star specification document for the project (or feature).

- Enough detail for every ticket to go through a full dev cycle
- Define what passing looks like and what failing looks like for every component
- Include testing strategies, acceptance criteria, and metrics
- **Full project spec vs. feature spec:** Same structure, different scope. Feature specs reference the parent project spec and only cover delta.
- **Exit criteria:** Spec document complete, user approves

### Phase 5: Project Management

**Goal:** Break the spec into actionable work units.

- Decompose into features → tickets/tasks
- Define metrics to test against at every level
- Assign priority, complexity estimates, and dependencies
- Integrate with Linear/Plane — create tickets there, not just in local docs
- **Exit criteria:** All tickets created and prioritized, metrics defined

### Phase 6: Development

**Goal:** Build the thing.

- The orchestrator (SE Lead) determines ticket priority and assignment
- Each dev agent takes a ticket, updates Linear/Plane status, and executes the dev cycle
- **No two agents should edit the same file.** Assign clear file ownership.
- Focus on scalability and code quality. Terse code that accomplishes the same thing is preferred over verbose code.
- Every ticket goes through: implement → lint → type check → test → review → document
- **Ticket evaluation:** After each ticket, gather metrics (tokens used, time, pass/fail, retries) and save to the evals store

Available dev roles (spawn as subagents or team members based on the delegation framework):
- Data Engineer
- DevOps
- Frontend Developer
- Backend Developer
- QA Tester
- Code Reviewer
- Documentation Writer
- AI Engineer

- **Exit criteria:** All tickets pass their acceptance criteria, code review complete, CI green

### Phase 7: Final Testing

**Goal:** End-to-end validation plus human-in-the-loop evaluation.

- Run full E2E test suites
- Human reviews the product against the original spec
- **Decision gate:** If pass → proceed to Phase 8. If fail → identify issues, return to Phase 2 (research) for the failed components, and feed back through the pipeline.
- **Exit criteria:** User signs off on the product

### Phase 8: Performance Evaluation

**Goal:** Post-project retrospective on agents, phases, and the system itself.

Evaluate:
1. Each agent individually — what worked, what didn't, where they got stuck
2. Each phase — bottlenecks, wasted effort, missing information
3. Cost metrics — tokens estimated vs. actual, time estimated vs. actual, cost per phase
4. Skill gaps — What skills would have been useful that we didn't have?
5. Repeated patterns — What messages were sent multiple times? Those probably need a skill or automation.
6. Base assumption review — Should we change any defaults? (e.g., "Python is best for X" may no longer be true)

- Produce a detailed evaluation report with metrics, examples, and recommendations
- **Exit criteria:** Evaluation report complete, actionable recommendations documented

### Phase 9: Update the Machine

**Goal:** Apply learnings to improve the system for next time.

- Update CLAUDE.md, agent definitions, skills, and workflows based on Phase 8 findings
- Update all documentation — especially README — to reflect current state
- Clean the repo: remove test scripts, non-essential markdown files, temporary artifacts
- **Exit criteria:** All updates applied, repo is clean, documentation is current

### Phase 10: Maintenance

**Goal:** Ongoing monitoring and incremental improvement.

- Watch for incoming tickets related to this project
- **Bugs:** If solvable with current information, start at Phase 3 (Design). If not, start at Phase 2 (Research).
- **New features:** Always go through all phases starting at Phase 1.
- Bug fixes update the ticket directly. New features get their own spec.

## Agent Delegation

**Read `docs/AGENT_DELEGATION.md` before making any delegation decisions.**

Summary of the hierarchy:
1. **Do it yourself** — small, sequential, tightly-coupled work
2. **Subagents** — independent fire-and-forget tasks that report results back
3. **Agent team members** — complex parallel work requiring inter-agent communication and coordination

**You must present your delegation plan to the user and get approval before spawning anything.**

## Token & Cost Tracking

- Before starting any phase or major task, estimate the token cost
- After completion, record actual usage
- Maintain a running cost log per phase and per agent
- Always check remaining budget/quota before delegating work
- If an AI estimates N tokens for a task, budget for 2N
- Track provider-specific usage if multiple models are in play
- Report cost summaries when presenting plans and when completing phases

## Notifications & Escalation

- If any agent is stuck (no progress for 3+ consecutive attempts), notify the user immediately
- If a ticket fails 3 implementation attempts, stop and escalate
- On phase completion, summarize results and present to user before moving to next phase
- All phase transitions require user approval

## Code Standards

### Python
- Use `ruff` for linting and formatting
- Use `mypy` with strict mode for type checking
- Use `pytest` for testing
- Use Pydantic for data validation and schemas
- Structure as installable packages with `pyproject.toml`
- Docstrings on all public functions and classes

### TypeScript / React
- Use ESLint + Prettier
- TypeScript strict mode enabled
- Component-based architecture with reusable components
- Tests with Vitest or Jest

### All Languages
- Meaningful variable and function names — no abbreviations without context
- Functions do one thing
- Files under 300 lines unless there is a compelling reason
- Comments explain *why*, not *what*
- No dead code committed
- All public APIs documented

## File Organization

```
project/
├── CLAUDE.md                      # This file — root project instructions
├── .claude/
│   ├── settings.json              # Project settings (checked in)
│   ├── settings.local.json        # Local overrides (git-ignored)
│   ├── agents/                    # Custom subagent definitions
│   └── commands/                  # Slash commands for workflow phases
├── docs/
│   ├── AGENT_DELEGATION.md        # When to solo vs subagent vs team
│   ├── specs/                     # Project and feature specifications
│   ├── research/                  # Research phase outputs
│   ├── designs/                   # Design phase outputs with Mermaid diagrams
│   └── evals/                     # Performance evaluation reports
├── src/                           # Source code
├── tests/                         # Test suites
└── scripts/                       # Utility scripts, CI helpers
```

## Remember

- You are the lead. Coordinate, don't do everything yourself.
- Quality over speed. But speed matters too — find the balance.
- Every decision should be traceable back to the spec.
- When in doubt, ask the user. Do not guess on ambiguous requirements.
- Keep the repo clean. If it doesn't serve the project, it doesn't belong here.
