fusion-horizon-plugin

Fusion-Horizon Plugin

A Claude Code plugin that implements a hermeneutic circle interpretation pipeline. Based on the Fusion-Horizon-UI project by Drift Johnson.

Live Web Version: https://fusion-horizon-ui.oragenai.com/ (openrouter API)

Fusion-Horizon decomposes any query through three philosophical phases — Horizon Mapping, Iterative Dialectical Analysis, and Horizon Fusion — to produce deeply interpreted, multi-perspective responses. The pipeline runs autonomously: once triggered, it coordinates multiple specialized agents, detects convergence algorithmically, and outputs polished interpretations with full metadata.

---

Table of Contents

• Three-Phase Pipeline
• Features
• Agent Roles
• Usage
• Natural Triggering
• Output Files and State Persistence
• Configuration Parameters
• Installation
• Plugin Structure
• Architecture Credit
• Citation

---

Three-Phase Pipeline

User Query + Optional Context + Optional Writer Prompt
    |
[Phase 1: Horizon Mapping] ──────────── 0% → 20%
    |
[Phase 2: Iterative Dialectic] ──────── 20% → 80%
    |
[Phase 3: Horizon Fusion] ──────────── 80% → 100%
    |
Output: Interpreted Response + Metadata → ./fusion-output/

Phase 1: Horizon Mapping (0% - 20%)

Maps the interpretive horizon before analysis begins. The "horizon" in hermeneutic philosophy represents the range of vision from a particular vantage point. This phase identifies:

• Assumptions (3-5) that someone might bring to the query
• Background Knowledge — domain-to-relevance mappings
• Biases (3-5) — cognitive or interpretive biases that might affect understanding
• User Context — inferred background, tone, deeper intent, and likely existing knowledge

Results are cached in horizon-cache.json for repeated queries.

Phase 2: Iterative Dialectical Analysis (20% - 80%)

Executes 2-5 cycles of part-whole dialectical analysis, the core of the hermeneutic circle. Each cycle:

1. Forms a provisional whole — an initial holistic interpretation
2. Performs part analysis — breaks the query into meaningful parts with literal meaning, contextual meaning, relation to whole, and challenges to the whole
3. Identifies tensions between parts and whole
4. Derives top-down insights (whole reveals about parts) and bottom-up insights (parts reveal about whole)
5. Produces a revised whole — an updated holistic interpretation informed by the parts

After each cycle (starting from cycle 2), the pipeline computes a convergence score using longest common substring text similarity between consecutive revised interpretations. When the score reaches 0.85 or higher, the pipeline naturally converges and moves to fusion.

Phase 3: Horizon Fusion (80% - 100%)

Performs the final synthesis — the "fusion of horizons" (Horizontverschmelzung) described by Hans-Georg Gadamer. This phase receives the complete interpretive journey and produces:

• Synthesis — all insights unified into coherent understanding
• Horizon Fusion — how the interpreter's horizon merged with the subject's horizon
• Evolution Narrative — the story of how understanding evolved across cycles
• Remaining Ambiguities — productive ambiguities that indicate interpretive richness
• Final Response — a polished, deeply informed answer to the original query
• Meta-Insights (optional) — higher-order observations about the process itself

---

Features

Feature	Description
Autonomous Execution	The pipeline runs start-to-finish without user interaction once triggered
Convergence Detection	Algorithmic text similarity measurement stops cycling when interpretations stabilize
State Persistence	JSON-based session state survives interruptions and enables resumption
Horizon Caching	Previously mapped horizons are cached (LRU, up to 100 entries) to skip redundant computation
Writer Prompt	Inject custom formatting guidance into the fusion phase for tailored output style
Trace Mode	Include full process data (horizon, all cycles, fusion details) in output JSON
Slash Commands	/fusion to run the pipeline, /fusion-reset to clear state
Natural Language Triggering	The plugin activates automatically when relevant phrases are detected

---

Agent Roles

The pipeline coordinates four specialized agent roles:

1. Horizon Mapper

Maps the interpretive landscape before analysis. Identifies assumptions, relevant domain knowledge, cognitive biases, and infers user context. Produces structured JSON output only. Called once per pipeline run.

2. Dialectic Analyzer

Performs the part-whole dialectical analysis central to the hermeneutic circle. Breaks queries into parts, examines tensions between parts and whole, derives bidirectional insights, and iteratively revises holistic understanding. Called once per cycle (2-5 times total).

3. Iteration Controller

A logic-only controller (no LLM call). Computes convergence scores between consecutive cycle interpretations using a longest common substring algorithm (ratio = 2 * matchingChars / (len1 + len2)) and decides whether to continue cycling or converge based on threshold rules:

• Below 2 cycles: always continue (forced)
• At 5 cycles: always converge (forced)
• Between 2-5 cycles: converge if score >= 0.85, otherwise continue

4. Horizon Fusion Agent

Performs the final Horizontverschmelzung. Receives the entire interpretive journey — horizon mapping, all dialectical cycles, convergence data, and accumulated insights — and synthesizes them into a polished final response with evolution narrative and meta-insights.

---

Usage

Main Command

/fusion <query> [--trace] [--writer "formatting prompt"] [--context "additional context"]

Arguments:

Argument	Required	Description
<query>	Yes	The query to interpret
--trace	No	Include detailed process data in output JSON
--writer "prompt"	No	Custom formatting guidance injected into the fusion phase
--context "text"	No	Additional context to inform interpretation

Examples:

# Standard hermeneutic interpretation
/fusion What is the nature of consciousness?

