# ADT – Software Design Document (v2)

> Design for Phase 0–3 (MVP): Multi-agent software development pipeline with minimal web UI.
> Incorporates: Task model, Context Manager, Agent Coordinator, Tracing, Archetypes,
> Top-down generation, Structural validation, and full Quality Assurance stack.
>
> Status: **Pending review & approval**

---

## Table of Contents

1. [Design Scope](#1-design-scope)
2. [High-Level Architecture](#2-high-level-architecture)
3. [Monorepo Structure](#3-monorepo-structure)
4. [Agent System Design](#4-agent-system-design)
5. [Task Model](#5-task-model)
6. [Workflow Engine & Adaptive Pipeline](#6-workflow-engine--adaptive-pipeline)
7. [Agent Coordinator](#7-agent-coordinator)
8. [Centralized Context Manager](#8-centralized-context-manager)
9. [Project Archetypes](#9-project-archetypes)
10. [Top-Down Generation Protocol](#10-top-down-generation-protocol)
11. [Self-Challenge Protocol](#11-self-challenge-protocol)
12. [Structural Validation Layer](#12-structural-validation-layer)
13. [LLM Abstraction Layer](#13-llm-abstraction-layer)
14. [Shared RAG Design](#14-shared-rag-design)
15. [Prompt Handler & Versioning](#15-prompt-handler--versioning)
16. [Tracing & Observability](#16-tracing--observability)
17. [Web UI Design (Minimal MVP)](#17-web-ui-design-minimal-mvp)
18. [Data Model](#18-data-model)
19. [API Design (Internal)](#19-api-design-internal)
20. [Inter-Agent Communication Protocol](#20-inter-agent-communication-protocol)
21. [File & Artifact Management](#21-file--artifact-management)
22. [Quality Assurance Stack](#22-quality-assurance-stack)
23. [Human Escalation Protocol](#23-human-escalation-protocol)
24. [Sequence Diagrams](#24-sequence-diagrams)
25. [Module Dependency Map](#25-module-dependency-map)
26. [Technology Decisions](#26-technology-decisions)
27. [Security Considerations (MVP)](#27-security-considerations-mvp)
28. [Open Questions & Assumptions](#28-open-questions--assumptions)
29. [Approval Checklist](#29-approval-checklist)

---

## 1. Design Scope

### In scope (MVP — Phases 0–3)

**Core Infrastructure:**
- Agent core framework (stateless workers, self-challenge, top-down generation)
- LLM abstraction layer (multi-provider, deterministic settings)
- Task model (persistent, pausable, resumable work units with acceptance criteria)
- Centralized Context Manager (smart windowing, context recipes, summarization)
- Agent Coordinator (hybrid assignment, module locking, parallelism)
- Workflow orchestrator with adaptive pipeline (archetype-driven)
- Tracing & observability (hierarchical traces, LLM cost tracking)
- Structural validation layer (lint, type check, parse before self-challenge)

**Agents:**
- PM, Architect, Dev, QA, DevOps, Reviewer, Delivery agents
- Billing Agent (independent traceability)

**Knowledge & Prompts:**
- Shared RAG with reference implementations per archetype
- Common prompt handler with versioning

**Platform (Minimal):**
- Minimal React + Tailwind web UI (chat + project tracking)
- GitHub repo management for customer projects
- Local artifact storage
- PostgreSQL for project/task/trace persistence
- Source code ZIP delivery

### Out of scope (post-MVP)

- UX Agent / navigable prototypes
- Kubernetes deployment & Kustomize
- CI/CD pipeline generation (GitHub Actions)
- Multi-tenant SaaS platform (auth, billing, org management)
- Analytics dashboards
- Post-delivery debugging flow
- Concurrent multi-project execution
- Outcome learning / feedback loops

---

## 2. High-Level Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│                          WEB BROWSER                                 │
│                     (React + Tailwind)                               │
│  ┌──────────┐  ┌──────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │ Chat UI  │  │ Project View │  │ Step Tracker │  │  Artifacts  │  │
│  └────┬─────┘  └──────┬───────┘  └──────┬──────┘  └──────┬──────┘  │
└───────┼───────────────┼────────────────┼────────────────┼───────────┘
   ─ ─ ─┼─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─┼─ ─ ─ ─ ─ ─ ─ ┼─ ─ HTTP/WS
┌───────▼───────────────▼────────────────▼────────────────▼───────────┐
│                       BACKEND API (FastAPI)                          │
│  ┌──────────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
│  │ /chat (WS)   │  │/projects │  │/artifacts│  │ /traces (REST) │  │
│  └──────┬───────┘  └────┬─────┘  └────┬─────┘  └───────┬────────┘  │
└─────────┼───────────────┼──────────────┼────────────────┼───────────┘
          │               │              │                │
┌─────────▼───────────────▼──────────────▼────────────────▼───────────┐
│                    ORCHESTRATION LAYER                               │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │          WORKFLOW ENGINE (pipeline-level)                      │  │
│  │  Loads archetype → defines pipeline → manages step gates      │  │
│  └──────────────────────────┬─────────────────────────────────────┘  │
│                             │                                        │
│  ┌──────────────────────────▼─────────────────────────────────────┐  │
│  │          AGENT COORDINATOR (task-level)                        │  │
│  │  Creates tasks → manages assignment → module locking →        │  │
│  │  parallel orchestration → dependency tracking                 │  │
│  └──────────────────────────┬─────────────────────────────────────┘  │
│                             │                                        │
│  ┌──────────────────────────▼─────────────────────────────────────┐  │
│  │              TASK QUEUE                                        │  │
│  │  Persistent tasks → role-based queues → claim & execute       │  │
│  └──────────────────────────┬─────────────────────────────────────┘  │
│                             │                                        │
│  ┌──────────────────────────▼─────────────────────────────────────┐  │
│  │              AGENTS (stateless workers)                        │  │
│  │                                                                │  │
│  │  ┌────┐ ┌──────┐ ┌─────┐ ┌────┐ ┌──────┐ ┌────────┐ ┌─────┐ │  │
│  │  │ PM │ │Archi.│ │ Dev │ │ QA │ │DevOps│ │Reviewer│ │Dlvry│ │  │
│  │  └──┬─┘ └──┬───┘ └──┬──┘ └──┬─┘ └──┬───┘ └──┬─────┘ └──┬──┘ │  │
│  └─────┼──────┼────────┼───────┼──────┼────────┼──────────┼─────┘  │
│        │      │        │       │      │        │          │         │
│  ┌─────▼──────▼────────▼───────▼──────▼────────▼──────────▼─────┐  │
│  │                AGENT CORE (shared infrastructure)             │  │
│  │  ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────────┐ │  │
│  │  │Self-     │ │Struct.  │ │Top-Down  │ │Context Manager    │ │  │
│  │  │Challenge │ │Validatn │ │Generator │ │(hydration+recipes)│ │  │
│  │  └──────────┘ └─────────┘ └──────────┘ └─────────┬─────────┘ │  │
│  │  ┌──────────┐ ┌─────────┐ ┌──────────┐           │           │  │
│  │  │LLM       │ │Prompt   │ │Escalation│           │           │  │
│  │  │Abstracn  │ │Handler  │ │Protocol  │           │           │  │
│  │  └────┬─────┘ └─────────┘ └──────────┘           │           │  │
│  └───────┼───────────────────────────────────────────┼───────────┘  │
│          │                                           │              │
│  ┌───────▼───────────────────────────────────────────▼───────────┐  │
│  │                    TRACE SYSTEM                                │  │
│  │  Hierarchical traces → LLM cost tracking → audit log          │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
          │                              │
    ┌─────┼──────────┐         ┌─────────┼──────────────┐
    │     │          │         │         │              │
┌───▼──┐┌─▼──────┐┌─▼──────┐┌─▼──────┐┌─▼───────┐┌────▼───┐
│OpenAI││ Google ││Anthropic││Postgres││ChromaDB ││ GitHub │
│ API  ││  API   ││  API   ││  (DB)  ││ (RAG)   ││  API   │
└──────┘└────────┘└────────┘└────────┘└─────────┘└────────┘
```

---

## 3. Monorepo Structure

```
adt/
├── pyproject.toml                    # Root project config
├── README.md
├── docs/                             # Documentation
│   ├── DESIGN.md                     # This document
│   └── ...
│
├── config/
│   ├── agents.yaml                   # Agent ↔ model mapping + self-challenge criteria
│   ├── workflow.yaml                 # Pipeline step definitions
│   ├── archetypes/                   # Project archetype definitions
│   │   ├── script.yaml
│   │   ├── cli_tool.yaml
│   │   ├── api_backend.yaml
│   │   ├── web_app.yaml
│   │   ├── data_pipeline.yaml
│   │   ├── library.yaml
│   │   ├── infrastructure.yaml
│   │   ├── mobile_backend.yaml
│   │   └── custom.yaml
│   └── .env.example                  # Environment variables template
│
├── src/
│   ├── agent_core/                   # A1 — Shared agent infrastructure
│   │   ├── __init__.py
│   │   ├── base_agent.py             # Abstract base (stateless worker)
│   │   ├── tool_registry.py          # Tool declaration & invocation
│   │   ├── memory.py                 # Short-term & long-term memory
│   │   ├── messaging.py              # Inter-agent message types & protocol
│   │   ├── self_challenge.py         # Self-challenge protocol
│   │   ├── top_down.py               # Top-down generation protocol (L1→L4)
│   │   ├── structural_validator.py   # Lint, type check, parse, import resolution
│   │   ├── escalation.py             # Human escalation protocol
│   │   ├── llm_provider.py           # Multi-provider LLM abstraction
│   │   ├── state.py                  # Agent state management
│   │   └── config.py                 # Per-agent configuration loader
│   │
│   ├── context_manager/              # A13 — Centralized context hydration
│   │   ├── __init__.py
│   │   ├── context_manager.py        # Main context service
│   │   ├── context_recipes.py        # Per-archetype, per-task-type, per-level recipes
│   │   ├── context_bundle.py         # ContextBundle dataclass
│   │   ├── snapshot.py               # Immutable context snapshots
│   │   └── summarizer.py             # Hierarchical summarization for large artifacts
│   │
│   ├── task_queue/                   # A14 — Task persistence & assignment
│   │   ├── __init__.py
│   │   ├── task_model.py             # Task entity + sub-tasks
│   │   ├── task_queue.py             # Role-based queues
│   │   ├── task_assignment.py        # Hybrid pull/push assignment
│   │   └── module_lock.py            # Module locking (EXCLUSIVE/SHARED)
│   │
│   ├── trace_system/                 # A15 — Tracing & cost tracking
│   │   ├── __init__.py
│   │   ├── tracer.py                 # Hierarchical trace creation
│   │   ├── trace_models.py           # Trace dataclasses
│   │   ├── cost_tracker.py           # LLM cost computation per provider/model
│   │   └── trace_store.py            # Persistence to PostgreSQL
│   │
│   ├── archetype_registry/           # A16 — Project archetype management
│   │   ├── __init__.py
│   │   ├── registry.py               # Load + query archetype definitions
│   │   ├── pipeline_adapter.py       # Archetype → adaptive pipeline
│   │   └── tech_stack_resolver.py    # Archetype defaults + customer overrides
│   │
│   ├── orchestrator/                 # A2a — Pipeline-level workflow engine
│   │   ├── __init__.py
│   │   ├── workflow_engine.py        # Pipeline definition & execution
│   │   ├── step_registry.py          # Step ↔ agent role mapping
│   │   ├── state_machine.py          # Project state transitions
│   │   └── gate_manager.py           # Customer acceptance gates
│   │
│   ├── coordinator/                  # A2b — Task-level agent coordination
│   │   ├── __init__.py
│   │   ├── agent_coordinator.py      # Event-driven task coordinator
│   │   ├── task_decomposer.py        # Step → module-scoped tasks → L1-L4 sub-tasks
│   │   ├── parallelism_manager.py    # Parallel execution within module boundaries
│   │   ├── dependency_tracker.py     # Task dependency graph
│   │   └── conflict_resolver.py      # Module lock conflict handling
│   │
│   ├── agents/                       # A3–A10 — Agent implementations
│   │   ├── pm/
│   │   │   ├── __init__.py
│   │   │   ├── pm_agent.py
│   │   │   ├── chat_handler.py
│   │   │   ├── requirement_builder.py
│   │   │   ├── complexity_assessor.py
│   │   │   ├── archetype_selector.py  # Determine project archetype
│   │   │   ├── tech_stack_resolver.py # Determine tech stack from archetype + customer input
│   │   │   └── cost_estimator.py
│   │   │
│   │   ├── architect/
│   │   │   ├── __init__.py
│   │   │   ├── architect_agent.py
│   │   │   ├── design_generator.py    # Top-down: L1 structure → L4 details
│   │   │   ├── diagram_engine.py
│   │   │   ├── integration_planner.py
│   │   │   └── modular_monolith.py    # Module boundary definition
│   │   │
│   │   ├── dev/
│   │   │   ├── __init__.py
│   │   │   ├── dev_agent.py
│   │   │   ├── skeleton_generator.py  # L1: file tree + responsibilities
│   │   │   ├── contract_generator.py  # L2: stubs with typed signatures
│   │   │   ├── wiring_generator.py    # L3: import graph + call chain
│   │   │   ├── logic_generator.py     # L4: business logic per function
│   │   │   ├── fix_loop.py
│   │   │   └── git_ops.py
│   │   │
│   │   ├── qa/
│   │   │   ├── __init__.py
│   │   │   ├── qa_agent.py
│   │   │   ├── test_definer.py        # Top-down: L1 test files → L4 assertions
│   │   │   ├── test_quality_reviewer.py # Pre-dev: reviews test completeness
│   │   │   ├── test_runner.py         # Runs ALL tests (regression protection)
│   │   │   ├── integration_tester.py  # Cross-module integration tests
│   │   │   └── report_generator.py
│   │   │
│   │   ├── devops/
│   │   │   ├── __init__.py
│   │   │   ├── devops_agent.py
│   │   │   ├── repo_manager.py
│   │   │   └── workspace_manager.py
│   │   │
│   │   ├── reviewer/
│   │   │   ├── __init__.py
│   │   │   ├── reviewer_agent.py
│   │   │   ├── workflow_verifier.py
│   │   │   ├── design_verifier.py
│   │   │   ├── code_verifier.py
│   │   │   ├── acceptance_checker.py
│   │   │   └── checklist_engine.py
│   │   │
│   │   ├── delivery/
│   │   │   ├── __init__.py
│   │   │   ├── delivery_agent.py
│   │   │   ├── zip_packager.py
│   │   │   └── doc_generator.py       # README, changelog, setup instructions
│   │   │
│   │   └── billing/                   # Billing Agent
│   │       ├── __init__.py
│   │       └── billing_agent.py       # Independent billing traceability
│   │
│   ├── rag/                           # A11 — Shared RAG
│   │   ├── __init__.py
│   │   ├── store.py                   # Vector store abstraction
│   │   ├── ingestion.py               # Document chunking & embedding
│   │   ├── retrieval.py               # Similarity search & context building
│   │   └── seed_data/                 # Reference implementations per archetype
│   │       ├── api_backend/
│   │       │   ├── reference_project/
│   │       │   ├── patterns.md
│   │       │   ├── anti_patterns.md
│   │       │   └── security_checklist.md
│   │       ├── web_app/
│   │       │   ├── reference_project/
│   │       │   └── patterns.md
│   │       ├── script/
│   │       │   └── patterns.md
│   │       └── ...
│   │
│   ├── prompt_handler/                # A12 — Common prompt management
│   │   ├── __init__.py
│   │   ├── template_engine.py         # Prompt template rendering
│   │   ├── role_prompts.py            # System prompts per agent role
│   │   └── templates/                 # Versioned prompt templates
│   │       ├── pm.yaml
│   │       ├── architect.yaml
│   │       ├── dev.yaml
│   │       ├── qa.yaml
│   │       ├── devops.yaml
│   │       ├── reviewer.yaml
│   │       └── delivery.yaml
│   │
│   ├── platform/                      # B — Minimal platform (MVP shell)
│   │   ├── __init__.py
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   ├── main.py               # FastAPI entrypoint
│   │   │   ├── routes/
│   │   │   │   ├── chat.py           # WebSocket chat endpoint
│   │   │   │   ├── projects.py       # Project CRUD
│   │   │   │   ├── artifacts.py      # Artifact download/view
│   │   │   │   └── traces.py         # Trace/cost query endpoint
│   │   │   ├── models/               # Pydantic request/response models
│   │   │   └── services/
│   │   │       ├── project_service.py
│   │   │       └── chat_service.py
│   │   │
│   │   └── db/
│   │       ├── __init__.py
│   │       ├── database.py           # Connection & session management
│   │       ├── models.py             # SQLAlchemy ORM models
│   │       └── migrations/           # Alembic migrations
│   │
│   └── web/                           # Minimal React frontend
│       ├── package.json
│       ├── tailwind.config.js
│       ├── vite.config.ts
│       ├── src/
│       │   ├── App.tsx
│       │   ├── main.tsx
│       │   ├── components/
│       │   │   ├── Chat.tsx
│       │   │   ├── ProjectList.tsx
│       │   │   ├── StepTracker.tsx
│       │   │   └── ArtifactView.tsx
│       │   ├── hooks/
│       │   │   ├── useWebSocket.ts
│       │   │   └── useProject.ts
│       │   └── api/
│       │       └── client.ts
│       └── public/
│
├── tests/
│   ├── unit/
│   │   ├── test_agent_core/
│   │   ├── test_context_manager/
│   │   ├── test_task_queue/
│   │   ├── test_trace_system/
│   │   ├── test_orchestrator/
│   │   ├── test_coordinator/
│   │   └── test_agents/
│   └── integration/
│       ├── test_pipeline_e2e.py
│       ├── test_agent_communication.py
│       └── test_top_down_generation.py
│
└── workspace/                         # Shared agent workspace (gitignored)
    └── projects/
```

---

## 4. Agent System Design

### 4.1 Core Principle: Agents Are Stateless Workers

Agents do **not** hold project state. They are workers that:
1. Claim a task from the queue
2. Request a context bundle from the Context Manager
3. Execute the task using top-down generation
4. Run structural validation
5. Run self-challenge
6. Return the result + artifacts
7. Become available for the next task

If an agent crashes, dies, or is replaced — another instance picks up the task from where it was paused (context is in the DB, not in the agent's memory).

### 4.2 Base Agent Class

```
┌───────────────────────────────────────────────┐
│              BaseAgent (abstract)              │
├───────────────────────────────────────────────┤
│ - agent_id: str                               │
│ - role: AgentRole (enum)                      │
│ - llm: LLMProvider                            │
│ - tools: ToolRegistry                         │
│ - config: AgentConfig                         │
│ - prompt_handler: PromptHandler               │
│ - context_manager: ContextManager             │
│ - tracer: Tracer                              │
├───────────────────────────────────────────────┤
│ + execute(task: Task) → TaskResult            │
│   1. context = context_manager.hydrate(task)  │
│   2. result = _do_work(task, context)         │
│   3. structural_validate(result)              │
│   4. challenge_result = self_challenge(result)│
│   5. trace(task, result, challenge_result)    │
│   6. return result                            │
│                                               │
│ + self_challenge(result) → ChallengeResult    │
│ + structural_validate(result) → ValidationRes │
│ + escalate(reason) → EscalationAction         │
│ + claim_task(queue) → Task                    │
│                                               │
│ # _do_work(task, context) → Result [abstract] │
│ # _challenge_criteria() → list [abstract]     │
│ # _supported_levels() → list[Level]           │
└───────────────────────────────────────────────┘
          ▲          ▲          ▲          ▲
          │          │          │          │
    ┌─────┘    ┌─────┘    ┌─────┘    ┌─────┘
┌───┴───┐ ┌───┴────┐ ┌───┴───┐ ┌───┴──────┐
│PMAgent│ │DevAgent│ │QAAgent│ │ArchAgent │  ... (all agents)
└───────┘ └────────┘ └───────┘ └──────────┘
```

### 4.3 Agent Lifecycle

```
  ┌──────┐
  │ IDLE │ ← Agent initialized, waiting for work
  └──┬───┘
     │ claim task from queue
  ┌──▼──────────┐
  │ HYDRATING   │ ← Requesting context bundle from Context Manager
  └──┬──────────┘
     │
  ┌──▼──────┐
  │ WORKING │ ← Executing _do_work() at current level (L1/L2/L3/L4)
  └──┬──────┘
     │ work complete
  ┌──▼──────────┐
  │ VALIDATING  │ ← Structural validation (lint, types, parse)
  └──┬──────┬───┘
     │ pass │ fail → auto-fix or rework
     │      │
  ┌──▼───────────┐
  │ CHALLENGING  │ ← Self-challenge against acceptance criteria
  └──┬───────┬───┘
     │ pass  │ fail
     │       │
     │   ┌───▼──────┐
     │   │ REWORKING │ ← Fix issues (max N retries)
     │   └───┬──────┘
     │       │ loop back to VALIDATING
     │       │
  ┌──▼──────▼──┐
  │    DONE    │ ← Result persisted, agent returns to IDLE
  └────────────┘
```

### 4.4 Agent Configuration (agents.yaml)

```yaml
agents:
  pm:
    role: "pm"
    display_name: "PM Agent"
    llm:
      provider: "google"
      model: "gemini-2.0-flash"
      temperature: 0.4            # Creative for conversation
    self_challenge:
      enabled: true
      max_retries: 2
      criteria:
        - "All ambiguities resolved"
        - "Complexity assessment justified with reasoning"
        - "No missing functional areas"
        - "Archetype selection matches project description"
        - "Tech stack is appropriate for the archetype"
    tools: ["chat", "rag_query", "rag_store"]

  architect:
    role: "architect"
    display_name: "Architect Agent"
    llm:
      provider: "anthropic"
      model: "claude-sonnet-4-20250514"
      temperature: 0              # Deterministic design
    self_challenge:
      enabled: true
      max_retries: 2
      criteria:
        - "All modules defined with clear boundaries"
        - "Diagrams match textual description"
        - "Integration points fully specified"
        - "Modular monolith constraint satisfied (when applicable)"
        - "No assumptions beyond provided requirements"
    top_down_levels: ["skeleton", "contracts", "wiring", "details"]
    tools: ["diagram_generator", "rag_query", "rag_store"]

  dev:
    role: "dev"
    display_name: "Dev Agent"
    llm:
      provider: "anthropic"
      model: "claude-sonnet-4-20250514"
      temperature: 0              # Deterministic code
    self_challenge:
      enabled: true
      max_retries: 3
      criteria:
        - "Code matches accepted design"
        - "All referenced imports/modules actually exist"
        - "No invented API endpoints or methods"
        - "No hardcoded secrets or credentials"
        - "No assumptions beyond provided context"
        - "Code follows reference implementation patterns"
      grounding_verification: true
    top_down_levels: ["skeleton", "contracts", "wiring", "logic"]
    structural_validation:
      - "syntax_check"
      - "lint"
      - "type_check"
      - "import_resolution"
      - "dependency_check"
    tools: ["code_writer", "file_system", "git", "rag_query"]

  qa:
    role: "qa"
    display_name: "QA Agent"
    llm:
      provider: "google"
      model: "gemini-2.0-flash"
      temperature: 0
    self_challenge:
      enabled: true
      max_retries: 2
      criteria:
        - "Test coverage addresses all acceptance criteria"
        - "Edge cases and boundary conditions covered"
        - "Error/exception paths tested"
        - "Tests are independent and meaningful"
        - "No tautological tests"
    top_down_levels: ["skeleton", "contracts", "wiring", "logic"]
    tools: ["test_runner", "report_writer", "rag_query", "log_analyzer"]

  devops:
    role: "devops"
    display_name: "DevOps Agent"
    llm:
      provider: "google"
      model: "gemini-2.0-flash"
      temperature: 0
    self_challenge:
      enabled: true
      max_retries: 2
      criteria:
        - "Repository structure matches design"
        - "All required files present"
        - "Workspace properly configured"
    top_down_levels: ["skeleton", "contracts", "wiring", "details"]
    tools: ["github_api", "file_system"]

  reviewer:
    role: "reviewer"
    display_name: "Reviewer Agent"
    llm:
      provider: "anthropic"
      model: "claude-sonnet-4-20250514"
      temperature: 0
    self_challenge:
      enabled: true
      max_retries: 1
      criteria:
        - "All workflow steps verified"
        - "Checklist is complete and accurate"
    tools: ["rag_query", "file_reader", "checklist_writer"]

  delivery:
    role: "delivery"
    display_name: "Delivery Agent"
    llm:
      provider: "google"
      model: "gemini-2.0-flash"
      temperature: 0
    self_challenge:
      enabled: true
      max_retries: 1
      criteria:
        - "All artifacts included"
        - "Documentation up to date (README, setup, changelog)"
        - "No secrets in deliverable"
    top_down_levels: ["skeleton", "contracts", "wiring", "details"]
    tools: ["zip_packager", "file_system", "git"]

  billing:
    role: "billing"
    display_name: "Billing Agent"
    llm:
      provider: "google"
      model: "gemini-2.0-flash"
      temperature: 0
    self_challenge:
      enabled: true
      max_retries: 1
      criteria:
        - "Cost calculation matches trace data"
        - "All steps accounted for"
    tools: ["trace_reader", "cost_calculator"]
```

---

## 5. Task Model

### 5.1 Task Entity

The unit of work in ADT. Every piece of work — from gathering requirements to implementing a function — is a Task with explicit acceptance criteria.

```python
@dataclass
class Task:
    id: UUID
    project_id: UUID
    step_id: str                     # "3.1", "3.2", "3.4", etc.
    module_id: str | None            # Target module (None = project-wide)
    type: str                        # "gather_requirements", "generate_skeleton", etc.
    level: GenerationLevel | None    # L1_SKELETON, L2_CONTRACTS, L3_WIRING, L4_LOGIC
    agent_role: str                  # Which agent role handles this
    status: TaskStatus
    acceptance_criteria: list[str]   # What defines "done"
    input_artifacts: list[UUID]      # Artifact references needed
    output_artifacts: list[UUID]     # Artifacts produced
    assigned_agent_id: str | None
    context_snapshot_id: UUID | None # Link to context snapshot
    parent_task_id: UUID | None      # For sub-tasks
    archetype: str                   # Project archetype
    priority: int
    created_at: datetime
    updated_at: datetime
    paused_at: datetime | None
    completed_at: datetime | None
    metadata: dict                   # Flexible per-task data

class TaskStatus(str, Enum):
    CREATED = "created"
    QUEUED = "queued"
    ASSIGNED = "assigned"
    IN_PROGRESS = "in_progress"
    VALIDATING = "validating"
    CHALLENGING = "challenging"
    REWORKING = "reworking"
    PAUSED = "paused"
    COMPLETED = "completed"
    FAILED = "failed"
    ESCALATED = "escalated"

class GenerationLevel(str, Enum):
    L1_SKELETON = "skeleton"
    L2_CONTRACTS = "contracts"
    L3_WIRING = "wiring"
    L4_LOGIC = "logic"
```

### 5.2 Task Decomposition Example

```
Project: "Build a task manager API" (archetype: api_backend, complexity: mid)

Step 3.4 (Development) decomposes into:

Task: "implement auth module"
  ├── Sub-task: "auth — L1 skeleton"       → Dev Agent
  │     acceptance_criteria:
  │       - "All files from design listed"
  │       - "Each file has clear responsibility"
  │
  ├── Sub-task: "auth — L2 contracts"      → Dev Agent
  │     acceptance_criteria:
  │       - "All public functions have typed signatures"
  │       - "Cross-module interfaces match design contracts"
  │       - "Structural validation passes"
  │
  ├── Sub-task: "auth — L3 wiring"         → Dev Agent
  │     acceptance_criteria:
  │       - "All imports resolve"
  │       - "Call chain matches sequence diagrams"
  │       - "No circular dependencies"
  │
  └── Sub-tasks: "auth — L4 [function]"    → Dev Agent (one per function, parallelizable)
        acceptance_criteria:
          - "Function passes its unit tests"
          - "Follows reference implementation patterns"
          - "No hardcoded values"

Task: "implement tasks module"              → Same L1-L4 structure (parallel with auth)
Task: "implement notifications module"      → Same L1-L4 structure (parallel)
Task: "integration — all modules"           → Sequential, locks all modules
```

### 5.3 Task Lifecycle

```
CREATED → QUEUED → ASSIGNED → IN_PROGRESS → VALIDATING → CHALLENGING → COMPLETED
                                    │              │            │
                                    │              │     fail   │
                                    │              │    ┌───▼───┤
                                    │              │    │REWORK │──► back to VALIDATING
                                    │              │    └───────┘   (max N retries)
                                    │         fail │
                                    │         auto-fix → back to IN_PROGRESS
                                    │
                                    ├─── pause ──► PAUSED ──► resume ──► IN_PROGRESS
                                    │
                                    └─── stuck ──► ESCALATED (human intervention)
```

---

## 6. Workflow Engine & Adaptive Pipeline

### 6.1 Adaptive Pipeline

The pipeline is NOT fixed. It's loaded from the selected **archetype** after step 3.1:

```yaml
# config/archetypes/api_backend.yaml
archetype:
  id: "api_backend"
  display_name: "API Backend Service"
  complexity_cap: null

  pipeline:
    required_steps: ["3.1", "3.2", "3.2.1", "3.4", "3.5", "3.7", "3.8"]
    optional_steps: ["3.6"]
    skipped_steps: ["3.3"]

  structure:
    modules: "determined_at_design"
    repo_required: true

  tech_stack:
    defaults:
      language: "python"
      framework: "fastapi"
      database: "postgresql"
      testing: "pytest"
      deployment: "docker"
    customer_overridable: true

  delivery:
    format: "repo_zip"

  context_recipe: "standard"

  acceptance_criteria_templates:
    development:
      - "All endpoints match API contract"
      - "Authentication works as specified"
      - "All tests pass with >90% coverage"
      - "Database migrations run cleanly"
```

```yaml
# config/archetypes/script.yaml
archetype:
  id: "script"
  display_name: "Simple Script"
  complexity_cap: "low"

  pipeline:
    required_steps: ["3.1", "3.4", "3.5", "3.8"]
    optional_steps: []
    skipped_steps: ["3.2", "3.3", "3.6", "3.7"]

  structure:
    modules: 1
    max_files: 5
    repo_required: false

  tech_stack:
    defaults:
      language: "determined_at_requirements"
      framework: null
      testing: "minimal"
      deployment: "none"
    customer_overridable: true

  delivery:
    format: "single_file_or_zip"

  context_recipe: "minimal"
```

### 6.2 Pipeline Loading Flow

```
Customer submits request
    │
    ▼
PM Agent gathers requirements
PM Agent selects archetype + resolves tech stack
PM Agent assesses complexity
    │
    ▼
Customer approves: requirement doc + archetype + tech stack
    │
    ▼
Orchestrator loads archetype definition
Orchestrator builds adaptive pipeline (only required + optional steps)
Orchestrator initializes project state machine
    │
    ▼
Pipeline executes step by step
```

### 6.3 State Machine

```
                    ┌──────────┐
                    │ CREATED  │
                    └────┬─────┘
                         │
                    ┌────▼───────────────┐
                    │ REQUIREMENTS (3.1) │
                    │ [PM Agent]         │
                    └────┬──────────┬────┘
                    approve     ┌───▼────┐
                         │      │CANCELED│ ← Customer can abort at ANY step
                         │      └────────┘
                    ┌────▼────┐
         ┌─────────│ DESIGN? │ ← Depends on archetype
         │ skip    │ (3.2)   │   (script skips this)
         │         └────┬────┘
         │              │ approve
         │         ┌────▼──────┐
         │         │ ENV SETUP │ (3.2.1) ← if repo_required
         │         └────┬──────┘
         │              │
         ├──────────────┤
         │              │
                   ┌────▼────────┐
                   │ DEVELOPMENT │ (3.4) ← Tasks decomposed per module + L1-L4
                   └────┬────────┘
                        │
                   ┌────▼────┐     ┌────────┐
                   │ TESTING │────►│DEV FIX │ (loop on failure)
                   │ (3.5)   │◄───│        │ (full regression re-run)
                   └────┬────┘     └────────┘
                        │ all pass
         ┌──────────────┤
         │ skip         │
         │ (script)┌────▼────────────┐
         │         │ VERIFICATION    │ (3.7) ← if in pipeline
         │         └────┬────────────┘
         │              │
         ├──────────────┤
         │              │
                   ┌────▼────┐
                   │DELIVERY │ (3.8)
                   └────┬────┘
                        │
                   ┌────▼──────┐
                   │ COMPLETED │
                   └───────────┘
```

### 6.4 Step 3.1 Outputs (Updated)

```
Step 3.1 produces:
  1. Refined requirement document
  2. Complexity assessment (low / mid / high)
  3. Cost/time estimate per step
  4. Selected archetype (from registry)
  5. Resolved tech stack (archetype defaults + customer overrides)
  6. Adapted pipeline definition (which steps will run)
```

---

## 7. Agent Coordinator

### 7.1 Role

The Agent Coordinator sits between the Workflow Engine (pipeline level) and the Task Queue (execution level). It is **event-driven** — reacts to task state changes.

```
Workflow Engine: "Step 3.4 (Development) is active"
      │
      ▼
Agent Coordinator:
  1. Read module definitions from design
  2. For each module, create task chain: L1 → L2 → L3 → L4[]
  3. Manage module locks
  4. Track dependencies between tasks
  5. Detect when all module tasks complete → signal integration task
  6. Detect when integration completes → signal step complete
      │
      ▼
Task Queue: Tasks available for agents to claim
```

### 7.2 Parallel Execution Model

```
Step 3.4 creates:

  auth module:     L1 ──► L2 ──► L3 ──┬── L4(func_a) ──► done
                                       ├── L4(func_b) ──► done
                                       └── L4(func_c) ──► done
                                                              │
  tasks module:    L1 ──► L2 ──► L3 ──┬── L4(func_x) ──► done│  ← parallel
                                       └── L4(func_y) ──► done│    modules
                                                              │
  notif module:    L1 ──► L2 ──► L3 ──── L4(func_z) ──► done │
                                                              │
                                 Integration task ◄───────────┘  ← sequential, locks all

Max parallel tasks = number of modules (one task per module at any time)
Within a module, L4 functions are also parallelizable
```

### 7.3 Module Locking

```python
@dataclass
class ModuleLock:
    module_id: str
    project_id: UUID
    locked_by_task_id: UUID
    lock_type: LockType        # EXCLUSIVE or SHARED
    acquired_at: datetime

class LockType(str, Enum):
    EXCLUSIVE = "exclusive"    # Normal module task (one writer)
    SHARED = "shared"          # Read-only access (multiple readers, e.g., QA reviewing)
```

- **Module tasks** (L1-L4): EXCLUSIVE lock on their module
- **Integration tasks**: EXCLUSIVE lock on ALL involved modules
- **QA review tasks**: SHARED lock (multiple readers OK, blocks writers)

### 7.4 Event-Driven Coordination

The Coordinator reacts to:

| Event | Action |
|-------|--------|
| Step activated | Decompose into module-scoped tasks + L1-L4 sub-tasks |
| Task completed | Check if next sub-task can start; release module lock |
| All L4 tasks for a module done | Mark module task chain as complete |
| All module chains done | Create integration task |
| Integration task done | Signal step complete to Workflow Engine |
| Task failed after max retries | Trigger escalation |
| Task paused | Hold module lock; task resumes where it left off |

---

## 8. Centralized Context Manager

### 8.1 Purpose

The Context Manager is the **single source of truth** for what context an agent receives. Agents never assemble their own context — they request a hydrated bundle.

### 8.2 Context Bundle

```python
@dataclass
class ContextBundle:
    project: ProjectSummary           # id, name, status, complexity, archetype
    task: TaskInfo                    # id, type, level, acceptance_criteria
    tech_stack: TechStack             # Language, framework, testing tools
    artifacts: dict[str, str]         # Relevant artifacts (curated, not all)
    rag_context: list[str]            # Retrieved RAG chunks
    reference_patterns: list[str]     # Archetype-specific patterns from RAG
    chat_history: list[Message] | None # Only for PM Agent tasks
    module_interfaces: dict | None     # Other modules' contracts (for wiring/integration)
    token_budget: int                  # Max tokens for this context
    snapshot_id: UUID                  # Immutable reference
    upstream_changed: bool             # Flag if upstream artifacts changed since snapshot
```

### 8.3 Context Recipes

Each combination of (archetype, task_type, generation_level) has a recipe:

```yaml
context_recipes:
  # Dev Agent implementing a function (L4)
  dev_logic:
    include:
      - "function_stub"                # This function's signature + docstring
      - "function_dependencies"        # Signatures of called functions
      - "function_tests"               # Test cases for this function
      - "reference_patterns"           # Archetype-specific code patterns
    exclude:
      - "full_design_doc"
      - "other_modules_code"
      - "chat_history"
      - "requirement_doc"
    max_tokens: 5000

  # Dev Agent creating file skeleton (L1)
  dev_skeleton:
    include:
      - "module_design_section"        # Just this module's design
      - "archetype_structure_template" # Expected project structure
    exclude:
      - "other_modules"
      - "code"
      - "tests"
    max_tokens: 3000

  # Architect Agent creating design (L2 — contracts)
  architect_contracts:
    include:
      - "requirement_doc"
      - "module_skeleton"              # L1 output
      - "integration_requirements"
      - "reference_patterns"
    exclude:
      - "code"
      - "chat_history_full"
    max_tokens: 15000

  # PM Agent chatting
  pm_chat:
    include:
      - "conversation_summary"         # Compressed history
      - "last_n_messages": 10          # Sliding window
      - "archetype_descriptions"       # For selection
      - "customer_initial_input"
    exclude:
      - "design_docs"
      - "code"
    max_tokens: 8000

  # QA Agent reviewing test quality (pre-dev)
  qa_test_review:
    include:
      - "test_definitions"
      - "acceptance_criteria"
      - "module_design_section"
      - "anti_patterns"
    exclude:
      - "code"
      - "other_modules_tests"
    max_tokens: 10000

  # Reviewer Agent — full verification
  reviewer_verify:
    include:
      - "requirement_summary"          # Summarized, not full
      - "design_summary"              # Summarized
      - "module_summaries"            # Code summaries per module
      - "test_report"
      - "acceptance_criteria"
    exclude:
      - "full_code"                   # Drill-in only if issues found
    max_tokens: 15000
```

### 8.4 Hierarchical Summarization

For artifacts too large for the token budget, the Context Manager summarizes:

```
Full design doc (15K tokens)
    │  summarize for Dev Agent
    ▼
Module-specific section (2K tokens)

Full codebase (50K tokens)
    │  summarize for Reviewer Agent
    ▼
Module summaries + interfaces (8K tokens)
    │  if issue detected → drill in
    ▼
Full code for specific module (10K tokens)
```

Summarization uses a **cheap/fast model** (e.g., Gemini Flash) to minimize cost.

### 8.5 Snapshot Strategy

- Context is **snapshotted at task assignment** (immutable input)
- If upstream artifacts change after snapshot, the `upstream_changed` flag is set
- Agent can check the flag and request a re-sync if needed
- This prevents mid-task confusion from changing inputs

---

## 9. Project Archetypes

### 9.1 Archetype Registry

Archetypes live in `config/archetypes/` as YAML files. New archetypes can be added without code changes.

| Archetype | Complexity Range | Pipeline | Example |
|-----------|-----------------|----------|---------|
| `script` | Low | 3.1→3.4→3.5→3.8 | "Parse CSV and email summary" |
| `cli_tool` | Low–Mid | 3.1→3.2(light)→3.4→3.5→3.8 | "Docker management CLI" |
| `api_backend` | Mid–High | 3.1→3.2→3.4→3.5→3.7→3.8 | "User management microservice" |
| `web_app` | Mid–High | 3.1→3.2→3.3→3.4→3.5→3.7→3.8 | "Task manager with React + API" |
| `data_pipeline` | Mid | 3.1→3.2→3.4→3.5→3.8 | "S3 ingest → transform → DB" |
| `library` | Low–Mid | 3.1→3.2(light)→3.4→3.5→3.8 | "Python SDK for payment API" |
| `infrastructure` | Mid | 3.1→3.2→3.4→3.5→3.6→3.7→3.8 | "Terraform AWS EKS setup" |
| `mobile_backend` | Mid–High | 3.1→3.2→3.4→3.5→3.6→3.7→3.8 | "Firebase + REST for iOS app" |
| `custom` | Any | PM defines pipeline | Edge cases |

### 9.2 Archetype Selection Flow

```
PM Agent during step 3.1:
  1. Analyze customer description
  2. Match to archetype (confidence score)
  3. Present to customer: "This looks like an API Backend project.
     I'll use Python + FastAPI. Does that sound right?"
  4. Customer confirms or overrides
  5. Tech stack resolved: archetype defaults + customer preferences
  6. Pipeline adapted from archetype definition
```

### 9.3 How Archetypes Reduce Risk

| Without Archetypes | With Archetypes |
|-------------------|-----------------|
| Every project gets full pipeline | Simple projects get minimal pipeline |
| Agent guesses tech stack | Tech stack pre-determined from archetype |
| Agent invents project structure | Structure comes from template |
| Generic self-challenge criteria | Archetype-specific, precise criteria |
| Unfocused RAG retrieval | RAG scoped to archetype + tech stack |
| Script gets enterprise pipeline | Script gets 4-step fast path |

---

## 10. Top-Down Generation Protocol

### 10.1 Overview

All producing agents (Dev, Architect, QA, DevOps, Delivery) follow a **general → particular** approach. Each level is a separate sub-task with its own acceptance criteria and structural validation gate.

### 10.2 Levels

```
Level 1 — SKELETON (Structure)
  "What do I need?"
  Output: File list + one-line purpose per file
  Validation: Matches design doc
  Context: ~2-3K tokens

Level 2 — CONTRACTS (Interfaces)
  "What does each piece expose?"
  Output: Function/class stubs with typed signatures, docstrings, no implementation
  Validation: Syntax, types, imports all resolve
  Context: ~5K tokens

Level 3 — WIRING (Integration)
  "How do the pieces connect?"
  Output: Function bodies with calls to other functions, business logic = NotImplementedError
  Validation: Import graph valid, call chain matches design, no circular deps
  Context: ~5-8K tokens

Level 4 — LOGIC (Implementation)
  "Fill in the actual behavior, one function at a time."
  Output: Complete function implementation
  Validation: Unit tests pass, lint clean, types check
  Context: ~3-5K tokens per function
```

### 10.3 Applied to Each Producing Agent

**Dev Agent (Code):**
```
L1: File tree + responsibilities
L2: Function/class stubs with signatures and types (valid, parseable code)
L3: Import graph + call chain + integration points
L4: Business logic per function (parallelizable)
```

**Architect Agent (Design):**
```
L1: Module names + one-line purposes
L2: Module interfaces + API contracts
L3: Module dependency map + data flow
L4: Internal class structure per module, sequence diagrams
```

**QA Agent (Tests):**
```
L1: Test file list + what each tests
L2: Test function names + what they verify (one-line each)
L3: Test execution order, fixtures, setup/teardown
L4: Test assertions and edge case implementations
```

**DevOps Agent (Infrastructure):**
```
L1: Config files needed + purposes
L2: File structure + key configuration stubs
L3: Dependencies between configs
L4: Actual configuration values
```

**Delivery Agent (Packaging):**
```
L1: Deliverable contents list
L2: Documentation structure (README sections, changelog format)
L3: File collection + cleanup rules
L4: Actual documentation content + packaging
```

### 10.4 Verification Gates Between Levels

```
L1 → L2 gate:
  ✅ Self-challenge: Are any files missing? Any unnecessary?

L2 → L3 gate:
  ✅ Structural: Syntax valid? Types resolve? Imports exist?
  ✅ Self-challenge: Do interfaces match design contracts?

L3 → L4 gate:
  ✅ Structural: No circular imports? Call chain complete?
  ✅ Self-challenge: Does wiring match sequence diagrams?

Each L4 function:
  ✅ Structural: Parses, lint passes, types check
  ✅ Tests: Unit tests for this function pass
  ✅ Self-challenge: Logic matches requirements? Edge cases?
```

### 10.5 L2 Output Example (Valid Code)

```python
# L2 output — auth/service.py (parseable, lintable, type-checkable)
from dataclasses import dataclass
from typing import Optional
from .models import User, AuthToken
from .repository import UserRepository


@dataclass
class AuthService:
    """Handles user authentication and token management."""

    repo: UserRepository

    def register_user(self, email: str, password: str) -> User:
        """Register a new user. Raises ValueError if email exists."""
        raise NotImplementedError  # L4

    def authenticate(self, email: str, password: str) -> AuthToken:
        """Authenticate and return token. Raises AuthError if invalid."""
        raise NotImplementedError  # L4

    def validate_token(self, token: str) -> Optional[User]:
        """Validate token, return user. Returns None if expired."""
        raise NotImplementedError  # L4
```

### 10.6 L4 Context per Function

```
Context for implementing `register_user`:
  - This function's signature + docstring (from L2)
  - UserRepository.create_user() signature (dependency, from L2)
  - Test cases for register_user (from QA L2)
  - Reference pattern: "create entity with duplicate check"

Total: ~3K tokens. Minimal hallucination risk.
```

---

## 11. Self-Challenge Protocol

### 11.1 Flow

```
Agent produces output (at current level)
        │
        ▼
Load acceptance criteria for this task
+ Load role-specific criteria from agents.yaml
+ Add anti-hallucination checks
        │
        ▼
LLM evaluates output:
  "You completed [task]. Your output: [output].
   Evaluate against each criterion:
   1. [criterion] — PASS or FAIL? Why?
   ...
   Did you invent anything not in the context?
   List every assumption you made."
        │
   ┌────▼────┐
   │All pass?│
   └┬───────┬┘
    YES     NO
    │       │
    │  Agent reworks based on feedback
    │  (up to max_retries)
    │       │
    ▼       ▼
  Return result + challenge log
```

### 11.2 Data Structures

```python
@dataclass
class ChallengeResult:
    passed: bool
    attempt: int
    criteria_results: list[CriterionResult]
    assumptions_declared: list[str]   # What the agent assumed
    grounding_check: bool             # Did it invent anything?
    feedback: str | None
    rework_description: str | None

@dataclass
class CriterionResult:
    criterion: str
    passed: bool
    explanation: str
```

### 11.3 Self-Challenge vs. Reviewer Agent

| Aspect | Self-Challenge | Reviewer Agent |
|--------|---------------|----------------|
| **When** | After each task (each level) | After full pipeline (step 3.7) |
| **Who** | The agent that did the work | Dedicated Reviewer Agent |
| **Scope** | Single task output | Entire workflow + all artifacts |
| **Purpose** | Catch gaps in own work | Cross-cutting end-to-end verification |
| **Criteria** | Task-specific + role-specific | Requirements ↔ design ↔ code ↔ tests alignment |

---

## 12. Structural Validation Layer

### 12.1 Purpose

Mechanical checks that run **before** the self-challenge. No LLM needed — just tools.

### 12.2 Validations

| Check | What It Catches | Tool | When |
|-------|----------------|------|------|
| Syntax check | Code that doesn't parse | Language parser/compiler | L2, L3, L4 |
| Linting | Style violations, common bugs | Ruff (Python), ESLint (JS/TS) | L2, L3, L4 |
| Type checking | Type mismatches | mypy (Python), tsc (TypeScript) | L2, L3, L4 |
| Import resolution | Nonexistent modules/packages | Static analysis | L2, L3 |
| Dependency check | Missing packages, version conflicts | pip check, npm audit | L3, L4 |
| Schema validation | API contracts mismatch | OpenAPI validator | L3 |
| File structure | Expected files missing | Archetype template checker | L1 |
| Circular dependency | Circular imports | Import graph analysis | L3 |

### 12.3 Flow

```
Agent produces output
    │
    ▼
STRUCTURAL VALIDATION (no LLM)
  - Parse? ✅
  - Lint? 2 warnings → auto-fix
  - Types? ✅
  - Imports? ✅
    │
    ▼ Only if passes
SELF-CHALLENGE (LLM reasoning)
    │
    ▼
Result returned
```

If structural validation fails, the agent gets the error output and retries **without consuming a self-challenge attempt**. Structural fixes are deterministic — no need for LLM review.

---

## 13. LLM Abstraction Layer

### 13.1 Class Design

```
┌──────────────────────────────────┐
│       LLMProvider (abstract)     │
├──────────────────────────────────┤
│ + generate(prompt, **kwargs)     │
│   → LLMResponse                 │
│ + generate_structured(prompt,    │
│   schema) → dict                │
│ + stream(prompt, **kwargs)       │
│   → AsyncIterator[str]          │
│ + count_tokens(text) → int      │
│ + get_model_info() → ModelInfo   │
├──────────────────────────────────┤
│ - provider_name: str             │
│ - model_name: str                │
│ - temperature: float             │
│ - api_key: str                   │
└──────────┬───────────────────────┘
           │
     ┌─────┼──────────────┐
     │     │              │
┌────▼──┐ ┌▼────────┐ ┌──▼────────┐
│OpenAI │ │ Google   │ │ Anthropic │
│Provdr │ │ Provider │ │ Provider  │
└───────┘ └──────────┘ └───────────┘

┌──────────────────────────────────┐
│       LLMProviderFactory         │
├──────────────────────────────────┤
│ + create(provider, model,        │
│   api_key, temp) → LLMProvider   │
│ + from_agent_config(config)      │
│   → LLMProvider                  │
└──────────────────────────────────┘
```

### 13.2 Response with Cost Tracking

```python
@dataclass
class LLMResponse:
    content: str
    model: str
    provider: str
    tokens: TokenUsage
    latency_ms: int
    cost_estimate: float           # Computed from tokens × price per token

@dataclass
class TokenUsage:
    prompt_tokens: int
    completion_tokens: int
    total_tokens: int
```

### 13.3 Deterministic Settings

| Agent Role | Temperature | Rationale |
|-----------|-------------|-----------|
| PM | 0.4 | Creative conversation |
| Architect | 0 | Deterministic design |
| Dev | 0 | Deterministic code generation |
| QA | 0 | Deterministic test definitions |
| DevOps | 0 | Deterministic configuration |
| Reviewer | 0 | Analytical verification |
| Delivery | 0 | Deterministic packaging |

---

## 14. Shared RAG Design

### 14.1 Architecture

```
┌────────────────────────────────────────────────┐
│                   RAG Store                     │
│                                                 │
│  ┌──────────┐        ┌──────────────────────┐  │
│  │Ingestion │        │     Retrieval        │  │
│  │chunk()   │        │ search(query, scope) │  │
│  │embed()   │        │ → [RelevantChunk]    │  │
│  │store()   │        └──────────────────────┘  │
│  └──────────┘                                  │
│                                                 │
│  Collections (ChromaDB):                        │
│  ├── project_{id}_requirements                  │
│  ├── project_{id}_design                        │
│  ├── project_{id}_code                          │
│  ├── project_{id}_tests                         │
│  ├── shared_knowledge                           │
│  └── archetype_{id}_references ← Reference impl │
└─────────────────────────────────────────────────┘
```

### 14.2 Reference Implementations (Few-Shot Grounding)

Pre-seeded, curated examples per archetype:

```
rag/seed_data/
├── api_backend/
│   ├── reference_project/          # Complete well-structured FastAPI project
│   ├── patterns.md                 # Design patterns to follow
│   ├── anti_patterns.md            # Common mistakes to avoid
│   ├── testing_patterns.md         # How tests should be structured
│   └── security_checklist.md       # Security patterns for APIs
├── web_app/
│   ├── reference_project/          # Full-stack React + FastAPI example
│   ├── component_patterns.md
│   └── state_management.md
├── script/
│   ├── reference_scripts/          # Well-structured script examples
│   └── patterns.md
└── general/
    ├── git_conventions.md
    ├── documentation_standards.md
    └── code_style_guides/
```

When an agent starts a task, the Context Manager pulls:
1. Archetype-specific reference code (**how it should look**)
2. Patterns doc (**what principles to follow**)
3. Anti-patterns doc (**what to avoid**)

### 14.3 Scoping

- Each project gets its own collections (no cross-project pollution)
- `shared_knowledge` = cross-project best practices
- `archetype_{id}_references` = curated reference implementations
- Agents query with `scope=project` (default) or `scope=archetype` or `scope=shared`

---

## 15. Prompt Handler & Versioning

### 15.1 Template Structure

```yaml
# templates/dev.yaml
version: "1.0.0"
last_updated: "2026-02-20"
changelog:
  - "1.0.0: Initial template with top-down levels and anti-hallucination checks"

system_prompt: |
  You are the Dev Agent in ADT. You implement software using Test-Driven Development.
  RULES:
  - Follow the top-down approach: skeleton → contracts → wiring → logic.
  - At your current level, produce ONLY that level's output.
  - Follow the accepted design exactly — no deviations.
  - Never hardcode secrets or credentials.
  - Use only what is in your context — do not invent APIs or modules.
  CONTEXT: {rag_context}

task_prompts:
  skeleton:
    template: |
      Create the file skeleton for module: {module_name}
      Design specification: {module_design}
      Archetype template: {archetype_structure}
      List every file needed with a one-line purpose.

  contracts:
    template: |
      Create typed function/class stubs for: {file_name}
      Module skeleton: {skeleton}
      Design contracts: {design_contracts}
      Output valid, parseable code with signatures and docstrings only.
      Every function body should be: raise NotImplementedError

  wiring:
    template: |
      Wire the call chain for: {file_name}
      Stubs: {contract_stubs}
      Sequence diagram: {sequence_diagram}
      Add import statements and function calls. Business logic = TODO placeholder.

  logic:
    template: |
      Implement the function: {function_name}
      Signature: {function_stub}
      Dependencies: {dependency_signatures}
      Tests to pass: {test_cases}
      Reference pattern: {reference_pattern}

self_challenge_prompt: |
  You completed: {task_name} (Level: {level})
  Your output: {output}
  Evaluate against criteria: {criteria_list}
  For each: PASS or FAIL + explanation.
  Did you invent anything not in your provided context? List all assumptions.
```

### 15.2 Versioning

- Every template has a `version` field (semver)
- Trace system logs `prompt_template_version` per LLM call
- Enables A/B testing of prompt variations in the future

---

## 16. Tracing & Observability

### 16.1 Hierarchical Trace Model

```
Project Trace (correlation_id)
  └── Step Trace (3.1, 3.2, 3.4, ...)
       └── Task Trace (implement_auth_module)
            └── Sub-Task Trace (auth_L2_contracts)
                 └── Agent Execution Trace
                      ├── LLM Call Trace (prompt, response, tokens, cost, latency)
                      ├── Tool Call Trace (tool name, params, result, duration)
                      ├── RAG Query Trace (query, results, relevance)
                      ├── Structural Validation Trace (checks, pass/fail)
                      ├── Self-Challenge Trace (criteria, pass/fail, attempts)
                      └── Decision Trace (what the agent decided and why)
```

### 16.2 Trace Data

Every trace has:
- `id` (UUID) — unique trace identifier
- `parent_id` — links the hierarchy
- `correlation_id` — project-level, spans everything
- `type` — project | step | task | subtask | agent_exec | llm_call | tool_call | rag_query | validation | challenge | decision
- Timestamps (start, end, duration)
- Cost (LLM tokens × price per token, per provider/model)

### 16.3 Cost Tracking

```python
@dataclass
class CostRecord:
    trace_id: UUID
    project_id: UUID
    step_id: str
    task_id: UUID
    agent_role: str
    module_id: str | None
    provider: str
    model: str
    prompt_tokens: int
    completion_tokens: int
    cost_per_input_token: Decimal
    cost_per_output_token: Decimal
    total_cost: Decimal
    prompt_template_version: str
    timestamp: datetime
```

Aggregation views:
- **Per project**: Total LLM cost for the entire project
- **Per step**: How much does requirements gathering cost vs. development?
- **Per agent**: Which agent is most expensive?
- **Per archetype**: Average cost for a "script" vs. "web_app"
- **Per module**: Which module was most expensive to build?

This feeds directly into the future pricing model.

### 16.4 Implementation Timing

Tracing is built in **Phase 0** — from the very first LLM call. Dashboards come in Phase 6, but data collection starts immediately.

---

## 17. Web UI Design (Minimal MVP)

### 17.1 Layout

```
┌──────────────────────────────────────────────────────┐
│  ADT — Auto Dev Team                    [New Project] │
├──────────┬───────────────────────────────────────────┤
│          │                                           │
│ PROJECTS │              MAIN AREA                    │
│          │                                           │
│ ● Proj 1 │  ┌─────────────────────────────────────┐  │
│   Proj 2 │  │          CHAT MESSAGES               │  │
│          │  │                                     │  │
│──────────│  │  🤖 PM: What kind of app...         │  │
│          │  │  👤 You: A task manager with...     │  │
│ PIPELINE │  │  🤖 PM: This looks like an API      │  │
│          │  │     Backend. Python + FastAPI.       │  │
│ ✅ 3.1   │  │     Sound right?                    │  │
│ ⏳ 3.2   │  │                                     │  │
│ ○ 3.4   │  │  [Approve] [Request Changes]        │  │
│ ○ 3.5   │  │                                     │  │
│ ○ 3.7   │  ├─────────────────────────────────────┤  │
│ ○ 3.8   │  │  📝 Type your message...    [Send]  │  │
│          │  └─────────────────────────────────────┘  │
│──────────│                                           │
│ ARTIFACTS│  ┌─────────────────────────────────────┐  │
│ 📄 Req   │  │ 📄 requirement_doc.md               │  │
│ 📊 Design│  │ 📊 architecture_diagram.mmd         │  │
│ 📋 Tests │  │ 📋 test_report.html                 │  │
│ 📦 ZIP   │  └─────────────────────────────────────┘  │
└──────────┴───────────────────────────────────────────┘
```

### 17.2 Frontend ↔ Backend Communication

| Feature | Protocol | Endpoint |
|---------|----------|----------|
| Chat messages | WebSocket | `ws://localhost:8000/ws/chat/{project_id}` |
| Project CRUD | REST | `GET/POST /api/projects` |
| Project state | REST | `GET /api/projects/{id}/state` |
| Artifacts | REST | `GET /api/projects/{id}/artifacts` |
| Step approval | REST | `POST /api/projects/{id}/steps/{step}/approve` |
| Cancel project | REST | `POST /api/projects/{id}/cancel` |
| Traces/costs | REST | `GET /api/projects/{id}/traces` |

### 17.3 SaaS-Ready Patterns

Even in MVP (single-user, no auth), these patterns are followed:

| Pattern | MVP | SaaS Expansion |
|---------|-----|----------------|
| Routing | `/projects/{id}` | Add `/org/{org}/projects/{id}` |
| State mgmt | React Context | Add auth + tenant context |
| API client | Direct fetch | Add auth headers |
| Layout | Fixed sidebar + main | Add top nav with user menu |

---

## 18. Data Model

### 18.1 PostgreSQL Schema

```sql
-- Projects
CREATE TABLE projects (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    status VARCHAR(50) NOT NULL,       -- ProjectStatus enum
    complexity VARCHAR(20),            -- low / mid / high
    archetype VARCHAR(50) NOT NULL,    -- script, api_backend, web_app, etc.
    tech_stack JSONB,                  -- Resolved tech stack
    pipeline_definition JSONB,         -- Adapted pipeline steps
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    canceled_at TIMESTAMPTZ
);

-- Project Steps
CREATE TABLE project_steps (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    step_id VARCHAR(20) NOT NULL,      -- "3.1", "3.2", etc.
    status VARCHAR(50) NOT NULL,       -- StepStatus enum
    agent_role VARCHAR(50),
    started_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,
    customer_approved BOOLEAN DEFAULT FALSE,
    artifacts JSONB
);

-- Tasks (core work units)
CREATE TABLE tasks (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    step_id VARCHAR(20) NOT NULL,
    module_id VARCHAR(100),
    type VARCHAR(100) NOT NULL,
    level VARCHAR(20),                 -- skeleton, contracts, wiring, logic
    agent_role VARCHAR(50) NOT NULL,
    status VARCHAR(50) NOT NULL,       -- TaskStatus enum
    acceptance_criteria JSONB NOT NULL,
    input_artifacts JSONB,
    output_artifacts JSONB,
    assigned_agent_id VARCHAR(100),
    context_snapshot_id UUID,
    parent_task_id UUID REFERENCES tasks(id),
    priority INTEGER DEFAULT 0,
    metadata JSONB,
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    paused_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ
);

-- Module Locks
CREATE TABLE module_locks (
    id UUID PRIMARY KEY,
    module_id VARCHAR(100) NOT NULL,
    project_id UUID REFERENCES projects(id),
    locked_by_task_id UUID REFERENCES tasks(id),
    lock_type VARCHAR(20) NOT NULL,    -- exclusive, shared
    acquired_at TIMESTAMPTZ NOT NULL,
    released_at TIMESTAMPTZ,
    UNIQUE(module_id, project_id, lock_type)
);

-- Context Snapshots
CREATE TABLE context_snapshots (
    id UUID PRIMARY KEY,
    task_id UUID REFERENCES tasks(id),
    project_id UUID REFERENCES projects(id),
    bundle JSONB NOT NULL,             -- Serialized ContextBundle
    created_at TIMESTAMPTZ NOT NULL
);

-- Chat Messages
CREATE TABLE chat_messages (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    role VARCHAR(20) NOT NULL,         -- "user" or "agent"
    agent VARCHAR(50),                 -- Which agent (null if user)
    content TEXT NOT NULL,
    metadata JSONB,
    created_at TIMESTAMPTZ NOT NULL
);

-- Artifacts
CREATE TABLE artifacts (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    step_id VARCHAR(20),
    task_id UUID REFERENCES tasks(id),
    type VARCHAR(50) NOT NULL,         -- ArtifactType enum
    name VARCHAR(255) NOT NULL,
    file_path VARCHAR(500) NOT NULL,
    mime_type VARCHAR(100),
    created_at TIMESTAMPTZ NOT NULL
);

-- Traces (hierarchical)
CREATE TABLE traces (
    id UUID PRIMARY KEY,
    parent_id UUID REFERENCES traces(id),
    correlation_id UUID NOT NULL,      -- Project-level trace ID
    type VARCHAR(50) NOT NULL,         -- TraceType enum
    project_id UUID REFERENCES projects(id),
    step_id VARCHAR(20),
    task_id UUID REFERENCES tasks(id),
    agent_role VARCHAR(50),
    module_id VARCHAR(100),
    status VARCHAR(50),
    metadata JSONB,                    -- Flexible per trace type
    started_at TIMESTAMPTZ NOT NULL,
    ended_at TIMESTAMPTZ,
    duration_ms INTEGER
);

-- LLM Call Details (linked to traces)
CREATE TABLE llm_call_details (
    trace_id UUID PRIMARY KEY REFERENCES traces(id),
    provider VARCHAR(50) NOT NULL,
    model VARCHAR(100) NOT NULL,
    temperature FLOAT,
    prompt_tokens INTEGER NOT NULL,
    completion_tokens INTEGER NOT NULL,
    total_tokens INTEGER NOT NULL,
    cost_per_input_token DECIMAL(20, 10),
    cost_per_output_token DECIMAL(20, 10),
    total_cost DECIMAL(20, 10),
    prompt_template_version VARCHAR(20),
    prompt_hash VARCHAR(64),           -- For dedup analysis
    latency_ms INTEGER
);

-- Indexes for common queries
CREATE INDEX idx_tasks_project_status ON tasks(project_id, status);
CREATE INDEX idx_tasks_agent_role_status ON tasks(agent_role, status);
CREATE INDEX idx_traces_correlation ON traces(correlation_id);
CREATE INDEX idx_traces_project_type ON traces(project_id, type);
CREATE INDEX idx_llm_costs_project ON llm_call_details(trace_id);
CREATE INDEX idx_module_locks_active ON module_locks(project_id, module_id)
    WHERE released_at IS NULL;
```

### 18.2 Key Enums

```python
class ProjectStatus(str, Enum):
    CREATED = "created"
    REQUIREMENTS = "requirements"
    DESIGN = "design"
    ENV_SETUP = "env_setup"
    DEVELOPMENT = "development"
    TESTING = "testing"
    VERIFICATION = "verification"
    DELIVERY = "delivery"
    COMPLETED = "completed"
    CANCELED = "canceled"

class TaskStatus(str, Enum):
    CREATED = "created"
    QUEUED = "queued"
    ASSIGNED = "assigned"
    IN_PROGRESS = "in_progress"
    VALIDATING = "validating"
    CHALLENGING = "challenging"
    REWORKING = "reworking"
    PAUSED = "paused"
    COMPLETED = "completed"
    FAILED = "failed"
    ESCALATED = "escalated"

class GenerationLevel(str, Enum):
    L1_SKELETON = "skeleton"
    L2_CONTRACTS = "contracts"
    L3_WIRING = "wiring"
    L4_LOGIC = "logic"

class TraceType(str, Enum):
    PROJECT = "project"
    STEP = "step"
    TASK = "task"
    SUBTASK = "subtask"
    AGENT_EXECUTION = "agent_execution"
    LLM_CALL = "llm_call"
    TOOL_CALL = "tool_call"
    RAG_QUERY = "rag_query"
    STRUCTURAL_VALIDATION = "structural_validation"
    SELF_CHALLENGE = "self_challenge"
    DECISION = "decision"
    ESCALATION = "escalation"

class ArtifactType(str, Enum):
    REQUIREMENT_DOC = "requirement_doc"
    DESIGN_DOC = "design_doc"
    DIAGRAM = "diagram"
    SOURCE_CODE = "source_code"
    TEST_DEFINITION = "test_definition"
    TEST_REPORT = "test_report"
    INTEGRATION_TEST_REPORT = "integration_test_report"
    VERIFICATION_CHECKLIST = "verification_checklist"
    DELIVERABLE_ZIP = "deliverable_zip"
    DOCUMENTATION = "documentation"
```

---

## 19. API Design (Internal)

### 19.1 REST Endpoints

```
# Projects
POST   /api/projects                              → Create project
GET    /api/projects                              → List projects
GET    /api/projects/{id}                         → Project details + state
DELETE /api/projects/{id}                         → Cancel project

# Steps
GET    /api/projects/{id}/steps                   → All steps with status
POST   /api/projects/{id}/steps/{step}/approve    → Approve gate
POST   /api/projects/{id}/steps/{step}/reject     → Reject with feedback

# Tasks
GET    /api/projects/{id}/tasks                   → All tasks with status/level
GET    /api/projects/{id}/tasks/{task_id}         → Task detail + sub-tasks

# Artifacts
GET    /api/projects/{id}/artifacts               → List artifacts
GET    /api/projects/{id}/artifacts/{aid}/download → Download

# Traces & Costs
GET    /api/projects/{id}/traces                  → Trace tree
GET    /api/projects/{id}/costs                   → Cost summary
GET    /api/projects/{id}/costs/breakdown         → Cost per step/agent/module
```

### 19.2 WebSocket Protocol

```json
// Client → Server: User message
{ "type": "user_message", "content": "...", "project_id": "uuid" }

// Server → Client: Agent message
{ "type": "agent_message", "agent": "pm", "content": "...", "project_id": "uuid" }

// Server → Client: Step status change
{ "type": "step_update", "step_id": "3.1", "status": "awaiting_approval", "project_id": "uuid" }

// Server → Client: Task progress
{ "type": "task_update", "task_id": "uuid", "status": "in_progress",
  "level": "contracts", "module": "auth", "project_id": "uuid" }

// Server → Client: Agent activity indicator
{ "type": "agent_activity", "agent": "dev", "activity": "Generating auth module contracts...",
  "project_id": "uuid" }

// Server → Client: Artifact produced
{ "type": "artifact_created", "artifact": { "id": "uuid", "name": "...", "type": "..." },
  "project_id": "uuid" }

// Server → Client: Escalation
{ "type": "escalation", "level": 1, "message": "...", "task_id": "uuid",
  "project_id": "uuid" }
```

---

## 20. Inter-Agent Communication Protocol

### 20.1 Message Structure

Agents don't talk directly. All communication goes through the Coordinator via structured messages.

```python
@dataclass
class AgentMessage:
    id: str
    from_agent: str
    to: str                   # "coordinator" | "orchestrator" | specific agent role
    project_id: str
    task_id: str
    type: MessageType
    payload: dict
    timestamp: datetime

class MessageType(str, Enum):
    TASK_ASSIGNMENT = "task_assignment"
    TASK_RESULT = "task_result"
    TASK_PAUSED = "task_paused"
    CHALLENGE_LOG = "challenge_log"
    VALIDATION_LOG = "validation_log"
    ARTIFACT = "artifact"
    FEEDBACK = "feedback"
    STATUS_UPDATE = "status_update"
    CUSTOMER_INPUT = "customer_input"
    CUSTOMER_APPROVAL = "customer_approval"
    ESCALATION = "escalation"
    CONTEXT_REQUEST = "context_request"
    CONTEXT_RESPONSE = "context_response"
```

---

## 21. File & Artifact Management

### 21.1 Workspace Layout

```
workspace/projects/{project_id}/
├── requirements/
│   └── requirement_doc.md
├── design/
│   ├── design_doc.md
│   ├── component_architecture.mmd
│   ├── class_diagram.mmd
│   └── sequence_diagrams/
├── source/                          # GitHub repo clone
│   ├── src/
│   ├── tests/
│   └── ...
├── reports/
│   ├── test_report.html
│   ├── integration_test_report.html
│   └── verification_checklist.md
├── documentation/
│   ├── README.md
│   ├── SETUP.md
│   └── CHANGELOG.md
└── delivery/
    └── project_name.zip
```

---

## 22. Quality Assurance Stack

Complete quality stack, bottom to top:

```
┌─────────────────────────────────────────────────────┐
│  10. Outcome Learning (post-MVP — data from Phase 0)│  ← Learn & improve
├─────────────────────────────────────────────────────┤
│   9. Prompt Versioning                              │  ← Track what works
├─────────────────────────────────────────────────────┤
│   8. Human Escalation Protocol                      │  ← Know when to stop
├─────────────────────────────────────────────────────┤
│   7. Cross-Module Integration Testing               │  ← Modules work together
├─────────────────────────────────────────────────────┤
│   6. Regression Protection (full test re-runs)      │  ← Fixes don't break things
├─────────────────────────────────────────────────────┤
│   5. Test Quality Review (QA reviews test defs)     │  ← Tests are meaningful
├─────────────────────────────────────────────────────┤
│   4. Self-Challenge Protocol                        │  ← Agent checks own work
├─────────────────────────────────────────────────────┤
│   3. Structural Validation (lint, types, parse)     │  ← Code is mechanically sound
├─────────────────────────────────────────────────────┤
│   2. Reference Implementations (RAG few-shot)       │  ← Code follows known-good patterns
├─────────────────────────────────────────────────────┤
│   1. Archetypes + Top-Down + Bounded Tasks          │  ← Right scope, right info, right order
└─────────────────────────────────────────────────────┘

Layers 1–8: MVP (7–8 light implementation)
Layer 9: MVP (prompt versioning — data collection starts Phase 0)
Layer 10: Post-MVP (architecture supports from day one)
```

### Testing Pipeline (Expanded)

```
Step 3.5 Testing:

Phase 1: QA reviews test definitions (pre-dev quality gate)
  - Coverage against acceptance criteria?
  - Edge cases covered?
  - Error paths tested?
  - Tests meaningful and independent?

Phase 2: Unit tests per module (parallel)
  - Run ALL tests (not just new ones)
  - Full regression on every fix loop iteration

Phase 3: Integration tests (sequential, after all modules)
  - Cross-module API calls work
  - Data flows correctly end-to-end
  - Shared state is consistent

Phase 4: System test (if deployed — post-MVP)
```

### Documentation as First-Class Output

Every deliverable includes:

| Document | Generated by | When |
|----------|-------------|------|
| README.md | Delivery Agent | Packaging |
| API docs | Dev Agent (auto from code) | Development (OpenAPI) |
| Setup instructions | DevOps Agent | Env setup |
| Architecture overview | Architect Agent | Step 3.2 |
| Inline code comments | Dev Agent | Development (explain "why") |
| Changelog | Delivery Agent | Packaging |
| .env.example | DevOps Agent | Env setup |

---

## 23. Human Escalation Protocol

### 23.1 Triggers

| Trigger | Condition |
|---------|-----------|
| Self-challenge exhausted | Failed after max_retries |
| Fix loop exhausted | Test failures persist after max iterations |
| High failure rate | >50% of tests failing |
| Contradictory requirements | Agent detects logical conflict |
| Confidence below threshold | Agent uncertain about approach |

### 23.2 Escalation Levels

```
Level 1: Clarification Request
  → Pause task, ask customer via chat
  → "I'm having trouble with X. Can you clarify Y?"

Level 2: Decision Request
  → Pause task, present options
  → "I can approach this two ways: A or B. Which do you prefer?"

Level 3: Human Review Required
  → Pause project, flag for human developer
  → "This task exceeds reliable autonomous delivery.
     A human should review before continuing."
```

All escalations are traced and the task enters `ESCALATED` status until resolved.

---

## 24. Sequence Diagrams

### 24.1 Full Pipeline with Top-Down Generation (Happy Path)

```mermaid
sequenceDiagram
    actor Customer
    participant Web as Web UI
    participant API as Backend API
    participant Orch as Orchestrator
    participant Coord as Coordinator
    participant Queue as Task Queue
    participant CtxMgr as Context Manager
    participant PM as PM Agent
    participant Arch as Architect Agent
    participant Dev as Dev Agent
    participant QA as QA Agent
    participant Rev as Reviewer Agent
    participant Del as Delivery Agent
    participant Trace as Trace System

    Customer->>Web: "I want a task manager API"
    Web->>API: WebSocket message
    API->>Orch: New project

    Note over Orch: Step 3.1 — Requirements
    Orch->>Coord: Activate step 3.1
    Coord->>Queue: Create task: gather_requirements
    PM->>Queue: Claim task
    PM->>CtxMgr: Hydrate context
    CtxMgr-->>PM: ContextBundle (minimal recipe)
    PM->>PM: Chat, gather, assess complexity
    PM->>PM: Select archetype: api_backend
    PM->>PM: Resolve tech stack: Python + FastAPI
    PM->>PM: Self-challenge ✅
    PM->>Trace: Log execution + cost
    PM->>Coord: Task complete + artifacts
    Orch->>API: Awaiting approval (req + archetype + stack)
    Customer->>Web: Approve

    Note over Orch: Load adaptive pipeline from archetype
    Orch->>Orch: Build pipeline: 3.1→3.2→3.2.1→3.4→3.5→3.7→3.8

    Note over Orch: Step 3.2 — Design
    Orch->>Coord: Activate step 3.2
    Coord->>Queue: Create task: generate_design (L1→L4)
    Arch->>Queue: Claim L1 task
    Arch->>CtxMgr: Hydrate context
    Arch->>Arch: L1: Module skeleton → L2: Interfaces → L3: Dependencies → L4: Details
    Arch->>Arch: Structural validate + self-challenge at each level ✅
    Arch->>Trace: Log all levels
    Arch->>Coord: Design complete + artifacts
    Customer->>Web: Approve design

    Note over Orch: Step 3.4 — Development (parallel modules)
    Orch->>Coord: Activate step 3.4
    Coord->>Coord: Decompose: auth + tasks + notif modules × L1-L4
    Coord->>Queue: Create 3 module task chains

    par Module: auth
        Dev->>Queue: Claim auth-L1
        Dev->>CtxMgr: Hydrate (skeleton recipe, ~2K tokens)
        Dev->>Dev: Generate skeleton
        Dev->>Dev: Structural validate ✅ → Self-challenge ✅
        Dev->>Queue: Claim auth-L2 → contracts → validate ✅
        Dev->>Queue: Claim auth-L3 → wiring → validate ✅
        par auth L4 functions (parallel)
            Dev->>CtxMgr: Hydrate (logic recipe, ~3K tokens)
            Dev->>Dev: Implement function → test passes → validate ✅
        end
    and Module: tasks
        Dev->>Dev: Same L1→L4 flow (parallel with auth)
    and Module: notif
        Dev->>Dev: Same L1→L4 flow (parallel with auth)
    end

    Coord->>Queue: Create integration task (locks all modules)
    Dev->>Dev: Integration wiring
    Coord->>Orch: Step 3.4 complete

    Note over Orch: Step 3.5 — Testing
    Coord->>Queue: Create test tasks
    QA->>QA: Review test quality (pre-check)
    QA->>QA: Run ALL unit tests
    QA->>QA: Run integration tests
    alt Tests fail
        QA->>Coord: Failures
        Coord->>Queue: Create fix tasks for Dev
        Dev->>Dev: Fix → QA re-runs ALL tests (regression protection)
    end
    QA->>Trace: Log results + costs
    Coord->>Orch: Step 3.5 complete

    Note over Orch: Step 3.7 — Verification
    Rev->>CtxMgr: Hydrate (reviewer recipe — summaries)
    Rev->>Rev: Verify workflow + acceptance criteria
    Rev->>Rev: Self-challenge ✅
    Rev->>Trace: Log verification
    Coord->>Orch: Step 3.7 complete

    Note over Orch: Step 3.8 — Delivery
    Del->>Del: Package ZIP (top-down: contents → structure → docs → package)
    Del->>Del: Self-challenge ✅
    Del->>Trace: Log delivery
    Orch->>API: Project COMPLETED
    API->>Web: Download available
    Customer->>Web: Download ZIP
```

---

## 25. Module Dependency Map

```
                    ┌─────────────┐
                    │   Web UI    │ (React + Tailwind)
                    └──────┬──────┘
                           │ HTTP / WS
                    ┌──────▼──────┐
                    │ Backend API │ (FastAPI)
                    └──────┬──────┘
              ┌────────────┼───────────────────┐
              │            │                   │
       ┌──────▼─────┐ ┌───▼────┐        ┌────▼──────┐
       │ Orchestrator│ │  DB    │        │ Trace Sys │
       └──────┬──────┘ └────────┘        └───────────┘
              │
       ┌──────▼──────┐
       │ Coordinator │
       └──────┬──────┘
              │
       ┌──────▼──────┐
       │  Task Queue │
       └──────┬──────┘
              │
    ┌─────────┼────────────────────────┐
    │         │ (claim tasks)          │
    │  ┌──────▼──────┐                 │
    │  │ Agent Core  │◄────────────────┤
    │  │             │  ┌────────────┐ │
    │  │• base_agent │  │   Agents   │ │
    │  │• top_down   │  │ (pm, arch, │─┘
    │  │• self_chall │  │  dev, qa,  │
    │  │• struct_val │  │  devops,   │
    │  │• escalation │  │  reviewer, │
    │  │• llm_provdr │  │  delivery, │
    │  └──────┬──────┘  │  billing)  │
    │         │         └────────────┘
    │  ┌──────▼──────┐
    │  │Context Mgr  │──── Recipes + Snapshots + Summarization
    │  └──────┬──────┘
    │         │
    │  ┌──────▼──────┐
    │  │Prompt Handlr│──── Versioned Templates
    │  └──────┬──────┘
    │         │
    │  ┌──────▼──────┐
    │  │ Shared RAG  │──── ChromaDB + Reference Implementations
    │  └─────────────┘
    │
    │  ┌─────────────┐
    └──│  LLM APIs   │ (OpenAI, Google, Anthropic)
       └─────────────┘
```

**Import rules:**
- Agents import from `agent_core`, never from each other
- `agent_core` imports from `context_manager`, `rag`, `prompt_handler`, `llm_provider`, `trace_system`
- `coordinator` imports from `task_queue`, `agent_core`
- `orchestrator` imports from `coordinator`
- `platform/api` imports from `orchestrator`
- `web` communicates only via HTTP/WS (no Python imports)

---

## 26. Technology Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Python version | 3.11+ | Required by Google ADK; good async |
| Agent framework | Google ADK | Multi-agent orchestration, tool support |
| Backend | FastAPI | Async, WebSocket, auto-docs |
| Database | PostgreSQL (SQLAlchemy + Alembic) | Reliable, JSONB, SaaS-ready |
| Vector DB | ChromaDB (MVP) | Local, no server, Python-native |
| Frontend | React 18 + TypeScript + Tailwind | SaaS-ready component model |
| Frontend build | Vite | Fast dev server |
| Diagrams | Mermaid | Text-based, browser + GitHub renderable |
| LLM providers | Multi-provider (Anthropic, Google, OpenAI) | Best model per agent role |
| Version control | GitHub API (PyGitHub) | Per requirement |
| Testing (backend) | pytest | Standard, good ecosystem |
| Testing (frontend) | Vitest | Fast, Vite-native |
| Python linting | Ruff | Extremely fast, replaces flake8+isort+black |
| Type checking | mypy | Standard for Python |
| Package mgmt | uv (Python), npm (frontend) | Fast, modern |
| API docs | Auto-generated (FastAPI /docs) | Free with FastAPI |
| Task queue | PostgreSQL-backed (MVP) | No Redis/RabbitMQ needed initially |

---

## 27. Security Considerations (MVP)

| Concern | Approach |
|---------|----------|
| API keys (LLM providers) | `.env` + `python-dotenv`, never committed |
| GitHub tokens | Personal access token in `.env` |
| Customer project secrets | Encrypted in DB (Fernet symmetric) |
| No secrets in code | Self-challenge criterion + structural check |
| No secrets in delivery | Self-challenge criterion for Delivery Agent |
| .gitignore | `.env`, `workspace/`, `__pycache__/`, `node_modules/` |

---

## 28. Open Questions & Assumptions

### Assumptions

| # | Assumption |
|---|-----------|
| A1 | Google ADK supports custom LLM providers — needs Phase 0 verification |
| A2 | ChromaDB sufficient for MVP RAG |
| A3 | Single PostgreSQL instance for MVP |
| A4 | Mermaid diagrams sufficient (no PlantUML for MVP) |
| A5 | Dev Agent handles frontend + backend code (no separate agents for MVP) |
| A6 | Shared workspace directory per project on local filesystem |
| A7 | WebSocket connection per project |
| A8 | PostgreSQL-backed task queue sufficient for MVP (no Redis) |

### Open Questions

| # | Question | Impact |
|---|----------|--------|
| Q1 | Does Google ADK allow non-Google LLMs? May need thin wrapper. | **High** |
| Q2 | GitHub account/org for customer repos? | Low — configuration |
| Q3 | Limit supported languages for MVP, or any language? | Medium — testing strategy |

---

## 29. Approval Checklist

- [ ] **High-level architecture** — System diagram with all new components
- [ ] **Agent design** — Stateless workers, lifecycle, configuration
- [ ] **Task model** — Persistent tasks, acceptance criteria, L1-L4 decomposition
- [ ] **Workflow engine** — Adaptive pipeline from archetypes
- [ ] **Agent Coordinator** — Hybrid assignment, module locking, parallelism
- [ ] **Context Manager** — Smart windowing, recipes, snapshots, summarization
- [ ] **Archetypes** — Registry, selection flow, tech stack resolution
- [ ] **Top-down generation** — L1→L4 protocol for all producing agents
- [ ] **Self-challenge** — Criteria, anti-hallucination, grounding checks
- [ ] **Structural validation** — Pre-LLM mechanical checks
- [ ] **LLM abstraction** — Multi-provider, deterministic settings, cost tracking
- [ ] **RAG** — Reference implementations, project scoping
- [ ] **Prompt handler** — Versioned templates
- [ ] **Tracing** — Hierarchical traces, cost tracking from Phase 0
- [ ] **Data model** — PostgreSQL schema (projects, tasks, locks, traces, LLM costs)
- [ ] **API design** — REST + WebSocket
- [ ] **Quality stack** — All 10 layers
- [ ] **Escalation protocol** — 3 levels
- [ ] **Tech stack** — All choices confirmed
- [ ] **Assumptions accepted** — Or flagged for change

---

*Please review each section. Flag anything you disagree with or want changed before we start Phase 0.*
