# Developing Standard Repository Policies

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

## Orientation

Read the [agent policy](policy/agents.md) 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 examples illustrate downstream adoption.

## Policy Reading Guide

| Policy | Read before… |
| --- | --- |
| [Adoption and update guide](adoption.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | 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.
- Select policies using the task triggers above. Follow cross-references to
  relevant sections 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.

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. Diff, link, and example
review suffice 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. Use local links for new
assets until a containing commit is available. Confirm public reference links
are accessible when preparing publication of the reference changes.