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

Estimated time: ~45 minutes
Outcome: Execute a Tier-0 Build phase using the Development Crew to transform PRD into working code
Framework version: AAMAD v0.7.5 (simplified path — see CHECKLIST.md for the full workflow)

Learning Objectives

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

Orchestrate the Development Crew using independent chat sessions
Work with @system.arch to create a Solution Architecture Document (SAD)
Work with @backend.eng to implement the CrewAI Application Crew
Work with @frontend.eng and @integration.eng to wire a minimal UI
Work with @qa.eng to smoke-test end-to-end functionality
Set AAMAD_TARGET_RUNTIME=crewai and use canonical Build artifacts
Use git branches for incremental development
Apply software development best practices as an Agentic Architect

Prerequisites

Completed Module 05 (Define phase with MRD and PRD)
Your recruitment-assistant project with AAMAD initialized (Framework version: 0.7.5 in AGENTS.md)
Python 3.9+ installed
Git installed and configured
Access to an AI coding assistant (Cursor recommended)
OpenAI API key (or other LLM provider API key)

Build Phase Overview

The Build phase transforms your PRD into working software through coordinated multi-agent execution. As an Agentic Architect, you’ll wear your Technical Hat to orchestrate the Development Crew, ensuring:

Single Responsibility: Each agent persona focuses on one aspect
Incremental Development: Build and validate in small, manageable steps
Asynchronous Work: Each persona works in independent chat sessions
Context Preservation: All decisions documented in canonical markdown artifacts
Quality Gates: Review and validate at each step

Tier-0 Development Crew order (simplified):

@system.arch — Creates project-context/1.define/sad.md
@backend.eng — Implements Application Crew → backend.md (core of this mini-project)
@frontend.eng — Builds minimal UI → frontend.md
@integration.eng — Wires components → integration.md
@qa.eng — Smoke tests → qa.md

Note: Full AAMAD projects also use @project.mgr → setup.md and recommended @security.eng → security.md. This Tier-0 path folds env/scaffold into Step 1 below. Optionally run aamad validate --phase build after QA.

Step 1: Configure Environment Variables

Before starting development, configure the required environment variables.

Create `.env` File

In your project root, create a .env file:

cd ~/projects/recruitment-assistant
touch .env

Add the following environment variables:

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key_here
   
# Optional: Use your preferred model
OPENAI_MODEL=gpt-4o
   
# AAMAD runtime target (default for this course)
AAMAD_TARGET_RUNTIME=crewai
   
# Application Configuration
APP_NAME=Recruitment Assistant
APP_ENV=development
   
# CrewAI Configuration (if needed)
CREWAI_TELEMETRY_OPT_OUT=true

Important: Add .env to .gitignore to avoid committing secrets:
```
echo ".env" >> .gitignore
```

Create a .env.example file as a template (commit this, not .env):

cp .env .env.example
# Edit .env.example to remove actual API keys, replace with placeholders

Verify Environment Setup

Test that your environment variables are accessible:

# In Python
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('API Key set:', bool(os.getenv('OPENAI_API_KEY'))); print('Runtime:', os.getenv('AAMAD_TARGET_RUNTIME'))"

Note: You may need to install python-dotenv:

pip install python-dotenv

Full projects: Invoke @project.mgr with *setup-project to scaffold directories, install dependencies, and document everything in project-context/2.build/setup.md. For Tier 0, the manual .env setup above is enough.

Step 2: System Architect - Create Solution Architecture Document (SAD)

The System Architect designs the technical architecture based on your PRD.

2.1 Create Architecture Branch

git checkout -b feature/architecture

2.2 Invoke System Architect Persona

Start a NEW chat session (this is important for context isolation):

Open a new chat in Cursor (or your AI assistant)

Reference the System Architect persona:

@system.arch
   
I need you to create a Solution Architecture Document (SAD) for the 
recruitment assistant application. Please:
   
1. Review the PRD: project-context/1.define/prd.md
2. Create a comprehensive SAD using the template: .cursor/templates/sad-template.md
   (or run *create-sad / *create-sad --mvp)
3. Design the architecture for:
   - Application Crew (Researcher, Evaluator, Recommender agents using CrewAI)
   - Frontend interface (simple web UI or CLI)
   - Backend API (FastAPI or Flask)
   - Integration points
