Generate custom instructions from codebase
Extract deterministic before/after rules from real repository history and write a scoped .instructions.md file.
When to invoke
- Preserve conventions established by an upgrade or refactor.
- Generate API correspondence guidance from a migration diff.
- Prevent reintroduction of obsolete patterns.
- Encode repeatable dependency or configuration transformations.
Inputs
Parse $ARGUMENTS and require MIGRATION_TYPE, SOURCE_REFERENCE, and TARGET_REFERENCE.
| Input |
Allowed values or purpose |
MIGRATION_TYPE |
Framework Version, Architecture Refactoring, Technology Migration, Dependencies Update, Pattern Changes |
SOURCE_REFERENCE |
Before branch, commit, tag, or release |
TARGET_REFERENCE |
After branch, commit, tag, or release |
ANALYSIS_SCOPE |
Entire project, specific folder, or modified files only |
CHANGE_FOCUS |
Breaking changes, conventions, obsolete patterns, APIs, configuration |
AUTOMATION_LEVEL |
Conservative, Balanced, or Aggressive |
GENERATE_EXAMPLES |
true or false |
VALIDATION_REQUIRED |
true or false |
Procedure
- Resolve source and target references to immutable commits and record them.
- Compare structure, moved/deleted files, configuration, dependencies, source, and tests in scope.
- Group repeated transformations by migration type and focus.
- Create an automatic rule only when the old pattern has a reliable trigger and the replacement is deterministic.
- Put ambiguous transformations under validation with concrete tests or compatibility checks.
- Build API correspondences from actual old/new symbols and examples.
- Escalate complex cases, architecture decisions, security changes, and business impact for human review.
- Write
.github/instructions/<migration-slug>.instructions.md with a narrow applyTo glob.
- Test the instructions against representative source and target examples.
Transformation shape:
BEFORE (<SOURCE_REFERENCE>)
<old code from repository>
AFTER (<TARGET_REFERENCE>)
<new code from repository>
RULE
When <reliable trigger> appears under <applyTo>, use <new pattern> and run <validation>.
Output template
## Copilot migration instructions result
**Status:** GENERATED | VALIDATION-REQUIRED | BLOCKED
**References:** <source SHA> -> <target SHA>
**Output:** `.github/instructions/<slug>.instructions.md`
| Rule | Evidence | Automation | Validation |
| --- | --- | --- | --- |
### Escalations
- <complex case, architecture decision, security/business impact, or none>
Limits
- Do not generate rules from generic migration advice or memory.
- Do not automate a transformation without a reliable trigger and deterministic replacement.
- Do not hide exceptions or force architecture/business decisions into mechanical rules.
- Do not write the unsupported
.github/copilot-migration-instructions.md path.
Related primitives
| Name |
Type |
Use it when |
brownfield-engineering |
skill |
The migration rules guide implementation in existing code. |
context-map |
skill |
The changed surface and dependencies need mapping first. |
validation-scripts |
skill |
Generated instructions need repository-level validation. |
Quality gate
1---2name: github-copilot-generate-custom-instructions-23description: Generates path-scoped GitHub Copilot migration instructions from actual branch, commit, tag, or release diffs. Use when handling framework upgrades, architecture refactors, technology migrations, dependency updates, API changes, and obsolete-pattern prevention.4---56# Generate custom instructions from codebase78Extract deterministic before/after rules from real repository history and write a scoped `.instructions.md` file.910## When to invoke1112- Preserve conventions established by an upgrade or refactor.13- Generate API correspondence guidance from a migration diff.14- Prevent reintroduction of obsolete patterns.15- Encode repeatable dependency or configuration transformations.1617## Inputs1819Parse `$ARGUMENTS` and require `MIGRATION_TYPE`, `SOURCE_REFERENCE`, and `TARGET_REFERENCE`.2021| Input | Allowed values or purpose |22| --- | --- |23| `MIGRATION_TYPE` | Framework Version, Architecture Refactoring, Technology Migration, Dependencies Update, Pattern Changes |24| `SOURCE_REFERENCE` | Before branch, commit, tag, or release |25| `TARGET_REFERENCE` | After branch, commit, tag, or release |26| `ANALYSIS_SCOPE` | Entire project, specific folder, or modified files only |27| `CHANGE_FOCUS` | Breaking changes, conventions, obsolete patterns, APIs, configuration |28| `AUTOMATION_LEVEL` | Conservative, Balanced, or Aggressive |29| `GENERATE_EXAMPLES` | true or false |30| `VALIDATION_REQUIRED` | true or false |3132## Procedure33341. Resolve source and target references to immutable commits and record them.352. Compare structure, moved/deleted files, configuration, dependencies, source, and tests in scope.363. Group repeated transformations by migration type and focus.374. Create an automatic rule only when the old pattern has a reliable trigger and the replacement is deterministic.385. Put ambiguous transformations under validation with concrete tests or compatibility checks.396. Build API correspondences from actual old/new symbols and examples.407. Escalate complex cases, architecture decisions, security changes, and business impact for human review.418. Write `.github/instructions/<migration-slug>.instructions.md` with a narrow `applyTo` glob.429. Test the instructions against representative source and target examples.4344Transformation shape:4546```text47BEFORE (<SOURCE_REFERENCE>)48<old code from repository>4950AFTER (<TARGET_REFERENCE>)51<new code from repository>5253RULE54When <reliable trigger> appears under <applyTo>, use <new pattern> and run <validation>.55```5657## Output template5859```markdown60## Copilot migration instructions result6162**Status:** GENERATED | VALIDATION-REQUIRED | BLOCKED63**References:** <source SHA> -> <target SHA>64**Output:** `.github/instructions/<slug>.instructions.md`6566| Rule | Evidence | Automation | Validation |67| --- | --- | --- | --- |6869### Escalations70- <complex case, architecture decision, security/business impact, or none>71```7273## Limits7475- Do not generate rules from generic migration advice or memory.76- Do not automate a transformation without a reliable trigger and deterministic replacement.77- Do not hide exceptions or force architecture/business decisions into mechanical rules.78- Do not write the unsupported `.github/copilot-migration-instructions.md` path.7980## Related primitives8182| Name | Type | Use it when |83| --- | --- | --- |84| `brownfield-engineering` | `skill` | The migration rules guide implementation in existing code. |85| `context-map` | `skill` | The changed surface and dependencies need mapping first. |86| `validation-scripts` | `skill` | Generated instructions need repository-level validation. |8788## Quality gate8990- [ ] Source and target resolve to immutable commits.91- [ ] Every rule cites actual before/after evidence.92- [ ] Automatic replacements are deterministic and scoped.93- [ ] Validation-required changes name concrete checks.94- [ ] Architecture, security, and business-impact decisions are escalated.95- [ ] The generated instruction has a narrow `applyTo` and passes primitive validation.
paulasilvatech