CLAUDE.md

Project Overview

This is a Python project that uses Microsoft Agent Framework--the new unified orchestration framework that combines the best of:

• Semantic Kernel: Enterprise-ready AI orchestration
• AutoGen: Multi-agent conversation patterns

To build a multi-agent event planning workflow.

Skills Protocol (Superpowers)

Mandatory First Response Protocol

Before responding to ANY user message, you MUST complete this checklist:

1. ☐ List available skills in your mind
2. ☐ Ask yourself: "Does ANY skill match this request?"
3. ☐ If yes → Use the Skill tool to read and run the skill file
4. ☐ Announce which skill you're using
5. ☐ Follow the skill exactly

Responding WITHOUT completing this checklist = automatic failure.

Common Rationalizations That Mean You're About To Fail

If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill.

• "This is just a simple question" → WRONG. Questions are tasks. Check for skills.
• "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills.
• "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills.
• "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it.
• "I remember this skill" → WRONG. Skills evolve. Run the current version.
• "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills.
• "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it.
• "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything.

Why: Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.

If a skill for your task exists, you must use it or you will fail at your task.

How to Use Skills

You have skills available.

Automatic Setup Detection

IMPORTANT: Before attempting to use skills, you MUST verify that the skills system and CLAUDE.md is properly configured by checking if you see skills like this. Also if the user already has a well-formatted CLAUDE.md with the project information filled in below, you can skip the setup:

Should see:

/superpowers:brainstorm - Interactive design refinement

/superpowers:write-plan - Create implementation plan

/superpowers:execute-plan - Execute plan in batches

1. Inform the user: "I've detected that the agent instructions system is not yet set up. I'll automatically install it now by fetching the metaprompt from the agent-instructions repository and executing it. You will need to install the setup process described in: https://github.com/obra/superpowers/tree/main?tab=readme-ov-file#claude-code-via-plugin-marketplace to enable Claude Code Superpowers."

Skills with Checklists

If a skill has a checklist, you MUST create TodoWrite todos for EACH item.

Don't:

• Work through checklist mentally
• Skip creating todos "to save time"
• Batch multiple items into one todo
• Mark complete without doing them

Why: Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.

Key Principles

1. Finding a relevant skill = mandatory to read and use it. Not optional.
2. Skills document proven techniques that save time and prevent mistakes.
3. Always announce which skill you're using and why.
4. Follow skills exactly - don't rationalize away the discipline.
5. Create TodoWrite todos for any skill checklists.

Custom Agents

The system supports custom specialized agents stored in agent-specific directories. These agents can be invoked for specific tasks that match their expertise.

Agent Selection and Usage

• IMPORTANT: ALWAYS start by invoking the agent-organizer sub-agent, an expert agent organizer specializing in multi-agent orchestration.
• Custom agents are automatically selected based on the context and task requirements
• The system analyzes the user's request and matches it with the most appropriate specialized agent
• Multiple sub-agents can work in parallel on different aspects of a complex task
• Maximum parallel agents: 50 sub-agents can operate simultaneously
• Each agent has its own expertise domain defined in its configuration
• Agents can coordinate and share context through the main agent orchestrator

When Custom Agents Are Used

The system automatically invokes custom agents when:

• The task matches a specialized agent's expertise domain
• Complex tasks benefit from parallel processing across multiple specialized agents
• Domain-specific knowledge or workflows are required
• The main agent determines delegation would improve efficiency or accuracy

ExecPlans

When writing complex features or significant refactors, use an ExecPlan (as described in specs/PLANS.md) from design to implementation. If the user request requires multiple specs, create multiple specification files in the specs/ directory. After creating the specs, create a master ExecPlan that links to each individual spec ExecPlan. Update the specs/README.md to include links to the new specs.

ALWAYS start an ExecPlan creation by consulting the DeepWiki tool for best practices on design patterns, architecture, and implementation strategies. Ask it questions about the system design and constructs in the library that will help you achieve your goals.

Skip using an ExecPlan for straightforward tasks (roughly the easiest 25%).

Architecture

This project follows a coordinator-centric star topology multi-agent workflow architecture.

Workflow Architecture

Star Topology with Coordinator Hub:

User Request
    ↓
EventPlanningCoordinator (Routing Hub)
    ↓ ↑ (bidirectional edges)
    ├── Venue Specialist (Web Search)
    ├── Budget Analyst (Code Interpreter)
    ├── Catering Coordinator (Web Search)
    └── Logistics Manager (Weather, Calendar)
    ↓
EventPlanningCoordinator (Synthesis)
    ↓
Final Event Plan

Key Architectural Patterns:

