Module 02: AAMAD Overview

Estimated time: ~15 minutes
Outcome: Can explain AAMAD’s three phases and the idea of Development Crew vs Application Crew
Framework version: This course targets AAMAD v0.7.5

Learning Objectives

By the end of this module, you will be able to:

Explain the Define–Build–Deliver phases of AAMAD
Distinguish between Development Crew and Application Crew
Identify key artifacts produced in each phase
Understand how rules, runtime adapters, and templates guide agent behavior
Recognize optional quality gates (aamad validate) and multi-IDE init

Content

What is AAMAD?

AAMAD (AI-Assisted Multi-Agent Application Development) is an open, production-grade context engineering framework for building, deploying, and evolving multi-agent applications. It systematizes research-driven planning, modular AI agent workflows, and rapid MVP/devops pipelines for enterprise-ready AI solutions.

Think of AAMAD as a methodology and toolkit that helps you:

Launch projects with autonomous or collaborative AI agents
Rapidly prototype MVPs with clear context boundaries
Use production-ready architecture/design patterns
Accelerate delivery, reduce manual overhead, and enable continuous iteration

In AAMAD, the development crew (personas, rules, templates, and artifacts) is the stable methodology. Runtime adapters are an implementation choice for what backend runtime your generated MVP targets—not a change to how Define → Build → Deliver is orchestrated.

AAMAD is built on the principle that context engineering (not model tweaking) is the core lever for building reliable, maintainable agentic systems.

The Three Phases: Define → Build → Deliver

AAMAD organizes work into three sequential phases, each with clear artifacts, personas, and rules to keep development auditable and reusable:

flowchart LR
    A[DEFINE<br/>Context Setup] --> B[BUILD<br/>Execution and Code]
    B --> C[DELIVER<br/>Operations and Deploy]
    
    style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px,color:#000000
    style B fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000000
    style C fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000000

Phase 1: Define

Goal: Establish a solid foundation with clear research, requirements, and project scope.

Persona: Product Manager (@product-mgr)

Key Activities:

Optional structured elicitation (*elicit-requirements) → system-description.md
Optional Market Research Document (MRD) for commercial / market-facing products
Generate Product Requirements Document (PRD)
Optional MVP user stories for architecture and QA traceability
Validate completeness: personas, features, acceptance criteria, success metrics
Record Sources, Assumptions, Open Questions, and Audit sections on artifacts

Key Artifacts (under project-context/1.define/):

system-description.md — recommended when elicitation was used
mrd.md — Market Research Document (optional; skip for internal/personal tools)
prd.md — Product Requirements Document (required)
user-stories/ — optional MVP stories
sad.md — Solution Architecture Document (produced by @system.arch before Build implementation)

Why This Matters: Without clear definition, AI agents lack the context needed to make good decisions. The Define phase ensures everyone (human and AI) understands what we’re building and why.

Phase 2: Build

Goal: Execute multi-agent development to produce working code, architecture, and integration for a selected runtime target.

Personas (invocation uses dotted handles; see AGENTS.md after init):

@system.arch — Designs solution architecture (sad.md)
@project.mgr — Scaffolds environment and documents setup.md
@frontend.eng — Builds UI components → frontend.md
@backend.eng — Implements backend for the selected runtime → backend.md
@integration.eng — Wires components and APIs → integration.md
@qa.eng — Unit + integration tests and smoke/acceptance → qa.md
@security.eng — Recommended pre-Deliver security assessment → security.md

Key Activities:

Generate SAD (and record AAMAD_TARGET_RUNTIME in the Audit section)
Scaffold environment and install dependencies
Build frontend UI and placeholders
Implement backend services using the selected runtime adapter
Wire up integrations and chat flows
Conduct quality assurance (*test-unit, *test-integration, smoke tests)
Optionally assess security before Deliver

Key Artifacts (under project-context/2.build/):

setup.md, frontend.md, backend.md, integration.md, qa.md
security.md (recommended)
Source code and configuration files

Note: The SAD lives in project-context/1.define/sad.md even though architecture work gates Build.

Why This Matters: The Build phase transforms requirements into working software through coordinated multi-agent execution. Each agent persona has a single responsibility, ensuring quality and maintainability.

Phase 3: Deliver

