Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dmccoystephenson--ports-and-adapters/badge.svg)](/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

i

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
  1. ---
  2. name: ports-and-adapters
  3. 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>.
  4. ---
  5. # /ports-and-adapters
  6. Turn tangled code (policy mixed with files, network, processes, clocks, logging and locks) into:
  7. - a **core**: plain domain values (`model`) and pure policy (`core`), with no I/O;
  8. - **ports**: small interfaces the core owns, **one file per port**;
  9. - **adapters**: implementations of those ports, **one file per adapter**;
  10. - a **composition root** (`service`) that wires the production adapters as defaults.
  11. The refactor is **behaviour-preserving**. A layered safety net proves it, and the owner
  12. approves the port map before any code moves.
  13. The skill is **language-agnostic**. The layers, rules and gates are the same in every language;
  14. only the idioms change. In this file, *interface* means the language's abstraction mechanism (a
  15. Python `Protocol`, a TypeScript or Java or C# or Go `interface`, a Rust `trait`, a C++ abstract
  16. class), and *index file* means its package entry point (`__init__.py`, `index.ts`,
  17. `package-info`, `mod.rs`, a header). See `references/layouts.md` for each language's layout,
  18. idioms and architecture-test recipe.
  19. Argument: a path or subsystem name (`/ports-and-adapters src/billing`). With none, ask which
  20. subsystem; never refactor a whole repository in one pass.
  21. ## Rules that apply throughout
  22. 1. **No behaviour change.** If you find a bug or want to tighten something, list it under
  23. "Flagged changes" in the report and do it in a separate step the owner approves. Never fold it
  24. silently into the move.
  25. 2. **The repo's own rules win.** Read the repo's agent and contributor docs (`CLAUDE.md`,
  26. `AGENTS.md`, `CONTRIBUTING.md`, architecture docs) before touching anything. Code they pin to a
  27. module (safety checks, auth, permission logic) stays there. Its adapter only *delegates* to it.
  28. 3. **No speculative ports.** A seam becomes a port only for a real reason: a second implementation
  29. exists or is planned, a test needs a fake, or a rule requires the code to live elsewhere.
  30. Anything else stays inline.
  31. 4. **Dependencies point inward.** `model`, `core` and `ports` never import `adapters` or
  32. `service`. Adapters may import `model`, `ports` and `core`. An automated test enforces this.
  33. 5. **One concept per file.** Each port file holds exactly one interface. Each adapter file holds
  34. exactly one implementation. Registries (e.g. a map of kind name to adapter) live in the
  35. adapters' index file. Where the language forces a different unit (e.g. Go, where a package is a
  36. directory), keep the same rule: one port or adapter per file.
  37. 6. **No new dependencies.** Use the language's own interface mechanism. Don't add a DI framework
  38. unless the repo already uses one.
  39. 7. **Respect the repo's workflow.** Work on a branch or in a worktree, use the repo's own test
  40. runner and interpreter, and don't commit, push or open PRs unless the user asked.
  41. ## Process
  42. Follow these steps in order. A **Gate** means stop and do not continue until it passes or the
  43. owner answers.
  44. ### 1. Scope and read the rules
  45. - Confirm the subsystem and its entry points (who calls it).
  46. - Read the repo's rules (rule 2) and note anything that must not move.
  47. - Make or confirm a branch or worktree.
  48. ### 2. Baseline and characterize
  49. - Find the repo's real test command and toolchain version (CI config, `Makefile`, the build
  50. file: `package.json`, `pyproject.toml`, `pom.xml`, `build.gradle`, `go.mod`, `Cargo.toml`,
  51. `*.csproj`, `CMakeLists.txt`). Run the **full** suite and record the pass, skip and fail
  52. counts. A suite that fails to build or import because of the wrong toolchain is not a
  53. baseline.
  54. - Where the subsystem's behaviour is weakly tested, write **characterization tests** first. They
  55. pin today's outputs (return values, explain or log text, error messages, written files), and
  56. they must pass on the *old* code.
  57. - **Gate:** the suite is green and the counts are recorded.
  58. See `references/safety-net.md`.
  59. ### 3. Find the seams
  60. List every place the subsystem touches the outside world:
  61. - files and directories
  62. - network and HTTP
  63. - subprocesses
  64. - environment variables and config files
  65. - clocks and sleeps
  66. - randomness
  67. - threads, locks and semaphores
  68. - logging and printing
  69. - other modules' internals
  70. - anything the tests currently `patch` or `mock`
  71. Each one is a candidate port.
  72. ### 4. Draw the port map
  73. Fill in `references/port-map-template.md`: for each candidate, record its port name, the
  74. question it answers, its methods, the current code, its adapters, and the **reason** it earns a
  75. port (rule 3). Also list the seams you chose to leave inline, with why.
  76. - Ports are named for their **role** (`HealthProbe`, `Clock`, `OrderStore`). Adapters are named
  77. **technology plus role** (`HttpHealthProbe`, `SystemClock`, `PostgresOrderStore`). Fakes are
  78. `Fake` plus role.
  79. - Keep ports small, usually one to three methods. A port with many unrelated methods is two
  80. ports.
  81. - Port signatures use domain types, not library types. Where an existing in-repo type really is
  82. the contract, use it and say so in the doc comment.
  83. - **Gate:** show the map to the owner and wait for approval. Apply their edits before writing any
  84. code.
  85. ### 5. Extract the model
  86. Move the plain value types into `model` (records, data classes, structs, value objects). Strip
  87. infrastructure
  88. detail out of them. Settings only one backend reads become an opaque `settings` mapping, which
  89. only that backend's adapter validates and reads.
  90. ### 6. Write the ports, test-first
  91. For each port, in its own file:
  92. - the interface, with its **contract** in its doc comment: inputs, outputs, what each failure
  93. means, whether it may block, and its threading or async rules;
  94. - a fake in the tests;
  95. - a contract test that the fake passes. The production adapter will pass the same test.
  96. Expected outcomes ("down", "not found", "paused") are **values** at the port
  97. (`Health.down(reason)`). Exceptions are for misconfiguration and bugs.
  98. ### 7. Move code into adapters
  99. One implementation per file. Move the existing code **nearly verbatim**, so the diff reads as a
  100. move, and save renames for a separate step. Code that the repo's rules pin to a module stays
  101. there, and its adapter only calls it. Put registries in the adapters' index file.
  102. ### 8. Point the core at the ports
  103. Replace module-level callables, globals and patched functions with port parameters. Remove flag
  104. arguments (`dry_run=True`, `health=None`) by choosing an adapter instead (e.g. `AssumeHealthy`).
  105. The core must not import any adapter.
  106. ### 9. Add the composition root
  107. Add `service` (a class, a factory function, or a constructor in the language's idiom) that
  108. takes the config and builds the core with production
  109. adapters as defaults. Callers construct it and override an adapter only where the choice is
  110. genuinely theirs: a command-line flag, or a per-call value only the caller knows.
  111. ### 10. Rewire the callers
  112. Move every caller (CLI, handlers, jobs, other modules) onto the service, then delete the old
  113. module. Leave a re-export shim only if code outside the repository imports it, and say so in the
  114. report.
  115. ### 11. Prove it
  116. - **Parity:** run the old code (built from a backup or the base commit) and the new code side by
  117. side over a generated grid of inputs, comparing every output field. `scripts/parity.py` drives
  118. this for any language: you write a tiny driver for each side that reads a JSON case on stdin and
  119. prints a JSON result. The target is zero differences; anything else is a flagged change.
  120. - **Architecture tests:** run `scripts/check_layers.py`, which works for any language. Then
  121. encode the same rule in the repo's own suite with the language's native tool (see
  122. `references/layouts.md`), so CI keeps enforcing it. It fails if an inner layer imports an outer
  123. one, or if a port or adapter file declares more than one top-level type.
  124. Prove each check can fail: plant one bad include and one second type in a copy, and see
  125. both reported. A checker that cannot see a violation passes it.
  126. - **Frozen assertions:** during the move, tests may change their imports and wiring, but not what
  127. they assert. Diff the old and new assertions. The test count may only go up.
  128. - **Full suite:** run it with the same command as the baseline. The pass count must be at or above
  129. the baseline.
  130. - Optionally, run mutation testing on the core (mutmut, Stryker, PIT) to show the tests would
  131. catch a change.
  132. - **Gate:** every check above holds, or the failure is reported, not hidden.
  133. ### 12. Update the docs
  134. - **Package overview:** the package's doc comment or README gets the diagram (callers → service →
  135. core → ports ← adapters), a port → adapters table, and a "how to add a new X" line, which should
  136. be one new file plus one registry entry.
  137. - **Old names:** fix every doc that named the old module or symbols, including the repo's agent
  138. docs and any doc-sync checklists.
  139. ### 13. Report
  140. - **Layout:** before and after, as file trees, plus the approved port map.
  141. - **Numbers:** baseline vs final test counts, the parity result (cases compared, differences) and
  142. the architecture-test result.
  143. - **Flagged changes:** every behaviour difference, with a recommendation to keep or split.
  144. - **Not done:** anything left undone, and why.
  145. - **Gate:** the owner decides about committing, and the skill doesn't commit on its own.
  146. ## When not to use it
  147. - **Tiny tools with one backend and no tests:** in scripts like these, the indirection costs more
  148. than it buys.
  149. - **When a framework is already the adapter layer** (e.g. a thin web controller): refactor the
  150. domain behind it instead.
  151. - **When the real goal is a behaviour change:** do that before or after, never during.
  152. ## Files in this skill
  153. - `references/port-map-template.md`: the table approved at step 4.
  154. - `references/safety-net.md`: characterization tests, parity, frozen assertions, mutation
  155. testing.
  156. - `references/layouts.md`: per-language layout, port, adapter and fake snippets, and the
  157. architecture-test recipe (Python, TypeScript/JavaScript, Java/Kotlin, C#, Go, Rust, C++).
  158. - `references/clean-code-architecture.md`: how Clean Architecture, SOLID and Clean Code apply
  159. here.
  160. - `references/example.md`: a worked example on an open-source CLI (written in Python; the steps
  161. are the same in any language).
  162. - `scripts/check_layers.py`: a dependency-direction and one-type-per-file checker for any of the
  163. languages above. It needs Python 3.8+ to run, and only the standard library.
  164. - `scripts/parity.py`: the old-vs-new parity runner, which drives drivers written in any
  165. language.
README.md · README · 87 lines
  1. # ports-and-adapters
  2. A Claude Code skill that refactors a project in **any language**, or one subsystem of it, into a
  3. pure core plus **ports and adapters**: one file per port and one file per adapter. It works
  4. without changing behaviour, and a layered test safety net proves that.
  5. It follows Clean Architecture (dependencies point inward, ports are owned by the core, a single
  6. composition root) and Clean Code (names reveal role and technology, one concept per file,
  7. expected failures as values). It stops for your approval of the **port map** before any code
  8. moves.
  9. ## What it produces
  10. ```
  11. <subsystem>/
  12. model domain values, no I/O
  13. core policy, written against ports only
  14. service composition root: production adapters as defaults
  15. ports/ one interface per file
  16. adapters/ one implementation per file, registries in the index file
  17. ```
  18. A new backend then becomes one new adapter file plus a registry entry, and tests use fakes
  19. instead of patching.
  20. ## Installation
  21. Copy this directory into a Claude Code skills directory, either `.claude/skills/ports-and-adapters/`
  22. in a project or `~/.claude/skills/ports-and-adapters/` for all projects.
  23. ```sh
  24. git clone https://github.com/dmccoystephenson/ports-and-adapters ~/.claude/skills/ports-and-adapters
  25. ```
  26. ## Usage
  27. ```
  28. /ports-and-adapters src/billing
  29. ```
  30. The skill:
  31. 1. scopes the subsystem and reads the repo's own rules;
  32. 2. runs the baseline suite and adds characterization tests where coverage is thin;
  33. 3. finds the seams and drafts a **port map**, then waits for your approval;
  34. 4. extracts the model, writes the ports test-first, moves code into adapters, points the core at
  35. the ports, adds the composition root and rewires the callers;
  36. 5. proves the result: parity between old and new, architecture tests, frozen assertions, and the
  37. full suite at or above the baseline count;
  38. 6. updates the docs and reports, without committing anything on its own.
  39. The full process is in [`SKILL.md`](SKILL.md).
  40. ## What's inside
  41. | Path | Purpose |
  42. |---|---|
  43. | [`SKILL.md`](SKILL.md) | the process, gates and rules |
  44. | [`references/port-map-template.md`](references/port-map-template.md) | the table you approve |
  45. | [`references/safety-net.md`](references/safety-net.md) | characterization tests, parity, frozen assertions, mutation testing |
  46. | [`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 |
  47. | [`references/clean-code-architecture.md`](references/clean-code-architecture.md) | how Clean Architecture, SOLID and Clean Code apply |
  48. | [`references/example.md`](references/example.md) | a worked example on an open-source CLI |
  49. | [`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 |
  50. | [`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 |
  51. Both scripts need only Python 3.8+ and its standard library; the code they check can be in any
  52. of the languages above.
  53. ```sh
  54. python3 scripts/check_layers.py src/billing # OK / FAIL with the reasons
  55. python3 scripts/parity.py grid axes.json > cases.jsonl
  56. python3 scripts/parity.py run --cases cases.jsonl --old "node old.js" --new "node new.js"
  57. ```
  58. ## Development
  59. ```sh
  60. python3 -m unittest discover -s tests
  61. ```
  62. The tests cover `check_layers.py` on clean and violating fixtures in seven languages, and
  63. `parity.py` end to end.
  64. ## License
  65. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.