1. Coordinator-Centric Routing: EventPlanningCoordinator manages all routing decisions based on structured output from specialists
2. Service-Managed Threads: All agents use store=True for automatic conversation history management via Azure AI service
3. Structured Output Routing: Specialists return SpecialistOutput Pydantic model with next_agent field for dynamic routing
4. Human-in-the-Loop: Framework-native ctx.request_info() + @response_handler for user interaction
5. Tool Content Conversion: Cross-thread message passing requires converting tool calls/results to text summaries

Agents and Tools

Each specialist agent has access to domain-specific tools:

Tool Integration:

• Custom Web Search: Replaces Bing Search, used by Venue Specialist and Catering Coordinator
• Weather Tool: Open-Meteo API (free, no key required), used by Logistics Manager
• Calendar Tools: iCalendar (.ics) management with create/list/delete operations, used by Logistics Manager
• Code Interpreter: Python REPL with scratchpad for financial calculations, used by Budget Analyst
• MCP Tool Orchestration: sequential-thinking-tools for complex reasoning (optional, all agents)

Directory Structure

IMPORTANT: For your agents to be discovered by the DevUI, they must be organized in a directory structure like below. Each agent/workflow must have an __init__.py that exports the required variable (agent or workflow).

Note: .env is a shared env file, it contains the Azure OpenAI config, if this doesn't exist refer to .env.example and ask user for values and create .env

spec-to-agents/
├── src/
│   └── spec_to_agents/
│       ├── __init__.py
│       ├── clients.py # contains shared client code for AI Foundry
│       ├── agents/ # contains core agent/workflow definitions
│       │   ├── __init__.py
│       │   ├── budget_analyst.py
│       │   ├── catering_coordinator.py
│       │   ├── event_coordinator.py
│       │   ├── logistics_manager.py
│       │   └── venue_specialist.py
│       ├── prompts/ # contains system prompts for each agent
│       │   ├── __init__.py
│       │   ├── budget_analyst.py
│       │   ├── catering_coordinator.py
│       │   ├── event_coordinator.py
│       │   ├── logistics_manager.py
│       │   └── venue_specialist.py
│       └── tools/ # contains reusable tool definitions for agents
│           └── __init__.py
├── tests/ # contains units tests for agents and tools
├── .env  
└── pyproject.toml

Development Guidelines

General

• Before implementing a large refactor or new feature explain your plan and get approval.
• Human-in-the-loop: If you're unsure about a design decision or implementation detail, ask for clarification before proceeding. Feel free to ask clarifying questions as you are working.
• Avoid re-inventing the wheel: Use existing libraries and tools where appropriate.

Python

uv is the command-line tool used to manage the development environment and dependencies in Python projects. This project uses the workspace feature of uv to manage multiple packages within the packages directory. Below are the common commands you'll use:

• uv sync --dev - Install / sync regular + dev dependencies
• uv add <package> - Add a dependency
• uv lock - Lock dependencies / regenerate lockfile
• uv run - You NEVER need to activate a virtual environment manually; just prefix commands with uv run
  • uv run <script>.py - Run a Python script
  • uv run -m <module> - Run a Python module
• uv run pytest - Run tests
• uv run ruff . - Run linting / formatting
• uv run mypy . - Run type checking

Project-specific Commands:

• uv run app - Start the Agent Framework DevUI for testing and debugging agents/workflows

Technology Stack Focus

• Python 3.11+: Latest stable version with modern features
• Pydantic: Data validation and settings management
• Agent Framework: Building and orchestrating agents
• Agent Framework DevUI: Workflow/agent frontend
• Infrastructure: AI Foundry, Azure Container Apps, AZD template, Managed Identity (No API Key Authentication)

Code Organization and Modularity

Prefer highly modular code that separates concerns into distinct modules. This improves:

• Testability: Each module can be tested in isolation
• Reusability: Modules can be used independently
• Maintainability: Changes are localized to specific modules
• Readability: Clear separation of concerns makes code easier to understand

Guidelines:

• Keep modules focused on a single responsibility
• Use clear module boundaries and minimal public APIs
• Prefer composition over large monolithic modules
• Extract shared functionality into dedicated modules as the codebase grows

Code Organization and Modularity

Prefer highly modular code that separates concerns into distinct modules. This improves:

• Testability: Each module can be tested in isolation
• Reusability: Modules can be used independently
• Maintainability: Changes are localized to specific modules
• Readability: Clear separation of concerns makes code easier to understand

Guidelines:

• Keep modules focused on a single responsibility
• Use clear module boundaries and minimal public APIs
• Prefer composition over large monolithic modules
• Extract shared functionality into dedicated modules as the codebase grows

Conversation History Management

