# CLAUDE.md
This file provides guidance to Claude Code when working with mcp-tool-factory tools.
## Sacred Primitive Specification
**CRITICAL: Before using any mcp-tool-factory tools, load the specification:**
```bash
cat coded-systems/*.jsonl | jq -s '.'
```
**Why this matters:**
Tools in this system are defined by their **REFUSALS**, not their capabilities. The specification encodes:
1. **The Sacred Primitive** (`primitive.jsonl`) - The immutable contract all tools share
2. **The Five Sacred Refusals** (`constraints.jsonl`) - What tools refuse, even when technically possible
3. **Infrastructure Capabilities** (`infrastructure.jsonl`) - System-level features (M1-M6)
4. **Tool Instances** (`tools.jsonl`) - Four tools with capabilities AND refusals
## Tool Essence
The essence of a tool is **what it protects**, not what it does:
- **Refusal to execute blindly** → Conversational alignment check
- **Refusal to escalate permissions** → Graduated permission ladder (Level 0-4)
- **Refusal to forget** → State continuity across hot-reloads
- **Refusal to break continuity** → WHO/WHAT/HOW dimensional tracking
- **Refusal to interfere** → Tool class isolation
## Available Tools
1. **example-tool** - Testing and demonstration (7 actions)
2. **data-tool** - CRUD operations (4 actions: create, read, update, list)
3. **admin-tool** - Administrative operations (2 actions: delete, validate)
4. **orchestrator-tool** - Multi-tool composition (3 actions: workflow, pipeline, aggregate)
## Permission Ladder
- **Level 0:** Meta-conversation actions (status, list, switch)
- **Level 1:** Read-only operations (greet, echo, evaluate, what-if, read, list)
- **Level 2:** State-modifying operations (write-file, dangerous, create, update)
- **Level 3:** Destructive operations (delete)
- **Level 4:** Orchestration (workflow, pipeline, aggregate)
## Orchestration Limits
When using `orchestrator-tool`:
- **Max depth:** 5 levels (prevents infinite nesting)
- **Circular dependency detection:** Automatic refusal if detected
- **Orchestration prohibition:** Orchestrator cannot spawn another orchestrator
## Validation Witness
To verify specification matches implementation:
```bash
node validate-spec.mjs
```
Expected output: `✅ 42/42 PASSED`
If validation fails, the specification has drifted from implementation. Investigate before using tools.
## Hot-Reload Support
All tools implement `getState()` and `setState()` for zero-downtime evolution. When tools reload:
- State preserves across reload (no amnesia)
- Conversation context maintained (WHO/WHAT/HOW)
- Permission levels persist
- Orchestration depth tracking continues
## Conversation Isolation
Every tool interaction requires `conversationId` parameter. This enforces:
- Multi-user isolation (conversations don't interfere)
- State scoping (each conversation has independent state)
- Permission context (graduated trust per conversation)
## Immutability Principle
From `primitive.jsonl`:
> "This primitive is not negotiable. This primitive is not augmented. Capabilities emerge from removing constraints on this primitive, never from adding features to it."
**What this means:**
If you find yourself wanting to add a feature to a tool, you are approaching it wrong. Instead, identify which constraint is preventing the desired behavior and consider if removing that constraint (with proper safeguards) is the correct approach.
## Emergence Principle
From `primitive.jsonl`:
> "Tool capabilities emerge from constraint removal, never from direct implementation. If you can implement a feature directly, you are doing it wrong."
New capabilities should emerge from:
1. Removing a refusal under specific conditions
2. Graduating permission requirements
3. Extending orchestration composition patterns
4. Adding new dimensional tracking to state continuity
Never from adding new action types or bypassing the sacred primitive.
## Usage Pattern
```javascript
// 1. Load specification (read this CLAUDE.md and coded-systems/*.jsonl)
// 2. Understand refusals before capabilities
// Tools refuse: blind execution, permission escalation, state amnesia,
// reload corruption, tool interference
// 3. Provide required context
const result = await mcp_tool({
conversationId: "user-session-123", // Required
action: "read-resource", // With appropriate permission level
name: "my-resource"
});
// 4. Respect refusals
// If tool refuses, it's protecting you. Don't try to bypass.
```
## Specification Files
- **primitive.jsonl** (1 line) - The sacred contract
- **constraints.jsonl** (5 lines) - Protection mechanisms with witness protocols
- **infrastructure.jsonl** (6 lines) - System capabilities (M1-M6)
- **tools.jsonl** (4 lines) - Tool instances with capabilities AND refusals
## Witness Protocols
Each constraint includes a witness protocol for validation:
- **Conversational Alignment:** `alignment_check_before_execution = true`
- **Permission Graduation:** `permission_ladder_enforced = true`
- **Hot-Reload Safety:** `state_preservation_rate = 100%`
- **State Continuity:** `dimensional_tracking_complete = true`
- **Tool Isolation:** `cross_tool_interference_rate = 0%`
These are not aspirational metrics. They are enforced constraints validated by `validate-spec.mjs`.
