docs: add scoped agent instruction hierarchy

[abhiksark]

Summary

• replace the root contributor overview with a canonical operational policy
• define the active branch and merge policy: topic branches target main, merge commits require green CI and resolved feedback, and merging requires explicit maintainer approval
• add scoped guides for the MkDocs site and generated local documentation
• reduce CLAUDE.md to a compatibility pointer to the canonical hierarchy

Why

The repository guidance was duplicated, partly stale, and did not capture the runtime, learner-state, curriculum, documentation-generation, security, release, and merge invariants that changes must preserve. This hierarchy keeps shared rules in one place and adds only directory-specific requirements locally.

The live repository uses main as its active integration branch; dev currently has no unique commits and is behind main. The policy therefore makes direct-to-main pull requests explicit while retaining dev only for an approved future release plan.

This changes contributor and automation guidance only. It does not change application behavior, public APIs, curriculum content, or release configuration.

Validation

• git diff --check
• python -m pytest -q (147 passed in 20.10s)
• pythonlings --root tests/fixtures/passing_curriculum verify (2 passed)
• mkdocs build --strict (passed; informational note that the local guide is not in site navigation)

Confirmation item

pyproject.toml declares Python 3.9 support, while the current CI matrix covers Python 3.11 through 3.13. This PR records that gap without changing CI.

Summary by CodeRabbit

• Documentation
  • Replaced repository contribution guidance with standardized development, validation, pull request, branching, compatibility, security, and release requirements.
  • Added dedicated guidance for the documentation site, including build validation, navigation updates, and content synchronization.
  • Added documentation-generation guidance covering source requirements, generated output review, licensing, and follow-up testing.
  • Updated coding-agent instructions to reference the applicable repository and documentation policies.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fde67d8a-9b79-4b6e-ae5f-ab6eb4f5db5f

📥 Commits

Reviewing files that changed from the base of the PR and between e3bdcc9 and 381581c.

📒 Files selected for processing (4)

• AGENTS.md
• CLAUDE.md
• docs-site/AGENTS.md
• pythonlings/docs/AGENTS.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (5)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Preserve learner-edited exercises during workspace updates. Reset snapshots
and bundled curriculum updates must not overwrite learner work implicitly.

• Report vulnerabilities privately. Never disclose them through public issues
  or pull requests; follow SECURITY.md.
• Use only pythonlings as the distribution name. Do not publish or document
  this repository under a different package name.
• Read RELEASE.md before changing versions, tags, release workflows, or
  publishing behavior.

Files:

• docs-site/AGENTS.md
• pythonlings/docs/AGENTS.md
• CLAUDE.md
• AGENTS.md

{docs-site,pythonlings/docs}/**

📄 CodeRabbit inference engine (CLAUDE.md)

{docs-site,pythonlings/docs}/**: Before editing docs-site/** or pythonlings/docs/**, read the corresponding
nested AGENTS.md in that directory.

Files:

• docs-site/AGENTS.md
• pythonlings/docs/AGENTS.md

docs-site/**

📄 CodeRabbit inference engine (docs-site/AGENTS.md)

docs-site/**: Run documentation commands from the repository root:

python -m pip install -r requirements-docs.txt
mkdocs build --strict

Keep documented commands, keyboard bindings, package versions, and
screenshots synchronized with current product behavior.
Run mkdocs build --strict before completing any documentation-site change.

Files:

• docs-site/AGENTS.md

pythonlings/docs/**

📄 CodeRabbit inference engine (pythonlings/docs/AGENTS.md)

This guide applies to generated local documentation under pythonlings/docs/**.

Files:

• pythonlings/docs/AGENTS.md

pythonlings/docs/**/*

📄 CodeRabbit inference engine (pythonlings/docs/AGENTS.md)

Commit generator or source changes with their regenerated outputs.

Files:

• pythonlings/docs/AGENTS.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: abhiksark/pythonlings

Timestamp: 2026-08-15T14:04:00.939Z
Learning: Read and follow the repository policy in `AGENTS.md`.

🔇 Additional comments (4)

CLAUDE.md (1)

3-7: LGTM!

docs-site/AGENTS.md (1)

1-21: LGTM!

AGENTS.md (1)

57-58: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Document the Python 3.9 CI coverage gap.

Line 57 declares Python 3.9 support, but this policy does not state that CI currently covers Python 3.11–3.13 or define how contributors must validate Python 3.9. Add the exact CI coverage and the required Python 3.9 validation step. The PR objective states that this gap is documented.

⛔ Skipped due to learnings

Learnt from: CR
Repo: abhiksark/pythonlings PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-06-20T06:33:51.513Z
Learning: Applies to **/*.py : Guard newer-stdlib usage with `requires-python = ">=3.9"` and use fallbacks (e.g. `tomllib` falls back to `tomli`) in modules like `core/manifest.py`

Learnt from: CR
Repo: abhiksark/pythonlings PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-06-18T15:54:06.978Z
Learning: Applies to **/*.py : Use Python 3.11+ idioms in all Python code

pythonlings/docs/AGENTS.md (1)

10-13: 🗄️ Data Integrity & Integration

No change required. The policy correctly identifies all generated outputs.

---

📝 Walkthrough

Walkthrough

The repository replaces general guidance with a canonical AGENTS.md policy and adds scoped documentation policies. CLAUDE.md now references the policy hierarchy. The policies define commands, validation, documentation generation, synchronization, compatibility, security, and release requirements.

Changes

Contributor policy hierarchy

Layer / File(s)	Summary
Canonical repository guidance AGENTS.md, CLAUDE.md	AGENTS.md now defines repository-wide contributor and coding-agent policies. CLAUDE.md directs contributors to the canonical policy hierarchy and nested documentation policies.
Documentation scope guidance docs-site/AGENTS.md, pythonlings/docs/AGENTS.md	The scoped guides define documentation-site builds and navigation requirements, plus generated-documentation regeneration, licensing, output review, and testing requirements.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: 🔵 Low · up to 38158

The change only reorganizes contributor guidance and does not alter application or release behavior. A bounded documentation follow-up remains to state the Python 3.9 CI gap and validation expectations; this is mergeable with maintainer awareness.

Poem

A rabbit checks the guides with care,
Root rules here and scoped rules there.
MkDocs builds, docs regenerate,
Tests and licenses keep things straight.
Hop, hop—policies coordinate!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the scope, rationale, changes, and validation, but it omits the template's Screenshots and Checklist sections.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding a scoped agent instruction hierarchy.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/instruction-hierarchy

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}