Goal: Package, deploy, and operationalize the validated MVP.

Persona: DevOps Engineer (@devops.eng)

Key Activities:

Confirm QA (and note security status)
Configure deployment and CI aligned with SAD and AAMAD_TARGET_RUNTIME
Document hosting, access control, rollback in deploy.md
Optionally generate user-guide.md (*document-user-guide)

Key Artifacts (under project-context/3.deliver/):

deploy.md — primary delivery runbook (hosting, env matrix, access, rollback)
user-guide.md — optional operator / end-user guide
Deploy configs and CI scaffolding as needed

Why This Matters: Building software is only half the battle. The Deliver phase ensures your application can run reliably, be operated by others, and evolve over time.

Development Crew vs Application Crew

This is a critical distinction in AAMAD:

Development Crew (The Builders)

The Development Crew consists of AI agent personas that build your application. These are the “construction workers” who create the software:

Product Manager (@product-mgr) — Defines what to build
System Architect (@system.arch) — Designs how to build it
Project Manager (@project.mgr) — Scaffolds the environment
Frontend Engineer (@frontend.eng) — Builds user interfaces
Backend Engineer (@backend.eng) — Implements business logic for the target runtime
Integration Engineer (@integration.eng) — Connects components
QA Engineer (@qa.eng) — Ensures quality
Security Engineer (@security.eng) — Assesses security (recommended)
DevOps Engineer (@devops.eng) — Deploys and operates

These agents are temporary—they exist during development to create your application. Once the project is complete, they’re done.

Example: When building a customer service chatbot, the Development Crew includes agents like @frontend.eng (who builds the chat UI) and @backend.eng (who implements the conversation logic).

Application Crew (The Application Itself)

The Application Crew consists of AI agents that are your application. These are the agents that end users interact with in production:

Customer Service Agent - Handles customer inquiries
Document Analyzer - Processes and extracts information from documents
Recommendation Engine - Suggests products or actions
Workflow Orchestrator - Coordinates multi-step processes

These agents are permanent—they run in production and deliver value to end users. Their implementation conventions come from the selected runtime adapter (CrewAI by default in this course).

Example: In a customer service chatbot application, the Application Crew might include:

A “Support Agent” that answers questions
A “Escalation Agent” that handles complex issues
A “Feedback Collector” that gathers user satisfaction

Visualizing the Distinction

flowchart TD
    subgraph AppCrew["APPLICATION CREW (Permanent)"]
        direction TB
        Support[Support Agent]
        Doc[Document Analyzer]
        Workflow[Workflow Orchestrator]
        Rec[Recommendation Engine]
    end
    
    AA((Agentic Architect))
    
    subgraph DevCrew["DEVELOPMENT CREW (Temporary)"]
        direction TB
        PM[Product Manager]
        SA[System Architect]
        FE[Frontend Engineer]
        BE[Backend Engineer]
        IE[Integration Engineer]
        QA[QA Engineer]
        DO[DevOps Engineer]
    end
    
    AppCrew <-->|Orchestrates| AA
    AA <-->|Orchestrates| DevCrew
    
    style AppCrew fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#000000
    style AA fill:#bbdefb,stroke:#1976d2,stroke-width:4px,color:#000000
    style DevCrew fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#000000
    style PM fill:#ffccbc,color:#000000
    style SA fill:#ffccbc,color:#000000
    style FE fill:#ffccbc,color:#000000
    style BE fill:#ffccbc,color:#000000
    style IE fill:#ffccbc,color:#000000
    style QA fill:#ffccbc,color:#000000
    style DO fill:#ffccbc,color:#000000
    style Support fill:#c8e6c9,color:#000000
    style Doc fill:#c8e6c9,color:#000000
    style Workflow fill:#c8e6c9,color:#000000
    style Rec fill:#c8e6c9,color:#000000

Core AAMAD Concepts

1. Persona-Driven Development

Each workflow is owned and documented by a clear AI agent persona with a single responsibility principle. This ensures:

Clear accountability
Specialized expertise
Maintainable code
Auditable decisions

2. Context Artifacts

All major actions, decisions, and documentation are stored as markdown artifacts, ensuring:

Explainability - You can always understand why decisions were made
Reproducibility - You can recreate the development process
Traceability - You can track how requirements became code

