mdan-cli 2.5.0 → 2.5.2

package/AGENTS.md

@@ -1,246 +1,308 @@
-# AGENTS.md — MDAN Development Guidelines
+# MDAN - Agent Development Guidelines
 
-> How to develop, test, and maintain MDAN projects
+This document provides guidelines for developing agents in the MDAN project, following the Better Agents framework standards.
+
+## 📋 Table of Contents
+
+- [Project Structure](#project-structure)
+- [Agent Development](#agent-development)
+- [Testing](#testing)
+- [Prompt Management](#prompt-management)
+- [Best Practices](#best-practices)
 
 ---
 
-## Purpose
+## 🏗️ Project Structure
 
-This file provides guidelines for developing reliable, testable, production-grade MDAN projects. It ensures every feature is properly tested, evaluated, and that prompts are versioned.
+```
+MDAN/
+├── app/                      # Agent code
+│   ├── core/                 # Core agents
+│   │   └── agents/
+│   ├── mmm/                  # Main module (Business Model & Management)
+│   │   └── agents/
+│   ├── mmb/                  # Module Builder
+│   │   └── agents/
+│   ├── cis/                  # Creative Innovation Strategy
+│   │   └── agents/
+│   ├── tea/                  # Test Engineering & Architecture
+│   │   └── agents/
+│   └── packs/                # Specialized packs
+│       ├── fintech/
+│       │   └── agents/
+│       ├── devops-azure/
+│       │   └── agents/
+│       └── db-optimization/
+│           └── agents/
+├── tests/
+│   ├── scenarios/            # End-to-end scenario tests
+│   │   ├── core/
+│   │   ├── mmm/
+│   │   ├── mmb/
+│   │   ├── cis/
+│   │   ├── tea/
+│   │   └── packs/
+│   └── evaluations/          # Jupyter notebooks for evaluations
+│       ├── core/
+│       ├── mmm/
+│       ├── mmb/
+│       ├── cis/
+│       ├── tea/
+│       └── packs/
+├── prompts/                  # Versioned prompts
+│   ├── core/
+│   ├── mmm/
+│   ├── mmb/
+│   ├── cis/
+│   ├── tea/
+│   └── packs/
+├── prompts.json              # Prompt registry
+├── .mcp.json                 # MCP server configuration
+├── AGENTS.md                 # This file
+├── CLAUDE.md                 # Claude Code compatibility
+└── .env                      # Environment variables
+```
 
 ---
 
-## Quick Start
+## 🤖 Agent Development
 
-```bash
-# Initialize MDAN project
-mdan init my-project
-cd my-project
-
-# Start development
-mdan phase 1 discover
+### Agent Structure
 
-# Test your changes
-mdan phase 4 verify
+Each agent should have the following structure:
 
-# Ship
-mdan phase 5 ship
+```
+app/{module}/agents/{agent-name}/
+├── agent.py                  # Agent implementation
+└── prompt.yaml               # Versioned prompt
 ```
 
----
-
-## Development Workflow
+### Agent Implementation (agent.py)
 
-### 1. Feature Development
+```python
+from typing import Optional, Dict, Any
+from dataclasses import dataclass
 
-When adding a new feature:
+@dataclass
+class AgentRequest:
+    """Request data structure for the agent."""
+    # Define your request fields here
+    pass
 
-1. **Create user story** in MDAN-STATE.json
-2. **Run DISCOVER phase** to define requirements
-3. **Run DESIGN phase** for architecture
-4. **Implement in BUILD phase**
-5. **Verify in VERIFY phase**
-6. **Ship in SHIP phase**
+class {AgentName}Agent:
+    """
+    Brief description of the agent.
 
-### 2. Code Standards
+    Detailed description of what the agent does,
+    its capabilities, and its role in the system.
+    """
 
-- ✅ Use type hints (TypeScript/Python)
-- ✅ Write unit tests (80%+ coverage)
-- ✅ Write integration tests for critical paths
-- ✅ Use environment variables for config
-- ✅ Handle errors explicitly
-- ❌ Never commit secrets
-- ❌ Never expose stack traces
+    def __init__(self):
+        """Initialize the agent."""
+        self.name = "{Agent Name}"
+        self.title = "{Agent Title}"
+        self.icon = "{emoji}"
 
-### 3. Testing Requirements
+    async def process(self, request: AgentRequest) -> Dict[str, Any]:
+        """
+        Process the request and return a response.
 
-All features MUST have:
+        Args:
+            request: The request to process
 
-- **Unit tests** for business logic
-- **Integration tests** for API/database
-- **E2E scenarios** for user flows
+        Returns:
+            A dictionary containing the response
+        """
+        # Implementation here
+        pass
+```
 
-Run tests:
-```bash
-# All tests
-npm test
+### Prompt Definition (prompt.yaml)
 
-# With coverage
-npm test -- --coverage
+```yaml
+name: {agent-name}
+version: 1.0.0
+description: Brief description of the agent
 
-# Specific scenario
-npm test -- tests/scenarios/auth.test.ts
-```
+system_prompt: |
+  You are {Agent Name}, a {Agent Title}.
 
-### 4. Evaluation Requirements
+  Your capabilities:
+  - Capability 1
+  - Capability 2
+  - Capability 3
 
-For RAG/ML features:
+  Your communication style:
+  - Style characteristic 1
+  - Style characteristic 2
 
-- Create evaluation dataset
-- Run evaluations in VERIFY phase
-- Set pass/fail thresholds
-- Track metrics over time
+  Your principles:
+  - Principle 1
+  - Principle 2
+  - Principle 3
 
-```bash
-# Run evaluations
-mdan evaluate --dataset customer-support
+user_prompt_template: |
+  {template for user prompts}
 ```
 
 ---
 
-## Prompt Versioning
+## 🧪 Testing
 
-All agent prompts are versioned in `templates/prompts/`.
+### Scenario Tests
 
-### Adding a New Prompt
+Every agent must have at least one scenario test in `tests/scenarios/{module}/{agent-name}.test.py`.
 
-1. Create YAML file: `templates/prompts/my-agent.yaml`
-2. Add to `templates/prompts.json`
-3. Test the prompt
-4. Commit with version bump
+```python
+from scenario import Scenario, expect
 
-### Updating a Prompt
+scenario = Scenario("{Agent Name} - Test Description")
 
-```bash
-# Show prompt
-mdan prompt show orchestrator
+@scenario.test
+async def test_{test_name}():
+    """
+    Test description.
+    """
+    agent = {AgentName}Agent()
+
+    request = AgentRequest(
+        # Set request fields
+    )
+
+    result = await agent.process(request)
 
-# Compare versions
-mdan prompt diff orchestrator 2.1.0 2.2.0
+    # Assertions
+    expect(result).to_have_key("expected_key")
+    expect(result["expected_key"]).to_equal("expected_value")
 ```
 
-### Version Rules
+### Evaluations
 
-| Change Type | Version Bump |
-|-------------|--------------|
-| Bug fix | PATCH (2.2.1) |
-| New feature | MINOR (2.3.0) |
-| Breaking change | MAJOR (3.0.0) |
+For agents with probabilistic components (RAG, classification, etc.), create evaluation notebooks in `tests/evaluations/{module}/{agent-name}.ipynb`.
 
 ---
 
-## Quality Gates
+## 📝 Prompt Management
 
-Each phase has a quality gate:
+### Versioning
 
-### DISCOVER → DESIGN
-- [ ] PRD is complete
-- [ ] User stories have acceptance criteria
-- [ ] Project profile detected
+All prompts must be versioned in YAML files in the `prompts/` directory.
 
-### DESIGN → BUILD
-- [ ] Architecture document complete
-- [ ] ADR decisions documented
-- [ ] UX designs reviewed
+### Prompt Registry
 
-### BUILD → VERIFY
-- [ ] All features implemented
-- [ ] Unit tests pass (80%+)
-- [ ] Integration tests pass
-- [ ] No critical bugs
+Update `prompts.json` when adding or modifying prompts:
 
-### VERIFY → SHIP
-- [ ] All scenarios pass
-- [ ] All evaluations pass
-- [ ] Security review complete
-- [ ] Performance criteria met
+```json
+{
+  "prompts": [
+    {
+      "name": "{agent-name}",
+      "version": "1.0.0",
+      "path": "prompts/{module}/{agent-name}.yaml",
+      "description": "Brief description"
+    }
+  ]
+}
+```
 
 ---
 
-## MCP Integration
+## ✅ Best Practices
 
-Configure your IDE with MCP:
+### 1. Agent Design
 
-```bash
-mdan mcp init
-```
+- **Single Responsibility**: Each agent should have a clear, focused purpose
+- **Type Hints**: Use type hints for all function signatures
+- **Async/Await**: Use async functions for I/O operations
+- **Error Handling**: Implement proper error handling with specific exceptions
 
-This generates `.mcp.json` with:
-- Available tools
-- Prompt paths
-- Quality gate settings
+### 2. Prompt Design
 
----
+- **Clear Instructions**: Provide clear, specific instructions
+- **Examples**: Include examples in prompts when helpful
+- **Constraints**: Specify constraints and boundaries
+- **Tone**: Define the communication style and tone
 
-## File Structure
+### 3. Testing
 
-```
-my-project/
-├── mdan/
-│   ├── orchestrator.md
-│   ├── agents/
-│   │   ├── dev.md
-│   │   ├── test.md
-│   │   └── ...
-│   └── skills/
-├── tests/
-│   ├── scenarios/      # E2E tests
-│   │   └── *.test.md
-│   └── evaluations/    # Component tests
-│       └── *.md
-├── templates/
-│   ├── prompts/        # Versioned prompts
-│   │   └── *.yaml
-│   └── prompts.json   # Prompt registry
-├── .mcp.json          # MCP config
-├── MDAN-STATE.json    # Project state
-└── AGENTS.md          # This file
-```
+- **Test Coverage**: Aim for high test coverage
+- **Edge Cases**: Test edge cases and error conditions
+- **Scenarios**: Create realistic scenario tests
+- **Evaluations**: Use evaluations for probabilistic components
+
+### 4. Documentation
+
+- **Docstrings**: Include docstrings for all public functions
+- **Comments**: Add comments for complex logic
+- **Examples**: Provide usage examples
+- **README**: Update module READMEs when adding agents
+
+### 5. Code Quality
+
+- **PEP 8**: Follow PEP 8 style guidelines
+- **Linting**: Use linters to catch issues
+- **Formatting**: Use consistent code formatting
+- **Reviews**: Get code reviews before merging
 
 ---
 
-## Troubleshooting
+## 🚀 Getting Started
 
-### Tests Failing
+### Creating a New Agent
 
-1. Check test output for specific failures
-2. Run single test: `npm test -- --testNamePattern="my test"`
-3. Check for environment issues
+1. Create the agent directory:
+   ```bash
+   mkdir -p app/{module}/agents/{agent-name}
+   ```
 
-### Evaluation Thresholds Not Met
+2. Create `agent.py` with the agent implementation
 
-1. Review evaluation output
-2. Check dataset quality
-3. Adjust thresholds if needed (document reason)
+3. Create `prompt.yaml` with the prompt definition
 
-### Prompt Not Working
+4. Create scenario test in `tests/scenarios/{module}/{agent-name}.test.py`
 
-1. Validate YAML: `mdan mcp validate`
-2. Check model compatibility
-3. Review changelog for breaking changes
+5. Update `prompts.json` with the new prompt
 
----
+6. Run tests to verify:
+   ```bash
+   npm test
+   ```
+
+### Running Tests
 
-## Best Practices
+```bash
+# Run all tests
+npm test
 
-1. **Always use MDAN state** - Keep MDAN-STATE.json updated
-2. **Run quality gates** - Never skip verification
-3. **Version prompts** - Document all changes
-4. **Test locally first** - Before committing
-5. **Monitor metrics** - Track performance over time
+# Run scenario tests
+npm run test:scenarios
+
+# Run evaluations
+npm run test:evaluations
+```
 
 ---
 
-## Commands Reference
+## 📚 Resources
 
-| Command | Description |
-|---------|-------------|
-| `mdan init` | Initialize project |
-| `mdan attach` | Add MDAN to existing project |
-| `mdan phase` | Show/run phase |
-| `mdan mcp init` | Generate MCP config |
-| `mdan prompt list` | List prompts |
-| `mdan test` | Run tests |
-| `mdan evaluate` | Run evaluations |
+- [Better Agents Documentation](https://github.com/langwatch/better-agents)
+- [Scenario Testing](https://github.com/langwatch/scenario)
+- [LangWatch Documentation](https://docs.langwatch.ai)
+- [MCP Protocol](https://modelcontextprotocol.io)
 
 ---
 
-## Resources
+## 🤝 Contributing
+
+When contributing to MDAN:
 
-- [MDAN Documentation](https://github.com/khalilbenaz/MDAN)
-- [Better Agents](https://langwatch.ai/docs/better-agents)
-- [Agent Skills Standard](https://agentskills.io)
+1. Follow the agent structure defined above
+2. Include tests for all new agents
+3. Update documentation
+4. Follow code quality standards
+5. Get code review before merging
 
 ---
 
-*This file is auto-generated by MDAN. Edit with care.*
+**Last Updated:** 28 February 2026
+**Version:** 1.0.0