crucible

Crucible — Autonomous Document Perfecter

A Claude Code plugin that takes raw human input (brain-dump transcript, meeting notes, messy first draft, pile of references) plus a target document type and produces a single canonical document that has been autonomously researched, epistemically tagged, stress-tested, citation-backed, and refined across multiple iterations until it meets a hard "perfected" bar.

Architecture

Crucible is markdown-and-config only. No scripts, no hooks, no MCP servers. Three pieces work together:

• Skill (skills/perfect/) — the entry point. SKILL.md is the trigger surface and execution flow. REFERENCE.md is methodology depth. PROMPT-TEMPLATE.md is the mission brief assembled per run.
• Subagent (agents/crucible-author.md) — the worker. Holds the persona, the methodology, and the five completion conditions. Writes the working document each iteration and decides when to emit the completion promise.
• Loop engine — depends on the ralph-wiggum plugin (must be installed separately). Ralph's Stop hook re-feeds the mission brief each iteration until the subagent emits <promise>PERFECTED</promise> or <promise>CAPPED</promise>.

Per-iteration methodology:

• Iteration 1 — Hypothesis Pass. Draft the full document. Tag every claim [CONFIRMED] / [HYPOTHESIS] / [UNKNOWN] / [CONCERN].
• Iterations 2+ — Research Pass (close [UNKNOWN]s) → Critique Pass (three naive questions surfacing failure modes) → Refine Pass (tighten, resolve contradictions) → Stop Check (evaluate the five completion conditions).

Installation

Prerequisite

Install ralph-wiggum first. Crucible spawns its loop via /ralph-loop.

# Example — exact marketplace path may vary on your machine
claude plugin install ralph-wiggum

macOS / iMac (Leo's primary)

git clone https://github.com/Knight-Ventures-Inc/crucible-plugin.git ~/kv-projects/crucible-plugin
claude plugin marketplace add ~/kv-projects/crucible-plugin
claude plugin install crucible@kv-plugins

Ubuntu (Amigo box, future hosts)

Once the repo is pushed to GitHub:

# Option A — install directly from the GitHub repo as a marketplace
claude plugin marketplace add Knight-Ventures-Inc/crucible-plugin
claude plugin install crucible@kv-plugins

# Option B — clone first, install from local path
git clone https://github.com/Knight-Ventures-Inc/crucible-plugin.git ~/crucible-plugin
claude plugin marketplace add ~/crucible-plugin
claude plugin install crucible@kv-plugins

Restart Claude Code after install so the skill and subagent register.

Verify

claude plugin list
claude plugin details crucible@kv-plugins

You should see skills/perfect and agents/crucible-author enumerated. The slash command is namespaced as /crucible:perfect.

How to Invoke

Slash command:

/crucible:perfect <target-type> <input-path-or-content> [--output <path>] [--max-iterations <n>] [--model <opus|sonnet>]

(Plugin skills in Claude Code are namespaced as /<plugin-name>:<skill-name>. Here the plugin is crucible and the skill is perfect. A standalone install of the skill files into ~/.claude/skills/crucible/ would invoke as the unnamespaced /crucible.)

Target types: plan, spec, report, vision, brief, north-star, strategy, proposal, manuscript, analysis, custom.

Natural-language trigger phrases (the skill is autoloaded when these appear in conversation):

• "perfect this"
• "iterate this"
• "build me a doc from this transcript"
• "research and refine"
• "make this best-practice"
• "make this the best ever"
• "draft it with hypotheses and unknowns and loop on it"

The skill is also autoloaded when the user hands over a long messy brain dump and asks for a structured output document, even without the exact phrases.

Completion-Promise Behavior

The subagent emits <promise>PERFECTED</promise> ONLY when ALL five conditions are true:

1. Every claim carries an epistemic tag.
2. Every [CONFIRMED] claim has a citation or [internal] rationale.
3. No [UNKNOWN] tags remain in the body (escalations to Open Questions must rewrite their inline tag to [DEFERRED → Open Q #N]).
4. Most recent Critique Pass produced zero new failure modes.
5. Prior iteration's Critique Pass also produced zero new failure modes (two consecutive clean passes = insight decay confirmed).

If the --max-iterations cap fires before completion, the subagent writes a ## IMPERFECT — Unmet Conditions section and emits <promise>CAPPED</promise>.

Because iteration 1 runs no Critique Pass, condition 5 is structurally unsatisfiable until iteration 3 at earliest. Deep document types (spec, strategy, proposal, analysis, manuscript) realistically need iterations 4–5 minimum before PERFECTED can fire.

Cost Note