florent/pages
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
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 <george.gcac@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
George 2026-01-31 19:52:26 -03:00 committed by GitHub
parent d86331af3c
commit b67d2a19d8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 90 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.gemini/settings.json Normal file
View File

@ -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"
]
}

47
.github/GIT_WORKFLOW.md vendored Normal file
View File

@ -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)

94
AGENTS.md
View File

@ -1,6 +1,6 @@
# Agent Guidelines for al-folio # 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 ## 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) ### Local Development (Docker)
The recommended approach is using Docker.
```bash ```bash
# Initial setup & start dev server # Initial setup & start dev server
docker compose pull && docker compose up docker compose pull && docker compose up
# Site runs at http://localhost:8080 # Site runs at http://localhost:8080
# Rebuild with updated dependencies # Rebuild after changing dependencies or Dockerfile
docker compose up --build docker compose up --build
# Stop containers # Stop containers and free port 8080
docker compose down docker compose down
``` ```
### Pre-Commit Checklist ### Pre-Commit Checklist
```bash Before every commit, you **must** run these steps:
# 1. Format code
npm install --save-dev prettier @shopify/prettier-plugin-liquid # (first time only)
npx prettier . --write
# 2. Build locally 1. **Format Code:**
docker compose up --build ```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 ```bash
# → Visit http://localhost:8080 and check navigation, pages, images, dark mode # Rebuild the site
docker compose up --build
# 4. Commit with clear message # Verify by visiting http://localhost:8080.
git add . # Check navigation, pages, images, and dark mode.
git commit -m "type: description" # See "Commit Format" below ```
```
## Critical Configuration ## 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/` - **Project site:** `url: https://username.github.io` + `baseurl: /repo-name/`
- **YAML errors:** Quote strings with special characters: `title: "My: Cool Site"` - **YAML errors:** Quote strings with special characters: `title: "My: Cool Site"`
## Common Issues ## Development Workflow
For troubleshooting common build, deployment, and configuration issues, see: - **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.
- [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)
**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:
| File Type | Instruction File | | 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) | | 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) | | 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 - [Common Pitfalls & Workarounds](.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md
- [`.github/instructions/*.md`](.github/instructions/) – Code-specific instruction files (loaded when editing relevant file types) - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions
- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) to search for your specific problem.
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`.

1
CLAUDE.md Normal file
View File

@ -0,0 +1 @@
@AGENTS.md