From b67d2a19d8f4cceae8c57004578e416c685ac618 Mon Sep 17 00:00:00 2001 From: George <31376482+george-gca@users.noreply.github.com> Date: Sat, 31 Jan 2026 19:52:26 -0300 Subject: [PATCH] Making Gemini and Claude configuration files point to AGENTS.md (#3494) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .gemini/settings.json | 14 ++++++ .github/GIT_WORKFLOW.md | 47 +++++++++++++++++++++ AGENTS.md | 94 ++++++++++++----------------------------- CLAUDE.md | 1 + 4 files changed, 90 insertions(+), 66 deletions(-) create mode 100644 .gemini/settings.json create mode 100644 .github/GIT_WORKFLOW.md create mode 100644 CLAUDE.md diff --git a/.gemini/settings.json b/.gemini/settings.json new file mode 100644 index 0000000..a01c594 --- /dev/null +++ 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 new file mode 100644 index 0000000..674db4a --- /dev/null +++ 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: + +``` +: + + +``` + +**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 index ba782a1..8b22fd6 100644 --- 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 +## Development Workflow -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 - -``` -: - - -``` - -**Types:** `feat` (feature), `fix` (bug), `docs` (docs), `style` (formatting), `config` (configuration), `chore` (maintenance) - -**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 +## Common Issues -The following files are automatically available to you in this agent context: +For troubleshooting, see: -- [`.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: - -- 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) - -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 new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md