Agentic Architect 101

Synaptic AI Consulting

Hands-On Mini-Project - Define Phase

Module 05: Hands-On Mini-Project - Define Phase

Estimated time: ~30 minutes
Outcome: Complete an AAMAD “Define” phase for a recruitment assistant application crew
Framework version: AAMAD v0.7.5

Learning Objectives

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

Project Scenario

For this hands-on exercise, we’ll build a Recruitment Assistant—an automated candidate sourcing and evaluation system. This use case is based on the CrewAI Recruitment Example, which demonstrates how to build a multi-agent system that:

This is a perfect example for learning AAMAD because it:

Your Goal: Use AAMAD’s Define phase to create comprehensive MRD and PRD documents that will guide the development of this recruitment assistant.

Prerequisites

Before starting, ensure you have:

Using Claude Code or VS Code? Run aamad init --ide claude-code or aamad init --ide vscode instead of the Cursor default below. Persona invocation and file locations differ by IDE—follow AGENTS.md after init. Templates and project-context/ stay the same.

Step-by-Step Instructions

Step 1: Create Your Project Folder

  1. Open your terminal and navigate to where you want to create your project:

    cd ~/projects  # or wherever you keep your projects

  2. Create a new directory for your recruitment project:

    mkdir recruitment-assistant
cd recruitment-assistant

  3. Initialize a Git repository:

    git init

    This creates a local Git repository to track your project artifacts.

Step 2: Install AAMAD

Install AAMAD v0.7.5 (or a compatible 0.7.x release):

pip install "aamad>=0.7.5,<0.8"
# or: uv pip install "aamad>=0.7.5,<0.8"

This installs the AAMAD CLI and framework bundle, including:

Step 3: Initialize AAMAD in Your Project

Initialize for Cursor (default for this course):

aamad init --ide cursor --dest .

What this does:

After init — skim these files:

  1. AGENTS.md — persona handles (@product-mgr, @backend.eng, …) and framework version
  2. CHECKLIST.md — full Define → Build → Deliver reference (this course uses a simplified Tier-0 path)

Optional: Copy aamad.config.example.yml → aamad.config.yml for shared language/UI/testing/security preferences.

If init looks wrong, inspect the bundle: aamad bundle-info --verbose

Step 4: Review the Project Structure

After initialization, your project should look like this (key files):

recruitment-assistant/
├── .cursor/
│   ├── agents/
│   │   ├── product-mgr.md
│   │   ├── system-arch.md
│   │   ├── backend-eng.md
│   │   ├── devops-eng.md
│   │   ├── dev-crew.md          # Naming convention reference
│   │   └── …
│   ├── templates/
│   │   ├── mrd-template.md
│   │   ├── prd-template.md
│   │   ├── sad-template.md
│   │   ├── system-description-template.md
│   │   └── user-guide-template.md
│   ├── rules/
│   │   ├── aamad-core.mdc
│   │   ├── development-workflow.mdc
│   │   ├── delivery-workflow.mdc
│   │   ├── adapter-registry.mdc
│   │   ├── adapter-crewai.mdc
│   │   └── …
│   └── prompts/
│       ├── prompt-phase-1
│       └── prompt-sync-docs
├── project-context/
│   ├── 1.define/
│   ├── 2.build/
│   └── 3.deliver/
├── AGENTS.md
├── CHECKLIST.md
├── aamad.config.example.yml
└── .git/

Step 5: Review the CrewAI Recruitment Example

Before creating your MRD and PRD, familiarize yourself with the reference implementation:

  1. Visit the CrewAI Recruitment Example
  2. Review the example to understand:
    • What agents are used (Researcher, Evaluator, Recommender)
    • What tasks each agent performs
    • How agents collaborate
    • What the end-to-end workflow looks like

Key Insights from the Example:

This understanding will help you create more accurate MRD and PRD documents.

Step 6: Invoke the Product Manager Persona

Now you’ll use @product-mgr to generate your MRD and PRD. The persona is defined in .cursor/agents/product-mgr.md.

Optional elicitation: For specialized projects, run *elicit-requirements first to produce project-context/1.define/system-description.md. For this recruitment scenario it is optional—you can go straight to MRD/PRD.

Option A: Using Cursor (Recommended)

  1. Open your project in Cursor
  2. Start a new chat session

  3. Reference the Product Manager persona:

    @product-mgr I need to create an MRD and PRD for a recruitment assistant application. 
The use case is based on the CrewAI recruitment example. 
Please run *create-mrd then *create-prd (or *create-context).
Ensure Sources, Assumptions, Open Questions, and Audit sections are complete.
  4. The agent will guide you through the process, using the templates from .cursor/templates/