Define templates require Sources, Assumptions, Open Questions, and Audit sections so decisions stay auditable across phases.

3. Runtime Adapters

AAMAD_TARGET_RUNTIME selects the backend conventions used when @backend.eng (and related Build personas) implement the Application Crew:

Runtime	Status	Best fit
`crewai`	Default	Declarative task orchestration with YAML-first runtime configuration
`claude-agent-sdk`	Supported	Agentic runtime harness with hooks, MCP, and session control
`cursor-sdk`	Supported	TypeScript-first Cursor runtime integration

This course uses crewai for the mini-project. Choosing another runtime changes generated MVP conventions—not the Define → Build → Deliver methodology.

4. Quality Gates

Required artifact headings (Sources / Assumptions / Open Questions / Audit)
Optional CLI: aamad validate --phase define|build|deliver
Recommended sequence: QA → security → Deliver
After code drifts from docs, use prompt-sync-docs (Claude Code: /sync-docs) to resynchronize project-context/

5. Parallelizable Epics & Reusability

Big tasks are broken into epics for faster, more autonomous work with retained quality control. Framework artifacts (in .cursor/ for Cursor, or IDE-equivalent paths) are reusable; project-context/ holds instance-specific documentation.

AAMAD Repository Structure

After aamad init --ide cursor, your project structure looks like this:

your-project/
├─ .cursor/                    # Framework artifacts (Cursor)
│ ├─ agents/                   # Persona definitions (@product-mgr, @backend.eng, …)
│ ├─ prompts/                  # prompt-phase-1, prompt-sync-docs
│ ├─ rules/                    # aamad-core, workflows, runtime adapters
│ └─ templates/               # MRD, PRD, SAD, system-description, user-guide, …
│
├─ project-context/            # Project-specific artifacts
│ ├─ 1.define/                 # system-description, MRD, PRD, SAD, stories
│ ├─ 2.build/                  # setup, frontend, backend, integration, qa, security
│ └─ 3.deliver/                # deploy.md, optional user-guide.md
│
├─ AGENTS.md                   # Bridge file + Framework version stamp
├─ CHECKLIST.md                # Step-by-step Define → Build → Deliver guide
├─ aamad.config.example.yml    # Optional project preferences template
└─ src/                        # Your application source code (created during Build)

Framework artifacts are reusable across projects.
Project-context contains all generated and instance-specific documentation.
Templates stay under .cursor/templates/ even when you init for Claude Code or VS Code.

Rules: The Framework’s Brain

