Agentic Architect Fundamentals
Synaptic AI Consulting
AAMAD Overview
Synaptic AI Consulting
Estimated time: ~15 minutes
Outcome: Can explain AAMAD’s three phases and the idea of Development Crew vs Application Crew
By the end of this module, you will be able to:
AAMAD (AI-Assisted Multi-Agent Application Development) is an open, production-grade framework for building, deploying, and evolving multi-agent applications using best context engineering practices. 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:
AAMAD is built on the principle that context engineering (not model tweaking) is the core lever for building reliable, maintainable agentic systems.
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 & Code]
B --> C[DELIVER<br/>Operations & 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
Goal: Establish a solid foundation with clear research, requirements, and project scope.
Persona: Product Manager (@product-mgr)
Key Activities:
Key Artifacts:
mrd.md - Market Research Documentprd.md - Product Requirements DocumentOutput Location: project-context/1.define/
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.
Goal: Execute multi-agent development to produce working code, architecture, and integration.
Personas: Multiple specialized agents working in sequence:
Key Activities:
Key Artifacts:
sad.md - Solution Architecture Documentsetup.md - Environment setup documentationfrontend.md - Frontend implementation notesbackend.md - Backend implementation notesintegration.md - Integration documentationqa.md - Quality assurance test resultsOutput Location: project-context/2.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.
Goal: Deploy, monitor, and operate the application in production.
Persona: DevOps Engineer
Key Activities:
Key Artifacts:
Output Location: project-context/3.deliver/
Why This Matters: Building software is only half the battle. The Deliver phase ensures your application can run reliably in production, be monitored, and evolve over time.
This is a critical distinction in AAMAD:
The Development Crew consists of AI agent personas that build your application. These are the “construction workers” who create the software:
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 Engineer” (who builds the chat UI) and “Backend Engineer” (who implements the conversation logic).
The Application Crew consists of AI agents that are your application. These are the agents that end users interact with in production:
These agents are permanent—they run in production and deliver value to end users.
Example: In a customer service chatbot application, the Application Crew might include:
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
Each workflow is owned and documented by a clear AI agent persona with a single responsibility principle. This ensures:
All major actions, decisions, and documentation are stored as markdown artifacts, ensuring:
Big tasks are broken into epics, making development:
The framework is reusable for any project. Framework artifacts (in .cursor/) are project-agnostic, while project-context/ contains instance-specific documentation.
When you use AAMAD, your project structure looks like this:
your-project/
├─ .cursor/ # Reusable framework artifacts
│ ├─ agents/ # Agent persona definitions
│ ├─ prompts/ # Parameterized agent prompts
│ ├─ rules/ # Architecture & workflow rules
│ └─ templates/ # Generation templates (MRD, PRD, SAD)
│
├─ project-context/ # Project-specific artifacts
│ ├─ 1.define/ # MRD, PRD, research reports
│ ├─ 2.build/ # SAD, code, setup docs
│ └─ 3.deliver/ # Deploy configs, runbooks, QA logs
│
└─ src/ # Your application source code
Framework artifacts (.cursor/) are reusable across projects.
Project-context contains all generated and instance-specific documentation.
AAMAD uses Cursor rules (stored in .cursor/rules/) to guide AI agent behavior and ensure consistent, high-quality output across all phases. These rules act as the “constitution” for your AI agents, defining how they should think, work, and make decisions.
Cursor rules are markdown files that define:
When you use CursorAI (or compatible AI coding assistants) with AAMAD, these rules are automatically loaded, ensuring all agents follow the same standards and patterns.
The AAMAD framework includes three main rule categories:
core)
development-workflow)
adapter-crewai)
Rules are loaded automatically when you:
@system-architect)Example: When you invoke @backend-engineer, the agent automatically:
This ensures consistency across:
AAMAD provides templates (stored in .cursor/templates/) that standardize artifact creation across all phases. These templates ensure consistency, completeness, and quality in all generated documentation.
The framework includes templates for each phase:
Phase 1: Define Templates
mrd-template.md - Market Research Document template
prd-template.md - Product Requirements Document template
Phase 2: Build Templates
sad-template.md - Solution Architecture Document template
Phase 3: Deliver Templates
runbook-template.md - Operational runbook template
@product-mgr), it knows which template to useExample Workflow:
You: @product-mgr Please create a 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 all required sections are complete
The .cursor/agents/ and .cursor/prompts/ folders complete the framework:
Agents (.cursor/agents/)
Prompts (.cursor/prompts/)
Together, rules, templates, agents, and prompts create a complete system for consistent, high-quality AI-assisted development.
AAMAD addresses common problems in AI-assisted development:
Context Chaos - Without structure, AI agents lack context. AAMAD provides clear context boundaries.
Quality Debt - Rapid AI coding often produces “slop.” AAMAD’s persona-driven approach ensures quality.
Maintenance Nightmares - Unstructured AI-generated code is hard to maintain. AAMAD’s artifact-driven approach ensures traceability.
Lack of Reusability - Each project starts from scratch. AAMAD’s framework artifacts are reusable.
No Clear Process - Teams don’t know how to systematically build agentic systems. AAMAD provides a proven methodology.
AAMAD can be used in two ways:
git clone https://github.com/synaptic-ai-consulting/AAMAD
pip install aamad
aamad init --dest /path/to/your/project
Once set up, you follow the three-phase process, using the Development Crew to build your Application Crew.
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 a runbook 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?
Cursor Rules Consistency: How do Cursor 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?
Continue to Module 03: Context Engineering Basics