Marketing Agents

A web application for marketing experts to generate and manage comprehensive marketing campaigns using AI Agents powered by the Microsoft Agent Framework.

Architecture

This project uses .NET 9, ASP.NET Core Minimal APIs, and .NET Aspire for local development orchestration.

Projects

• MarketingAgents.AppHost - .NET Aspire orchestration project for local development
• MarketingAgents.Api - Backend API service using ASP.NET Core Minimal APIs
• MarketingAgents.AgentHost - Dedicated agent execution and orchestration service
• MarketingAgents.ServiceDefaults - Shared service defaults for telemetry, service discovery, and resilience

Technology Stack

• .NET 9 - Latest .NET platform
• ASP.NET Core Minimal APIs - High-performance web APIs
• .NET Aspire 9.5.1 - Local development orchestrator
• Azure Cosmos DB - Primary database (using emulator for local dev)
• Redis - Caching layer (using container for local dev)
• OpenTelemetry - Observability (logs, metrics, traces)
• xUnit + FluentAssertions - Testing framework

Prerequisites

• .NET 9 SDK
• Docker Desktop (for Redis and Cosmos DB emulator)
• Visual Studio 2022 17.14+ or VS Code with C# Dev Kit

Getting Started

1. Clone the repository

git clone <repository-url>
cd marketing-agents

2. Restore dependencies

dotnet restore

3. Run the application

dotnet run --project MarketingAgents.AppHost

This will:

