base

AGENTS.md: A Guide for AI Assistants

Hello, AI assistant! This file is your guide to understanding and working with the base repository. Please read it carefully before making any changes.

Core Philosophy

The base repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are:

1. Code-Independent: The base template itself should not be tied to any specific programming language. The included Docker environment is based on Ubuntu and NGINX to be as generic as possible.

• Well-Documented: Every feature, configuration file, and workflow should have corresponding documentation in the /docs directory. The goal is to leave no part of the repository unexplained.
• Guidance over Prescription: For files like CONTRIBUTING.md or LICENSE, the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice.

1. Automation: The repository leverages GitHub Actions for CI, deployment, and releases to automate common developer tasks.

Repository Structure

This is a breakdown of the most important files and directories in this repository:

• .github/: Contains all GitHub-specific configurations.
  • workflows/: Houses the GitHub Actions workflows.
    • ci.yml: Lints configuration files for syntax and style.
    • pages.yml: Deploys the documentation to GitHub Pages.
    • release-on-tag.yml: Automates the creation of GitHub Releases from a git tag.
  • ISSUE_TEMPLATE/ & PULL_REQUEST_TEMPLATE.md: Templates for contributors.
  • RELEASE_TITLE.txt & RELEASE_BODY.md: User-editable files for customizing release notes.
  • SECURITY.md: A template for the user’s security policy.
• docs/: Contains all documentation for the project. The documentation is organized into namespaces.
  • docs/README.md: The main entry point for documentation, which serves as a Table of Contents.
  • docs/<namespace>.md: Each namespace has a top-level index file (e.g., docs/ai.md) that provides an overview and links to all the sub-pages within that namespace.
  • docs/<namespace>.<topic>.md: Individual documentation pages for specific topics within a namespace.
• docker/: Contains the development environment.
  • Dockerfile: Builds a generic Ubuntu + NGINX environment.
  • nginx.conf & html/index.html: A simple web server that acts as a health check.

• .devcontainer/: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud.

• Root Files:
  • AGENTS.md: This file!
  • README.md: The main entry point, which links to the documentation.
  • CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE: Standard community files, designed as templates for the end-user.
  • .gitignore, .editorconfig, .gitattributes, .prettierrc: Configuration files for git and code styling.
  • docker-compose.yml: Used to build and run the Docker-based development environment.
  • _config.yml: Configuration for the Jekyll build for GitHub Pages.

Guidelines for Modification

• Maintain the Philosophy: When adding or changing features, always adhere to the core principles, especially being code-independent.
• Update Documentation: If you change a feature, you must update its corresponding documentation in the docs/ directory. All documentation must follow these rules:
  1. Breadcrumb: The first line of every documentation file must be a clickable breadcrumb trail with correct relative links.
     • For docs/README.md: [base](../README.md) > docs
     • For docs/ai.md: [base](../README.md) > [docs](/base/) > ai
     • For docs/ai.prompting.md: [base](../../README.md) > [docs](../README.md) > [ai](./ai.md) > Prompting AI Agents
  2. in-dev Namespace: Any documentation that is a work-in-progress or not ready for general use should be placed in the in-dev namespace (e.g., docs/in-dev.my-draft.md). Files in this namespace are automatically excluded from all Tables of Contents.
  3. Dual TOC Structure: If you add a new, non-in-dev documentation file, you must add a link to it in two places:
     • The main Table of Contents in docs/README.md, under the appropriate namespace heading.
     • The namespace-specific index file, docs/<namespace>.md.
• Verify Your Work: After creating or modifying a file, use a read-only tool like read_file or ls to confirm your changes were applied correctly before marking a step as complete.

Thank you for your help in maintaining and improving this repository!

For Jules: Specific Instructions

As an advanced AI assistant, you have a unique responsibility to uphold the quality and philosophy of this repository. The following guidelines are tailored to you.

1. Onboarding & Planning

• Initial Read-Through: Always start by reading this file (AGENTS.md) and the main README.md in their entirety.
• Documentation-First Planning: Your plan must include steps for updating or creating documentation. For any change to a feature, identify and list the corresponding documentation file in docs/ that you will update. For a new feature, your plan must include a step to create a new, well-named file in docs/.

2. Upholding Core Philosophy

• Code-Independence: If a user asks you to add language-specific code (e.g., Python, JavaScript), you must first ask for clarification. Confirm if they intend to make the repository language-specific, as this is a deviation from the core philosophy. Propose language-agnostic solutions where possible (e.g., shell scripts, Docker configurations, GitHub Actions).
• Automation: When adding or modifying workflows in .github/workflows/, ensure your changes are robust and well-documented with comments within the YAML file itself.

3. Verification & Testing

• Use the CI: This repository has a ci.yml workflow that lints common configuration files. If you modify files like docker-compose.yml or GitHub Actions workflows, your plan should include a step to observe the CI run and ensure it passes.
• Targeted Testing: Since the repository is language-agnostic, your testing approach must be specific to the changes you make.
  • Docker Changes: If you modify docker/Dockerfile or docker-compose.yml, a step in your plan must be to run docker-compose build to ensure it builds successfully.
  • GitHub Actions: If you change a workflow file, your verification should involve checking the “Actions” tab on the repository to confirm the run was successful.

4. Submitting Your Work

• Run Prettier: Before requesting a review, run npx prettier --write . to ensure all files are formatted correctly.
• Mandatory Code Review: You must call request_code_review() before submitting any change.
• Descriptive Commit Messages: Your commit messages should be clear and follow conventions. The body of the message should explain why a change was made, not just what the change was.

This site is open source. Improve this page.