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.

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

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

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