Clean Room Skill
whit3rabbit/clean-room-skill
Fluxo de clean-room para análise segura e implementação isolada de código
Ver no GitHubUma skill de fluxo de agentes para transformar análise de código-fonte autorizado em especificações comportamentais limpas, planos de implementação isolados e código de destino verificado. Implementa uma separação documentada entre leitura de fonte e trabalho de implementação limpa, reduzindo riscos de engenharia e contaminação de código.
Instalação
npx convez-ai whit3rabbit/clean-room-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Reduzir riscos legais ao implementar features baseadas em análise de código existente
- Criar especificações comportamentais limpas separadas de artefatos de implementação
- Documentar separação entre agentes contaminados (que leem fonte) e agentes limpos (que implementam)
Veredito

Ferramental especializado e bem arquitetado para workflows de engenharia que exigem separação rigorosa entre análise de fonte e implementação. Ideal para times que precisam mitigar riscos legais ou de propriedade intelectual em desenvolvimento guiado por código existente; não é legal advice, mas um POC funcional do modelo clean-room.
README
A tradução para o português deste README ainda está na fila.
Clean Room
Clean Room is an agent workflow for turning authorized source analysis into clean behavioral specs, clean implementation plans, and clean destination code. When no indexable source code is available, it can use authorized screenshots/images as contaminated fallback evidence for behavior specs.
It is a POC based on ideas from malus.sh. It is an engineering risk-reduction workflow, not legal advice, and it does not create a legal safe harbor.
What This Is / Does
Use this package when you need documented separation between source-reading work and clean implementation work.
It installs:
- Clean-room skills for Codex, Claude Code, and other agent runtime layouts.
- Role-agent prompts for contaminated analysis, clean planning, clean implementation, and final polish.
- JSON schemas and examples for durable workflow artifacts.
- Hook guardrails that help keep source material out of clean artifacts.
- A small CLI for runtime installation, bootstrap folders, preflight contracts, hook smoke tests, and the bounded inner clean-room runner.
The workflow creates clean behavioral spec packages and clean implementation outputs. It does not generate replacement code directly from source.
Core boundary:
- Contaminated roles may read authorized source or fallback visual evidence and write contaminated artifacts.
- Source-denied roles may read only clean artifacts, implementation roots, schemas, and approved public/reference roots.
- Clean implementation code is written only under the clean implementation root.
- Raw source, raw screenshots, source or visual paths, private identifiers, raw diffs, copied comments, copied UI text, and source-shaped pseudocode must not cross into clean handoff artifacts.
For the full boundary model, see docs/ARCHITECTURE.md. For CLI and troubleshooting details, see docs/REFERENCE.md.
Install
Requires Node.js >=22.
Recommended path:
npm install -g clean-room-skill
clean-room-skill
The first command installs the CLI. The second command starts the interactive installer for runtime files, skills, agents, and hooks.
For a direct global runtime install, pass the runtime flag:
clean-room-skill --claude --global --yes
clean-room-skill --codex --global --yes
clean-room-skill --opencode --global --yes
clean-room-skill --all --global --yes
If you do not want the CLI installed globally, run the same installer once through npx:
npx clean-room-skill@latest --claude --global --yes
npx clean-room-skill@latest --codex --global --yes
npx clean-room-skill@latest --all --global --yes
Those npx commands install the selected runtime files globally. You do not need to keep running npx to use the installed Claude Code, Pi, Codex, or other runtime entry points.
For edge cases such as ccsilo variants or modified Claude directories, add --config-dir <path-to-claude-config-root> to target that Claude config root explicitly. If Claude is launched through a wrapper, set CLEAN_ROOM_CLAUDE_EXECUTABLE=/absolute/path/to/wrapper; the installer runs that exact executable and rejects relative, cwd-local, and node_modules/.bin paths.
Claude global installs use Claude's plugin system for skills and agents, so entry points are namespaced as /clean-room:init, /clean-room:preflight, and /clean-room. The installer still manages hook files and migrates older standalone Claude skill copies out of the config root on reinstall or update.
Hook modes:
--hooks=safe: default. Hooks are installed but enforce only during clean-room role sessions with the required environment.--hooks=strict: fail-closed hook mode for dedicated Codex, Claude, or OpenCode clean-room homes.--hooks=copy-onlyor--no-hooks: copy hook files without registering runtime hook config.
Verified runtimes are Codex, Claude Code, and OpenCode. OpenCode support uses native skills, commands, and a generated local plugin bridge for hook enforcement. Other runtime layouts are installed on a best-effort basis. See docs/REFERENCE.md for the full support table and install roots.
Marketplace install is also supported.
Codex:
codex plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
Claude Code:
/plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
/plugin install clean-room@clean-room-skill
Pi:
pi install npm:clean-room-skill@latest
npx clean-room-skill@latest --pi --global --yes
Pi-native package install is preferred. This package declares pi.skills: ["./skills"], so pi install npm:clean-room-skill@latest lets Pi discover the bundled SKILL.md entry points directly. Use the npx ... --pi installer only when you want this repo's compatibility installer to manage the same files alongside other runtimes. Global Pi compatibility installs target ~/.pi/agent; local installs target .pi.
Both Pi install paths load bundled skills as /skill:<name>, for example /skill:clean-room. Pi installs do not currently register clean-room hooks. Installer-managed Pi layouts copy the hook scripts to hooks/clean-room/ for inspection and future bridge work, but those files are not active enforcement in Pi.
Pi hook enforcement would need a Pi extension, not a settings.json edit. This package does not ship that extension yet, so clean-room safety in Pi still depends on role separation, path isolation, schema validation, and any supported hook runtime used for enforcement.
Workflow
-
Initialize or bootstrap the run. Use
clean-room-skill init,/clean-room:init, or/skill:initto create neutral external run folders and record run preferences. The activeinit-config.jsonstays out of the clean implementation repository. -
Record the goal contract. Use
/clean-room:preflightor/skill:preflightfor the conversational flow, orclean-room-skill preflightfor artifact-first CLI setup. This creates or validatespreflight-goal.jsonon the contaminated/controller side before source discovery, attended mode, or unattended mode. -
Start the controller. Use
/clean-room:attendedor/skill:attendedfor human review gates. Use/clean-room:unattendedor/skill:unattendedonly after preflight allows bounded unattended work with finite iteration limits and no open questions. -
Refocus when state is unclear. Use
/clean-room:refocusor/skill:refocusto audit durable artifacts, compare them to declared scope, and route the run back to missed gates without adding scope.
Use /clean-room or /skill:clean-room when you want the skill to talk through setup, inspect where the run is, and decide whether to continue, refocus, resume, or start over.
The CLI also has a bounded inner-loop runner for already approved unattended spec slices:
clean-room-skill run \
--task-manifest ~/Documents/CleanRoom/task-1234abcd/contaminated/task-manifest.json \
--agent-runtime claude \
--max-iterations 3
The run command is not the normal starting point. It executes one bounded inner clean-room loop after the outer controller has created approved durable artifacts.
Claude Code skills use /clean-room:<name>. Pi skills use /skill:<name>. In Codex, invoke the clean-room plugin or bundled skills through @ or the skills UI.
Useful maintenance commands:
clean-room-skill doctor --runtime codex --hooks=safe
clean-room-skill status --global
clean-room-skill update --global --yes
Reference files:
- docs/REFERENCE.md: CLI flags, hook modes, troubleshooting, and local verification.
- docs/ARCHITECTURE.md: operating model, roles, environment, guardrails, and flow details.
- docs/HOOKS.md: hook install locations, generated matchers, and per-hook behavior.
- skills/clean-room/references/PROCESS.md: detailed clean-room process.
- skills/clean-room/references/LEAKAGE-RULES.md: clean handoff rules.
Development
Install dependencies:
npm ci --ignore-scripts
Run tests:
npm test
Run installer tests only:
npm run test:install
Run the full local verifier:
npm run verify
Documentation-only changes usually need review plus link/path checks, not the full test suite.
Useful development checks:
node --check bin/install.js
node --test tests/run.test.js
npm pack --dry-run
Python schema validation requires jsonschema with format extras:
python3 -m venv .venv
.venv/bin/python -m pip install "jsonschema[format]>=4.18,<5"
.venv/bin/python tests/validate_jsonschema.py
Use st for repository search.