# ADT – README & Project Recommendations

> This document summarizes recommendations for improving the ADT project documentation and structure.  
> Status: **Draft for discussion**

---

## 1. Split the README into Multiple Documents

The current `README.MD` mixes product vision, technical specs, workflow definitions, and business model. This makes it hard to navigate and maintain.

### Proposed document structure:

| File | Purpose |
|------|---------|
| `README.md` | Project intro, tech stack, quickstart, how to contribute |
| `docs/PRD.md` | Full Product Requirements Document (what ADT does) |
| `docs/ARCHITECTURE.md` | System architecture, agent definitions, data flow |
| `docs/WORKFLOW.md` | The 3.1–3.8 customer development workflow in detail |
| `docs/PRICING.md` | Pricing strategy, cancellation policy, tier definitions |
| `docs/PHASE-0-LOCAL.md` | Local bootstrap guide (VS Code + Python + ADK) |
| `docs/AGENTS.md` | Agent roles, tools, responsibilities, handoff rules |

### Why?
- Each doc has a single audience and purpose.
- Easier to update independently.
- The README becomes a quick entry point, not a wall of text.

---

## 2. Define the Agent Roster Explicitly 

The README mentions agents with "clear roles" but never names them. A concrete roster helps with implementation planning.

### Suggested agent roster (refine as needed):

| Agent | Role | Key Tools / Capabilities |
|-------|------|--------------------------|
| **PM Agent** | Requirements gathering, clarification, complexity assessment | Chat interface, RAG, cost estimator |
| **Architect Agent** | Software design, diagrams, tech decisions | Diagram generators (Mermaid/PlantUML), design templates |
| **UX Agent** | UI/UX flow prototyping, mockup generation | Figma API / HTML prototype generator |
| **Dev Agent** | Code implementation following accepted design | Code generation, file system, Git operations |
| **QA Agent** | Test definition (TDD), test execution, report generation | Test frameworks, Kubernetes client, report publisher |
| **DevOps Agent** | Repo setup, CI/CD, deployment, namespace management | GitHub API, Kustomize, GitHub Actions, kubectl |
| **Review Agent** | Challenge-based internal review, quality gates | Code review tools, design validation, checklist engine |
| **Delivery Agent** | Packaging, documentation cleanup, final handoff | ZIP tools, Git fork API, container registry |

### Questions to resolve:
- Should the **PM Agent** also handle pricing/cancellation logic, or should there be a **Billing Agent**? 
R: Billing agent sounds great, because we can have better traceability if it´s independent.
- Is the **Review Agent** a standalone agent or a mode that other agents activate?
is a state, review agent should do the over all verification of the workflow, not challenge based ones.
- Do we need a **Debug Agent** specifically for post-delivery debugging, or does the Dev Agent handle it?
i think someone should analyze the issue, maybe include capabilities to check logs, and understart that sort of behavioral patterns, could be the QA agent though, the generated action items should be taken by developers.

---

## 3. Add a Tech Stack Section

The README references several technologies but never consolidates them. A clear tech stack helps contributors and sets expectations.

### Proposed tech stack (to confirm/adjust):

| Layer | Technology | Notes |
|-------|-----------|-------|
| **Language** | Python | Primary language for agents and orchestration |
| **Agent Framework** | Google ADK (Agent Development Kit) | Multi-agent orchestration |
| **LLM Provider** | ??? | Google Gemini? OpenAI? Multi-provider? |
| **Knowledge Base** | Shared RAG | Provider TBD (vector DB choice?) |
| **Repository Mgmt** | GitHub (personal account initially) | Via GitHub API |
| **CI/CD** | GitHub Actions | Pipeline definition per project |
| **Containerization** | Docker | For packaging deliverables |
| **Orchestration** | Kubernetes | Project deployment target |
| **Deployment Tool** | Kustomize | Environment-specific overlays |
| **Diagrams** | ??? | Mermaid? PlantUML? Both? |
| **Database** | ??? | For multi-tenant platform data |
| **Auth** | ??? | For customer signup & org management |
| **Frontend** | ??? | For dashboards, chat, project management UI |

### Questions to resolve:
- What LLM provider(s) will power the agents?
R: it should be multi provider, it must fit the best available model for the role specification of the agent.
- What database will back the SaaS platform (PostgreSQL, MongoDB, etc.)?
R: i think Postgresql fits well, is flexible, and available in many different platforms as well as locally with docker
- What frontend framework for the customer-facing dashboards?
R: we should use React, for graphic components i think tailwind is fine.
- Will the chat interface be a web UI, a CLI, or both?
R: i think web is fine, later we could add CLI but just web for now

---

## 4. Add Non-Functional Requirements

The current doc focuses on *what* ADT does but not *how well* it should do it. These are critical for a SaaS product.

### Suggested NFRs to define:

| Category | Consideration |
|----------|--------------|
| **Scalability** | How many concurrent projects? How many tenants? |
| **Availability** | Uptime target (99.9%?)? |
| **Latency** | Max response time for chat interactions? |
| **Observability** | Logging, tracing, metrics — what tools? |
| **Rate Limits** | Per-tenant API/agent usage limits? |
| **Data Retention** | How long are project artifacts kept? |
| **Backup & Recovery** | Strategy for customer project data? |
| **Compliance** | GDPR, SOC2, or other compliance targets? |