4. Set / confirm AAMAD_TARGET_RUNTIME=crewai and record it in the SAD Audit section
5. Save the SAD as: project-context/1.define/sad.md

2.3 Review and Iterate

Wearing your Technical Hat, review the SAD:

Architecture aligns with PRD requirements
Technology choices are appropriate (CrewAI, Python, etc.)
AAMAD_TARGET_RUNTIME=crewai is recorded in Audit
Components are well-defined and modular
Integration points are clear
Sources, Assumptions, Open Questions, and Audit sections are present
Security considerations included at MVP scope

If adjustments are needed:

Continue the conversation with @system.arch
Request specific changes: “Update the API design to use FastAPI instead of Flask”
Review again until satisfied

2.4 Validate and Commit

Once the SAD is complete and reviewed:

git add project-context/1.define/sad.md
git commit -m "feat: Add Solution Architecture Document (SAD)

- System Architect created comprehensive SAD
- Runtime target crewai recorded in Audit
- Architecture reviewed and approved"

2.5 Merge to Main

git checkout main
git merge feature/architecture
git branch -d feature/architecture

Step 3: Backend Engineer - Implement Application Crew (core)

The Backend Engineer implements the Application Crew and backend services. For this mini-project, do backend first—the Application Crew is the product’s intelligence.

3.1 Create Backend Branch

git checkout -b feature/backend

3.2 Invoke Backend Engineer Persona

Start a NEW chat session:

@backend.eng

I need you to implement the backend for the recruitment assistant. Please:

1. Review the PRD: project-context/1.define/prd.md
2. Review the SAD: project-context/1.define/sad.md
3. Follow adapter-crewai conventions (AAMAD_TARGET_RUNTIME=crewai)
4. Implement the Application Crew using CrewAI:
   - Researcher Agent
   - Evaluator Agent
   - Recommender Agent
5. Implement API endpoints (FastAPI or Flask)
6. Document all work in: project-context/2.build/backend.md
   (use *develop-be if available)

3.3 Review Backend Artifact

Review project-context/2.build/backend.md:

Application Crew agents are well-defined
API endpoints match SAD
Implementation approach is sound
Audit / status notes are present

Iterate with @backend.eng if needed.

3.4 Implementation

The Backend Engineer will:

Create backend code in src/backend/ or src/
Implement CrewAI agents (Researcher, Evaluator, Recommender)
Create API endpoints
Implement business logic
Update backend.md with status

Key Implementation Notes:

Use CrewAI to create the Application Crew
Follow the architecture defined in SAD
Ensure agents can access required tools/APIs
Implement proper error handling

3.5 Review Implementation

Wearing your Technical Hat, review:

Application Crew agents are correctly implemented
API endpoints match SAD specification
Code follows best practices
Error handling is comprehensive
Environment variables are used correctly

3.6 Validate and Commit

git add project-context/2.build/backend.md src/backend/ src/
git commit -m "feat: Add backend implementation

- Backend Engineer implemented Application Crew (CrewAI)
- API endpoints created
- backend.md documented"

3.7 Merge to Main

git checkout main
git merge feature/backend
git branch -d feature/backend

Step 4: Frontend Engineer - Build UI Components

The Frontend Engineer creates a minimal user interface for the recruitment assistant.

4.1 Create Frontend Branch

git checkout -b feature/frontend

4.2 Invoke Frontend Engineer Persona

Start a NEW chat session:

@frontend.eng

I need you to build the frontend for the recruitment assistant. Please:

1. Review the PRD: project-context/1.define/prd.md
2. Review the SAD: project-context/1.define/sad.md
3. Implement a simple web interface (HTML/CSS/JS or React) or CLI interface
4. Document decisions and status in: project-context/2.build/frontend.md
   (use *develop-fe if available)

4.3 Review and Implement

Review frontend.md and the code:

UI covers MVP requirements from PRD
API integration points match SAD
Error handling is implemented
Code is clean and maintainable

git add project-context/2.build/frontend.md src/frontend/
git commit -m "feat: Add frontend implementation

- Frontend Engineer created UI components
- UI matches PRD requirements
- frontend.md documented"

