git:20260423.b0aeb97 to git:20260904.6c1f699
21 added, 19 removed. Audit A to A.
---
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.
- 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 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. 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.
+ 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.
- - If repo policy and docs disagree, fix the policy or the docs so the checker, template, and guidance converge again.
+ - 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
- 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
+ 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.