Option B: Using Any AI Coding Assistant

  1. Open the Product Manager persona file: .cursor/agents/product-mgr.md
  2. Review the prompts and instructions
  3. Open the MRD template: .cursor/templates/mrd-template.md
  4. Use your AI assistant to help fill out the template based on:
    • The recruitment assistant use case
    • Insights from the CrewAI example
    • Your understanding of the problem domain

Step 7: Generate the Market Research Document (MRD)

MRD decision (v0.7.x): Commercial / market-facing products → produce MRD. Internal / personal / operational tools → skip MRD and note the rationale in PRD Assumptions.
This recruitment assistant is treated as a commercial-style scenario, so we keep the MRD.

Work with @product-mgr (*create-mrd) to create your MRD. The MRD should cover:

  1. Problem Statement
    • What problem does the recruitment assistant solve?
    • Why is manual candidate sourcing and evaluation inefficient?
  2. Target Users
    • Recruiters who need to find and evaluate candidates
    • Hiring managers who need candidate recommendations
    • HR teams managing high-volume recruitment
  3. Market Opportunity
    • Time savings in candidate sourcing
    • Improved candidate matching accuracy
    • Scalability for high-volume recruitment
  4. Competitive Landscape
    • Existing ATS (Applicant Tracking Systems)
    • Manual recruitment processes
    • How an AI-powered multi-agent system differs

Save your MRD as: project-context/1.define/mrd.md

Step 8: Generate the Product Requirements Document (PRD)

Next, create your PRD. The PRD should include:

  1. Product Overview
    • High-level description of the recruitment assistant
    • Core value proposition
  2. Goals and Success Metrics
    • Time to source candidates
    • Candidate match accuracy
    • Recruiter satisfaction
  3. User Personas
    • Primary: Recruiter (needs to find qualified candidates quickly)
    • Secondary: Hiring Manager (needs ranked candidate recommendations)
  4. Core Features
    • Candidate search based on job requirements
    • Automated candidate evaluation
    • Ranked candidate recommendations
    • Integration with job posting systems (optional for mini-project)
  5. Application Crew Definition
    • Researcher Agent: Searches and sources candidates
    • Evaluator Agent: Evaluates candidates against job criteria
    • Recommender Agent: Provides ranked recommendations
  6. Development Crew Mapping (Define + upcoming Build)
    • @product-mgr (you, using this persona in Define)
    • @system.arch, @backend.eng, @frontend.eng, @integration.eng, @qa.eng (Module 06)
    • @devops.eng (Module 07)
  7. Out of Scope (for this mini-project)
    • Full ATS integration
    • Candidate communication automation
    • Advanced analytics and reporting

Save your PRD as: project-context/1.define/prd.md

Step 9: Review PRD as Agentic Architect

Critical Step: Before proceeding, you must review the PRD wearing your Agentic Architect hats—specifically the Experience and Business hats. This is where you exercise judgment and ensure the application aligns with your vision.

Wearing the Experience Hat

Review the PRD from a user experience and design perspective:

  1. User Experience Alignment
    • Does the PRD describe an experience that users will find valuable?
    • Are the user personas accurate and representative?
    • Will the Application Crew agents provide a smooth, intuitive experience?
    • How will users interact with the system? Is it clear and well-defined?
  2. Interaction Design
    • How will recruiters input job requirements?
    • How will recommendations be presented? (ranked list, detailed reports, etc.)
    • What happens when agents encounter ambiguous requirements?
    • How are errors and edge cases handled?
  3. Brand and Voice
    • Does the PRD specify the tone and personality of agent interactions?
    • Is the experience aligned with your organization’s brand values?
    • How do agents represent your brand in candidate interactions?

Action Items:

Wearing the Business Hat

Review the PRD from a business outcomes and strategic perspective:

  1. Business Value Alignment
    • Do the success metrics directly tie to business outcomes?
    • Will this system create measurable value (time savings, cost reduction, quality improvement)?
    • Is the ROI clear and defensible?
  2. Strategic Fit
    • Does this application align with organizational goals?
    • Are the out-of-scope items appropriate for the current business context?
    • Does the scope balance ambition with feasibility?
  3. Risk and Constraints
    • Are technical constraints realistic given business timelines?
    • Are there compliance or regulatory considerations?
    • What are the risks if the system doesn’t meet success metrics?

Action Items:

Making Adjustments

If your review reveals gaps or misalignments:

  1. Iterate with Product Manager Persona
    • Go back to @product-mgr and request specific updates
    • Example: “Update the PRD to include error handling for ambiguous job requirements”
    • Example: “Add success metrics that measure recruiter time savings in hours per week”
  2. Document Your Decisions
    • Note any changes you make and why
    • This creates traceability for future reference

Remember: As an Agentic Architect, you’re not just accepting what the Product Manager persona creates—you’re actively shaping it to ensure technical excellence, user experience quality, and business value alignment.