git checkout main
git merge feature/frontend
git branch -d feature/frontend

Step 5: Integration Engineer - Wire Up Components

The Integration Engineer connects frontend, backend, and external services.

5.1 Create Integration Branch

git checkout -b feature/integration

5.2 Invoke Integration Engineer Persona

Start a NEW chat session:

@integration.eng

I need you to integrate all components of the recruitment assistant. Please:

1. Review the PRD: project-context/1.define/prd.md
2. Review the SAD: project-context/1.define/sad.md
3. Review: project-context/2.build/frontend.md
4. Review: project-context/2.build/backend.md
5. Wire frontend to backend API and verify a basic round-trip
6. Document integration and known issues in: project-context/2.build/integration.md
   (use *integrate-api if available)

5.3 Review Integration

Wearing your Technical Hat, verify:

Frontend can communicate with backend
API endpoints are correctly integrated
Data flows correctly end-to-end
Error handling works across boundaries

git add project-context/2.build/integration.md
git commit -m "feat: Integrate frontend and backend components

- Integration Engineer wired up all components
- End-to-end data flow verified
- integration.md documented"

git checkout main
git merge feature/integration
git branch -d feature/integration

Step 6: QA Engineer - Smoke Test End-to-End

The QA Engineer ensures the MVP works for the core flow.

6.1 Create QA Branch

git checkout -b feature/qa

6.2 Invoke QA Engineer Persona

Start a NEW chat session:

@qa.eng

I need you to smoke-test the recruitment assistant application. Please:

1. Review the PRD: project-context/1.define/prd.md
2. Review the SAD: project-context/1.define/sad.md
3. Review: project-context/2.build/frontend.md, backend.md, integration.md
4. Run smoke / acceptance checks on the main chat/recruitment flow
5. Log issues, known gaps, and future work in: project-context/2.build/qa.md
   (use *qa / *verify-flow if available)

Go deeper (optional): Full AAMAD QA includes *test-unit and *test-integration with AC-* traceability. For Tier 0, a documented smoke pass is enough.

6.3 Fix Issues and Commit

If issues are found:

Create a fix branch: git checkout -b fix/issue-description
Work with the appropriate engineer persona to fix
Re-test with @qa.eng
Commit fixes and merge to main

git add project-context/2.build/qa.md
git commit -m "feat: Add QA smoke test results

- QA Engineer executed smoke tests
- Test results documented in qa.md
- Application validated against PRD MVP scope"

git checkout main
git merge feature/qa
git branch -d feature/qa

Optional quality gate:

aamad validate --phase build

Step 7: Final Review and Documentation

7.1 Review All Artifacts

As an Agentic Architect, review all Build phase artifacts:

project-context/1.define/sad.md — Architecture is sound
project-context/2.build/backend.md — Backend / Application Crew complete
project-context/2.build/frontend.md — Frontend complete
project-context/2.build/integration.md — Integration complete
project-context/2.build/qa.md — Smoke tests passed (or scoped gaps noted)
All code is committed and merged

7.2 Update Project README

Update your project README with:

Current status (Build phase complete)
How to run the application
Environment setup instructions (AAMAD_TARGET_RUNTIME=crewai)
Architecture overview

7.3 Final Commit

git add README.md
git commit -m "docs: Update README with Build phase completion

- All Build phase artifacts complete
- Application ready for Deliver phase"

Exercise Summary

Complete the Build phase by:

✅ Configure environment variables (.env with AAMAD_TARGET_RUNTIME=crewai)
✅ @system.arch: Create SAD in 1.define/sad.md
✅ @backend.eng: Implement Application Crew and backend.md
✅ @frontend.eng: Build UI and frontend.md
✅ @integration.eng: Wire components and integration.md
✅ @qa.eng: Smoke test and qa.md
✅ Review all artifacts and update documentation

Key Practices Applied:

Independent chat sessions for each persona
Canonical AAMAD artifacts (not custom *-plan.md files)
Git branches for incremental development
Review and iteration at each step
Technical hat for orchestration and quality gates

Deliverables

By the end of this module, you should have:

