Skip to content

Commit 7298b60

Browse files
attogramattogram
authored
Merge pull request #36 from attogram/reorganize-docs
Refactor documentation for updating and merging base
2 parents 9746f88 + c6a3841 commit 7298b60

35 files changed

Lines changed: 1505 additions & 534 deletions

‎AGENTS.md‎

Lines changed: 114 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,154 @@
11
# AGENTS.md: A Guide for AI Assistants
22

3-
Hello, AI assistant! This file is your guide to understanding and working with the `base` repository. Please read it carefully before making any changes.
3+
Hello, AI assistant!
4+
This file is your guide to understanding and working with the `base`
5+
repository.
6+
Please read it carefully before making any changes.
47

58
## Core Philosophy
69

7-
The `base` repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are:
10+
The `base` repository serves as a high-quality, professional, and
11+
language-agnostic template for creating new software projects.
12+
Its core principles are:
813

9-
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.
14+
1. **Code-Independent:** The `base` template itself should not be tied to any
15+
specific programming language.
16+
The included Docker environment is based on Ubuntu and NGINX to be as
17+
generic as possible.
1018

11-
- **Well-Documented:** Every feature, configuration file, and workflow should have corresponding documentation in the [`/docs`](./docs) directory. The goal is to leave no part of the repository unexplained.
12-
- **Guidance over Prescription:** For files like [`CONTRIBUTING.md`](./CONTRIBUTING.md) or [`LICENSE`](./LICENSE), the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice.
19+
- **Well-Documented:** Every feature, configuration file, and workflow should
20+
have corresponding documentation in the [`/docs`](./docs) directory.
21+
The goal is to leave no part of the repository unexplained.
22+
- **Guidance over Prescription:** For files like
23+
[`CONTRIBUTING.md`](./CONTRIBUTING.md) or [`LICENSE`](./LICENSE), the
24+
template provides sensible defaults and guides the end-user on how to
25+
customize them, rather than enforcing a single choice.
1326

14-
4. **Automation:** The repository leverages GitHub Actions for CI, deployment, and releases to automate common developer tasks.
27+
4. **Automation:** The repository leverages GitHub Actions for CI,
28+
deployment, and releases to automate common developer tasks.
1529

1630
## Repository Structure
1731

18-
This is a breakdown of the most important files and directories in this repository:
32+
This is a breakdown of the most important files and directories in this
33+
repository:
1934

2035
- **[`.github/`](./.github/)**: Contains all GitHub-specific configurations.
2136
- `workflows/`: Houses the GitHub Actions workflows.
22-
- [`ci.yml`](./.github/workflows/ci.yml): Lints configuration files for syntax and style.
23-
- [`pages.yml`](./.github/workflows/pages.yml): Deploys the documentation to GitHub Pages.
24-
- [`release-on-tag.yml`](./.github/workflows/release-on-tag.yml): Automates the creation of GitHub Releases from a git tag.
25-
- [`ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) & [`PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md): Templates for contributors.
26-
- [`RELEASE_TITLE.txt`](./.github/RELEASE_TITLE.txt) & [`RELEASE_BODY.md`](./.github/RELEASE_BODY.md): User-editable files for customizing release notes.
27-
- [`SECURITY.md`](./.github/SECURITY.md): A template for the user's security policy.
28-
29-
- **[`docs/`](./docs/)**: Contains all documentation for the project. Each major feature or component has its own corresponding `.md` file in this directory.
37+
- [`ci.yml`](./.github/workflows/ci.yml): Lints configuration files for
38+
syntax and style.
39+
- [`pages.yml`](./.github/workflows/pages.yml): Deploys the documentation
40+
to GitHub Pages.
41+
- [`release-on-tag.yml`](./.github/workflows/release-on-tag.yml):
42+
Automates the creation of GitHub Releases from a git tag.
43+
- [`ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) &
44+
[`PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md):
45+
Templates for contributors.
46+
- [`RELEASE_TITLE.txt`](./.github/RELEASE_TITLE.txt) &
47+
[`RELEASE_BODY.md`](./.github/RELEASE_BODY.md): User-editable files for
48+
customizing release notes.
49+
- [`SECURITY.md`](./.github/SECURITY.md): A template for the user's
50+
security policy.
51+
52+
- **[`docs/`](./docs/)**: Contains all documentation for the project.
53+
Each major feature or component has its own corresponding `.md` file in this
54+
directory.
3055

