docs(agents): require conventional commit messages

2 files changed, 23 insertions, 2 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 6f7c200..ed64ac7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,4 @@
 Refer to all markdown files in `AGENTS/`
 
-@AGENTS/ARCH.md
+@AGENTS/HOW_TO_COMMIT.md
+@AGENTS/*
\ No newline at end of file
diff --git a/AGENTS/HOW_TO_COMMIT.md b/AGENTS/HOW_TO_COMMIT.md
index e09a3c0..fc94655 100644
--- a/AGENTS/HOW_TO_COMMIT.md
+++ b/AGENTS/HOW_TO_COMMIT.md
@@ -55,4 +55,24 @@ The closing `'@` MUST be at column 0 with no leading whitespace.`}
   }
 }
 ```
-Set `commit` or `pr` to empty string `""` to hide that attribution. To hide all of it, set both to `""` and also set `"sessionUrl": false`. Write this object form, not `"attribution": false`: older Claude Code versions reject true or false here and then skip the whole settings file.
\ No newline at end of file
+Set `commit` or `pr` to empty string `""` to hide that attribution. To hide all of it, set both to `""` and also set `"sessionUrl": false`. Write this object form, not `"attribution": false`: older Claude Code versions reject true or false here and then skip the whole settings file.
+
+## Commit workflow for AI agents
+
+Use conventional commit format, following [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/): `<type>[optional scope][optional !]: <description>`.
+
+1. Inspect `git status --short`, `git diff` and `git diff --cached` to understand the working tree, the staged changes and the intended commit scope.
+2. Review `git log -10 --format='%s'` for recent naming conventions. When useful, inspect related history with `git log -5 --format='%s' -- <affected paths>` or search commit messages with `git log --oneline --grep='<topic>'`. Use history to choose consistent scopes and terminology; base the message on the actual diff.
+3. Choose a lowercase type: `feat` for a new feature, `fix` for a bug fix, `docs` for documentation, or `refactor`, `perf`, `test`, `build`, `ci`, `style` or `chore` when appropriate. Use a short scope for the affected subsystem when it adds useful context.
+4. Write a concise English description in the imperative, without a trailing period. For example: `docs(agents): require conventional commit messages`. Add a body only when it helps explain the reason or consequences of the change. Separate the body and any trailers with blank lines. Mark breaking changes with `!` before the colon or a `BREAKING CHANGE:` footer explaining the incompatibility.
+5. Preserve the user's staged selection and stage only additional files relevant to the authorized task, using explicit paths. Review `git diff --cached` and run `git diff --cached --check`, plus any checks appropriate to the changes, before committing.
+6. Complete staging before creating the commit, then run `git status --short` after the commit succeeds. These dependent operations must run sequentially; only independent inspections may run in parallel.
+
+Pass the message inline through a quoted HEREDOC on Bash or Zsh, as required above. Use concrete text; do not copy unresolved template variables or invent attribution trailers.
+
+```bash
+git commit -m "$(cat <<'EOF'
+docs(agents): require conventional commit messages
+EOF
+)"
+```