# MADD — Multi-Agent Driven Development

> MADD is an open-source methodology for AI-assisted development that provides the framework to control drift and drive convergence between intention and implementation. When AI codes faster than you specify, your methodology must evolve.

## Core Principles

MADD is built on 6 fundamental principles:

1. **Intention is a first-class artifact** - Intention is not a forgotten conversation. It's a versioned, structured document that answers "why" and "what" before any "how".

2. **The contract is executable** - A specification that cannot be automatically verified is not a contract, it's a wish. Every requirement has automatable validation criteria.

3. **No agent validates its own work** - An agent that generates code cannot be the source of truth on the quality of that code. Validation must always come from an agent that did not participate in production.

4. **Retro-specification is the system's memory** - What was actually implemented must be documented objectively, independently of what the development agent claims to have done.

5. **Foundations precede features** - When the marginal cost of development decreases, investing in architecture becomes rational. We prioritize what de-risks the rest.

6. **Skills are knowledge contracts** - AI has outdated training data. Skills inject up-to-date knowledge and define quality criteria between phases.

## The 4-Agent Architecture

MADD uses a mandatory architecture of 4 agents with zero conflict of interest:

- **Spec Agent** (Intention Architect): Formalizes the "why" and "what", produces the Intention Document, defines validation criteria
- **Dev Agent** (Developer): Transforms intention into code, respects the contract, documents technical choices
- **Audit Agent** (Verifier): Audits without complacency, analyzes produced code, verifies intention/code alignment, identifies drifts and risks
- **Scribe Agent** (Witness): Documents objective reality, analyzes what actually exists, compares specs vs reality, produces the retro-specification

In practice, a 5th role — the **Orchestrator** — can coordinate the flow between agents, manage dev/audit iteration loops (max 3), and determine validation scope. This role can be human or automated.

## Pages

- [Home](https://madd.sh/): Main page with overview, problem statement, principles, and quickstart guide
- [Concepts](https://madd.sh/concepts.html): Core concepts of MADD methodology - Intention Document, Executable Contract, Retro-Specification, Operations
- [Skills](https://madd.sh/skills.html): Skills documentation - knowledge contracts for agents
- [Manifesto](https://madd.sh/manifesto.html): Full MADD manifesto - founding document
- [Examples](https://madd.sh/examples.html): Case studies and examples

## Pages (French versions)

- [Accueil](https://madd.sh/fr/): Page principale
- [Concepts](https://madd.sh/fr/concepts.html): Les concepts MADD
- [Skills](https://madd.sh/fr/skills.html): Les Skills MADD
- [Manifeste](https://madd.sh/fr/manifesto.html): Le Manifeste MADD
- [Exemples](https://madd.sh/fr/examples.html): Études de cas

## Key Concepts

### Intention Document
A structured, versioned document that formalizes the "why" and "what" before any "how". It serves as the contract between human intention and AI execution.

### Retro-Specification
Objective documentation of what was actually implemented, produced by an independent Scribe agent. This becomes the project's memory and the starting point for any new iteration.

### Skills
Explicit knowledge contracts that inject up-to-date knowledge into AI agents and define quality criteria between phases. They mediate each transition in the development cycle. Skills operate at two levels: methodological (how the agent works, often embedded in agent definitions) and domain (what the agent needs to know — organized as public, project, or delta files).

### Operations
The specification of how the system runs beyond development: environments, infrastructure, deployment strategy, and monitoring. Specifying operations upfront — as part of the contract — ensures deployment constraints are considered from the start.

### Drift Control
The core framework of MADD: providing the mechanisms to control drift and drive convergence between what you intended and what was actually implemented, through mandatory separation of concerns and independent validation.

## Migration from Legacy Methodologies

MADD provides a path from Scrum/Kanban/SAFe:
- Sprints → Intention Cycles (no fixed duration)
- Stories → Intention Docs + Executable Contracts
- Estimation → Obsolete (development is too fast)
- Code Review → Independent Agent Audit
- Definition of Done → Formal Audit Skill
- Retrospectives → Consolidations (improve skills, not process)

## Links

- [GitHub](https://github.com/madd-sh): Source code and contributions
- [Full Documentation (HTML)](https://madd.sh/): Complete website with interactive features
- [MADD Boilerplate](https://github.com/madd-sh/madd-boilerplate): Ready-to-use implementation with 5 agents, distributed JSON contract, and audit recommendation system

## License

MADD is open source under MIT license.