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.

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 package files (`.nimble`), dependency lock files (`nimble.lock`), 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 CI/CD pipeline definitions (`.github/workflows/*.yml`).
3. 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.
4. 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 Nim wrapper for a C library.", "Web backend service", "CLI tool for data processing"]
* **Business Domain:** [Describe the domain the project operates in, e.g., "Game Development", "Systems Programming", "Web Backend."]

## 2. Core Technologies & Stack

* **Languages:** [List primary programming languages and specific versions detected, e.g., "Nim (version 2.0.0 or higher)", "C for bindings".]
* **Frameworks & Runtimes:** [List any core frameworks or runtimes that are central to the project, e.g., "SDL2", "OpenGL", "Node.js".]
* **Databases:** [Identify the database systems used, e.g., "PostgreSQL," "Redis for caching," "MongoDB."]
* **Key Libraries/Dependencies:** [List the most critical libraries that define the project's functionality. Infer from the `.nimble` file and imports.]
* **Platforms:** [List target platforms if specified in documentation or CI/CD configurations, e.g., "Windows, Linux, macOS, WebAssembly."]
* **Package Manager:** [Identify the package manager used, e.g., "nimble".]

## 3. Architectural Patterns

* **Overall Architecture:** [Infer the high-level architecture. State your reasoning. Examples: "Language binding library," "Monolithic web service," "Component-based UI framework," "Data-oriented design."]
* **Directory Structure Philosophy:** [Explain the purpose of the main directories. Example:
    * `/src`: Contains all primary Nim source code.
    * `/tests`: Contains all unit and integration tests.
    * `/tools`: Contains utility scripts and tools for development.]
    * [Add other first-level directories with brief purpose (e.g., /examples, /assets). Exclude consumer-only package manager dirs like /dist, /deps, /nimbledeps.]
* **Module Organization:** [Describe how Nim modules are organized in the project]

## 4. Coding Conventions & Style Guide

* **Formatting:** [Infer from source files. Note any style guides mentioned (e.g., NEP1 or the Status Nim style guide). Example: "Follows Nim's standard style conventions. Use 2-space indentation."]
* **Naming Conventions:** [Analyze variable, function, class, and file names. Example:
    * Variables, procedures: camelCase (`myVariable`, `myProc`)
    * Types: PascalCase (`MyObject`)
    * Constants: SCREAMING_SNAKE_CASE or PascalCase (`MaxBufferSize`)
    * Enum values: [State convention; camelCase with identifying prefix (`pcDir`) or PascalCase without prefix (Dir)]
    * Files: snake_case (`my_module.nim`)]
* **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).
    * **Trade-offs:** Does the API prioritize performance (e.g., `{.noInit.}`, zero-cost abstractions), safety (e.g., `not nil` annotations, concepts), or developer ergonomics (e.g., DSLs, syntactic sugar)?]
* **Common Patterns & Idioms:** [Identify recurring Nim-specific patterns in the codebase to understand the project's preferred style.
    * **Metaprogramming:** Is there significant use of `templates` or `macros` to create DSLs or reduce boilerplate?
    * **Memory Management:** Reliance on stdlib collections (`seq`/`string`) and GC-managed `ref` types, or focus on custom containers with destructors?
    * **Polymorphism:** Preference for compile-time polymorphism (generics, concepts) or runtime polymorphism (method dispatch, object variants with `case` statements)?
    * **Type Safety:** How is Nim's type system used for correctness? (e.g., `distinct` types for units, `range` types for constrained integers, `not nil` annotations).
    * **Concurrency:** What is the preferred model for concurrency, if any? (`spawn` for threads, `async/await`, channels).]
* **Error Handling:** [Observe common error handling patterns. Examples: "Uses Nim's exception system with custom `Error` types", "Returns `Result` types or options", "Uses `assert` for precondition checking."]

## 5. 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., `nim.cfg`, `config.nims`.]
* **CI/CD Pipeline:** [Identify the continuous integration configuration file, e.g., `.github/workflows/main.yml`, `.gitlab-ci.yml`.]

## 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:
    * **Install Nim**
      ```bash
      wget https://codeberg.org/janAkali/grabnim/raw/branch/master/misc/install.sh
      sh install.sh
      grabnim
      ```
    * **Setting up the project**
      1. Run `nimble develop <projectname>` to clone the repository
      2. Run `nimble check` to verify setup
      3. Run `nimble lock` to generate a package lock file]
* **Task Configuration:** 
    * **Nimble Tasks:** Run `nimble tasks` to list all available tasks in the .nimble file, then execute with `nimble <taskname>`
    * **Custom .nims Tasks:** 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.]

## 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. Submit pull requests against the `main` branch."]
* **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 `atlas use <dependency>` or edit the .nimble file, 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:`)."]