3156
- **[`docker/`](./docker/)**: Contains the development environment.
32-
- [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX environment.
33-
- [`nginx.conf`](./docker/nginx.conf) & [`html/index.html`](./docker/html/index.html): A simple web server that acts as a health check.
57+
- [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX
58+
environment.
59+
- [`nginx.conf`](./docker/nginx.conf) &
60+
[`html/index.html`](./docker/html/index.html): A simple web server that
61+
acts as a health check.
3462

35-
- **[`.devcontainer/`](./.devcontainer/)**: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud.
63+
- **[`.devcontainer/`](./.devcontainer/)**: Configuration for GitHub
64+
Codespaces, making it easy to spin up the development environment in the
65+
cloud.
3666

3767
- **Root Files**:
3868
- [`AGENTS.md`](./AGENTS.md): This file!
39-
- [`README.md`](./README.md): The main entry point, which links to the documentation.
40-
- [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), [`LICENSE`](./LICENSE): Standard community files, designed as templates for the end-user.
41-
- [`.gitignore`](./.gitignore), [`.editorconfig`](./.editorconfig), [`.gitattributes`](./.gitattributes), [`.prettierrc`](./.prettierrc): Configuration files for git and code styling.
42-
- [`docker-compose.yml`](./docker-compose.yml): Used to build and run the Docker-based development environment.
43-
- [`render.yaml`](./render.yaml): Infrastructure-as-code for deploying the application to Render.com.
44-
- [`_config.yml`](./_config.yml): Configuration for the Jekyll build for GitHub Pages.
69+
- [`README.md`](./README.md): The main entry point, which links to the
70+
documentation.
71+
- [`CONTRIBUTING.md`](./CONTRIBUTING.md),
72+
[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), [`LICENSE`](./LICENSE):
73+
Standard community files, designed as templates for the end-user.
74+
- [`.gitignore`](./.gitignore), [`.editorconfig`](./.editorconfig),
75+
[`.gitattributes`](./.gitattributes), [`.prettierrc`](./.prettierrc):
76+
Configuration files for git and code styling.
77+
- [`docker-compose.yml`](./docker-compose.yml): Used to build and run the
78+
Docker-based development environment.
79+
- [`render.yaml`](./render.yaml): Infrastructure-as-code for deploying the
80+
application to Render.com.
81+
- [`_config.yml`](./_config.yml): Configuration for the Jekyll build for
82+
GitHub Pages.
4583

4684
## Guidelines for Modification
4785

48-
- **Maintain the Philosophy:** When adding or changing features, always adhere to the core principles, especially being code-independent.
49-
- **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the [`docs/`](./docs/) directory. If you add a new feature, you **must** create a new documentation file for it.
50-
- **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.
86+
- **Maintain the Philosophy:** When adding or changing features, always adhere
87+
to the core principles, especially being code-independent.
88+
- **Update Documentation:** If you change a feature, you **must** update its
89+
corresponding documentation in the [`docs/`](./docs/) directory.
90+
If you add a new feature, you **must** create a new documentation file for
91+
it.
92+
- **Verify Your Work:** After creating or modifying a file, use a read-only
93+
tool like `read_file` or `ls` to confirm your changes were applied
94+
correctly before marking a step as complete.
5195

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

5498
## For Jules: Specific Instructions
5599

56-
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.
100+
As an advanced AI assistant, you have a unique responsibility to uphold the
101+
quality and philosophy of this repository.
102+
The following guidelines are tailored to you.
57103

58104
### 1. Onboarding & Planning
59105

60-
- **Initial Read-Through:** Always start by reading this file ([`AGENTS.md`](./AGENTS.md)) and the main [`README.md`](./README.md) in their entirety.
61-
- **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/`](./docs) that you will update. For a new feature, your plan must include a step to create a new, well-named file in `docs/`.
106+
- **Initial Read-Through:** Always start by reading this file
107+
([`AGENTS.md`](./AGENTS.md)) and the main [`README.md`](./README.md) in
108+
their entirety.
109+
- **Documentation-First Planning:** Your plan **must** include steps for
110+
updating or creating documentation.
111+
For any change to a feature, identify and list the corresponding
112+
documentation file in [`docs/`](./docs) that you will update.
113+
For a new feature, your plan must include a step to create a new,
114+
well-named file in `docs/`.
62115

63116
### 2. Upholding Core Philosophy
64117

65-
- **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).
66-
- **Automation:** When adding or modifying workflows in [`.github/workflows/`](./.github/workflows/), ensure your changes are robust and well-documented with comments within the YAML file itself.
118+
- **Code-Independence:** If a user asks you to add language-specific code
119+
(e.g., Python, JavaScript), you must first ask for clarification.
120+
Confirm if they intend to make the repository language-specific, as this is
121+
a deviation from the core philosophy.
122+
Propose language-agnostic solutions where possible (e.g., shell scripts,
123+
Docker configurations, GitHub Actions).
124+
- **Automation:** When adding or modifying workflows in
125+
[`.github/workflows/`](./.github/workflows/), ensure your changes are robust
126+
and well-documented with comments within the YAML file itself.
67127

68128
### 3. Verification & Testing
69129

70-
- **Use the CI:** This repository has a [`ci.yml`](./.github/workflows/ci.yml) workflow that lints common configuration files. If you modify files like [`docker-compose.yml`](./docker-compose.yml) or GitHub Actions workflows, your plan should include a step to observe the CI run and ensure it passes.
71-
- **Targeted Testing:** Since the repository is language-agnostic, your testing approach must be specific to the changes you make.
72-
- **Docker Changes:** If you modify [`docker/Dockerfile`](./docker/Dockerfile) or [`docker-compose.yml`](./docker-compose.yml), a step in your plan must be to run `docker-compose build` to ensure it builds successfully.
73-
- **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.
130+
- **Use the CI:** This repository has a
131+
[`ci.yml`](./.github/workflows/ci.yml) workflow that lints common
132+
configuration files.
133+
If you modify files like [`docker-compose.yml`](./docker-compose.yml) or
134+
GitHub Actions workflows, your plan should include a step to observe the CI
135+
run and ensure it passes.
136+
- **Targeted Testing:** Since the repository is language-agnostic, your
137+
testing approach must be specific to the changes you make.
138+
- **Docker Changes:** If you modify [`docker/Dockerfile`](./docker/Dockerfile)
139+
or [`docker-compose.yml`](./docker-compose.yml), a step in your plan must
140+
be to run `docker-compose build` to ensure it builds successfully.
141+
- **GitHub Actions:** If you change a workflow file, your verification
142+
should involve checking the "Actions" tab on the repository to confirm the
143+
run was successful.
74144

75145
### 4. Submitting Your Work
76146

77-
- **Run Prettier:** Before requesting a review, run `npx prettier --write .` to ensure all files are formatted correctly.
78-
- **Mandatory Code Review:** You **must** call `request_code_review()` before submitting any change.
79-
- **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.
147+
- **Run Prettier:** Before requesting a review, run `npx prettier --write .`
148+
to ensure all files are formatted correctly.
149+
- **Mandatory Code Review:** You **must** call `request_code_review()` before
150+
submitting any change.
151+
- **Descriptive Commit Messages:** Your commit messages should be clear and
152+
follow conventions.
153+
The body of the message should explain _why_ a change was made, not just
154+
_what_ the change was.

‎docs/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@ This directory contains the documentation for the `base` project.
3030

3131
- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development.
3232
- [Docker Environment](./development.docker.md) - Using the included Docker setup.
33-
- [Merging `base`](./development.merging-base.md) - Incorporating `base` into an existing project.
3433
- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files.
3534
- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier.
3635
- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code.
@@ -43,6 +42,11 @@ This directory contains the documentation for the `base` project.
4342

4443
- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.
4544

45+
## Updating
46+
47+
- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template.
48+
- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it.
49+
4650
## Project Management
4751

4852
- [Repository Badges](./project.badges.md) - How to use and create repository badges.

‎docs/ai.agents-md.md‎

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,48 @@
11
# Guiding AI with `AGENTS.md`
22

3-
The `AGENTS.md` file is a special document within this repository designed to be a direct line of communication between you (the user) and any AI agent or assistant working on your project. Think of it as a set of permanent instructions or a "cheat sheet" for the AI.
3+
The `AGENTS.md` file is a special document within this repository designed to
4+
be a direct line of communication between you (the user) and any AI agent or
5+
assistant working on your project.
6+
Think of it as a set of permanent instructions or a "cheat sheet" for the AI.
47

58
## What is its Purpose?
69

7-
While you can give an AI instructions in a prompt, those instructions are temporary and specific to that one conversation. The `AGENTS.md` file provides a persistent set of rules and guidelines that the AI can refer to at any time.
10+
While you can give an AI instructions in a prompt, those instructions are
11+
temporary and specific to that one conversation.
12+
The `AGENTS.md` file provides a persistent set of rules and guidelines that
13+
the AI can refer to at any time.
814

915
This is particularly useful for establishing:
1016

1117
- **Coding Standards:** "Always use tabs, not spaces."
12-
- **Architectural Rules:** "All new components must be registered in the main application file."
13-
- **Testing Requirements:** "Every new function must be accompanied by a unit test."
14-
- **Repository-Specific Information:** "The `api/` directory is auto-generated, do not edit it directly."
18+
- **Architectural Rules:** "All new components must be registered in the main
19+
application file."
20+
- **Testing Requirements:** "Every new function must be accompanied by a unit
21+
test."
22+
- **Repository-Specific Information:** "The `api/` directory is
23+
auto-generated, do not edit it directly."
1524

1625
## How to Use and Modify It
1726

18-
The `AGENTS.md` file is written in simple Markdown. You can edit it just like any other text file.
27+
The `AGENTS.md` file is written in simple Markdown.
28+
You can edit it just like any other text file.
1929

2030
### Best Practices
2131

22-
1. **Be Clear and Direct:** Write instructions as if you are speaking directly to the AI. Use clear, unambiguous language.
23-
2. **Use Markdown for Structure:** Use headings, bullet points, and code blocks to keep the document organized and easy for the AI to parse.
24-
3. **Keep It Updated:** As your project evolves, so should your `AGENTS.md` file. If you change your architecture or coding standards, update the file to reflect those changes.
25-
4. **Reference It in Your Prompts:** For best results, remind the AI to look for and follow the instructions in your `AGENTS.md` file as part of your initial prompt. The `prompting-ai-agents.md` guide provides examples of how to do this.
26-
27-
By maintaining a well-structured `AGENTS.md` file, you can significantly improve the quality and consistency of the work done by AI agents on your project, reducing the need for corrections and rework.
32+
1. **Be Clear and Direct:** Write instructions as if you are speaking
33+
directly to the AI.
34+
Use clear, unambiguous language.
35+
2. **Use Markdown for Structure:** Use headings, bullet points, and code
36+
blocks to keep the document organized and easy for the AI to parse.
37+
3. **Keep It Updated:** As your project evolves, so should your `AGENTS.md`
38+
file.
39+
If you change your architecture or coding standards, update the file to
40+
reflect those changes.
41+
4. **Reference It in Your Prompts:** For best results, remind the AI to look
42+
for and follow the instructions in your `AGENTS.md` file as part of your
43+
initial prompt.
44+
The `prompting-ai-agents.md` guide provides examples of how to do this.
45+
46+
By maintaining a well-structured `AGENTS.md` file, you can significantly
47+
improve the quality and consistency of the work done by AI agents on your
48+
project, reducing the need for corrections and rework.

0 commit comments

Comments
 (0)