Skip to content

docs(contributing): add agent-facing playbooks and architecture overview #2007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bearomorphism wants to merge 8 commits into
base: master
Choose a base branch
from
Open

docs(contributing): add agent-facing playbooks and architecture overview #2007

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
197ca17
docs(contributing): add architecture overview
bearomorphism May 30, 2026
cf16a87
docs(contributing): add agent-facing playbooks and validation guide
bearomorphism May 30, 2026
157cb18
docs(agents): slim AGENTS.md to a routing layer
bearomorphism May 30, 2026
741ee63
style(docs): unwrap hard-wrapped paragraphs in new agent docs
bearomorphism May 30, 2026
801fc2a
docs(agents): trim Do-Not-Touch to commitizen-specific traps
bearomorphism May 30, 2026
f1d1fcd
docs(agents): drop redundant `Agent-specific deltas` section
bearomorphism May 30, 2026
ac589a8
docs(agents): cut more redundant content
bearomorphism May 30, 2026
6dda294
docs(agents): fix incorrect playbook examples
bearomorphism May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs(agents): drop redundant Agent-specific deltas section 
The four items in this section all duplicated content from AGENTS.md's Mandatory PR reminders (PR template, poe all vs poe ci, do-not-touch) or pointed at validation.md (targeted tests). The `When to read what` table above already routes readers to the same destinations in a more compact form, so the section was pure noise.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  • Loading branch information
@bearomorphism
bearomorphism and Copilot committed May 30, 2026
commit f1d1fcd04a1f38077a5b8b92b27a1dcc4cc031b1
9 changes: 0 additions & 9 deletions docs/contributing/agents/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,6 @@ When two documents could host a piece of guidance, this table is the tie-breaker

The repo-root [`AGENTS.md`](https://github.com/commitizen-tools/commitizen/blob/master/AGENTS.md) is the auto-loaded entry point for most agent tools. It holds the rules an agent needs in every session; this page is the deeper reference.

## Agent-specific deltas

Humans absorb these rules through review; agents need them stated:

1. **Complete the PR template fully**, including the AI-disclosure checkbox and the `Generated-by:` trailer. The maintainers re-run the commands you list under "Steps to Test This Pull Request" — make them exact.
2. **`uv run poe all` is the pre-push verification command** named in the PR template. `poe ci` is the CI-equivalent runner (uses `prek` and does not auto-format); run it too if you want to mirror CI exactly. See the [Validation Guide](validation.md#choosing-a-final-check) for the distinction.
3. **Do not touch generated artifacts.** See the do-not-touch list in [`AGENTS.md`](https://github.com/commitizen-tools/commitizen/blob/master/AGENTS.md).
4. **Prefer targeted test selectors during iteration** — see the [targeted-test map](validation.md#targeted-test-map). The full suite is fine for a final pre-push run.

## Playbooks

Recipes for recurring task types. Each playbook is self-contained: trigger, files to read first, ordered steps, verification commands, and known pitfalls. They link out to the human-facing concept docs rather than restating concepts.
Expand Down
Loading