development-contract-repo-overlay-template git:20260405.2f8d9a2A

Immutable. This exact content is served forever at /api/v1/blob/7b1cc05e8414a082.

---
name: development-contract-repo-overlay-template
description: Template for the repo-local overlay generated by the development contract system. Use when a target repo already has the contract system and you need the local policy path, plan directory, helper command, or validation profiles.
---

# Development Contract Repo Overlay Template

This skill documents the expected shape of the repo-local overlay that a target repository should have after adopting the development contract system.
It is not guidance for this skills repository itself, which only stores the reusable skills.

In a target repo, start by reading that repo's policy file, then apply `development-contract-process`.
Treat repo guidance as secondary to the policy file for contract mechanics; if they disagree, fix the mismatch instead of guessing.

## Use this skill when

- authoring or revising the repo-local overlay generated for a target repository
- work in a target repo may touch a substantive path or top-level file listed in that repo's policy file
- creating, updating, or verifying a non-template plan under the target repo's plan directory
- deciding which validation profile the target repo expects for a change

Do not use this skill alone for generic coding advice; pair it with a more specific implementation skill when needed.

## Repo overlay workflow

1. Read the touched files before editing.
2. Read the target repo's policy file for the plan directory, substantive path rules, required lanes, and validation profiles.
3. Apply `development-contract-process` for the generic workflow and decision rules.
4. If the change is substantive under repo policy, update a non-template plan in the lifecycle subdirectory under the repo's plan directory that matches the record's `State`.
   Prefer the repo's lifecycle helper when changing an existing record's lifecycle.
5. Keep verifier notes concrete: record commands, observed results, and any contract mismatches explicitly.
6. Run the smallest repo policy profile that proves the change, then extend when the surface justifies it.
7. Before closing work, run the checker command declared in the repo policy file.

## Decision rules

- Treat the target repo's policy file as the source of truth for what is substantive in that repo.
- Do not leave a substantive change without a non-template plan update.
- Use the repo's lifecycle helper with its supersede option when superseding a record so the replacement link is updated with the move.
- Keep the repo overlay thin: change policy data first, then only add prose when the repo needs extra human guidance that policy cannot express.
- If repo policy and docs disagree, fix the policy or the docs so the checker, template, and guidance converge again.

## What the generated overlay should contain

- the concrete policy file path used by the target repo
- the checker command used by that repo
- the lifecycle helper command when the repo uses state-specific directories
- the named validation profiles exposed by the repo policy
- only the extra repo-specific human guidance that policy cannot express

## Example target-repo literals

Many repos generated from the example system will expose names such as:

- `config/change-contract-policy.sh`
- `bash scripts/check-change-contracts.sh`
- `bash scripts/set-feature-record-lifecycle.sh`
- `FRAME_CONTRACT_VALIDATION_PROFILE_DOCS`
- `FRAME_CONTRACT_VALIDATION_PROFILE_CODE`
- `FRAME_CONTRACT_VALIDATION_PROFILE_RELEASE`

Treat those as common examples, not universal constants.

## Output expectations

When this skill applies, the final work should leave behind:

- a thin repo-local overlay aligned with `development-contract-process`
- code or docs aligned with repo guidance and policy
- an updated non-template plan when the change is substantive
- explicit verifier evidence in the plan
- repo policy, docs, and checker behavior that still agree
- a concise report of what was validated and what could not be validated

## Examples

- `Implement this feature in a repo that already uses the contract system`:
  read that repo's policy file, update the relevant non-template record, implement narrowly, run the smallest proving profile, and record verifier commands/results.
- `Update the CI workflow to enforce a new repo rule`:
  treat it as substantive workflow work under policy, update the record, run the checker, and verify workflow/docs alignment.
- `Finish a feature and accept it`:
  update verification evidence, then use the repo's lifecycle helper to move the record to `done`.
- `Port this contract system into another repo`:
  use `development-contract-system` to build the repo-owned policy, checker, template, helper, tests, docs, and generated repo-local overlay.