ports-and-adapters
Refactor a project in any language, or one subsystem of it, into a pure core plus ports and adapters, with one file per port and one file per adapter, without changing behaviour. Use when the user asks to decouple code from its I/O, make a backend swappable, introduce hexagonal / clean architecture, add seams for testing, or invokes /ports-and-adapters <path-or-subsystem>.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 21 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dmccoystephenson/ports-and-adapters with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dmccoystephenson/ports-and-adapters'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/dmccoystephenson--ports-and-adapters)HTML
<a href="/listings/dmccoystephenson--ports-and-adapters"><img src="/api/listings/dmccoystephenson--ports-and-adapters/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Copy this directory into a Claude Code skills directory, either `.claude/skills/ports-and-adapters/` in a project or `~/.claude/skills/ports-and-adapters/` for all projects.
git clone https://github.com/dmccoystephenson/ports-and-adapters ~/.claude/skills/ports-and-adapters
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 197 lines
- ---
- name: ports-and-adapters
- description: Refactor a project in any language, or one subsystem of it, into a pure core plus ports and adapters, with one file per port and one file per adapter, without changing behaviour. Use when the user asks to decouple code from its I/O, make a backend swappable, introduce hexagonal / clean architecture, add seams for testing, or invokes /ports-and-adapters <path-or-subsystem>.
- ---
- # /ports-and-adapters
- Turn tangled code (policy mixed with files, network, processes, clocks, logging and locks) into:
- - a **core**: plain domain values (`model`) and pure policy (`core`), with no I/O;
- - **ports**: small interfaces the core owns, **one file per port**;
- - **adapters**: implementations of those ports, **one file per adapter**;
- - a **composition root** (`service`) that wires the production adapters as defaults.
- The refactor is **behaviour-preserving**. A layered safety net proves it, and the owner
- approves the port map before any code moves.
- The skill is **language-agnostic**. The layers, rules and gates are the same in every language;
- only the idioms change. In this file, *interface* means the language's abstraction mechanism (a
- Python `Protocol`, a TypeScript or Java or C# or Go `interface`, a Rust `trait`, a C++ abstract
- class), and *index file* means its package entry point (`__init__.py`, `index.ts`,
- `package-info`, `mod.rs`, a header). See `references/layouts.md` for each language's layout,
- idioms and architecture-test recipe.
- Argument: a path or subsystem name (`/ports-and-adapters src/billing`). With none, ask which
- subsystem; never refactor a whole repository in one pass.
- ## Rules that apply throughout
- 1. **No behaviour change.** If you find a bug or want to tighten something, list it under
- "Flagged changes" in the report and do it in a separate step the owner approves. Never fold it
- silently into the move.
- 2. **The repo's own rules win.** Read the repo's agent and contributor docs (`CLAUDE.md`,
- `AGENTS.md`, `CONTRIBUTING.md`, architecture docs) before touching anything. Code they pin to a
- module (safety checks, auth, permission logic) stays there. Its adapter only *delegates* to it.
- 3. **No speculative ports.** A seam becomes a port only for a real reason: a second implementation
- exists or is planned, a test needs a fake, or a rule requires the code to live elsewhere.
- Anything else stays inline.
- 4. **Dependencies point inward.** `model`, `core` and `ports` never import `adapters` or
- `service`. Adapters may import `model`, `ports` and `core`. An automated test enforces this.
- 5. **One concept per file.** Each port file holds exactly one interface. Each adapter file holds
- exactly one implementation. Registries (e.g. a map of kind name to adapter) live in the
- adapters' index file. Where the language forces a different unit (e.g. Go, where a package is a
- directory), keep the same rule: one port or adapter per file.
- 6. **No new dependencies.** Use the language's own interface mechanism. Don't add a DI framework
- unless the repo already uses one.
- 7. **Respect the repo's workflow.** Work on a branch or in a worktree, use the repo's own test
- runner and interpreter, and don't commit, push or open PRs unless the user asked.
- ## Process
- Follow these steps in order. A **Gate** means stop and do not continue until it passes or the
- owner answers.
- ### 1. Scope and read the rules
- - Confirm the subsystem and its entry points (who calls it).
- - Read the repo's rules (rule 2) and note anything that must not move.
- - Make or confirm a branch or worktree.
- ### 2. Baseline and characterize
- - Find the repo's real test command and toolchain version (CI config, `Makefile`, the build
- file: `package.json`, `pyproject.toml`, `pom.xml`, `build.gradle`, `go.mod`, `Cargo.toml`,
- `*.csproj`, `CMakeLists.txt`). Run the **full** suite and record the pass, skip and fail
- counts. A suite that fails to build or import because of the wrong toolchain is not a
- baseline.
- - Where the subsystem's behaviour is weakly tested, write **characterization tests** first. They
- pin today's outputs (return values, explain or log text, error messages, written files), and
- they must pass on the *old* code.
- - **Gate:** the suite is green and the counts are recorded.
- See `references/safety-net.md`.
- ### 3. Find the seams
- List every place the subsystem touches the outside world:
- - files and directories
- - network and HTTP
- - subprocesses
- - environment variables and config files
- - clocks and sleeps
- - randomness
- - threads, locks and semaphores
- - logging and printing
- - other modules' internals
- - anything the tests currently `patch` or `mock`
- Each one is a candidate port.
- ### 4. Draw the port map
- Fill in `references/port-map-template.md`: for each candidate, record its port name, the
- question it answers, its methods, the current code, its adapters, and the **reason** it earns a
- port (rule 3). Also list the seams you chose to leave inline, with why.
- - Ports are named for their **role** (`HealthProbe`, `Clock`, `OrderStore`). Adapters are named
- **technology plus role** (`HttpHealthProbe`, `SystemClock`, `PostgresOrderStore`). Fakes are
- `Fake` plus role.
- - Keep ports small, usually one to three methods. A port with many unrelated methods is two
- ports.
- - Port signatures use domain types, not library types. Where an existing in-repo type really is
- the contract, use it and say so in the doc comment.
- - **Gate:** show the map to the owner and wait for approval. Apply their edits before writing any
- code.
- ### 5. Extract the model
- Move the plain value types into `model` (records, data classes, structs, value objects). Strip
- infrastructure
- detail out of them. Settings only one backend reads become an opaque `settings` mapping, which
- only that backend's adapter validates and reads.
- ### 6. Write the ports, test-first
- For each port, in its own file:
- - the interface, with its **contract** in its doc comment: inputs, outputs, what each failure
- means, whether it may block, and its threading or async rules;
- - a fake in the tests;
- - a contract test that the fake passes. The production adapter will pass the same test.
- Expected outcomes ("down", "not found", "paused") are **values** at the port
- (`Health.down(reason)`). Exceptions are for misconfiguration and bugs.
- ### 7. Move code into adapters
- One implementation per file. Move the existing code **nearly verbatim**, so the diff reads as a
- move, and save renames for a separate step. Code that the repo's rules pin to a module stays
- there, and its adapter only calls it. Put registries in the adapters' index file.
- ### 8. Point the core at the ports
- Replace module-level callables, globals and patched functions with port parameters. Remove flag
- arguments (`dry_run=True`, `health=None`) by choosing an adapter instead (e.g. `AssumeHealthy`).
- The core must not import any adapter.
- ### 9. Add the composition root
- Add `service` (a class, a factory function, or a constructor in the language's idiom) that
- takes the config and builds the core with production
- adapters as defaults. Callers construct it and override an adapter only where the choice is
- genuinely theirs: a command-line flag, or a per-call value only the caller knows.
- ### 10. Rewire the callers
- Move every caller (CLI, handlers, jobs, other modules) onto the service, then delete the old
- module. Leave a re-export shim only if code outside the repository imports it, and say so in the
- report.
- ### 11. Prove it
- - **Parity:** run the old code (built from a backup or the base commit) and the new code side by
- side over a generated grid of inputs, comparing every output field. `scripts/parity.py` drives
- this for any language: you write a tiny driver for each side that reads a JSON case on stdin and
- prints a JSON result. The target is zero differences; anything else is a flagged change.
- - **Architecture tests:** run `scripts/check_layers.py`, which works for any language. Then
- encode the same rule in the repo's own suite with the language's native tool (see
- `references/layouts.md`), so CI keeps enforcing it. It fails if an inner layer imports an outer
- one, or if a port or adapter file declares more than one top-level type.
- Prove each check can fail: plant one bad include and one second type in a copy, and see
- both reported. A checker that cannot see a violation passes it.
- - **Frozen assertions:** during the move, tests may change their imports and wiring, but not what
- they assert. Diff the old and new assertions. The test count may only go up.
- - **Full suite:** run it with the same command as the baseline. The pass count must be at or above
- the baseline.
- - Optionally, run mutation testing on the core (mutmut, Stryker, PIT) to show the tests would
- catch a change.
- - **Gate:** every check above holds, or the failure is reported, not hidden.
- ### 12. Update the docs
- - **Package overview:** the package's doc comment or README gets the diagram (callers → service →
- core → ports ← adapters), a port → adapters table, and a "how to add a new X" line, which should
- be one new file plus one registry entry.
- - **Old names:** fix every doc that named the old module or symbols, including the repo's agent
- docs and any doc-sync checklists.
- ### 13. Report
- - **Layout:** before and after, as file trees, plus the approved port map.
- - **Numbers:** baseline vs final test counts, the parity result (cases compared, differences) and
- the architecture-test result.
- - **Flagged changes:** every behaviour difference, with a recommendation to keep or split.
- - **Not done:** anything left undone, and why.
- - **Gate:** the owner decides about committing, and the skill doesn't commit on its own.
- ## When not to use it
- - **Tiny tools with one backend and no tests:** in scripts like these, the indirection costs more
- than it buys.
- - **When a framework is already the adapter layer** (e.g. a thin web controller): refactor the
- domain behind it instead.
- - **When the real goal is a behaviour change:** do that before or after, never during.
- ## Files in this skill
- - `references/port-map-template.md`: the table approved at step 4.
- - `references/safety-net.md`: characterization tests, parity, frozen assertions, mutation
- testing.
- - `references/layouts.md`: per-language layout, port, adapter and fake snippets, and the
- architecture-test recipe (Python, TypeScript/JavaScript, Java/Kotlin, C#, Go, Rust, C++).
- - `references/clean-code-architecture.md`: how Clean Architecture, SOLID and Clean Code apply
- here.
- - `references/example.md`: a worked example on an open-source CLI (written in Python; the steps
- are the same in any language).
- - `scripts/check_layers.py`: a dependency-direction and one-type-per-file checker for any of the
- languages above. It needs Python 3.8+ to run, and only the standard library.
- - `scripts/parity.py`: the old-vs-new parity runner, which drives drivers written in any
- language.
README.md · README · 87 lines
- # ports-and-adapters
- A Claude Code skill that refactors a project in **any language**, or one subsystem of it, into a
- pure core plus **ports and adapters**: one file per port and one file per adapter. It works
- without changing behaviour, and a layered test safety net proves that.
- It follows Clean Architecture (dependencies point inward, ports are owned by the core, a single
- composition root) and Clean Code (names reveal role and technology, one concept per file,
- expected failures as values). It stops for your approval of the **port map** before any code
- moves.
- ## What it produces
- ```
- <subsystem>/
- model domain values, no I/O
- core policy, written against ports only
- service composition root: production adapters as defaults
- ports/ one interface per file
- adapters/ one implementation per file, registries in the index file
- ```
- A new backend then becomes one new adapter file plus a registry entry, and tests use fakes
- instead of patching.
- ## Installation
- Copy this directory into a Claude Code skills directory, either `.claude/skills/ports-and-adapters/`
- in a project or `~/.claude/skills/ports-and-adapters/` for all projects.
- ```sh
- git clone https://github.com/dmccoystephenson/ports-and-adapters ~/.claude/skills/ports-and-adapters
- ```
- ## Usage
- ```
- /ports-and-adapters src/billing
- ```
- The skill:
- 1. scopes the subsystem and reads the repo's own rules;
- 2. runs the baseline suite and adds characterization tests where coverage is thin;
- 3. finds the seams and drafts a **port map**, then waits for your approval;
- 4. extracts the model, writes the ports test-first, moves code into adapters, points the core at
- the ports, adds the composition root and rewires the callers;
- 5. proves the result: parity between old and new, architecture tests, frozen assertions, and the
- full suite at or above the baseline count;
- 6. updates the docs and reports, without committing anything on its own.
- The full process is in [`SKILL.md`](SKILL.md).
- ## What's inside
- | Path | Purpose |
- |---|---|
- | [`SKILL.md`](SKILL.md) | the process, gates and rules |
- | [`references/port-map-template.md`](references/port-map-template.md) | the table you approve |
- | [`references/safety-net.md`](references/safety-net.md) | characterization tests, parity, frozen assertions, mutation testing |
- | [`references/layouts.md`](references/layouts.md) | Python, TypeScript/JavaScript, Java/Kotlin, C#, Go, Rust and C++: layout, port, adapter and fake snippets, and CI enforcement |
- | [`references/clean-code-architecture.md`](references/clean-code-architecture.md) | how Clean Architecture, SOLID and Clean Code apply |
- | [`references/example.md`](references/example.md) | a worked example on an open-source CLI |
- | [`scripts/check_layers.py`](scripts/check_layers.py) | checks inward-only dependencies and one type per port/adapter file, for all of the languages above |
- | [`scripts/parity.py`](scripts/parity.py) | runs the old and new code over a generated case grid through small drivers in any language, and diffs the results |
- Both scripts need only Python 3.8+ and its standard library; the code they check can be in any
- of the languages above.
- ```sh
- python3 scripts/check_layers.py src/billing # OK / FAIL with the reasons
- python3 scripts/parity.py grid axes.json > cases.jsonl
- python3 scripts/parity.py run --cases cases.jsonl --old "node old.js" --new "node new.js"
- ```
- ## Development
- ```sh
- python3 -m unittest discover -s tests
- ```
- The tests cover `check_layers.py` on clean and violating fixtures in seven languages, and
- `parity.py` end to end.
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.