Purpose
Promote proven local adaptations upward — turn a project's accumulated adaptation into a drafted promotion proposal, routed to the governance owner that actually controls the target. It is manual and on-demand: a developer runs it when a local tweak looks generally useful. It only drafts and routes — it never edits the framework, never opens a PR, and never approves anything.
Layer: cross-cutting utility (governance-facing; not a lifecycle layer).
When to Use
Use when:
- A project's
.aidoc/profile.yaml/.aidoc/learnings.mdshows a recurring adaptation that might belong in the framework. - Reviewing whether local deviations should be standardized.
Do NOT use to:
- Create or maintain the profile — that is
../project-profile/SKILL.md. - Author a change record or run a gate yourself — this skill drafts the input;
../doc-chg/SKILL.mdand../gate-check/SKILL.mdown the CHG process.
Behavior
The framework ships no runtime code — this skill is the analyst. It reads, classifies, and drafts; a human takes each draft into the right path.
1. Read the signal
Load .aidoc/profile.yaml and .aidoc/learnings.md (entry shape:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md §7). Diff the profile against framework
defaults to list the project's active deviations.
2. Judge generalizability (manual)
For each deviation decide generalizable vs project-idiosyncratic. Weigh — do not let either decide alone:
recurrence(higher → stronger signal it is not a one-off);conflict: true(the project overrode the developer's own seed → weaker; a per-project exception is less likely to be universal);- whether the rationale is project-specific or speaks to the artifact in general.
Idiosyncratic items stay local — say so explicitly and stop there.
3. Classify the target owner
For each generalizable item, decide what it would actually change:
| If the change is to… | Owner | Path |
|---|---|---|
a template, a governance rule, or the registry (framework/) |
framework spec | CHG (change management) |
| how an engine guides authoring (a skill's checklist/wording) | the platform | ordinary platform review (PR) |
4. Route and draft
- Spec target → a CHG record. Shape it to
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yamlwithchange_source: spec,entry_gate: GATE-SPEC, and asemver_impact(additive →minor, breaking →major); carry provenance (the learnings entries + profile keys that motivated it) inchange_description.why/.trigger. Hand it to../doc-chg/SKILL.mdto complete the record and../gate-check/SKILL.mdto run GATE-SPEC, the framework-spec change gate (${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/gates/GATE-SPEC_FRAMEWORK.md). A human approves; the extractor never opens a PR or grants approval. - Engine-guidance target → a PR-ready change description. Name the file, give
a before/after, and carry the same provenance. This is an ordinary platform
change, not a CHG record (per
${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md§7).
5. Hand off
Present the drafts grouped by path, with the idiosyncratic items listed as "kept local". Never apply, open, or approve — a human decides.
Output contract
| Target | Artifact | Carries | Status |
|---|---|---|---|
| framework spec | CHG record (change_source: spec → GATE-SPEC) |
provenance | ready for GATE-SPEC review |
| engine guidance | PR-ready change description | provenance (file, before/after) | ready for ordinary review |
| neither | "kept local" note | rationale | no action |
Related Resources
- Signal source:
../project-profile/SKILL.md,${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md(§7 learnings log) - CHG authoring:
../doc-chg/SKILL.md; template${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yaml - Spec gate:
../gate-check/SKILL.md→${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/gates/GATE-SPEC_FRAMEWORK.md
Quick Reference
| Step | Action |
|---|---|
| 1 | Read profile + learnings; diff vs defaults |
| 2 | Judge generalizable vs idiosyncratic (recurrence ↑, conflict ↓) |
| 3 | Classify owner: spec → CHG/GATE-SPEC, guidance → PR |
| 4 | Draft + provenance (spec record routed to GATE-SPEC) |
| 5 | Hand off; never apply/approve |