Skip to main content
skill CX Codex

056-design-avoid-breaking-changes — Claude Code skill

056-design-avoid-breaking-changes reviews plans, OpenSpec changes, and APIs for breaking changes and migration risks before release.

Apache-2.0 172 installs ★ 465 updated 2026-10-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-code
Open on GitHub

What 056-design-avoid-breaking-changes does

Part of the Plinth Toolkit, this interactive skill evaluates proposed repository modifications before they ship. It scans command definitions, skill routing triggers, generated files, XML sources, data schemas, and CI expectations. By default, the workflow remains strictly read-only, preventing unexpected file mutations during analysis.

The review workflow mandates reading references/056-design-avoid-breaking-changes.md before processing any surfaces. Each flagged issue receives a concrete classification: BREAKING, POTENTIALLY BREAKING, NON-BREAKING, or UNKNOWN. Missing the reference document stalls execution, so keep that path accessible.

At the end of the run, the agent delivers a structured summary with severity-ordered findings. If changes inherently break existing contracts, the report includes guidance for deprecation periods, release notes, and targeted validation checks.

What it helps with

  • detect breaking changes across specifications and OpenSpec plans
  • audit command and skill routing compatibility before deployment
  • evaluate migration risks in API schemas and runtime configuration
  • generate deprecation and release guidance for intentional breaking changes

Example prompts for the agent

  • Review breaking changes in this spec
  • Check compatibility risks in this OpenSpec change
  • Assess command and skill compatibility before release

How to install 056-design-avoid-breaking-changes

1Skills CLI (Vercel)

npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-code

2Manually: put the files in place

~/.claude/skills/056-design-avoid-breaking-changes/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/056-design-avoid-breaking-changes/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about 056-design-avoid-breaking-changes

How to install 056-design-avoid-breaking-changes in Claude Code?

Run npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-code in your terminal.

What does 056-design-avoid-breaking-changes do?

It performs a read-only compatibility review across commands, skills, APIs, schemas, and generated files to highlight breaking risks before releases.

Will this skill modify my source code?

No, it operates purely in read-only mode and avoids editing plans or files unless you specifically ask for implementation.

Source text

SKILL.md · Apache-2.0
---
name: 056-design-avoid-breaking-changes
description: Use when you need to review a plan, OpenSpec change, specification, or implementation proposal for breaking-change risk across commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance. This should trigger for requests such as Review breaking changes in this spec; Check compatibility risks; Avoid breaking changes in this OpenSpec change; Review migration impact before release; Assess command and skill compatibility. Part of Plinth Toolkit
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral
  version: 0.19.0
---
# Avoid Breaking Changes

Review planned repository changes for breaking-change and compatibility risk before implementation or release promotion. **This is an interactive SKILL**.

**What is covered in this Skill?**

- Command contract compatibility: names, inputs, owning agents, outputs, safeguards, installer registration, and command inventories
- Skill routing compatibility: identifiers, metadata, descriptions, triggers, references, generated local output, and acceptance coverage
- Generated-output ownership: XML/source files versus `.agents/skills`, public `skills/`, `.cursor/commands`, `.cursor/rules`, and `docs/`
- Source and generator contracts: XML, XInclude, XSLT, Maven modules, schema expectations, and module validation
- README, localized README, changelog, migration, and deprecation guidance
- External and runtime contracts: APIs, schemas, data formats, configuration keys, persistence, CLI behavior, and CI expectations
- Structured compatibility reports with severity-ranked findings and validation guidance

## Constraints

Keep the review evidence-based, read-only, and scoped to compatibility risk unless the user explicitly asks for implementation.

- **MUST** read `references/056-design-avoid-breaking-changes.md` before producing compatibility guidance
- **MUST** identify the source artifacts reviewed and the compatibility surfaces considered
- **MUST** distinguish confirmed breaking changes, potential risks, non-breaking changes, and unknowns that need maintainer decision
- **MUST** include migration, deprecation, validation, or release-note guidance for intentional breaking changes
- **MUST** respect repository source ownership: edit XML and source docs, regenerate generated output through documented workflows, and avoid direct generated-output edits unless the repository explicitly owns that file
- **MUST NOT** modify plans, specs, source files, generated outputs, or issue descriptions during review unless the user explicitly requests implementation

## When to use this skill

- Review breaking changes in this spec
- Check compatibility risks
- Avoid breaking changes in this OpenSpec change
- Review migration impact before release
- Assess command and skill compatibility
- Find generated output compatibility risks
- Review API schema configuration or data contract changes

## Workflow

1. **Read the compatibility reference**

Read `references/056-design-avoid-breaking-changes.md`, then identify the source artifacts to review, their authority, and whether the request is read-only review or approved implementation.

2. **Inventory compatibility surfaces**

Check commands, skills, generated outputs, XML/source ownership, README/docs, tests, CI/build gates, external contracts, runtime behavior, data/configuration contracts, and release or migration guidance relevant to the proposed change.

3. **Classify findings**

Classify each finding as `BREAKING`, `POTENTIALLY BREAKING`, `NON-BREAKING`, or `UNKNOWN`. Include the affected users, artifacts, contracts, and validation evidence or missing evidence.

4. **Recommend migration and validation**

For each confirmed or potential risk, recommend deprecation, compatibility windows, migration notes, release-note updates, generator checks, focused tests, or owner decisions.

5. **Report the review outcome**

Produce a concise compatibility report with reviewed sources, risk summary by surface, severity-ranked findings, recommended validation, and a clear no-risk statement when no breaking-change risks are found.

## Reference

For detailed guidance, examples, and constraints, see [references/056-design-avoid-breaking-changes.md](references/056-design-avoid-breaking-changes.md).

© Juan Antonio Breña Moral · Apache-2.0 · jabrena/plinth

Similar skills

All skills for Code review and refactoring →

From the same set123

The whole set →
806-regulations-eu-data-act 806-regulations-eu-data-act is a Claude Code skill that checks Java services, APIs, and pipelines for EU Data Act controls before a data-sharing feature ships. CX Codex +1 212installs 500-frameworks-micronaut-create-project The 500-frameworks-micronaut-create-project skill scaffolds a Micronaut 4.x Maven project with SDKMAN-managed tools and checks the generated build. Use it when starting a Micronaut service. CX Codex +1 211installs 054-design-tdd 054-design-tdd — a skill that walks Java developers through red-green-refactor cycles with test-driven development. Write a failing test first, implement just enough code to pass, then refactor while tests stay green. CX Codex +1 177installs 707-technologies-hexagonal-architecture 707-technologies-hexagonal-architecture is a Claude Code skill that reviews and improves Hexagonal architecture boundaries in Java projects without coupling to Spring Boot, Quarkus, or Micronaut. CX Codex +1 174installs 055-design-parallel-change The 055-design-parallel-change skill guides you through designing safe database schema changes when old and new application versions must run simultaneously. It breaks complex migrations into three separately deployable phases. CX Codex +1 172installs 052-design-hamburger-method 052-design-hamburger-method splits oversized user stories and specs into thin vertical slices using the Hamburger Method. Delivers end-to-end observable value instead of isolated technical tasks. CX Codex +1 172installs 053-design-simple-rules 053-design-simple-rules is a Claude skill that checks Java design and refactoring decisions against Kent Beck's four rules, in order. CX Codex +1 172installs 057-design-feature-toggles 057-design-feature-toggles — an interactive skill for designing and reviewing feature toggles in Java services, including kill switches, staged rollouts, experiments, and cleanup. CX Codex +1 171installs

Project sponsors

Companies that keep this analytics open