The workflow uses service-managed threads for automatic conversation history management, eliminating manual message tracking.

Service-Managed Threads Pattern

How It Works: When agents are created with store=True, the Azure AI Agent Client leverages service-managed threads:

1. Thread Creation: Client creates service_thread_id in Azure AI service backend
2. Message Storage: All messages automatically stored in service backend
3. Automatic Retrieval: On subsequent agent.run() calls, conversation history retrieved automatically
4. No Manual Tracking: No need for full_conversation passing or manual message arrays

Implementation:

agent = client.create_agent(
    name="Agent Name",
    instructions=PROMPT,
    tools=[...],
    store=True,  # Enable service-managed threads
)

Benefits:

• Eliminates manual conversation tracking in coordinator
• Conversation persists across workflow sessions
• Simplifies coordinator logic significantly
• Reduces risk of message synchronization bugs

Code Location: All agents in src/spec_to_agents/agents/*.py use store=True

Tool Content Conversion Pattern

Problem: FunctionCallContent and FunctionResultContent cannot cross thread boundaries because they embed thread-specific run_id in their call_id.

Error: "No thread ID was provided, but chat messages includes tool results"

Solution: The convert_tool_content_to_text() function converts tool-related content to text summaries:

• FunctionCallContent → "[Tool Call: tool_name({args})]"
• FunctionResultContent → "[Tool Result for call_id: result]"
• Other content types passed through unchanged

When To Use:

• When passing messages between agents with different service thread IDs
• In _route_to_agent(): Before sending messages to specialists
• In _synthesize_plan(): Before sending conversation to coordinator

Code Location: src/spec_to_agents/workflow/executors.py:25-86

Human-in-the-Loop (HITL)

The workflow supports pausing for user input using framework-native patterns.

HITL Pattern: ctx.request_info() + @response_handler

How It Works:

1. Specialist Signals Need: Specialist sets user_input_needed=True in SpecialistOutput
2. Coordinator Pauses Workflow: Calls ctx.request_info(HumanFeedbackRequest, ...)
3. Framework Creates Checkpoint: Serializes workflow state including conversation history
4. DevUI Emits RequestInfoEvent: User sees prompt in UI
5. User Responds: Provides feedback via DevUI
6. Framework Restores Checkpoint: Deserializes workflow state automatically
7. Handler Receives Response: @response_handler gets original request + user feedback
8. Coordinator Continues: Routes back to requesting specialist with feedback

Implementation:

# In coordinator
await ctx.request_info(
    request_data=HumanFeedbackRequest(
        prompt="Which venue do you prefer?",
        conversation=full_conversation,  # Preserved in checkpoint
        requesting_agent="venue",
    ),
    request_type=HumanFeedbackRequest,
    response_type=str,
)

@response_handler
async def on_human_feedback(
    self,
    original_request: HumanFeedbackRequest,
    feedback: str,
    ctx: WorkflowContext,
) -> None:
    # Framework automatically restored conversation
    conversation = list(original_request.conversation)
    await self._route_to_agent(
        original_request.requesting_agent,
        feedback,
        ctx,
        prior_conversation=conversation,
    )

Key Benefits:

• Automatic conversation preservation via checkpointing
• No manual state tracking required
• DevUI integration out-of-the-box
• Clean separation: specialists declare needs, coordinator handles interaction

Code Location: src/spec_to_agents/workflow/executors.py:201-235

Key Implementation Patterns

1. Coordinator-Centric Routing

The EventPlanningCoordinator custom executor manages all routing decisions:

• Receives initial requests via @handler start(prompt: str)
• Processes specialist responses via @handler on_specialist_response(AgentExecutorResponse)
• Handles human feedback via @response_handler on_human_feedback(HumanFeedbackRequest, str)
• Synthesizes final plan via _synthesize_plan(conversation)

Code Location: src/spec_to_agents/workflow/executors.py:89-277

2. Structured Output Routing

Specialists return Pydantic SpecialistOutput model with explicit routing decisions:

class SpecialistOutput(BaseModel):
    summary: str  # Concise summary of recommendations
    next_agent: str | None  # ID of next agent ("venue", "budget", "catering", "logistics") or None
    user_input_needed: bool = False  # Whether user input is required
    user_prompt: str | None = None  # Question to ask user if input needed

Routing Logic:

if specialist_output.user_input_needed:
    await ctx.request_info(...)  # Pause for human input
elif specialist_output.next_agent:
    await self._route_to_agent(specialist_output.next_agent, ...)  # Route to next specialist
else:
    await self._synthesize_plan(...)  # Workflow complete, synthesize

Benefits:

• Specialists control their own routing
• No hardcoded agent sequence
• Enables conditional logic (e.g., skip agents based on context)
• Explicit, debuggable routing decisions

Code Location: src/spec_to_agents/models/messages.py:52-83

3. Star Topology Workflow Builder

The workflow uses bidirectional edges connecting coordinator to each specialist:

workflow = (
    WorkflowBuilder(name="Event Planning Workflow", max_iterations=30)
    .set_start_executor(coordinator)
    # Bidirectional edges: Coordinator ←→ Each Specialist
    .add_edge(coordinator, venue_exec)
    .add_edge(venue_exec, coordinator)
    .add_edge(coordinator, budget_exec)
    .add_edge(budget_exec, coordinator)
    # ... other specialists ...
    .build()
)

Benefits:

• Simple mental model: all routing through coordinator hub
• Easy to debug and trace execution
• Natural fit for human-in-the-loop mediation
• Coordinator has complete control over execution flow

Code Location: src/spec_to_agents/workflow/core.py:148-170

Code Style

Documentation

IMPORTANT: Documentation means docstrings and type hints in the code, NOT separate documentation files.

• You should NOT create any separate documentation pages (README files, markdown docs, etc.)
• The code itself should contain proficient documentation in the form of docstrings and type hints (for Python)
• For Python: Add comprehensive numpy-style docstrings to all functions, classes, and modules

Avoid Over-Documenting:

• Do NOT document obvious behavior (e.g., a function named get_name that returns a name doesn't need extensive documentation)
• Focus documentation on WHY and HOW, not WHAT (the code itself shows what it does)
• Document edge cases, non-obvious behavior, and important constraints
• Skip docstrings for trivial functions where the name and type hints are self-explanatory
• Prioritize documenting public APIs, complex logic, and non-intuitive design decisions

Python

Documentation and Comments

• Write clear and concise comments for each function.

• Ensure functions have descriptive names and include type hints.

• Provide docstrings following PEP 257 conventions.

  • Use numpy style for docstrings. Example:

  def calculate_area(radius: float) -> float:
      """
      Calculate the area of a circle given the radius.
  
      Parameters
      ----------
      radius : float
          The radius of the circle.
  
      Returns
      -------
      float
          The area of the circle, calculated as π * radius^2.
      """
      import math
      return math.pi * radius ** 2

• Use proper built-in type annotations (e.g. dict[..., ...], list[...], tuple[...]) and only using typing module when needed.

• Prefer to use | for union types instead of Union[...], type | None instead of Optional[...], etc.

• Break down complex functions into smaller, more manageable functions.

Test-Driven Development (TDD)

• Never create throwaway test scripts or ad hoc verification files
• If you need to test functionality, write a proper test in the test suite

Python

• Write tests for all new features in the tests/ directory
• Use pytest as the testing framework
• Use pytest-mock for mocking dependencies
• Aim for high test coverage, especially for critical components
• Always include test cases for critical paths of the application.
• Account for common edge cases like empty inputs, invalid data types, and large datasets.
• Include comments for edge cases and the expected behavior in those cases.
• Write unit tests for functions and document them with docstrings explaining the test cases.

Tools

You have a collection of tools available to assist with development and debugging. These tools can be invoked as needed.

• sequential-thinking-tools
  • When to use: For complex reasoning tasks that require step-by-step analysis. A good rule of thumb is if the task requires more than 25% effort.
• deepwiki
  • When to use: Consult for external knowledge or documentation that is not part of the immediate codebase. Can be helpful for system design questions or understanding third-party libraries.
• context7
  • When to use: For retrieving immediate documentation on the latest version of a library or framework. Useful for quick lookups to double-check syntax, parameters, or usage examples.
• playwright
  • When to use: Interact with DevUI for testing the workflow end-to-end from prompt to final result. Prefer using this as your default snapshot testing tool. You also have the ability to use playwright for viewing the browser console logs and network requests to help debug issues that may arise.
• tmux-cli is a bash command that enables Claude Code to control CLI applications running in separate tmux panes - launch programs, send input, capture output, and manage interactive sessions. Run tmux-cli --help for detailed usage instructions.
  • When to use:
    • Interact with a script that waits for user input
    • Launch another Claude Code instance to have it perform some analysis or review or debugging etc
    • Run a Python script with the Pdb debugger to step thru its execution, for code-understanding and debugging
    • Launch web apps and test them with browser automation MCP tools like Puppeteer

Updates to This Document

• Update this document as needed to reflect changes in development practices or project structure
  • Updates usually come in the form of the package structure changing
• Do NOT contradict existing guidelines in the document
• This document should be an executive summary of the development practices for this project
  • Keep low-level implementation details out of this document