Making Gemini and Claude configuration files point to AGENTS.md (#3494)

george-gca · Copilot · web-flow · commit b67d2a19d8f4 · 2026-01-31T19:52:26.000-03:00
This pull request updates project documentation to clarify and
standardize the development workflow, Git practices, and troubleshooting
resources. The main changes include adding a dedicated Git workflow
guide and reorganizing the `AGENTS.md` file for better clarity and
usability.

**Documentation and Workflow Improvements:**

* Added a new `.github/GIT_WORKFLOW.md` file detailing commit message
conventions, types, and best practices for staging and ignoring files.
* Reorganized and clarified the pre-commit checklist and local
development instructions in `AGENTS.md`, emphasizing Docker usage and
proper code formatting.
* Updated the section on configuration and troubleshooting in
`AGENTS.md` to better direct users to relevant resources and removed
redundant or outdated instructions.
[[1]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L57-R58)
[[2]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L100-R74)

**Configuration and Context Updates:**

* Added a `.gemini/settings.json` file to define context files for
Gemini agent operations, ensuring relevant documentation is available
for automation tools.
* Created `CLAUDE.md` file pointing to `AGENTS.md`.

---------

Signed-off-by: George Araújo &lt;george.gcac@gmail.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/.gemini/settings.json b/.gemini/settings.json
@@ -0,0 +1,14 @@
+{
+  "context": [
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+    ".github/agents/customize.agent.md",
+    ".github/agents/docs.agent.md",
+    ".github/instructions/**/*.md",
+    "CUSTOMIZE.md",
+    "INSTALL.md",
+    "TROUBLESHOOTING.md",
+    "QUICKSTART.md",
+    "README.md"
+  ]
+}
diff --git a/.github/GIT_WORKFLOW.md b/.github/GIT_WORKFLOW.md
@@ -0,0 +1,47 @@
+# Git Workflow
+
+This document outlines the conventions for using Git and writing commit messages in this project.
+
+## Commit Message Format
+
+All commit messages should follow this format:
+
+```
+<type>: <subject>
+
+<body (optional)>
+```
+
+**Types:**
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
+- `config`: Changes to configuration files
+- `chore`: Changes to the build process or auxiliary tools and libraries
+
+**Examples:**
+
+```
+feat: Add dark mode toggle button to header
+fix: Correct baseurl in project site configuration
+docs: Update INSTALL.md with Docker troubleshooting
+style: Format all Liquid templates with Prettier
+config: Enable blog section in _config.yml
+chore: Update Jekyll dependencies with bundle update --all
+```
+
+## Staging Changes
+
+**Always `git add` files explicitly.** Do not stage everything with `git add .` unless you are certain of what's being committed. Check `git status` first to review your changes.
+
+## What NOT to Commit
+
+**Always obey the project's [`.gitignore`](../.gitignore) file.** It prevents the accidental commit of:
+
+- Build outputs (`_site/`, `.jekyll-cache/`)
+- Dependencies (`node_modules/`, `vendor/`)
+- OS-specific files (`.DS_store`)
+- Editor temporary files (`.idea/`, `.swp`, `.swo`)
+- Secrets and API keys (never commit credentials)
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,6 @@
 # Agent Guidelines for al-folio
 
-This is a hub for AI agents and automation tools working with the al-folio repository. It directs you to specialized resources by role and task type.
+A simple, clean, and responsive Jekyll theme for academics.
 
 ## Quick Links by Role
 
@@ -16,35 +16,40 @@ This is a hub for AI agents and automation tools working with the al-folio repos
 
 ### Local Development (Docker)
 
+The recommended approach is using Docker.
+
 ```bash
 # Initial setup & start dev server
 docker compose pull && docker compose up
 # Site runs at http://localhost:8080
 
-# Rebuild with updated dependencies
+# Rebuild after changing dependencies or Dockerfile
 docker compose up --build
 
-# Stop containers
+# Stop containers and free port 8080
 docker compose down
 ```
 
 ### Pre-Commit Checklist
 
-```bash
-# 1. Format code
-npm install --save-dev prettier @shopify/prettier-plugin-liquid  # (first time only)
-npx prettier . --write
+Before every commit, you **must** run these steps:
 
-# 2. Build locally
-docker compose up --build
+1.  **Format Code:**
+    ```bash
+    # (First time only)
+    npm install --save-dev prettier @shopify/prettier-plugin-liquid
+    # Format all files
+    npx prettier . --write
+    ```
+2.  **Build Locally & Verify:**
 
-# 3. Verify site
-# → Visit http://localhost:8080 and check navigation, pages, images, dark mode
+    ```bash
+    # Rebuild the site
+    docker compose up --build
 
-# 4. Commit with clear message
-git add .
-git commit -m "type: description"  # See "Commit Format" below
-```
+    # Verify by visiting http://localhost:8080.
+    # Check navigation, pages, images, and dark mode.
+    ```
 
 ## Critical Configuration
 
@@ -54,40 +59,10 @@ When modifying `_config.yml`, these **must be updated together**:
 - **Project site:** `url: https://username.github.io` + `baseurl: /repo-name/`
 - **YAML errors:** Quote strings with special characters: `title: "My: Cool Site"`
 
-## Common Issues
-
-For troubleshooting common build, deployment, and configuration issues, see:
-
-- [Common Pitfalls & Workarounds](https://github.com/alshedivat/al-folio/blob/master/.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md
-- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions
-- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) to search for your specific problem
-
-## Commit Format
-
-```
-<type>: <subject>
-
-<body (optional)>
-```
-
-**Types:** `feat` (feature), `fix` (bug), `docs` (docs), `style` (formatting), `config` (configuration), `chore` (maintenance)
+## Development Workflow
 
-**Examples:**
-
-```
-feat: Add dark mode toggle button to header
-fix: Correct baseurl in project site configuration
-docs: Update INSTALL.md with Docker troubleshooting
-style: Format all Liquid templates with Prettier
-config: Enable blog section in _config.yml
-chore: Update Jekyll dependencies with bundle update --all
-```
-
-**Always git add explicitly** – Do not stage everything with `git add .` unless you're certain of what's being committed. Check `git status` first.
-
-## Code-Specific Instructions
-
-Always consult the relevant instruction file for your code type:
+- **Git & Commits:** For commit message format and Git practices, see [.github/GIT_WORKFLOW.md](.github/GIT_WORKFLOW.md).
+- **Code-Specific Instructions:** Consult the relevant instruction file for your code type.
 
 | File Type                                     | Instruction File                                                                                |
 | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -97,23 +72,10 @@ Always consult the relevant instruction file for your code type:
 | Liquid templates (`_includes/`, `_layouts/`)  | [liquid-templates.instructions.md](.github/instructions/liquid-templates.instructions.md)       |
 | JavaScript (`_scripts/`)                      | [javascript-scripts.instructions.md](.github/instructions/javascript-scripts.instructions.md)   |
 
-## Auto-Loaded Context
-
-The following files are automatically available to you in this agent context:
-
-- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) – Primary technical reference
-- [`.github/instructions/*.md`](.github/instructions/) – Code-specific instruction files (loaded when editing relevant file types)
-
-Other files need to be accessed explicitly.
-
-## What NOT to Commit
-
-**Always obey [`.gitignore`](.gitignore).** It prevents accidental commits of:
+## Common Issues
 
-- Build outputs (`_site/`, `.jekyll-cache/`, etc.)
-- Dependencies (`node_modules/`, `Gemfile.lock`, `vendor/`)
-- OS files (`.DS_store`)
-- Editor temp files (`.idea/`, `.swp`, `.swo`)
-- Secrets and API keys (never commit credentials)
+For troubleshooting, see:
 
-If you create new files, ensure they follow the patterns in `.gitignore`.
+- [Common Pitfalls & Workarounds](.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions
+- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) to search for your specific problem.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
