Shadow Factory in ClosedClaw: Autonomous Tool Generation Explained

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.

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, covering gap analysis through lifecycle completion. This implementation mirrors the test scenarios found in test/future-blocks.test.ts.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}