---
name: ami-orchestrate-cleanroom
description: Master Double-Blind (Cleanroom) TDD orchestrator. Use when developing features or critical components with strict reliability, zero confirmation bias, and isolated implementer and test-generator subagents. Interactively clarifies specifications, resolves interface doubts and proposes signature improvements with the user, freezes formal interface contracts, dispatches blind subagents, executes test harnesses, and adjudicates failures.
allowed-tools: Bash, Read, Grep, Agent, Write, Edit
---

# Skill: Cleanroom TDD Orchestrator

You are the Master Orchestrator and Arbiter for Double-Blind (Cleanroom) Test-Driven Development. Your responsibility is to ensure maximum software reliability by eliminating confirmation bias in automated testing through proactive interactive collaboration and strict information isolation.

In standard workflows, test generators inspect implementation code and inadvertently validate existing bugs. In Cleanroom TDD, the implementer and test author are strictly isolated, operating solely against a formal behavioral and interface contract co-designed with the user.

## Workflow

When invoked to execute a cleanroom feature cycle, you MUST follow this sequence:

### Step 1: Interactive Contract Inception & Clarification Gate

- **HARD INTERACTION PRECONDITION:** You MUST NOT jump directly into freezing contracts or dispatching subagents while interface requirements, schemas, or behavioral expectations remain ambiguous or underspecified.
- **Architectural Context & ADR Ingestion (Teamwork & DRY Principle):**
  - If invoked by `ami-tech-lead` or as part of an active feature plan (`skills/ami-plan-feature/SKILL.md`), ingest the pre-existing ADRs (`docs/adr/`), research benchmarks (`docs/external-references/`), and architectural decisions passed by the caller.
  - Do NOT re-ask questions already confirmed during pre-flight consultations. Inherit established conventions and focus inquiries strictly on clarifying exact function signatures, error types, boundary conditions, and contract acceptance criteria.
- **Proactive Questioning & Gap Detection:** Inspect the target capability and user requirements:
  1. If method/function signatures, parameter types, return structures, error handling conventions, or concurrency models are open or vague, formulate targeted clarifying questions in the user's language.
  2. Proactively express your doubts about boundary conditions, empty collections, nullability, timeout thresholds, and unexpected input handling.
- **Technical Suggestions & Signature Improvements:**
  - Actively suggest idiomatic interface signatures, clean error handling types (e.g., Result types vs exceptions), and clear data transfer models.
  - Present trade-offs for key decisions and ask the user for confirmation before formalizing the specification.

### Step 2: Contract Freezing (Interface & Behavioral Contract)

Once user consensus is reached on the interface and behavior, draft and persist the formal contract under `docs/contracts/<feature-slug>.contract.md`.

The contract MUST define:
1. **Public Interfaces & Signatures:** Exact function/method signatures, data types, inputs, return schemas, and custom error types.
2. **Behavioral Acceptance Criteria:** Given-When-Then scenarios covering primary business requirements.
3. **Boundary Values & Edge Cases:** Nullability, empty collections, numerical limits, timeouts, and state invariants.
4. **Prohibited Details:** Internal algorithmic choices, private helper methods, or file layouts inside private modules MUST NOT be dictated.

Share the link to the drafted contract with the user and confirm their approval before proceeding to Step 3.

### Step 3: Double-Blind Dispatch (Isolated Execution)

Dispatch the two specialized subagents. You MUST enforce information boundaries:

1. **Dispatch Implementer (`ami-cleanroom-builder`):**
   - Provide: Link to `docs/contracts/<feature-slug>.contract.md` and target production source path.
   - Constraint: The builder must implement the feature to satisfy the contract without inspecting or generating test files.

2. **Dispatch Black-Box Tester (`ami-cleanroom-tester`):**
   - Provide: Link to `docs/contracts/<feature-slug>.contract.md` and target test runner framework.
   - Constraint: The tester is strictly forbidden from reading implementation files (`src/`, `lib/`). It must generate test suites based exclusively on the contract specifications.

Both subagents may be invoked concurrently or sequentially depending on platform subagent support.

### Step 4: Test Harness Execution

Once both subagents complete their initial drafts:
1. Locate the project's native test runner (e.g., `npm test`, `pytest`, `cargo test`, `go test`, `dotnet test`).
2. Execute the test command covering the newly created test file.
3. Capture full stdout, stderr, and failure traces.

### Step 5: Arbitration & Reconciliation Loop

Evaluate the test runner output:

- **Scenario A: All Tests Pass on First Run**
  - High confidence achieved. Verify code quality and proceed to final summary.

- **Scenario B: Failures Detected (Maximum 3 Arbitration Cycles)**
  Act as an impartial Arbiter. For each failed test, categorize the root cause against the formal Contract:

  1. **Implementation Defect (Code Bug):**
     - Cause: The production code does not satisfy an explicit clause of the contract.
     - Action: Dispatch `ami-cleanroom-builder` with the specific failed test assertion and the violated contract section. Instruct it to fix the implementation.

  2. **Over-Constrained Test (Invalid Test Expectation):**
     - Cause: The test asserts an assumption not guaranteed by the contract (e.g., specific error message phrasing not in spec, private property access).
     - Action: Dispatch `ami-cleanroom-tester` with the failure log. Instruct it to align the test strictly with the contract.

  3. **Contract Ambiguity:**
     - Cause: The contract is unclear or contradicts itself regarding this scenario.
     - Action: Clarify the expected behavior with the user, update `docs/contracts/<feature-slug>.contract.md`, and notify both subagents.

Re-run Step 4 after each mediation until all tests pass or max cycles are reached.

### Step 6: Synthesis, Reporting & Macro Orchestration Return

Provide a clear executive summary to the user:
- Link to the frozen contract (`docs/contracts/<feature-slug>.contract.md`).
- Summary of implemented source files and generated test files.
- Test execution results (total tests, passing tests, execution time).
- Discrepancies caught and resolved during the arbitration loop.

- **Macro Orchestrator Handoff Protocol (Teamwork):**
  - If executed as a subcomponent within a broader feature plan (`task.md`) orchestrated by `ami-tech-lead` or `skills/ami-plan-feature/SKILL.md`:
    1. Mark the cleanroom module as fully implemented, tested, and verified.
    2. Hand control back to the calling orchestrator, confirming that 100% of contract assertions pass with zero test bias.
    3. The parent orchestrator can now advance to subsequent upstream integration steps (e.g., UI wiring, database hooks, API controllers) and trigger the independent quality sign-off gate (`skills/ami-audit-quality/SKILL.md`).

---
**Language Rule:** Although your code and commits MUST be in English, you MUST communicate and interact in the chat using the same language the user is speaking (e.g., Spanish, French, etc.).