souschef copilot-instructions.md

SousChef Project - GitHub Copilot Instructions

Project Overview

SousChef is an AI-powered MCP (Model Context Protocol) server that assists with converting Chef cookbooks to Ansible playbooks.

Specialised Agents

For focused expertise on specific tasks, refer to AGENTS.md which defines specialised agents:

• Test Coverage Guardian: Achieve 100% coverage with best-in-class testing
• Quality Enforcer: Zero warnings from ruff, mypy, Pylance
• Architecture Reviewer: Ensure code follows modular structure
• TDD Coach: Guide test-driven development
• Migration Specialist: Chef-to-Ansible conversion expertise
• Documentation Maintainer: Keep docs accurate and current
• Performance Optimiser: Profile and optimise bottlenecks

Invoke agents with: @AgentName [task description]

Project Architecture

Module Structure

The project follows a 7-layer modular architecture with strict dependency discipline:

souschef/
├── __init__.py          # Package initialization
├── server.py            # MCP server entry point (Layer 7)
├── cli.py               # Command-line interface (Layer 7)
├── ui/                  # Web interface (Layer 7)
├── orchestrators/       # Workflow coordination (Layer 6)
├── assessment.py        # Migration planning (Layer 6)
├── deployment.py        # AWX/Tower deployment (Layer 6)
├── api/                 # REST API endpoints (Layer 5)
├── integrations/        # External integrations (Layer 5)
│   └── github/          # GitHub integration
├── auth/                # Authentication & RBAC (Layer 4)
├── audit/               # Audit logging (Layer 4)
├── benchmarking/        # Performance profiling (Layer 4)
├── parsers/             # Input parsing (Layer 3)
│   ├── attributes.py    # Chef attribute parsing
│   ├── habitat.py       # Habitat plan parsing
│   ├── inspec.py        # InSpec profile parsing
│   ├── metadata.py      # Cookbook metadata parsing
│   ├── recipe.py        # Recipe parsing
│   ├── resource.py      # Custom resource parsing
│   └── template.py      # ERB template parsing
├── converters/          # Transformations (Layer 3)
│   ├── habitat.py       # Habitat to Docker
│   ├── playbook.py      # Recipe to playbook
│   └── resource.py      # Resource to task
├── generators/          # Output generation (Layer 3)
├── storage/             # Data persistence (Layer 2)
├── filesystem/          # File operations (Layer 2)
├── ir/                  # Intermediate representation (Layer 2)
└── core/                # Foundation utilities (Layer 1)
    ├── constants.py     # Shared constants
    ├── errors.py        # Custom exceptions
    ├── path_utils.py    # Path normalization
    ├── ruby_utils.py    # Ruby value parsing
    └── validation.py    # Validation helpers