✅ .env file configured (not committed) with AAMAD_TARGET_RUNTIME=crewai
✅ .env.example template (committed)
✅ project-context/1.define/sad.md — Solution Architecture Document
✅ project-context/2.build/backend.md — Backend / Application Crew notes
✅ project-context/2.build/frontend.md — Frontend notes
✅ project-context/2.build/integration.md — Integration notes
✅ project-context/2.build/qa.md — QA smoke results
✅ Working frontend code
✅ Working backend code with Application Crew
✅ Integrated application
✅ All code committed and merged to main
✅ Updated README.md

Check Your Understanding

Why use independent chat sessions for each persona?
- What happens if you use the same chat session for all personas?
Why use canonical artifacts (backend.md, qa.md) instead of chat memory?
- How do these enable asynchronous development and handoffs?
Why use git branches for each step?
- What are the benefits of incremental commits and merges?
How does the Technical Hat help in the Build phase?
- What decisions do you make as an Agentic Architect that the personas don’t?
What does AAMAD_TARGET_RUNTIME=crewai control?
- What does it not change about Define → Build → Deliver?

Troubleshooting

Issue: Environment variables not loading

Solution: Ensure .env file is in project root
Install python-dotenv: pip install python-dotenv
Verify .env is in .gitignore

Issue: Agent persona not following instructions

Solution: Be explicit in your prompts; use dotted handles (@backend.eng)
Reference specific files: “Review project-context/1.define/prd.md”
Skim AGENTS.md for the correct invocation names

Issue: Git merge conflicts

Solution: Resolve conflicts manually
Use git status to see conflicted files
Review changes carefully before committing

Issue: Application Crew agents not working

Solution: Check CrewAI installation: pip install crewai
Verify API keys and AAMAD_TARGET_RUNTIME=crewai are set
Review agent configuration in code

Issue: Frontend can’t connect to backend

Solution: Check API endpoint URLs
Verify backend is running
Check CORS settings if using web frontend

Best Practices Applied

Throughout this module, you’ve applied key software development best practices:

Single Responsibility Principle: Each persona has one clear job
Incremental Development: Build in small, validated steps
Context Isolation: Independent chat sessions prevent context pollution
Documentation: Canonical artifacts under project-context/
Version Control: Git branches enable safe experimentation
Quality Gates: Review and validation at each step
Asynchronous Work: Artifacts enable parallel development

Next Steps

Once the Build phase is complete:

Review all artifacts - Ensure everything is documented
Test the application - Run it end-to-end
Commit all work - Ensure main branch is up to date
Proceed to Module 07 - Deliver phase (@devops.eng → deploy.md)

Continue to Module 07: Hands-On Mini-Project - Deliver Phase

Additional Resources

CrewAI Documentation - CrewAI framework guide
AAMAD Framework Repository - Framework documentation
AAMAD CHECKLIST.md - Full workflow reference
Git Branching Best Practices - Git workflow guide

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

Learning Objectives

Prerequisites

Build Phase Overview

Step 1: Configure Environment Variables

Create .env File

Verify Environment Setup

Step 2: System Architect - Create Solution Architecture Document (SAD)

2.1 Create Architecture Branch

2.2 Invoke System Architect Persona

2.3 Review and Iterate

2.4 Validate and Commit

2.5 Merge to Main

Step 3: Backend Engineer - Implement Application Crew (core)

3.1 Create Backend Branch

3.2 Invoke Backend Engineer Persona

3.3 Review Backend Artifact

3.4 Implementation

3.5 Review Implementation

3.6 Validate and Commit

3.7 Merge to Main

Step 4: Frontend Engineer - Build UI Components

4.1 Create Frontend Branch

4.2 Invoke Frontend Engineer Persona

4.3 Review and Implement

Step 5: Integration Engineer - Wire Up Components

5.1 Create Integration Branch

5.2 Invoke Integration Engineer Persona

5.3 Review Integration

Step 6: QA Engineer - Smoke Test End-to-End

6.1 Create QA Branch

6.2 Invoke QA Engineer Persona

6.3 Fix Issues and Commit

Step 7: Final Review and Documentation

7.1 Review All Artifacts

7.2 Update Project README

7.3 Final Commit

Exercise Summary

Deliverables

Check Your Understanding

Troubleshooting

Best Practices Applied

Next Steps

Additional Resources

Create `.env` File