# Shadow Factory in ClosedClaw: Autonomous Tool Generation Explained

> Discover the Shadow Factory in ClosedClaw. Learn how this autonomous component generates new tools by identifying capability gaps and optimizing agents.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: deep-dive
- Published: 2026-02-25

---

**The Shadow Factory is the core autonomous component in ClosedClaw that transforms unmet user intents into fully-featured `.claws` tools by scanning for capability gaps, drafting new agents, and iteratively optimizing them through telemetry-driven feedback loops.**

The **Shadow Factory** enables the ClosedClaw ecosystem to evolve without manual intervention. As implemented in the `asafelobotomy/closedclaw` repository, this module autonomously discovers missing capabilities and scaffolds new tooling through a strict three-stage pipeline defined in [`src/agents/clawtalk/shadow-factory.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/clawtalk/shadow-factory.ts).

## The Three-Stage Autonomous Pipeline

The Shadow Factory converts an unmet user intent into a production-ready tool by following a deterministic pipeline. Each stage produces specific artifacts that feed into the next, creating a closed loop of continuous improvement.

### Step A – Dependency Analysis with `analyzeGaps`

The pipeline begins with **Dependency Analysis**, where the factory scans the current environment—including CLI tools, APIs, databases, and existing agents—to identify interaction gaps. The `analyzeGaps` function (lines 58-86) compares user requests against available capabilities, flagging unmet needs that require new tooling.

This function evaluates the environment context against existing tools like `web_search` or `calculator`, producing a gap report that drives the subsequent drafting phase.

### Step B – Drafting and Fuzzing with `generateDraft`

Once gaps are identified, the **Drafting Sub-agent** generates a provisional `.claws` file describing the new tool. The `generateDraft` function (lines 102-128) creates the specification, while `recordFuzzResults` (lines 133-149) executes lightweight fuzz tests and captures pass/fail metrics.

This stage validates the draft against synthetic inputs before production exposure, recording test outcomes that inform the optimization phase.

### Step C – Optimization and Auto-Rewriting with `evaluateOptimization`

The final stage consumes telemetry—including success-rate, correction-rate, and latency—to determine if the tool requires refinement. The `evaluateOptimization` function (lines 155-185) triggers an **auto-rewrite** when performance thresholds are breached, sending the tool back through the drafting phase for iterative improvement.

When latency exceeds acceptable thresholds or success rates drop, the system generates a rewrite recommendation, enabling autonomous evolution without human intervention.

## Lifecycle Management and State Machine Enforcement

Beyond generation, the Shadow Factory enforces a strict **state machine** that governs tool maturity through the `ShadowToolState` type. This prevents illegal transitions—such as jumping from *reconnaissance* directly to *deployment*—ensuring every tool passes mandatory validation gates.

The `createShadowTool` function (lines 191-203) initializes new tools in the reconnaissance phase, while `advancePhase` (lines 207-244) manages legal transitions between states like `drafting`, `sandbox_testing`, `verification`, and `monitoring`. This architectural contract ensures that scaffolding-only components delegate heavy lifting (WASM compilation, sandbox execution) to external systems while maintaining strict lifecycle integrity.

## Practical Implementation of the Shadow Factory Pipeline

Below is a complete example demonstrating the public API exported from [`shadow-factory.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/shadow-factory.ts), covering gap analysis through lifecycle completion. This implementation mirrors the test scenarios found in [`test/future-blocks.test.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/test/future-blocks.test.ts).

```typescript
import {
  analyzeGaps,
  generateDraft,
  recordFuzzResults,
  evaluateOptimization,
  createShadowTool,
  advancePhase,
} from "./agents/clawtalk/shadow-factory.js";

// 1️⃣ Dependency analysis – a user wants to invoice Stripe data
const env = {
  cliTools: [],
  apis: ["stripe.com"],
  databases: [],
  repositories: [],
};
const gaps = analyzeGaps(
  "Generate invoice from Stripe data",
  ["web_search", "calculator"],
  env,
).gaps;

// 2️⃣ Draft the tool (only one gap in this simple case)
const draft = generateDraft(gaps[0], [{ name: "stripe", level: "read" }]);

// Simulate a successful fuzz run
const finishedDraft = recordFuzzResults(draft, 1000, 1000, []);

// 3️⃣ Optimization – assume telemetry shows high latency
const signal = evaluateOptimization(0.96, 0.05, 7000);
if (signal.rewriteRecommended) {
  console.log("Rewrite needed:", signal.reason);
}

// 4️⃣ Lifecycle management
let tool = createShadowTool("stripe_invoice_tool");
tool = advancePhase(tool, "drafting", "Gap identified");
tool = advancePhase(tool, "sandbox_testing", "Draft generated");
tool = advancePhase(tool, "verification", "All sandbox tests passed");
tool = advancePhase(tool, "deployment", "Verification proof accepted");
tool = advancePhase(tool, "monitoring", "Deployed to production");

console.log(tool);

```

The repository's test suite validates each component: gap detection confirms missing capabilities like Stripe invoicing, drafting tests verify content creation logic, optimization tests trigger rewrites based on telemetry, and lifecycle tests enforce valid state transitions while rejecting illegal ones.

## Summary

- The **Shadow Factory** in ClosedClaw autonomously bridges capability gaps by analyzing dependencies, drafting new `.claws` tools, and optimizing them via telemetry feedback.
- The three-stage pipeline—**Dependency Analysis**, **Drafting**, and **Optimization**—is fully implemented in [`src/agents/clawtalk/shadow-factory.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/clawtalk/shadow-factory.ts) with functions like `analyzeGaps` (lines 58-86), `generateDraft` (lines 102-128), and `evaluateOptimization` (lines 155-185).
- **State machine enforcement** via `createShadowTool` (lines 191-203) and `advancePhase` (lines 207-244) prevents premature deployment by mandating progression through reconnaissance, drafting, sandbox testing, verification, and monitoring phases.
- The design is intentionally **scaffolding-only**, delegating WASM compilation and sandbox execution to external components while maintaining strict architectural contracts for data production and phase transitions.

## Frequently Asked Questions

### What is the primary purpose of the Shadow Factory in ClosedClaw?

The Shadow Factory serves as the autonomous development engine that transforms unmet user intents into production-ready tools. It continuously scans for missing capabilities and iteratively drafts, tests, and refines new agents without requiring manual coding, effectively enabling a self-evolving ecosystem of tools.

### How does the Shadow Factory determine when to create a new tool?

The factory uses `analyzeGaps` (lines 58-86) to compare incoming user requests against the current environment—including available CLI tools, APIs, and existing agents. When the analysis identifies an interaction gap that cannot be satisfied by existing tooling, it triggers the drafting phase to scaffold a solution.

### What triggers an automatic rewrite of a generated tool?

The `evaluateOptimization` function (lines 155-185) monitors telemetry metrics including success-rate, correction-rate, and latency. When these metrics fall below performance thresholds—such as high latency exceeding 7000ms or elevated correction rates—the system recommends an auto-rewrite, sending the tool back through the drafting pipeline for refinement.

### How does the Shadow Factory prevent premature deployment of unfinished tools?

Through the `ShadowToolState` state machine managed by `createShadowTool` (lines 191-203) and `advancePhase` (lines 207-244). These functions enforce valid phase transitions, rejecting illegal moves like jumping from reconnaissance directly to deployment, ensuring every tool passes through mandatory sandbox testing and verification stages before reaching production.