development-contract-repo-overlay-template git:20260904.6c1f699A

Immutable. This exact content is served forever at /api/v1/blob/019b9e6e3c5c0ce6.

---
name: development-contract-repo-overlay-template
description: Template for authoring or revising the thin repo-local overlay generated by the development contract system. Use when writing overlay guidance that names a target repo's policy path, plan directory, checker command, lifecycle helper, or validation profiles; use `development-contract-process` for ordinary work in a repo that already has the system.
---

# 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.

Use target policy as the source for contract mechanics within the host's
instruction hierarchy. Keep an unresolved policy/documentation conflict visible;
do not decide it merely by preferring whichever file was opened first.

## Use this skill when

- authoring or revising the repo-local overlay generated for a target repository
- checking that overlay guidance matches the target repo's policy file,
  checker command, lifecycle helper, plan directory, and validation profiles
- deciding which repo-specific literals belong in the overlay versus the policy
  file

Do not use this skill as the primary process for ordinary implementation work
inside a target repo. For that, use `development-contract-process` plus the
target repo's actual local overlay and implementation skill.

## Repo overlay workflow

1. Select findings, draft, or apply from the request. Findings and conversation
   drafts do not authorize repository writes.
2. Read existing overlays and the policy, checker, helper, and profile definitions
   that establish the target's actual commands and paths.
3. Write only the overlay's local bindings and exceptional human guidance. Refer
   to `development-contract-process` when it is available to the target agent;
   otherwise include the minimum operator steps needed to use the repo's system.
4. During authorized application, follow the target's existing contract process
   if changing the overlay is itself substantive. Do not require an unrelated
   implementation or record update merely to produce a draft.
5. Check the overlay against the real files and safe checker modes. Report
   observed commands separately from proposed or unrun commands.

## 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.
- Resolve policy/documentation mismatches from evidence within authorized scope;
  report unresolved decisions rather than silently changing policy.

## 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

Return findings, a draft, or the applied thin overlay as requested, with concrete
policy/command bindings and validation limitations. Applied edits must follow
any target-repo record requirement. This authoring workflow does not itself
authorize product-code changes or adoption of a new contract system.

## Examples

- `Generate the repo-local contract overlay after porting the system`:
  write a thin overlay that names the concrete policy file, checker, helper,
  plan directory, and validation profile names without duplicating schema
  details.
- `Tighten this target repo's contract overlay because policy paths changed`:
  read the policy and helper names, update only the repo-specific literals in
  the overlay, and leave day-to-day process rules in
  `development-contract-process`.
- `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.