codex: add a repo-local cli-surface-contract skill for public CLI/scaffold changes

[mk3008]

Summary

Add a repo-local skill that treats public CLI, scaffold, and generated-file changes as a contract surface, so implementation changes do not land without the expected docs/tests/generated-output follow-through.

Background

Recent work repeatedly needed the same correction pattern after CLI/scaffold changes:

• implementation changed first
• then README / guide / tutorial / prompt / generated output expectations had to be synchronized
• review comments repeatedly pushed on docs/tests/generated-output alignment

This suggests the main improvement is not to grow the root AGENTS.md, but to move this recurring correction into a dedicated repo-local skill.

Problem

The current workflow relies too much on reviewers or ad hoc prompts to remember the full write set for public CLI/scaffold changes.

As a result, the repository is vulnerable to repeated drift across:

• CLI behavior
• scaffold output
• generated files
• README / guide / tutorial text
• tests and expectations
• compatibility notes such as JSON or dry-run behavior

This is not a one-off issue. It is a repeated review pattern.

Proposal

Add a repo-local skill, tentatively named cli-surface-contract, with the following responsibility:

When a PR changes a public CLI command, scaffold flow, or generated file contract, the skill must explicitly check and report whether the following surfaces were updated as needed:

• README
• guide / tutorial / init guidance
• prompts or onboarding guidance
• generated output expectations
• tests
• JSON / dry-run surface
• compatibility notes, when relevant

The goal is not to force all surfaces to change every time. The goal is to make the changed and unchanged surfaces explicit, so drift is intentional rather than accidental.

Expected benefit

• reduce repeated review comments about docs/tests/generated-output sync
• reduce contract drift for public CLI/scaffold behavior
• keep root AGENTS.md thin while moving high-churn rules into a reusable skill
• make Codex output more consistent without requiring long reviewer prompts

Definition of done

• a repo-local cli-surface-contract skill exists
• the skill states the expected write set for public CLI/scaffold/generated-file changes
• PRs that change those surfaces can reference the skill and produce an explicit sync report
• repeated reviewer corrections about README/tests/generated-output drift are reduced