René's URL Explorer Experiment

Title: docs(contributing): add agent-facing playbooks and architecture overview by bearomorphism · Pull Request #2007 · commitizen-tools/commitizen · GitHub

Open Graph Title: docs(contributing): add agent-facing playbooks and architecture overview by bearomorphism · Pull Request #2007 · commitizen-tools/commitizen

X Title: docs(contributing): add agent-facing playbooks and architecture overview by bearomorphism · Pull Request #2007 · commitizen-tools/commitizen

Description: Description Adds an agent-shaped contributor track that links back to the existing human docs instead of restating them, and slims AGENTS.md to a routing layer. Why. AGENTS.md currently mixes routing, bootstrap commands, CI failure patterns, and coding guidelines that duplicate contributing.md/contributing_tldr.md/pull_request.md and drift out of sync. Nothing in the repo is reusable for recurring agent task types (add a provider, deprecate an API, regenerate snapshots, ...), so every session re-derives the workflow. What. docs/contributing/architecture.md — one-page subsystem map (cli, commands, config, providers, changelog_formats, version_schemes, plugins) with extension points and config layering. General-audience. docs/contributing/agents/ — router index.md with a source-of-truth map, validation.md (targeted-test selectors + poe all vs poe ci + CI failure recipes), and 5 playbooks: add a version provider, add a changelog format, add/modify a CLI flag, deprecate a public API, update snapshots/screenshots. AGENTS.md slimmed: keeps project pitch, key entrypoints, the "Read before changing" table; adds a "Do not touch" list of auto-managed files and the mandatory PR reminders; drops everything that now duplicates a human doc. One-line "For AI agents" callouts in contributing.md and pull_request.md. Wired into mkdocs nav (new "For AI Agents" section) and into mkdocs-llmstxt so the pages appear in llms-full.txt. Dedup rule. Every fact lives in exactly one place. The source-of-truth map in agents/index.md enforces it — agent docs link to human docs, never restate them. Checklist I have read the contributing guidelines Was generative AI tooling used to co-author this PR? Yes (please specify the tool below) Generated-by: GitHub Copilot CLI following the guidelines Code Changes Docs-only PR. No Python, dependencies, or CI workflows changed. Run uv run poe all locally to ensure this change passes linter check and tests Ensure backward compatibility is maintained Update the documentation for the changes Documentation Changes Run uv run poe doc locally to ensure the documentation pages renders correctly (used poe doc:build for finite output) Check and fix any broken links (internal or external) Expected Behavior A new "For AI Agents" section appears under Contributing in the rendered docs, llms-full.txt includes the new pages, and AGENTS.md is shorter and routes to them. Steps to Test This Pull Request git checkout docs/agent-playbooks && uv sync --frozen --all-groups uv run poe doc:build — confirm no broken-link warnings. Open site/contributing/agents/index.html and walk the cross-links. Open site/llms-full.txt and confirm the new entries appear under Contributing. Additional Context Split into 3 commits (architecture, agent docs + nav + callouts, AGENTS.md slim) for review clarity; squash-merge friendly.

Open Graph Description: Description Adds an agent-shaped contributor track that links back to the existing human docs instead of restating them, and slims AGENTS.md to a routing layer. Why. AGENTS.md currently mixes routi...

X Description: Description Adds an agent-shaped contributor track that links back to the existing human docs instead of restating them, and slims AGENTS.md to a routing layer. Why. AGENTS.md currently mixes routi...

Opengraph URL: https://github.com/commitizen-tools/commitizen/pull/2007

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width