diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..4b7d20e --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,7 @@ +#!/usr/bin/env bash + +set -euo pipefail + +repo_root="$(git rev-parse --show-toplevel)" + +"$repo_root/scripts/pre-commit.sh" diff --git a/.github/agents/commiter.agent.md b/.github/agents/commiter.agent.md new file mode 100644 index 0000000..1224ba7 --- /dev/null +++ b/.github/agents/commiter.agent.md @@ -0,0 +1,50 @@ +--- +name: Committer +description: Proactive commit specialist for this repository. Use when asked to commit, prepare a commit, review staged changes before committing, write a commit message, run pre-commit checks, or create a signed Conventional Commit. +argument-hint: Describe what should be committed, any files to exclude, and whether the changes are already staged. +tools: [execute, read, search, edit, todo] +model: GPT-5 (copilot) +user-invocable: true +disable-model-invocation: false +--- + +You are the repository's commit specialist. Your job is to prepare safe, clean, +and reviewable commits for the current branch. + +Treat every commit request as a review-and-verify workflow, not as a blind +request to run `git commit`. + +## Repository Rules + +- Follow `AGENTS.md` for repository-wide behavior and `.github/skills/commit/skill.md` for commit-specific reference details. +- The pre-commit validation command is `./scripts/pre-commit.sh`. +- Create GPG-signed Conventional Commits. + +## Required Workflow + +1. Read the current branch, `git status`, and the staged or unstaged diff relevant to the request. +2. Summarize the intended commit scope before taking action. +3. Ensure the commit scope is coherent and does not accidentally mix unrelated changes. +4. Run `./scripts/pre-commit.sh` when feasible and fix issues that are directly related to the requested commit scope. +5. Propose a precise Conventional Commit message. +6. Create the commit with `git commit -S` only after the scope is clear and blockers are resolved. +7. After committing, run a quick verification check and report the resulting commit summary. + +## Constraints + +- Do not write code. +- Do not bypass failing checks without explicitly telling the user what failed. +- Do not rewrite or revert unrelated user changes. +- Do not create empty, vague, or non-conventional commit messages. +- Do not commit secrets, backup junk, or accidental files. + +## Output Format + +When handling a commit task, respond in this order: + +1. Commit scope summary +2. Blockers, anomalies, or risks +3. Checks run and results +4. Proposed commit message +5. Commit status +6. Post-commit verification diff --git a/.github/skills/commit/skill.md b/.github/skills/commit/skill.md index 04629cb..f175527 100644 --- a/.github/skills/commit/skill.md +++ b/.github/skills/commit/skill.md @@ -23,17 +23,27 @@ Also requires: Node.js ≥ 20, `yamllint`, and `shellcheck` available on `$PATH` ## Run Linters Before Committing ```sh -./scripts/lint.sh +./scripts/pre-commit.sh ``` -This runs markdown, YAML, spell check, and shell script linters in sequence. -Stops on first failure. +This is the pre-commit entry point and currently delegates to `./scripts/lint.sh`. +It runs markdown, YAML, spell check, and shell script linters in sequence and +stops on first failure. + +The repository also provides a tracked Git hook at `.githooks/pre-commit`. +Enable it locally with: + +```sh +git config core.hooksPath .githooks +``` Fix all reported issues before committing. Add any new project-specific words to `project-words.txt` (one word per line). ## Commit Message Format +All commits must be GPG-signed. + Follow [Conventional Commits](https://www.conventionalcommits.org/): ```text diff --git a/AGENTS.md b/AGENTS.md index 68e2c35..2e630b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,10 +44,28 @@ recovery and sharing purposes. ## Code Conventions +## Mutual Support And Proactivity + +These rules apply repository-wide to every assistant, including custom agents. + +When acting as an assistant in this repository: + +- Do not flatter the user or agree with weak ideas by default. +- Push back when a request, diff, or proposed commit looks wrong. +- Flag unclear but important points before they become problems. +- Ask a clarifying question instead of making a random choice when the decision matters. +- Call out likely misses such as naming inconsistencies, accidental generated files, + staged-versus-unstaged mismatches, missing docs updates, or suspicious commit scope. + +When raising a likely mistake or blocker, say so clearly and early instead of +burying it after routine status updates. + ### Commit Messages Use [Conventional Commits](https://www.conventionalcommits.org/): +- All commits must be GPG-signed. + - `feat:` — new features or configuration - `fix:` — bug fixes - `docs:` — documentation-only changes @@ -80,13 +98,32 @@ Format: ### Linting Summary - The canonical lint entry point is `./scripts/lint.sh`. +- The pre-commit entry point is `./scripts/pre-commit.sh`. +- The repository includes a tracked Git hook at `.githooks/pre-commit` that runs the pre-commit script. +- Enable tracked hooks locally with `git config core.hooksPath .githooks`. - Install the wrapper with `cargo install torrust-linting --locked`. - Install `yamllint` and `shellcheck` on `$PATH` before running the script. - If npm install steps fail with `EACCES`, use a user-local npm prefix. - See [docs/linting.md](docs/linting.md) for installation and troubleshooting. +### Commit Review Expectations + +Before creating a commit, review the diff like a skeptical reviewer, not a blind +operator. + +- Read `git status` and the relevant `git diff` first. +- Look for unusual states such as a file being staged and also deleted, mixed + unrelated changes, or files that do not fit repository naming patterns. +- Prefer stopping to clarify an anomaly over committing something ambiguous. +- If documentation, spelling word lists, or ignore rules should change with the + diff, call that out before committing. +- Use `./scripts/pre-commit.sh` as the commit-time validation command. + +After creating a commit, verify the result with a short `git status` check and +briefly summarize what was committed. + ## Pull Request Guidelines - Title must follow the Conventional Commits format: `[scope]: ` -- Run `./scripts/lint.sh` before opening a PR. +- Run `./scripts/pre-commit.sh` before opening a PR. - Reference related issues in the PR body using `Refs: #`. diff --git a/docs/linting.md b/docs/linting.md index d10ed26..667ef83 100644 --- a/docs/linting.md +++ b/docs/linting.md @@ -14,6 +14,30 @@ Run all linters with: This is the preferred command for local validation before committing or opening a pull request. +## Pre-commit Script + +The repository also provides a pre-commit wrapper: + +```sh +./scripts/pre-commit.sh +``` + +For now this script delegates directly to `./scripts/lint.sh`. + +## Git Pre-commit Hook + +A tracked Git hook is included at `.githooks/pre-commit` and runs +`./scripts/pre-commit.sh` automatically before `git commit`. + +Enable the tracked hooks once per local clone: + +```sh +git config core.hooksPath .githooks +``` + +After that, `git commit` will execute the repository's pre-commit checks +automatically. + The script runs these linters in order: ```sh @@ -73,7 +97,7 @@ Run this before committing: ```sh export NPM_CONFIG_PREFIX="$HOME/.local" export PATH="$HOME/.local/bin:$PATH" -./scripts/lint.sh +./scripts/pre-commit.sh ``` If the script passes, the repository is clean for Markdown, YAML, spelling, and @@ -167,6 +191,8 @@ Use spaces for wrapped list items and paragraph continuations. ## Files Involved - [scripts/lint.sh](../scripts/lint.sh) +- [scripts/pre-commit.sh](../scripts/pre-commit.sh) +- [.githooks/pre-commit](../.githooks/pre-commit) - [project-words.txt](../project-words.txt) - [cspell.json](../cspell.json) - [.markdownlint.json](../.markdownlint.json) @@ -175,6 +201,7 @@ Use spaces for wrapped list items and paragraph continuations. ## Notes - `./scripts/lint.sh` is the canonical repository command. +- `./scripts/pre-commit.sh` is the hook-friendly entry point for commit-time checks. - If you document new product names, services, or command tokens, update `project-words.txt` as part of the same change. - Run the full script again after fixing targeted issues to ensure the complete diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh new file mode 100755 index 0000000..34f9ed8 --- /dev/null +++ b/scripts/pre-commit.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash + +set -euo pipefail + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +"$script_dir/lint.sh"