capability-distiller

name	capability-distiller
description	Use when distilling a bounded framework capability — a subsystem with state machine, external protocol (CLI/API/socket/process), multiple adapters, async/streaming, cancellation/timeout, or provider drift risk. Builds a fake harness BEFORE any local implementation, then verifies via conformance tests. Do NOT use for narrow pure functions; use function-distiller for those.

Capability Distiller (Mode C)

Install destination: copy this folder to .agents/skills/capability-distiller/ in your target repo (Codex / AGENTS.md-compatible agents). install.sh does it for you.

Purpose

Distill a bounded framework capability into a local, minimal, conformance-tested implementation that does not copy upstream code. The unit of reuse here is not a function contract; it is:

Capability = boundary + protocol + state machine + adapters + fixtures + conformance tests + drift policy

If your target is a single pure function, stop and use function-distiller instead.

When to activate

Activate this skill (Mode C) when any of these signals are present:

• target invokes / owns a subprocess, daemon, or watcher
• there is a protocol on the wire (CLI / HTTP / socket / file / env)
• the target has visible states beyond cache (running / canceled / timeout / failed)
• there are 2+ adapter implementations for the same capability
• output is streamed / event-driven
• callers can cancel or time out mid-execution
• upstream provider versions are expected to drift

Required inputs

If missing, write them down as unknowns in the capability brief and stop:

• target repo or local path
• target capability (one phrase)
• local use case
• must_keep / must_drop lists
• constraints (language, runtime, deps, distribution)
• legal posture (open-source / closed-source / public-api)

Phase 0 — Triage + Mode + Strategy

Use prompts/11_mode_selection.md. Return:

• mode = capability (otherwise switch skill)
• strategy = wrap | fork | distill | reimplement | no-go — distill is default
• triage decision = GO | SPIKE | NO-GO

Scaffold:

python3 scripts/make_distillation_workspace.py <target> --mode capability --repo <owner/repo>

This drops the capability templates into .distillations/<target>/.

Phase 1 — Research

Use the same hierarchy as Mode A (DeepWiki → gh / git / rg → tests/docs → local code) but pay attention to:

• the actual protocol (commands, headers, files, sockets, exit codes)
• visible states in upstream code or runtime traces
• which behaviors are accidental vs contractual
• provider versions and how upstream advertises them

Notes go to research-notes.md. Every claim cites a source/test/doc/observation.

Phase 2 — Capability Map

Write capability-map.md from templates/capability-map-template.md. Required:

• capability statement
• sub-capabilities
• inside-scope vs outside-scope boundaries
• cross-cuts (logging / config / persistence / concurrency / errors / cleanup)
• adapter boundary
• excluded responsibilities

Do NOT implement until the map is reviewed.

Phase 3 — Spec set

Write the spec set:

• functional-spec.md — the same template as Mode A; describes the normalized contract
• protocol-spec.md — REQUIRED if external_protocol = true
• state-machine-spec.md — REQUIRED if state_machine = true
• adapter-matrix.md — REQUIRED if multi_adapter = true
• event-schema.md — REQUIRED if streaming_events = true

Score against references/protocol-spec-rubric.md and references/state-machine-rubric.md. Below 8/10 → revise.

Phase 4 — Harness FIRST

Capability mode inverts Mode A: write the fake harness before the implementation.

1. Add scenarios to conformance-plan.md.
2. Wire each scenario into scripts/fake_cli.py (configure or extend).
3. Capture golden traces under tests/fixtures/conformance/F-NNN.jsonl.
4. Conformance tests are written against the fake.

See references/harness-first-pattern.md.

Phase 5 — Implement

Now write original code. Adapters are translators, not extenders. Use prompts/15_capability_clean_room_implementation.md to spawn a fresh subagent if license/copying risk is medium or high.

Files:

src/<capability_module>.*
src/adapters/<provider>.*
tests/test_*_unit.*
tests/test_*_conformance.*
.distillations/<target>/implementation-plan.md

Phase 6 — Verify

Run before claiming done:

• unit tests
• conformance tests against the fake (must equal goldens with scripts/compare_events.py)
• at least one live smoke test per supported provider, behind a --live flag
• failure-mode tests (cancel, timeout, escape)

Record in verification-report.md. The lint refuses to certify Decision: pass if any test file still contains REASON_NOT_IMPLEMENTED / pytest.skip / pytest.mark.xfail.

Phase 7 — Drift + Review

Write drift-policy.md if provider_drift = true. Verifier signs off in verification-report.md. For closed-source / public-api targets, the report MUST include the License: line and the observer/implementer/verifier role separation block (lint enforces).

Final answer format

Mode: capability
Strategy: <wrap | fork | distill | reimplement | no-go>
Decision: GO / SPIKE / NO-GO
Capability boundary (one paragraph):
Files changed:
- ...
Conformance:
- N scenarios, M passing
Live smoke:
- provider X: pass / pending
Known limitations:
- ...
Maintenance notes (drift):
- ...