• Start the Aspire dashboard (typically at http://localhost:15888)
• Launch Redis container
• Launch Cosmos DB emulator
• Start the API service
• Start the AgentHost service

4. Access the services

• Aspire Dashboard: http://localhost:15888
• API Service: http://localhost:<port> (check Aspire dashboard for actual port)
• Swagger UI: http://localhost:<port>/swagger
• AgentHost Service: http://localhost:<port> (check Aspire dashboard for actual port)

Development

Project Structure

MarketingAgents/
├── MarketingAgents.AppHost/          # Aspire orchestration
├── MarketingAgents.Api/              # API service
│   ├── Endpoints/                    # Minimal API endpoints
│   ├── Services/                     # Business logic
│   ├── Models/                       # DTOs and domain entities
│   └── Data/                         # Cosmos DB repositories
├── MarketingAgents.AgentHost/        # Agent service
│   ├── Agents/                       # Agent providers
│   └── Services/                     # Orchestration services
├── MarketingAgents.ServiceDefaults/  # Shared configurations
├── MarketingAgents.Api.Tests/        # Unit tests
└── MarketingAgents.Api.IntegrationTests/ # Integration tests

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Building

# Build all projects
dotnet build

# Build specific project
dotnet build MarketingAgents.Api

Code Quality

This project uses:

• Nullable reference types - Enabled across all projects
• EditorConfig - Consistent coding standards
• StyleCop Analyzers - C# style rules
• SonarAnalyzer - Code quality and security rules

All warnings are treated as errors to maintain high code quality.

Configuration

User Secrets

For local development, use .NET User Secrets:

# Set a secret for the API project
dotnet user-secrets set "ConnectionStrings:CosmosDb" "<connection-string>" --project MarketingAgents.Api

Environment Variables

Key environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT - OpenTelemetry collector endpoint
• ASPNETCORE_ENVIRONMENT - Environment name (Development, Staging, Production)

Documentation

Building and Viewing Documentation

This project uses MkDocs with Material theme for comprehensive documentation. All documentation lives in the docs/ directory and is deployed automatically to GitHub Pages.

Local Development

# Install MkDocs and dependencies (first time only)
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin

# Serve documentation locally
npm run docs:serve
# OR
mkdocs serve

# Access at http://localhost:8000/marketing-agents/

Building Documentation

# Build documentation
npm run docs:build
# OR
mkdocs build

# Build with strict validation (recommended before committing)
npm run docs:build:strict
# OR
mkdocs build --strict

CI/CD

Documentation is automatically built and deployed to GitHub Pages on every push to main that affects:

• docs/** - Documentation markdown files
• mkdocs.yml - MkDocs configuration
• specs/adr/** - Architecture Decision Records

Live Documentation: View on GitHub Pages

Documentation Structure

docs/
├── index.md                      # Landing page
├── getting-started/
│   ├── installation.md           # Setup instructions
│   ├── quick-start.md            # 5-minute tutorial
│   └── configuration.md          # Configuration guide
├── architecture/
│   ├── overview.md               # High-level architecture
│   ├── system-design.md          # Detailed system design
│   ├── data-flow.md              # Data flows and transformations
│   └── decisions.md              # ADR index
├── api/
│   ├── rest-api.md               # REST API reference
│   └── realtime-api.md           # SignalR WebSocket API
├── guides/
│   ├── development.md            # Development workflow
│   ├── deployment.md             # Azure deployment procedures
│   └── troubleshooting.md        # Common issues and solutions
└── reference/
    ├── configuration.md          # Configuration options
    └── environment-variables.md  # Environment variables reference

specs/
├── prd.md                        # Product Requirements
├── adr/                          # Architecture Decision Records
│   ├── template.md               # MADR template
│   ├── 0001-use-aspire-for-orchestration.md
│   └── 0002-use-mkdocs-for-documentation.md
├── features/                     # Feature specifications
├── tasks/                        # Technical task specs
└── journal/                      # Engineering journal

Contributing

1. Follow the coding standards defined in .editorconfig
2. Ensure all tests pass before submitting PR
3. Maintain ≥85% code coverage
4. Update documentation as needed

License

[Add your license here]

Spec2Win-encoded.mp4

🎯 Overview

This repository provides a preconfigured development environment and agent-driven workflow that takes you from product concept to deployed application through a structured, step-by-step process.

🚀 Quick Start

1. Open in Dev Container - Everything is preconfigured in .devcontainer/
2. Describe your app idea - The more specific, the better
3. Follow the workflow - Use the prompts to guide specialized agents through each phase

🏗️ Architecture

Development Environment

The .devcontainer/ folder provides a ready-to-use development container with:

• Python 3.12

• Azure CLI & Azure Developer CLI (azd)

• TypeScript

• Docker-in-Docker

• VS Code extensions: GitHub Copilot Chat, Azure Pack, AI Studio

MCP Servers

The .vscode/mcp.json configures Model Context Protocol servers that give agents access to:

• context7 - Up-to-date library documentation
• github - Repository management and operations
• microsoft.docs.mcp - Official Microsoft/Azure documentation
• playwright - Browser automation capabilities
• deepcontext - Repository context and understanding for external repos

AI Agents (Chat Modes)

Four specialized agents in .github/chatmodes/:

1. PM Agent (@pm) - Product Manager

• Model: o3-mini
• Tools: Edit files, search, fetch web content
• Purpose: Translates ideas into structured PRDs and FRDs
• Instructions: Asks clarifying questions, identifies business goals, creates living documentation

2. Dev Lead Agent (@dev-lead) - Technical Lead

• Model: Claude Sonnet 4
• Tools: Read files, search, semantic analysis
• Purpose: Reads all standards from standards/ and generates comprehensive AGENTS.md
• Instructions: Analyzes engineering standards, creates unified agent guidelines, establishes coding patterns
• Usage: Run /generate-agents at project start (can defer until before /plan and /implement)

3. Dev Agent (@dev) - Developer

• Model: Claude Sonnet 4
• Tools: Full development suite + Context7, GitHub, Microsoft Docs, Copilot Coding Agent, AI Toolkit
• Purpose: Breaks down features into tasks, implements code, or delegates to GitHub Copilot
• Instructions: Analyzes specs, writes modular code, follows architectural patterns, creates GitHub issues

4. Azure Agent (@azure) - Cloud Architect

• Model: Claude Sonnet 4
• Tools: Azure resource management, Bicep, deployment tools, infrastructure best practices
• Purpose: Deploys applications to Azure with IaC and CI/CD pipelines
• Instructions: Analyzes codebase, generates Bicep templates, creates GitHub Actions, uses Azure Dev CLI

📋 Workflow

graph TB
    Start[("👤 User<br/>High-level app description")]
    
    Start --> PRD["<b>/prd</b><br/>📝 PM Agent creates<br/>Product Requirements Document"]
    
    PRD --> FRD["<b>/frd</b><br/>📋 PM Agent breaks down<br/>Feature Requirements Documents"]
    
    FRD --> GenAgents["<b>/generate-agents</b><br/>🎯 Dev Lead reads standards<br/>& generates AGENTS.md<br/>(optional, before /plan)"]
    
    GenAgents --> Plan["<b>/plan</b><br/>🔧 Dev Agent creates<br/>Technical Task Breakdown"]
    
    Plan --> Choice{"Implementation<br/>Choice"}
    
    Choice -->|Local| Implement["<b>/implement</b><br/>💻 Dev Agent<br/>implements code locally"]
    
    Choice -->|Delegated| Delegate["<b>/delegate</b><br/>🎯 Dev Agent creates<br/>GitHub Issue + assigns<br/>Copilot Coding Agent"]
    
    Implement --> Deploy["<b>/deploy</b><br/>☁️ Azure Agent<br/>creates IaC + deploys to Azure"]
    
    Delegate --> Deploy
    
    Deploy --> Done[("✅ Production-Ready<br/>Application on Azure")]
    
    style Start fill:#e1f5ff
    style PRD fill:#fff4e6
    style FRD fill:#fff4e6
    style GenAgents fill:#e3f2fd
    style Plan fill:#e8f5e9
    style Implement fill:#e8f5e9
    style Delegate fill:#e8f5e9
    style Deploy fill:#f3e5f5
    style Done fill:#e1f5ff
    style Choice fill:#fff9c4

Loading

Workflow Steps

1. /prd - Product Requirements Document

   • PM Agent engages in conversation to understand the product vision
   • Creates specs/prd.md with goals, scope, requirements, and user stories
   • Living document that evolves with feedback

2. /frd - Feature Requirements Documents

   • PM Agent decomposes the PRD into individual features
   • Creates files in specs/features/ for each feature
   • Defines inputs, outputs, dependencies, and acceptance criteria

3. /generate-agents - Generate Agent Guidelines (Optional)

   • Dev Lead Agent reads all standards from standards/ directory
   • Consolidates engineering standards into comprehensive AGENTS.md
   • Can be run at project start or deferred until before /plan and /implement
   • Must be completed before planning and implementation begins

4. /plan - Technical Planning

   • Dev Agent analyzes FRDs and creates technical task breakdowns
   • Creates files in specs/tasks/ with implementation details
   • Identifies dependencies, estimates complexity, defines scaffolding needs

5. /implement OR /delegate - Implementation

   • Option A (/implement): Dev Agent writes code directly in src/backend and src/frontend
   • Option B (/delegate): Dev Agent creates GitHub Issues with full task descriptions and assigns to GitHub Copilot Coding Agent

6. /deploy - Azure Deployment

   • Azure Agent analyzes the codebase
   • Generates Bicep IaC templates
   • Creates GitHub Actions workflows for CI/CD
   • Deploys to Azure using Azure Dev CLI and MCP tools

📁 Documentation Structure

The workflow creates living documentation:

specs/
├── prd.md              # Product Requirements Document
├── features/           # Feature Requirements Documents
│   ├── feature-1.md
│   └── feature-2.md
└── tasks/              # Technical Task Specifications
    ├── task-1.md
    └── task-2.md

src/
├── backend/            # Backend implementation
└── frontend/           # Frontend implementation

standards/
├── general/            # General engineering standards
├── backend/            # Backend-specific standards
└── frontend/           # Frontend-specific standards

AGENTS.md               # Consolidated agent guidelines (generated)
mkdocs.yml              # MKdocs configuration for documentation site
docs/                   # MKdocs documentation source files

Documentation with MKdocs

This repository is configured with MKdocs for generating beautiful project documentation:

• Configuration: mkdocs.yml contains site settings and navigation
• Source Files: Documentation markdown files in docs/ directory
• Standards: Documentation practices defined in standards/general/documentation-guidelines.md
• Build & Serve: Use MKdocs commands to preview and deploy documentation

The documentation standards ensure consistency, accessibility, and maintainability across all project documentation.

🔧 Managing Standards with Git Subtrees

This repository uses git subtrees to integrate engineering standards from external repositories. The standards/ folder contains subtrees from three separate guideline repositories.

Technology-Specific Standards via Branches

Each standards repository uses branches to organize technology-specific rules:

• Backend Standards: Choose between dotnet or python branches
• Frontend Standards: Choose between react, angular, or other framework branches
• General Standards: Use main branch for universal guidelines

This approach allows you to pull only the standards relevant to your tech stack.

Adding Subtrees (Initial Setup)

When setting up the repository, specify the appropriate branch for your tech stack:

# General standards (always use main)
git subtree add --prefix standards/general https://github.com/EmeaAppGbb/spec2cloud-guidelines.git main --squash

# Backend standards - choose your stack
git subtree add --prefix standards/backend https://github.com/EmeaAppGbb/spec2cloud-guidelines-backend.git dotnet --squash
# OR
git subtree add --prefix standards/backend https://github.com/EmeaAppGbb/spec2cloud-guidelines-backend.git python --squash

# Frontend standards - choose your framework
git subtree add --prefix standards/frontend https://github.com/EmeaAppGbb/spec2cloud-guidelines-frontend.git react --squash
# OR
git subtree add --prefix standards/frontend https://github.com/EmeaAppGbb/spec2cloud-guidelines-frontend.git angular --squash

Updating Subtrees

To pull the latest changes from the upstream guideline repositories, use the same branch:

# Update general standards
git subtree pull --prefix standards/general https://github.com/EmeaAppGbb/spec2cloud-guidelines.git main --squash

# Update backend standards (use your chosen branch)
git subtree pull --prefix standards/backend https://github.com/EmeaAppGbb/spec2cloud-guidelines-backend.git dotnet --squash

# Update frontend standards (use your chosen branch)
git subtree pull --prefix standards/frontend https://github.com/EmeaAppGbb/spec2cloud-guidelines-frontend.git react --squash

Note: The --squash flag combines all commits from the subtree repository into a single commit, keeping the history clean.

Switching Technology Stacks

If you need to switch to a different tech stack (e.g., from React to Angular), remove the old subtree and add the new one:

# Remove old subtree
git rm -r standards/frontend
git commit -m "Remove React standards"

# Add new subtree
git subtree add --prefix standards/frontend https://github.com/EmeaAppGbb/spec2cloud-guidelines-frontend.git angular --squash

🎓 Example Usage

# Start with your product idea
"I want to create a smart AI agent for elderly care that tracks vitals and alerts caregivers"

# Step 1: Create the PRD
/prd

# Step 2: Break down into features
/frd

# Step 3: Generate agent guidelines from standards (optional, can defer)
/generate-agents

# Step 4: Create technical plans
/plan

# Step 5a: Implement locally
/implement

# OR Step 5b: Delegate to GitHub Copilot
/delegate

# Step 6: Deploy to Azure
/deploy

🔑 Key Benefits

• Zero Setup - Dev container has everything preconfigured
• Structured Process - Clear workflow from idea to production
• AI-Powered - Specialized agents handle different aspects
• Best Practices - Built-in architectural guidance via AGENTS.md
• Flexible Implementation - Choose local development or delegation
• Azure-Ready - Automated IaC and CI/CD generation

📖 Learn More

• See AGENTS.md for comprehensive engineering guidelines
• Explore .github/chatmodes/ for agent configurations
• Review .github/prompts/ for prompt templates

🤝 Contributing

Contributions welcome! Extend with additional agents, prompts, or MCP servers.

---

From idea to production in minutes, not months. 🚀