policy/docs/development.md

Developing Standard Repository Policies

This repository maintains reusable policy templates and reference materials. For adopting them into another project, use the adoption guide.

Orientation

Read the agent policy and inspect the working tree before editing. Preserve unrelated work. Follow explicit task instructions, including requests to leave changes uncommitted. This repository's policy files retain their template adoption sections because they are distributed as templates. Application-specific template examples do not require this repository to acquire application interfaces or infrastructure.

Policy Reading Guide

Policy	Read before…
Agents	Recommending, planning, or implementing repository changes.
Architecture	Planning or changing application code or its structure.
Testing	Selecting validation for code changes, or adding, changing, removing, or evaluating tests.
Documentation	Writing, revising, or reorganizing documentation.
OSS	Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution.
Release	Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions.

• Read applicable policies before making decisions they govern; multiple policies may apply.
• Do not read the entire suite by default or recursively follow every cross-reference. Read relevant sections of supporting references when needed to resolve a concrete question.
• Reuse policies already available in context; reread when changed or no longer available.
• Expand reading when the task's scope expands.
• When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.

Editing And Validation

Keep reusable instructions portable. Put adoption instructions in template sections and project-specific contributor procedures here. Original licensing examples belong under examples/licensing/; explanatory instructions belong in their guide or policy so they are not copied into notices.

Increment the affected template's Base Policy Version and update its date when changing its substantive rules or adoption instructions. Preserve the licensing scope defined in COPYRIGHT; reproduced license texts must remain verbatim.

Review the diff, run git diff --check for changed prose, and check affected links and examples. Example placeholders and destination-relative links should be validated against the documented downstream layout, not treated as published URLs or missing local dependencies. No application build or new test suite is needed for prose-only changes. Retain upstream formatting in verbatim license texts even where it would trigger whitespace warnings.

Pin adopted-source and example links to commits that contain the referenced files. Discovery links to the upstream project and current adoption guide may track main so downstream agents can find updates. New assets can use local links within this repository until a containing commit is available; do not invent a future hash or publish changes merely to obtain one. Before publication, confirm that public reference links are accessible. This is change validation, not a recurring downstream release gate.