Step 10: Generate Project README

Once your PRD is finalized and reviewed, have the Product Manager persona create a README.md file for your project repository. This README will serve as the public-facing documentation for your project.

Invoke the Product Manager Persona:

@product-mgr Based on the PRD in project-context/1.define/prd.md, 
create a comprehensive README.md file for the project repository. 
The README should include:
- Project overview and description
- Problem statement and value proposition
- Key features
- Application architecture overview (agents and their roles)
- Getting started instructions
- Project structure
- Next steps for contributors

The README should include:

  1. Project Title and Description
    • Clear, concise description of what the project does
    • Value proposition for users
  2. Problem Statement
    • What problem does this solve?
    • Why is it important?
  3. Features
    • Core capabilities of the recruitment assistant
    • What users can expect
  4. Architecture Overview
    • Brief description of the Application Crew
    • Agent roles and responsibilities
    • How agents collaborate
  5. Getting Started
    • Prerequisites
    • Installation instructions
    • Basic usage (to be completed in Build phase)
  6. Project Structure
    • Overview of the AAMAD directory structure
    • Where to find key artifacts
  7. Development Status
    • Current phase (Define, Build, or Deliver)
    • What’s been completed
    • What’s next

Save the README as: README.md (in the project root)

Why This Matters:

Step 11: Review and Validate

Before moving to the Build phase, complete this final review checklist:

Document Completeness:

Optional quality gate: aamad validate --phase define

Agentic Architect Review:

Project Documentation:

Exercise

Complete the following tasks:

  1. Set up your project:
    • Create recruitment-assistant folder
    • Initialize Git
    • Install AAMAD: pip install "aamad>=0.7.5,<0.8"
    • Run aamad init --ide cursor --dest .
    • Skim AGENTS.md and CHECKLIST.md
  2. Study the reference:
    • Review the CrewAI Recruitment Example
    • Identify the three main agents and their responsibilities
    • Understand the workflow between agents
  3. Generate artifacts:
    • Use @product-mgr persona to create MRD
    • Use @product-mgr persona to create PRD
    • Save both documents in project-context/1.define/
  4. Review as Agentic Architect:
    • Review PRD wearing the Experience hat (user experience, interaction design, brand)
    • Review PRD wearing the Business hat (business value, strategic fit, risk)
    • Make adjustments as needed
    • Finalize PRD for Build phase
  5. Create project documentation:
    • Use @product-mgr persona to generate README.md based on PRD
    • Save README.md in project root
  6. Define your Application Crew:
    • Document the Researcher Agent role and responsibilities
    • Document the Evaluator Agent role and responsibilities
    • Document the Recommender Agent role and responsibilities
    • Describe how they will collaborate
  7. Commit your work: 
    git add .
git commit -m "Define phase: MRD and PRD for recruitment assistant"

Deliverables

By the end of this module, you should have:

  1. ✅ A new project folder with AAMAD framework initialized
  2. ✅ project-context/1.define/mrd.md - Market Research Document
  3. ✅ project-context/1.define/prd.md - Product Requirements Document (reviewed and finalized)
  4. ✅ README.md - Project README generated from PRD
  5. ✅ Application Crew definition (3 agents: Researcher, Evaluator, Recommender)
  6. ✅ Development Crew mapping (personas you’ll use in Build phase)
  7. ✅ PRD reviewed from Experience and Business perspectives (Agentic Architect review)
  8. ✅ Git repository with initial commit

Check Your Understanding

Answer these questions to verify you understand the Define phase:

  1. Why do we create MRD and PRD before writing code? What happens if AI agents don’t have clear context about what to build?

  2. What’s the difference between Application Crew and Development Crew? Which crew are you defining in the PRD?

  3. Which crew will build the Application Crew?

  4. Why use the AAMAD templates instead of creating documents from scratch? What benefits do standardized templates provide?

  5. How does the Product Manager persona help in the Define phase? What would happen if you tried to create MRD/PRD without using a persona?

  6. Why is it important to review the PRD as an Agentic Architect? What’s the difference between accepting the PRD as-is vs. reviewing it with your Experience and Business hats?

  7. How does reviewing the PRD demonstrate the value of the Agentic Architect role?

Troubleshooting

Issue: aamad: command not found or No matching distribution found for aamad

Issue: Templates not found after aamad init

Issue: Product Manager persona not responding correctly

Next Steps

Once you’ve completed the Define phase:

  1. Review your artifacts - Make sure MRD and PRD are complete and clear
  2. Commit your work - Save your Define phase artifacts to Git
  3. Proceed to Module 06 - You’ll use these documents to guide the Build phase (AAMAD_TARGET_RUNTIME=crewai)

Continue to Module 06: Hands-On Mini-Project - Build Phase

Additional Resources