R: let's keep NFRs for later. We'll define concrete targets before the SaaS platform phase (Phase 5).

---

## 5. Flesh Out Phase 0 (Local Bootstrap)

The README cuts off at "Phase 0 – Local Bootstrap (Mandatory)." This is the most critical section for actually getting started.

### Suggested Phase 0 content:

1. **Prerequisites**: Python version, VS Code extensions, ADK installation
2. **Project structure**: Folder layout for the agent system
3. **First agent**: Build a minimal PM Agent that can chat and gather requirements
4. **Agent-to-agent communication**: Define the message protocol locally
5. **Shared workspace**: How agents share files on a local filesystem
6. **RAG setup**: Local vector store for shared knowledge
7. **Validation**: A simple end-to-end test (requirement → design sketch)

### Questions to resolve:
- Should Phase 0 cover only agent orchestration, or also the SaaS platform scaffolding?
R: i think we have enough time for the SaaS platform scaffolding, and we will have the view from the customer point of view
- What's the minimum viable agent interaction to validate the architecture?
R: we need to aim to fulfill the goal, my recommendation for evaluating if it´s good or bad, is to have some predetermined projects to ask for, one small, one medium, one high complexity, so if the determination on every step is fine, and makes sense, then we are ok, otherwise we need maybe to include some specific agent, for example, separate frontend of the backend or database, but let´s evaluate this based on outcome, as is for now, looks good.

---

## 6. Formalize the Pricing Model

The current pricing section is self-described as "made up numbers." Even as a draft, it should be structured.

### Suggested pricing framework:

| Step | Deliverable | Cancellation Fee | Notes |
|------|------------|-------------------|-------|
| 3.1 Requirements | Refined requirement doc | Minimal (e.g., $2) | Low effort |
| 3.2 Design | Architecture + diagrams | Complexity-based | Low / Mid / High tiers |
| 3.3 UX Prototype | Navigable mockup | Complexity-based | Iteration cost included? |
| 3.4 Development | Working code + tests | Significant | Largest cost center |
| 3.5 Testing | Reports + fixes | Included in 3.4? | Or separate? |
| 3.6 Deployment | Running on K8s | Included? | Infra cost pass-through? |
| 3.7 Verification | Checklist | Included? | Quality gate |
| 3.8 Delivery | Final package | Full price | Project complete |

### Questions to resolve:
- Is pricing per-step or bundled with discounts for full completion?
- Is there a subscription model for the platform itself vs. per-project pricing?
- How is "complexity" objectively measured (lines of code? modules? integrations?)?
R: let´s have the pricing discussion later, we could have different pricing models for different clients, so keep it flexible, so we can include it later, keep it pending, for now, focus on the core.

---

## 7. Expand the Debugging / Post-Delivery Flow

The README says "debugging treated as a new requirement flow" but this needs more definition.

### Suggested debugging workflow:

1. **Issue Intake**: Customer reports a bug (expected vs. actual behavior)
2. **Triage**: System assesses severity and affected module(s)
3. **Root Cause Analysis**: Agents review code, logs, and tests
4. **Fix as Mini-Requirement**: A scoped requirement is created
5. **Regression Test**: New test case added to prevent recurrence
6. **Hotfix vs. Full Cycle**: Simple fixes skip UX/design; complex ones go through 3.2+
7. **Re-deployment**: Patched version deployed to the same namespace
8. **Verification**: Automated check that the issue is resolved

### Questions to resolve:
- Is debugging included in the original project price or billed separately?
R: will depend on the pricing model
- How long after delivery is debugging support available?
R: let´s put a deadline per project, but will depend of the client, it could be always a new project, where the input will be the old project, so all the steps will run, architectural changes, testing, development, graphical changes, etc, so we will have to charge based on complexity of what the client is requesting.
- Can the customer trigger debugging themselves, or must they go through ADT's intake?
R: if they have the code, then they can do whatever they want, the analysis of full code will be expensive, so we anyways need to ask if it´s as is code (as we deliver to them) or it´s modified, if is as is, we can take internal project documentation, if not, we need to analyze full code.

---

## 8. Improve README Formatting

Regardless of document splitting, the README needs proper Markdown:

- [ ] Use `#`, `##`, `###` heading hierarchy consistently
- [ ] Use proper numbered and bulleted lists
- [ ] Add a table of contents at the top
- [ ] Use tables for structured data (agent roles, pricing, tech stack)
- [ ] Add badges (build status, license, version) once applicable
- [ ] Add a "Getting Started" section with actual setup commands

---

## Next Steps

1. **Discuss & prioritize** these recommendations together.
2. **Decide on document structure** (split or keep unified).
3. **Answer the open questions** marked above.
4. **Rewrite the README** based on agreed decisions.
5. **Build out Phase 0** as the first actionable milestone.

---

*This document is a living draft. Let's refine it together.*
