/sc-clean-room

name: sc-clean-room
description: >
  Clean-room reimplementation of a repository, library, API, protocol, or other software artifact.
  This skill SHOULD be used when the user wants to create a functionally equivalent implementation of an existing artifact
  without copying its internal design or expression. NOT for refactoring existing code.
argument-hint: "[target: repo URL, local path, or artifact name] [optional: scope or focus]"
allowed-tools: Task, Read, Bash, Grep, Glob, AskUserQuestion, TodoWrite, WebSearch, WebFetch, Write, Edit

Clean-Room Design

A structured approach to reimplementing a software artifact without copying its internals. A **discovery agent** examines the original and writes a behavioral specification with fixtures. Then a **separate implementation agent** builds from that specification alone. Fixtures captured during discovery verify the reimplementation in Phase 4.

Compaq used this technique in 1982 to clone the IBM PC BIOS — one team documented what the BIOS did, a second team (who had never seen IBM's code) wrote compatible firmware from those docs. Copyright protects expression, not ideas. A functional spec describes ideas.

EXECUTION MODEL

**Phases 0 through 6 run in sequence. The core phases (1-4) MUST NOT be skipped or reordered.**

• Phase 0 establishes scope and pins the artifact version
• Phase 1 (Discovery) examines the original via a `Task()` agent, produces observations and fixtures
• Phase 2 (Specify) distills observations into a clean functional spec
• Phase 3 (Implement) builds from the spec in a fresh `Task()` agent that has never seen the original
• Phase 4 (Verify) confirms equivalence via spec compliance and fixture replay
• Phases 5-6 present results and offer next steps

**After each phase, present the output to the user and wait for approval before proceeding.**

Isolation

Discovery and Implementation run in **separate `Task()` agents** with no shared context. The implementation agent receives only the specification file path. The original artifact, discovery notes, and fixtures never enter the implementation agent's prompt.

This provides process-level isolation, not OS-level sandboxing. For stronger isolation (IP-sensitive work), run Phase 3 in an entirely separate Claude session — the artifacts this skill produces support that handoff cleanly.

Phase 0: Resolve Target and Scope

Parse $ARGUMENTS. The first argument is the target, anything after is a scope or focus hint.

Target resolution

| Argument | Target | Version pin | |----------|--------|-------------| | Repository URL | Clone or fetch the repo | Record commit SHA | | Local path | Examine directly | Record git commit SHA; if not a git repo, record a checksum | | Package name | Locate via registry (npm, PyPI, RubyGems, crates.io, etc.) | Record exact package version | | Protocol or API name | Fetch public docs and specs | Record document revision or access date |

**Version pinning is mandatory.** Record an immutable identifier so all artifacts reference the same version.

Scope negotiation

Use `AskUserQuestion`:

• Which parts to reimplement (the whole thing, a subset, a single module)
• Target language and runtime (same as original, or different)
• Quality attributes that matter (performance parity, API compatibility, simplified interface)
• What's explicitly out of scope

Tell the user: "Target: [what]. Scope: [boundaries]. Language: [target stack]."

Run directory

**Slug**: `<artifact-name>-<version-prefix>` (lowercase, hyphens). Create with `mkdir -p .agent-history/clean-room/<slug>`.

Run `git check-ignore -q .agent-history/` — if it fails, warn the user to add the ignore rule.

If the directory already exists, ask: start fresh, resume, or abort.

Classify the artifact

| Type | Discovery focus | |------|-----------------| | **Library/Package** | Exported functions, types, behavior contracts | | **CLI Tool** | Command interface, input/output formats, exit codes | | **API/Service** | Routes, request/response schemas, error codes | | **Protocol** | Message types, sequencing, state transitions | | **Data Format** | Syntax, semantics, edge cases, error recovery | | **Algorithm** | Inputs, outputs, invariants, complexity characteristics |

Phase 1: Discovery (The Dirty Room)

Examine the original to document **what it does** (not how) and capture **behavioral fixtures** for verification.

**BLOCKING**: Complete discovery before moving to Phase 2.

Launch as a `Task()` agent. This agent reads the original freely. Its output goes to disk — the orchestrator reads those files afterward but does NOT pass the agent's context into later phases.

Task(
  description: "Clean-room discovery: examine original artifact",
  prompt: """
  ## Role: Discovery Agent (Dirty Room)

  Examine the original artifact and produce two deliverables:
  1. A behavioral discovery document
  2. A behavioral fixtures file

  Target: [resolved target from Phase 0]
  Scope: [scope from Phase 0]
  Source version: [pinned version from Phase 0]

  ## What to document
  - Public interface: function signatures, types, config options, error types
  - Behavioral contracts: input/output mappings, side effects, edge cases
  - Integration surface: dependencies, consumers, environment expectations
  - Non-functional characteristics: performance envelope, concurrency model

  ## What NOT to document (clean-room rule)
  - Internal data structures and their layout
  - Private helper functions and their signatures
  - Optimization techniques and implementation tricks
  - Comments, variable names, or code organization from the original

  ## Behavioral fixtures
  Capture black-box input/output recordings. Coverage requirements:
  - At least one fixture per public interface element
  - At least one per documented error condition
  - Edge-case fixtures for behaviors with boundary conditions
  - For stateful artifacts: fixtures covering key state transitions
  Scale with the artifa