prowler-studio AGENTS.md

Agent Development Guide

This document covers the architecture of Prowler Studio and the coding standards for developing its agents. Read System Architecture to understand how the pieces fit together; read the development best practices that follow before adding or modifying an agent.

Table of Contents

System Architecture

• Overview
• Project Structure
• Agents
• ChecKreatorAgent Flow
• Shared Tools
• Logging & Observability
• Main CLI Orchestration
• Adding a New Agent

Development Best Practices

• Architecture Principles
• Code Organization
• Method Decomposition
• Type Safety
• Named Parameters
• Return Types with Pydantic
• Constants Management
• File Structure
• Examples
• Checklist for New Agents

---

System Architecture

Overview

Prowler Studio uses the Claude Agent SDK to automate the creation of security checks for Prowler. The architecture separates each task (implementation, testing, compliance mapping, review, PR creation) into an independent agent. Agents run sequentially, with built-in verification and error-correction loops between them.

Project Structure

prowler_studio/
├── src/
│   ├── core/
│   │   ├── main.py              # CLI entry point
│   │   └── exceptions.py        # Custom exceptions
│   ├── agents/
│   │   ├── base.py              # Agent base class
│   │   ├── implementation/      # ChecKreatorAgent for check creation
│   │   │   ├── agent.py         # Main agent implementation
│   │   │   ├── models.py        # Data models
│   │   │   └── prompts/         # Jinja2 prompt templates
│   │   ├── testing/             # TestingAgent for test generation
│   │   ├── review/              # ReviewAgent for code review
│   │   ├── compliance_mapping/  # ComplianceMappingAgent
│   │   └── pr_creation/         # PRCreationAgent for PR workflow
│   ├── tools/                   # Shared tools
│   │   ├── git.py               # Git operations and worktree management
│   │   ├── prowler.py           # Prowler-specific tools
│   │   ├── skills.py            # AI skills setup
│   │   ├── jira.py              # Jira URL parsing
│   │   ├── jira_client.py       # Jira API client
│   │   ├── github_issue.py      # GitHub issue URL parsing
│   │   ├── github_client.py     # GitHub REST API client
│   │   └── models.py            # Tool data models
│   └── utils/                   # Utilities
│       ├── prompts.py           # Prompt loading utilities
│       └── logging.py           # Logging utilities (agent output + tool calls)
└── pyproject.toml               # Project configuration