infrastructure-adapters
Skill2 starsChanged 5 months agoApache-2.0View on GitHub
Implement infrastructure adapters in src/infra/ behind port interfaces in src/ports/ — the only place side effects are allowed.
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- boundariesSkill
- cli-view-layerSkill
- effect-servicesSkill
- find-docsSkill
- model-routingSkill
- observabilitySkill
- phax-cliSkill
- phax-decide-planSkill
- phax-decide-reviewSkill
- phax-decide-specSkill
- phax-planningSkill
- phax-reviewSkill
- phax-specSkill
- state-machinesSkill
- validation-boundariesSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 56
Add a fake in src/infra/fakes/Fake<Name>.ts implementing the same tag.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Infrastructure adapters
The rule
Every infrastructure adapter must implement a port interface defined in
src/ports/. Adapters live in src/infra/ and are the only place where
side effects (filesystem, shell, git, Claude, editor, clock) are allowed.
Port/adapter pairs
Port (src/ports/) | Adapter (src/infra/) | What it wraps |
fs.ts (FileSystem) | fs.ts (NodeFileSystem) | node:fs/promises; writeAtomic uses temp-rename |
git.ts (Git) | git.ts (NodeGit) | git CLI via node:child_process execFile |
shell.ts (Shell) | shell.ts (NodeShell) | node:child_process spawn; opaque argv arrays, no interpolation |
backend.ts (Backend) | claudeCli.ts (ClaudeCliBackend) | claude CLI; streams JSONL, captures session id |
editor.ts (Editor) | editor.ts (NodeEditor) | Configured editor command |
lock.ts (Lock) | lock.ts (FileLock) | Lock files under ~/.phax/locks/ |
output.ts (OutputPort) | (in cli/) consoleOutput | console.log / console.error |
No shell interpolation
Shell and git adapters must never interpolate user-controlled data into a
command string. Always pass branch names, paths, and other arguments as
separate argv array tokens:
// Good
Command.make("git", "worktree", "add", worktreePath, branchName);
// Bad — do not do this
Command.make("sh", "-c", `git worktree add ${worktreePath} ${branchName}`);Atomic writes
FileSystem.writeAtomic(path, content) writes to <path>.tmp.<random> in the
same directory, fsyncs, then renames. This ensures readers never see a partial
write. All status JSON files and registry updates must use writeAtomic.
Fake adapters for tests
In-memory fakes for every port live in src/infra/fakes/. Use them in unit
and integration tests. Never use real filesystem, real git, or real claude
in the default test suite.
How to write a new adapter
- Define the port interface in
src/ports/<name>.tsas an EffectContext.Service. - Implement the adapter in
src/infra/<name>.tsas aLayer. - Add a fake in
src/infra/fakes/Fake<Name>.tsimplementing the same tag. - Provide the real adapter layer in
cli/main.ts; provide the fake in tests.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