# With debug trace output
/fusion explain the relationship between language and thought --trace

# With custom formatting guidance
/fusion Why do empires fall? --writer "Format as a structured essay with headers"

# With additional context
/fusion What makes music beautiful? --context "The user is a professional musician"

Reset Command

/fusion-reset [--all | --state | --cache | --output]

Flag	Description
--all	Delete both ./fusion-state/ and ./fusion-output/ (default if no flag specified)
--state	Delete only ./fusion-state/ (session states)
--cache	Delete only ./fusion-state/horizon-cache.json (horizon mapping cache)
--output	Delete only ./fusion-output/ (response files)

Examples:

# Reset everything
/fusion-reset

# Reset everything (explicit)
/fusion-reset --all

# Clear only the horizon cache
/fusion-reset --cache

# Clear session state and output files
/fusion-reset --state --output

---

Natural Triggering

The plugin activates automatically when the user's message contains any of these phrases — no slash command required:

• "use the hermeneutic circle"
• "run fusion horizon"
• "interpret this deeply"
• "hermeneutic analysis"
• "dialectical analysis"
• "fuse horizons"
• "let fusion handle this"
• "run through the interpretation pipeline"
• "deep interpretation"
• "part-whole analysis"
• "convergence analysis"
• "horizon mapping"
• "philosophical interpretation"
• "fusion pipeline"
• "interpret this query"

Or any mention of the keywords: hermeneutic, dialectic, horizon fusion, convergence detection, or interpretive circle.

Example natural triggers:

"Run this through the hermeneutic circle: What is consciousness?"

"Interpret this deeply: Why do civilizations collapse?"

"Use fusion horizon to analyze this query and format the response as bullet points: What makes a good leader?"

---

Output Files and State Persistence

Output Files

After successful execution, results are written to ./fusion-output/ in the working directory:

File	Description
{query-slug}-response.md	Final interpreted response with metadata footer
{query-slug}-result.json	Full ProcessingResult with all phase data (generated when --trace is used)

The query slug is generated from the first 50 characters of the query, lowercased, with non-alphanumeric characters replaced by hyphens.

Example output:

fusion-output/
  what-is-the-nature-of-consciousness-response.md
  what-is-the-nature-of-consciousness-result.json

State Files

Session state is persisted in ./fusion-state/ for resumption and caching:

File	Purpose	Reset Effect
fusion-state/{sessionId}/state.json	Session state snapshot tracking horizon, dialectic, and iteration layers	Lose session progress
fusion-state/horizon-cache.json	Cached horizon mappings (LRU eviction, max 100 entries)	Re-compute horizons on next run

Delete the ./fusion-state/ directory (or use /fusion-reset) for a clean reset.

---

Configuration Parameters

Parameter	Value	Description
minCycles	2	Minimum dialectical cycles before convergence is allowed
maxCycles	5	Maximum dialectical cycles before forced convergence
convergenceThreshold	0.85	Text similarity score required for natural convergence
convergenceTrendUp	0.05	Score difference threshold indicating a converging trend
convergenceTrendDown	-0.05	Score difference threshold indicating a diverging trend
maxCacheEntries	100	Maximum horizon cache entries before LRU eviction
cacheEnabled	true	Whether horizon caching is active
stateDir	./fusion-state/	Directory for persistent session state files
outputDir	./fusion-output/	Directory for output response and result files
horizonComplete	20%	Progress milestone after Phase 1 completes
dialecticRange	20% - 80%	Progress range during Phase 2, distributed per cycle
fusionComplete	100%	Progress milestone after Phase 3 completes

---

Installation

1. Clone or download the fusion-horizon-plugin repository.

2. Place the plugin folder inside your Claude Code commands directory at ~/.claude/commands/:

   # Create the commands directory if it does not exist
   mkdir -p ~/.claude/commands
   
   # Copy the plugin folder into the commands directory
   cp -r fusion-plugin ~/.claude/commands/
   

   The ~/.claude/commands/ directory is where Claude Code discovers user-installed plugins and custom slash commands.

3. Restart Claude Code. The plugin will be available immediately via the /fusion slash command or through natural language triggering.

---

Plugin Structure

fusion-plugin/
├── .claude-plugin/
│   └── plugin.json                  # Plugin metadata (name, version, author)
├── agents/
│   └── fusion-coordinator.md        # Autonomous pipeline coordinator agent
├── commands/
│   ├── fusion.md                    # /fusion slash command definition
│   └── fusion-reset.md              # /fusion-reset slash command definition
├── skills/
│   └── hermeneutic-circle/
│       ├── SKILL.md                 # Skill definition, pipeline overview, and triggering
│       └── references/
│           ├── pipeline-spec.md     # Full algorithm specification and convergence details
│           ├── prompt-templates.md  # All four system prompts and user prompt templates
│           └── data-structures.md   # Data types, state structures, and constants
├── CLAUDE.md                        # Plugin summary for Claude Code context
└── README.md

---

Architecture Credit

Based on the Fusion-Horizon-UI project by Drift Johnson. Originally a React/TypeScript browser application using the OpenRouter API, re-architected for native Claude Code CLI execution with Agent subagents and JSON file persistence.

---

📚 Citation

Academic Citation

If you use this codebase in your research or project, please cite:

@software{fusion_horizon_plugin,
  title = {Fusion-Horizon Plugin: Hermeneutic Circle Interpretation Pipeline for Claude Code},
  author = {Drift Johnson},
  year = {2025},
  url = {https://github.com/MushroomFleet/fusion-horizon-plugin},
  version = {1.0.0}
}

Donate: