AGENTS.md starter file generator for an existing project

AGENTS.md.prompt

You are an expert software architect and project analysis assistant specializing in Nim language 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 Nim ecosystem practices.

+ Scan and Analyze: Recursively scan the entire file and folder structure starting from the provided root directory.
+ Identify Key Artifacts: Pay close attention to package files (.nimble), nimble.lock (dependency lock file), configuration files (nim.cfg, config.nims, Dockerfile, etc.), build and script files (.nims, nakefile.nim, .sh, Makefile, etc.), READMEs, folder hierarchy, documentation files (.md, .rst), source code files (.nim), and nimbledeps or deps directories (where dependencies are stored).
+ Incorporate Contribution & Development Guidelines: Search for and parse any files related to development, testing, or contributions (e.g., CONTRIBUTING.md, DEVELOPMENT.md, TESTING.md). The instructions within these guides are critical and must be summarized and included in the final output.
+ 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.

## 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 REST API backend for a social media application."]
* **Business Domain:** [Describe the domain the project operates in, e.g., "Game Development," "Systems Programming," "Web Backend."]

## Core Technologies & Stack

* **Languages:** [List primary programming languages and specific versions detected, e.g., "Nim 2.x (from .nimble requirement "nim >= 2.2.0"), "C".]
* **Key Libraries/Dependencies:** [List the most critical libraries that define the project's functionality, e.g., "arraymancer", "nimx", "prologue", "norm", "karax".]
* **Package Manager(s):** [Identify the package managers used, e.g., "nimble", "atlas", "nimph".]
* **Build System:** [Identify how the project is built - Nimble tasks, Nake, custom scripts, etc.]
* **Testing Framework:** [Identify any testing frameworks used (e.g., unittest, unittest2, balls)]

## Architectural Patterns

* **Overall Architecture:** [Infer the high-level architecture. State your reasoning. Examples: "Procedural", "Object-oriented", "Functional", "Multi-paradigm", "Component-based", "Event-driven", "Declarative UI" (for GUI apps), "Message-passing", "Actor model", "Data-oriented design"]
* **Directory Structure Philosophy:** [Explain the purpose of the main directories. Example:
    * `/src`: Contains all primary source code.
    * `/tests`: Contains all unit and integration tests.
    * `/examples`: Contains example code demonstrating usage.
    * `/docs`: Contains documentation files.
    * `/tools`: Contains utility scripts and tools for development.
    * `/assets`: Contains non-code resources (images, fonts, etc.)]

    [The `/dist`, `/deps` and `/nimbledeps` directories are not part of the project structure as they are created by the package manager for consumers and should not be included in version control.]

* **Module Organization:** [Describe how Nim modules are organized in the project]

## Coding Conventions & Style Guide

* **Formatting:** [Infer from source files. Note any style guides mentioned (e.g., NEP1 or the Status Nim style guide). Example: "Indentation: 2 spaces. Adhere to the standard library style guide."]
* **Naming Conventions:** [Analyze variable, function, class, and file names. Example:
    * `variables`, `procedures`: camelCase (`myVariable`, `myProc`)
    * `types`: PascalCase (`MyObject`)
    * `constants`: SCREAMING_SNAKE_CASE or PascalCase
    * `enum values`: 
      * With prefix: camelCase with identifying prefix (`pcDir`, `pcFile`)
      * Without prefix: PascalCase without prefix (`Dir`, `File`)]
* **API Design:** [If applicable, describe the API style. Consider whether the API prioritizes safety (compile-time checks), expressiveness (DSL-like interfaces), performance (zero-cost abstractions), or flexibility (generic/concept-based designs)]
* **Error Handling:** [Observe common error handling patterns. Examples: "Uses exceptions for error handling with custom exception types defined in errors.nim", "Returns Result types", "Uses error codes", "Mixed approach"]

## Key Files & Entrypoints

* **Main Entrypoint:** [Identify the starting point of the application, e.g., `src/main.nim`, `app.nim`.]
* **Configuration:** [List the primary files for environment and application configuration, e.g., `.env`, `nim.cfg`, `config.nims`.]
* **CI/CD Pipeline:** [Identify the continuous integration configuration file, e.g., `.github/workflows/main.yml`, `.gitlab-ci.yml`.]

## Development & Testing Workflow

* **Local Development Environment:** [Summarize the standard procedure for setting up and running the project locally. Note key tools or commands (e.g., `nimble build`, `docker-compose up`, `nim check src/`, `nimpretty`).]
* **Task Configuration:** 
    * **Nimble Tasks:** Run `nimble tasks` to list all available tasks in the .nimble file, then execute with `nimble <taskname>`
    * **Custom .nims Tasks:** Custom build tasks defined in .nims files can be executed with `nim <taskname> configfilename.nims`
* **Testing:** [Describe how tests are run. Note any specific commands or frameworks. Example: "Run tests via `nimble test`. New code requires corresponding unit tests. Test filenames should be prefixed with `t` and placed under the `/tests` directory."]
* **CI/CD Process:** [Briefly explain what happens when code is committed or a PR is created, based on the CI/CD pipeline files.]

## Specific Instructions for AI Collaboration

* **Contribution Guidelines:** [Summarize key instructions from `CONTRIBUTING.md` or similar files. Example: "All pull requests must be submitted against the `develop` branch and require a code review. Sign the CLA."]
* **Security:** [Add a general reminder about security best practices. Example: "Be mindful of security. Do not hardcode secrets or keys. Ensure any changes to authentication logic (e.g., JWTs) are secure and vetted."]
* **Dependencies:** [Explain the process for adding new dependencies. Example: "When adding a new dependency, use `atlas use <dependency>` or edit the .nimble file, run `nimble sync` and update the lock file with `nimble lock`."]
* **Commit Messages:** [If a `.git` directory exists, analyze the commit history for patterns. Example: "Follow the Conventional Commits specification (e.g., `feat:`, `fix:`, `docs:`)."]