Craft CMS Brown Field AGENTS.md Generator

craftcms-brow-field-agent-generator.md

You are an expert software architect and project analysis assistant specializing in Craft CMS projects. Analyze the current project directory recursively and generate a comprehensive AGENTS.md file. This file will serve as a foundational context guide for any future AI model, like yourself, that interacts with this project. The goal is to ensure that future AI-generated code, analysis, and modifications are consistent with the project's established standards, architecture, and Craft CMS framework best practices.

1. Scan and Analyze: Recursively scan the entire file and folder structure starting from the provided root directory.
2. Identify Key Artifacts: Pay close attention to Craft CMS-specific components such as:
   • Configurations: Inside the config/ directory.
   • Modules: Inside the modules/ directory.
   • Plugins: Custom plugins, if any, inside the plugins/ directory.
   • Templates: Twig templates inside the templates/ directory.
   • composer.json for third-party plugins and dependencies.
   • Environment Settings: .env files for environment-specific configurations.
3. Infer Standards: Do not just list files. You must infer the project's implicit and explicit standards from its structure and code.

Output a single, well-formatted Markdown file named AGENTS.md. The content of this file must be structured according to the following template. Populate each section based on your analysis. If you cannot confidently determine the information for a section, state that it is inferred and note your confidence level, or suggest it as an area for the human developer to complete.

FILE STRUCTURE TO GENERATE:

AGENTS.md: AI Collaboration Guide

This document provides essential context for AI models interacting with this project. Adhering to these guidelines will ensure consistency and maintain code quality.

1. Project Overview & Purpose

• Primary Goal: [Analyze the README.md, documentation, and folder names to infer and summarize the project's main purpose and what it's designed to do. For example: "This is a Craft CMS project for Client"]
• Business Domain: [Describe the domain the project operates in, e.g., "Web Backend, E-commerce, Content Management, etc."]

2. Core Technologies & Stack

• Languages: [List primary programming languages and specific versions detected, e.g., "PHP 8.3, Twig"]
• Frameworks & Runtimes: [List any core frameworks or runtimes that are central to the project, e.g., "Craft CMS", "Alpine.js", "Node.js".]
• Databases: [Identify the database systems used, e.g., "MySQL", "Redis for caching"]
• Key Libraries/Plugins/Dependencies: [List the most critical libraries and plugins that define the project's functionality. Infer from the require section of composer.json and dependencies in package.json if present.]
• Environment Management: [Note any environment management tools or practices, e.g., "Dotenv for environment variables".]

3. Architectural Patterns

• Overall Architecture: [Infer the high-level architecture. State your reasoning. Examples: "Modular MVC architecture typical of Craft CMS projects", "Service-oriented architecture inferred from the presence of multiple modules/plugins".]
• Directory Structure Philosophy: [Explain the purpose of the main directories. Example:
  • config/: Configuration files for Craft CMS and custom settings.
  • modules/: Custom modules that extend Craft CMS functionality.
  • plugins/: Local copies of third-party or custom plugins for Craft CMS.
  • templates/: Twig templates for the front-end presentation layer.
  • src/: Frontend source files, including JavaScript, stylesheets, fonts, images, etc.
  • tests/: Automated tests for ensuring code quality and functionality.
  • web/: Public web root containing entry points like index.php.
  • [Add other first-level directories with brief purpose (e.g., /examples, /assets). Exclude consumer-only package manager dirs like /vendor, /node_modules, etc.]

4. Coding Conventions & Style Guide

• Formatting: [Infer from source files. Note any style guides mentioned in documentation or comments. Examples: "PSR-12 for PHP", "Twig coding standards", "Use 2-space indentation.".]
• Naming Conventions: [Analyze variable, function, class, and file names. Example:
  • Variables, procedures: camelCase (myVariable, myProc)
  • Classes, Types: PascalCase (MyClass, MyType)
  • Constants: UPPER_SNAKE_CASE (MY_CONSTANT)
  • Files: kebab-case (my-file.php)]
• API Design: [Describe the high-level principles of the public-facing API.
  • Style: Is the API primarily procedural, object-oriented, functional, or a mix? Does it use a fluent interface (method chaining)?
  • Abstraction: Does the API hide implementation details effectively? What are the core abstractions it exposes to the user?
  • Extensibility: How is the API designed to be extended? (e.g., through user-defined types that satisfy a concept, by passing procedures, or through inheritance).
• Common Patterns & Idioms: [Identify recurring Craft CMS-specific patterns or idioms in the codebase to understand the project's preferred style.
  • Polymorphism: Use of interfaces and abstract classes to define common behaviors across different modules/plugins.
  • Dependency Injection: Use of service containers to manage dependencies.
  • Event-Driven Architecture: Use of events and listeners to decouple components.
  • Type Safety: Use of type hints and strict typing in PHP code.
  • Concurrency: Use of queues and background jobs for handling asynchronous tasks.
• Error Handling: [Observe common error handling patterns. Examples: "Uses try-catch blocks extensively", "Custom error pages defined in templates".]

5. Key Files & Entrypoints

• Main Entrypoint: [Identify the primary entry point for the application, e.g., web/index.php.]
• Configuration: [List the primary files for environment and application configuration, e.g., config/general.php, config/app.php, config/routes.php, .env, etc.]
• CI/CD Pipeline: [Identify the continuous integration configuration file, e.g., .github/workflows/main.yml, Jenkinsfile, etc.]

6. Development & Testing Workflow

• Local Development Environment: [Summarize the standard procedure for setting up and running the project locally. Note key tools or commands from docs. For example:
  • Start Local Development:

    cog up

  • Build frontend assets:

    cog fe build -p

• Testing: [Describe how tests are run. Note any specific commands or frameworks. Example:
  • Run tests via Pest for Craft CMS:

    cog test

7. Specific Instructions for AI Collaboration

• Contribution Guidelines: [Summarize key instructions from CONTRIBUTING.md or similar files. Example: "Follow the existing code style. Ensure all new functionality is tested."]
• Security: [Add a general reminder about security best practices. Example: "Be mindful of security when handling file I/O and external resources. Do not hardcode secrets or keys."]
• Dependencies: [Explain the process for adding new dependencies. Example: "When adding a new dependency, use cog shell web composer require vendor/package to ensure compatibility."]