Development Contract Repo Overlay Template

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.