AAMAD uses rules to guide AI agent behavior and ensure consistent, high-quality output across all phases. On Cursor these live in .cursor/rules/*.mdc with alwaysApply: true. Other IDEs get equivalent instruction files via aamad init --ide ….

What Are Rules?

Rules define:

Architecture patterns - How to structure code and systems
Workflow patterns - How agents should coordinate and execute tasks
Quality standards - What “good” looks like for code, documentation, and artifacts
Runtime conventions - How the selected AAMAD_TARGET_RUNTIME shapes backend implementation

AAMAD Rule Categories (v0.7.5)

The AAMAD framework ships these rule files (Cursor names):

aamad-core — Fundamental principles, context engineering, artifact standards, project configuration
development-workflow — How agents execute the Build phase
delivery-workflow — Deploy, CI, hosting, and Deliver documentation
epics-index — Epic → persona mapping
adapter-registry — Resolves AAMAD_TARGET_RUNTIME to a concrete adapter
Runtime adapters — adapter-crewai, adapter-claude-agent-sdk, adapter-cursor-sdk

How Rules Work

Rules are loaded automatically when you:

Start a new chat session with an agent persona
Reference an agent persona (e.g., @system.arch)
Work within the AAMAD project structure

Example: When you invoke @backend.eng, the agent automatically:

Loads aamad-core (quality standards, context engineering)
Loads development-workflow (code patterns, testing)
Follows the active runtime adapter (e.g. adapter-crewai when AAMAD_TARGET_RUNTIME=crewai)
Applies these rules to all code and documentation it creates

Templates: Structured Context Generation

AAMAD provides templates (stored in .cursor/templates/) that standardize artifact creation across all phases.

Available Templates (v0.7.5)

Phase 1: Define

system-description-template.md — Structured elicitation intake
mrd-template.md — Market Research Document (optional for commercial products)
prd-template.md — Product Requirements Document
user-story-template.md — MVP user stories
sad-template.md — Solution Architecture Document (runtime-neutral; parameterized by AAMAD_TARGET_RUNTIME)
sfs-template.md — System Functional Specifications

Phase 3: Deliver

user-guide-template.md — Operator / end-user guide

Also included: aamad-config-template.yml for optional project preferences (language, UI, testing, security).

How Templates Work

Agent Invocation: When you invoke an agent persona (e.g., @product-mgr), it knows which template to use
Structured Generation: The agent uses the template to create artifacts with consistent structure
Completeness Check: Templates ensure all necessary sections are included (including Audit)
Quality Assurance: Standardized format makes artifacts easier to review and maintain

Example Workflow:

You: @product-mgr *create-prd for our customer service chatbot

Agent: 
1. Loads prd-template.md
2. Fills in each section based on your requirements
3. Creates project-context/1.define/prd.md
4. Ensures Sources, Assumptions, Open Questions, and Audit are complete

Agents, Prompts, and CHECKLIST

Agents (.cursor/agents/)

Define each persona’s role, responsibilities, and expertise
Use hyphenated file ids (backend-eng.md) and dotted chat handles (@backend.eng)
dev-crew.md documents the full Development Crew naming convention

Prompts (.cursor/prompts/)

prompt-phase-1 — Phase 1 Define kickoff
prompt-sync-docs — Resynchronize project-context/ after code changes

CHECKLIST.md (project root)

Step-by-step guide for the full Define → Build → Deliver workflow
This course uses a simplified Tier-0 path; the checklist is the deep reference for production runs

AGENTS.md (project root)

Bridge file for IDE discoverability
Stamps Framework version: from the installed package (e.g. 0.7.5)

Getting Started with AAMAD

Recommended path (Cursor):

# Requires Python 3.9+ (pip install from PyPI)
pip install "aamad>=0.7.5,<0.8"
# or: uv pip install "aamad>=0.7.5,<0.8"
aamad init --ide cursor --dest /path/to/your/project

Other IDEs:

IDE	Command
Cursor (default)	`aamad init --ide cursor --dest .`
Claude Code	`aamad init --ide claude-code --dest .`
VS Code + GitHub Copilot	`aamad init --ide vscode --dest .`

Optional next steps after init:

Copy aamad.config.example.yml → aamad.config.yml for shared preferences
Set AAMAD_TARGET_RUNTIME=crewai (default) before Build
Follow CHECKLIST.md (or this course’s simplified hands-on path)
Run aamad validate --phase define (optional) at phase gates

Once set up, you follow the three-phase process, using the Development Crew to build your Application Crew.

Check Your Understanding

Reflect on these questions to solidify your understanding:

Phase Identification: Which AAMAD phase does “Writing a Product Requirements Document” belong to?
Phase Identification: Which AAMAD phase does “Deploying an application to production” belong to?
Phase Identification: Which AAMAD phase does “Writing unit tests for a feature” belong to?
Phase Identification: Which AAMAD phase does “Creating deploy.md for operations” belong to?
Phase Identification: Which AAMAD phase does “Designing the system architecture” belong to?
Crew Distinction: Imagine you’re building a document processing system. What would be in your Application Crew? (What agents will users interact with?)
Crew Distinction: Imagine you’re building a document processing system. What would be in your Development Crew? (What agents will build the system?)
Artifact Traceability: Why is it important that AAMAD stores all decisions as markdown artifacts? How does this help with maintenance and debugging?
Persona Benefits: How does the persona-driven approach (single responsibility per agent) help prevent the “slop” problem in AI-assisted development?
Phase Dependencies: Why must the phases run in order (Define → Build → Deliver)? What would happen if you tried to Build without Define, or Deliver without Build?
Rules Consistency: How do AAMAD rules ensure consistency across different agent personas and chat sessions?
Templates vs Artifacts: What’s the difference between a template (like prd-template.md) and the actual artifact (like prd.md)? Why are templates important for maintaining quality in AI-generated artifacts?
Runtime Adapters: What does AAMAD_TARGET_RUNTIME control—and what does it not change about AAMAD?

Next Steps

Continue to Module 03: Context Engineering Basics