Skip to content

Plugin Architecture

This document provides a comprehensive technical overview of the Mistaber encoding plugin architecture, covering component interactions, data flows, state management, and integration with the Mistaber engine and Sefaria MCP.

System Architecture Overview

graph TB
    subgraph "Claude Code Runtime"
        CC[Claude Code CLI]
        PM[Plugin Manager]
        HE[Hook Engine]
        AM[Agent Manager]
        SM[Skill Manager]
    end

    subgraph "Mistaber Plugin"
        direction TB
        PJ[plugin.json]

        subgraph "Skills"
            S1[corpus-prep]
            S2[hll-encode]
            S3[validate]
            S4[review]
            S5[commit]
            S6[workflow-guide]
        end

        subgraph "Hooks"
            H1[session-init]
            H2[phase-gate]
            H3[encoding-guard]
            H4[sefaria-logger]
            H5[validation-handler]
            H6[checkpoint-enforcement]
            H7[git-commit-guard]
        end

        subgraph "Agents"
            A1[encoding-orchestrator]
        end

        subgraph "Templates"
            T1[corpus-report]
            T2[encoding-report]
            T3[validation-report]
            T4[review-package]
        end
    end

    subgraph "External Systems"
        SEF[Sefaria MCP]
        GIT[Git Repository]
        FS[File System]
        CLINGO[Clingo ASP]
        ME[Mistaber Engine]
    end

    CC --> PM
    PM --> PJ
    PM --> SM
    PM --> HE
    PM --> AM

    SM --> S1
    SM --> S2
    SM --> S3
    SM --> S4
    SM --> S5
    SM --> S6

    HE --> H1
    HE --> H2
    HE --> H3
    HE --> H4
    HE --> H5
    HE --> H6
    HE --> H7

    AM --> A1

    S1 --> SEF
    S3 --> CLINGO
    S3 --> ME
    S5 --> GIT

    H2 --> FS
    H3 --> FS
    H4 --> FS
    H7 --> GIT

Plugin Manifest Structure

The plugin is defined in .claude-plugin/plugin.json:

{
  "name": "mistaber-skills",
  "version": "1.0.0",
  "description": "Comprehensive AI agent skill set for systematically encoding halacha into the Mistaber formal reasoning system with human supervision at every step",
  "author": {
    "name": "Mistaber Project",
    "url": "https://github.com/BrainyBlaze/mistraber"
  },
  "repository": "https://github.com/BrainyBlaze/mistraber",
  "license": "Apache-2.0",
  "keywords": [
    "halacha",
    "encoding",
    "kripke-semantics",
    "asp",
    "formal-ontology",
    "sefaria",
    "computational-halacha"
  ],
  "hooks": "./hooks/hooks.json",
  "skills": "./skills",
  "agents": "./agents"
}

Key Fields:

Field Purpose
name Unique plugin identifier used for skill invocation (mistaber:skill-name)
hooks Path to hooks configuration file
skills Directory containing skill definitions
agents Directory containing agent definitions

Skill Lifecycle

Skill Discovery

On plugin load, the skill manager scans the skills/ directory:

skills/
├── corpus-prep/
│   └── SKILL.md          # Skill definition
├── hll-encode/
│   └── SKILL.md
├── validate/
│   └── SKILL.md
├── review/
│   └── SKILL.md
├── commit/
│   └── SKILL.md
└── workflow-guide/
    └── SKILL.md

Each SKILL.md file contains:

  1. YAML Frontmatter: Metadata and trigger patterns
  2. Markdown Body: Detailed instructions for the AI

Skill Definition Format

---
name: corpus-prep
description: This skill should be used when the user asks to "prepare corpus", "fetch sources", "start encoding seif", "begin encoding", "prepare sources for encoding", "build derivation chain", "get source texts from Sefaria", "prepare halachic sources", or mentions starting work on a new seif/siman. Provides comprehensive guidance for Phase 1 of the encoding pipeline - fetching and organizing source texts from Sefaria with complete derivation chains.
---

# Corpus Preparation Skill

## Purpose
...

## Prerequisites
...

## Phase A: Reference Resolution & Validation
...

Frontmatter Fields:

Field Required Description
name Yes Skill identifier
description Yes Trigger patterns and purpose (used for skill matching)

Skill Invocation Flow

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant SM as Skill Manager
    participant Skill as Skill Definition
    participant Hooks as Hook Engine

    User->>Claude: "Prepare corpus for YD 87:3"
    Claude->>SM: Match skill by description
    SM->>SM: Match: corpus-prep (keywords: "prepare corpus", "fetch sources")
    SM->>Skill: Load SKILL.md
    Skill-->>SM: Skill instructions
    SM->>Claude: Inject skill context

    Note over Claude: Execute skill instructions

    Claude->>Hooks: PreToolUse event
    Hooks->>Hooks: Run matching hooks
    Hooks-->>Claude: Continue/Block decision

    Claude->>User: Skill output

Skill Dependencies

Skills form a linear pipeline with explicit checkpoint dependencies:

graph LR
    A[corpus-prep] -->|Checkpoint 1 Approved| B[hll-encode]
    B -->|Checkpoint 2 Approved| C[validate]
    C -->|Checkpoint 3 Approved| D[review]
    D -->|Checkpoint 4 Approved| E[commit]

    style A fill:#90EE90
    style B fill:#87CEEB
    style C fill:#DDA0DD
    style D fill:#F0E68C
    style E fill:#98FB98

Hook Event System

Hook Configuration

Hooks are defined in hooks/hooks.json:

{
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-init.py",
          "timeout": 10000
        }
      ]
    }
  ],
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.py \"$TOOL_INPUT\"",
          "timeout": 5000
        }
      ]
    },
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/encoding-guard.py \"$TOOL_INPUT\"",
          "timeout": 5000
        }
      ]
    },
    {
      "matcher": "mcp__sefaria",
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/sefaria-logger.py \"$TOOL_NAME\" \"$TOOL_INPUT\"",
          "timeout": 3000
        }
      ]
    },
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/git-commit-guard.py \"$TOOL_INPUT\"",
          "timeout": 5000
        }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validation-handler.py \"$TOOL_OUTPUT\"",
          "timeout": 5000
        }
      ]
    }
  ],
  "Stop": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/checkpoint-enforcement.py",
          "timeout": 5000
        }
      ]
    }
  ]
}

Hook Event Types

Event When Triggered Available Variables
SessionStart At the beginning of a Claude Code session -
PreToolUse Before any tool is executed $TOOL_NAME, $TOOL_INPUT
PostToolUse After tool execution completes $TOOL_NAME, $TOOL_INPUT, $TOOL_OUTPUT
Stop When session ends or user stops -

Hook Execution Flow

sequenceDiagram
    participant Claude as Claude Code
    participant HE as Hook Engine
    participant Hook as Hook Script
    participant Tool as Tool Execution

    Claude->>HE: PreToolUse(Write, {file_path, content})
    HE->>HE: Match hooks by tool pattern

    Note over HE: Matches: phase-gate, encoding-guard

    loop Each matching hook
        HE->>Hook: Execute hook script
        Hook->>Hook: Validate request
        Hook-->>HE: {continue: true/false, message: "..."}

        alt Hook returns continue: false
            HE-->>Claude: BLOCKED with message
            Note over Claude: Tool execution prevented
        else Hook returns continue: true
            Note over HE: Continue to next hook
        end
    end

    HE->>Tool: Execute tool
    Tool-->>HE: Tool result

    HE->>HE: PostToolUse hooks
    HE-->>Claude: Final result

Hook Response Format

Hook scripts must output JSON to stdout:

{
  "continue": true,
  "message": "Optional message to display"
}

Response Fields:

Field Type Required Description
continue boolean Yes true to allow operation, false to block
message string No Message to display to user

Hook Chaining

Multiple hooks can match the same event. They execute in order and must all return continue: true for the operation to proceed:

graph TD
    A[Write Tool Called] --> B{phase-gate hook}
    B -->|continue: true| C{encoding-guard hook}
    B -->|continue: false| X[BLOCKED]
    C -->|continue: true| D[Tool Executes]
    C -->|continue: false| X

Session State Management

State File Structure

Session state is persisted in .mistaber-session.yaml:

# Core session information
current_phase: hll-encode
target_seif: "YD:87:3"
started: 2026-01-25T10:00:00Z
last_activity: 2026-01-25T14:30:00Z

# Checkpoint tracking
checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: 2026-01-25T10:30:00Z
    artifacts:
      - .mistaber-artifacts/corpus-report-YD-87-3.md
      - .mistaber-artifacts/corpus-sources-YD-87-3.yaml
      - .mistaber-artifacts/corpus-chain-YD-87-3.mermaid
      - .mistaber-artifacts/corpus-questions-YD-87-3.yaml
    complexity_score: 6

  hll-encode:
    status: pending_review
    artifacts:
      - mistaber/ontology/corpus/yd_87/base.lp
      - mistaber/ontology/worlds/mechaber.lp
      - mistaber/ontology/worlds/rema.lp
      - .mistaber-artifacts/encoding-report-YD-87-3.md
      - .mistaber-artifacts/encoding-mapping-YD-87-3.yaml
    rules_count: 8

  validate:
    status: not_started

  review:
    status: not_started

# Session metadata
metadata:
  topic: "dag_bechalav"
  topic_title: "Fish and Dairy"
  machloket_count: 1
  worlds_involved:
    - base
    - mechaber
    - rema

Checkpoint Status Transitions

stateDiagram-v2
    [*] --> not_started
    not_started --> in_progress: Skill invoked
    in_progress --> pending_review: Artifacts generated
    pending_review --> approved: Human approval
    pending_review --> in_progress: Revision requested
    approved --> [*]

    note right of pending_review: Blocks next phase\nuntil approved

State Access Patterns

Reading State (Hook Scripts):

def load_session_state() -> dict | None:
    """Load existing session state if it exists."""
    session_path = Path(".mistaber-session.yaml")
    if not session_path.exists():
        return None

    try:
        with open(session_path, "r") as f:
            return yaml.safe_load(f)
    except Exception as e:
        return {"exists": True, "parse_error": str(e)}

Writing State (Hook Scripts):

def save_session_state(session: dict) -> None:
    """Save session state."""
    session["last_activity"] = datetime.now().isoformat()
    session_path = Path(".mistaber-session.yaml")

    with open(session_path, "w") as f:
        yaml.dump(session, f, default_flow_style=False, allow_unicode=True)

Integration with Mistaber Engine

Engine Initialization

from mistaber.engine import HsrsEngine
from pathlib import Path

# Initialize engine with ontology path
engine = HsrsEngine(Path("mistaber/ontology"))

# Engine loads:
# - Schema definitions (sorts.lp)
# - World definitions (kripke_rules.lp)
# - Corpus rules (corpus/yd_*/base.lp)
# - World-specific rules (worlds/*.lp)

Rule File Organization

The plugin produces rules that integrate with the existing ontology structure:

mistaber/ontology/
├── schema/
│   └── sorts.lp              # Type definitions, sort hierarchies
├── worlds/
│   ├── kripke_rules.lp       # World accessibility, inheritance
│   ├── base.lp               # Base world rules
│   ├── mechaber.lp           # Mechaber-specific rules
│   ├── rema.lp               # Rema-specific rules
│   ├── gra.lp                # Gra-specific rules
│   ├── sefardi_yo.lp         # Yalkut Yosef rules
│   ├── ashk_mb.lp            # Mishnah Berurah rules
│   └── ashk_ah.lp            # Aruch HaShulchan rules
├── corpus/
│   ├── index.yaml            # Corpus index
│   └── yd_{siman}/
│       ├── base.lp           # Shared definitions for siman
│       └── manifest.yaml     # Siman metadata
└── tests/
    └── yd_{siman}/
        └── seif_{seif}_test.yaml

Compilation Pipeline

graph LR
    subgraph "Encoding Phase"
        HLL[HLL Rules]
    end

    subgraph "Validation Phase"
        HLL --> COMPILE[HLL Compiler]
        COMPILE --> ASP[ASP Rules]
        ASP --> GROUND[Clingo Grounding]
        GROUND --> SAT[Satisfiability Check]
    end

    subgraph "Testing Phase"
        SAT --> ENGINE[Mistaber Engine]
        ENGINE --> TESTS[Test Execution]
    end

Integration with Sefaria MCP

MCP Tool Mapping

The plugin uses Sefaria MCP tools for source access:

MCP Tool Purpose Used By
mcp__sefaria_texts__get_text Fetch primary text corpus-prep
mcp__sefaria_texts__get_english_translations Get translations corpus-prep
mcp__sefaria_texts__get_links_between_texts Get cross-references corpus-prep
mcp__sefaria_texts__clarify_name_argument Validate references corpus-prep
mcp__sefaria_texts__get_text_or_category_shape Get structure info corpus-prep
mcp__sefaria_texts__text_search Search texts corpus-prep
mcp__sefaria_texts__english_semantic_search Semantic search corpus-prep
mcp__sefaria_texts__search_in_dictionaries Dictionary lookup corpus-prep
mcp__sefaria_texts__get_topic_details Topic metadata corpus-prep

Source Logging

The sefaria-logger hook captures all MCP calls:

# .mistaber-artifacts/source-chain-log.yaml
source_chain:
  - tool: get_text
    reference: "Shulchan Arukh, Yoreh De'ah 87:3"
    category: text_fetch
    timestamp: "2026-01-25T10:05:00Z"

  - tool: get_links_between_texts
    reference: "Shulchan Arukh, Yoreh De'ah 87:3"
    category: links_fetch
    timestamp: "2026-01-25T10:05:30Z"

  - tool: get_text
    reference: "Shakh on Shulchan Arukh, Yoreh De'ah 87:3"
    category: text_fetch
    timestamp: "2026-01-25T10:06:00Z"

last_updated: "2026-01-25T10:06:00Z"

Agent Architecture

Agent Definition

The encoding-orchestrator agent is defined in agents/encoding-orchestrator.md:

---
name: encoding-orchestrator
description: Use this agent when the user asks to "encode halacha", "start encoding session", "encode seif", "prepare sources for encoding", "begin systematic encoding", or wants to systematically encode halachic content into Mistaber. This agent orchestrates the complete encoding pipeline with human supervision at every checkpoint.
model: inherit
color: cyan
tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Task", "AskUserQuestion", "TodoWrite", "mcp__sefaria_texts__get_text", ...]
---

You are the **Mistaber Encoding Orchestrator**...

Agent Configuration:

Field Value Description
name encoding-orchestrator Agent identifier
model inherit Use session's model
color cyan UI indicator color
tools [...] Allowed tools for agent

Agent-Skill Coordination

sequenceDiagram
    participant User
    participant Agent as encoding-orchestrator
    participant Skills as Skill System
    participant Hooks as Hook System

    User->>Agent: "Encode YD 87:3"
    Agent->>Agent: Parse request

    Agent->>Skills: Invoke corpus-prep
    Skills-->>Agent: Corpus artifacts
    Agent->>User: Present for review

    User->>Agent: "Approved"
    Agent->>Agent: Update checkpoint status

    Agent->>Skills: Invoke hll-encode
    Note over Agent,Skills: Process continues...

Data Flow Architecture

Encoding Pipeline Data Flow

graph TB
    subgraph "Phase 1: Corpus Prep"
        SEF[(Sefaria)] --> |MCP| CP1[Fetch Texts]
        CP1 --> CP2[Build Chain]
        CP2 --> CP3[Identify Machloket]
        CP3 --> CART[Corpus Artifacts]
    end

    subgraph "Phase 2: HLL Encode"
        CART --> HE1[Map Statements]
        HE1 --> HE2[Generate Rules]
        HE2 --> HE3[World Scoping]
        HE3 --> EART[Encoding Artifacts]
    end

    subgraph "Phase 3: Validate"
        EART --> V1[Compile HLL]
        V1 --> V2[Ground ASP]
        V2 --> V3[Run Tests]
        V3 --> VART[Validation Artifacts]
    end

    subgraph "Phase 4: Review"
        CART --> R1[Assemble Package]
        EART --> R1
        VART --> R1
        R1 --> RART[Review Package]
    end

    subgraph "Phase 5: Commit"
        RART --> C1[Verify Checkpoints]
        C1 --> C2[Organize Files]
        C2 --> C3[Git Commit]
        C3 --> ARCH[(Archive)]
    end

Artifact Lifecycle

graph TD
    subgraph "Working Artifacts"
        WA[.mistaber-artifacts/]
        WA --> CR[corpus-report.md]
        WA --> CS[corpus-sources.yaml]
        WA --> CC[corpus-chain.mermaid]
        WA --> ER[encoding-report.md]
        WA --> VR[validation-report.md]
        WA --> RP[review-package.md]
    end

    subgraph "Permanent Files"
        PF1[mistaber/ontology/corpus/]
        PF2[mistaber/ontology/worlds/]
        PF3[mistaber/ontology/tests/]
    end

    subgraph "Archive"
        AR[docs/encoding-sessions/]
    end

    WA -->|On Commit| PF1
    WA -->|On Commit| PF2
    WA -->|On Commit| PF3
    WA -->|On Commit| AR

Security Considerations

Input Validation

All hook scripts validate inputs:

def parse_tool_input(tool_input: str) -> dict:
    """Parse tool input safely."""
    try:
        data = json.loads(tool_input)
        return data
    except json.JSONDecodeError:
        # Safe fallback for malformed input
        return {}

Path Validation

The phase-gate hook validates file paths:

def is_ontology_file(file_path: str) -> bool:
    """Check if file is an ontology .lp file."""
    path = Path(file_path)
    return (
        path.suffix == ".lp" and
        "ontology" in str(path) and
        "corpus" in str(path)
    )

Checkpoint Enforcement

Hooks enforce checkpoint requirements before destructive operations:

  • phase-gate: Prevents writing to ontology without corpus approval
  • encoding-guard: Validates HLL syntax and makor requirements
  • git-commit-guard: Requires all checkpoints approved before commit

Performance Considerations

Hook Timeouts

Each hook has a configured timeout to prevent blocking:

Hook Timeout Typical Duration
session-init 10s <1s
phase-gate 5s <100ms
encoding-guard 5s <500ms
sefaria-logger 3s <100ms
validation-handler 5s <200ms
checkpoint-enforcement 5s <100ms
git-commit-guard 5s <500ms

Validation Performance

The validation skill sets performance targets:

Metric Target Action if Exceeded
Grounding time <100ms Warning
First query <50ms Warning
Subsequent queries <10ms Warning
Memory usage <100MB Warning

Extensibility

Adding New Skills

  1. Create directory: skills/new-skill/
  2. Create skill file: skills/new-skill/SKILL.md
  3. Define frontmatter with name and description
  4. Write skill instructions in markdown body

Adding New Hooks

  1. Create script: hooks/scripts/new-hook.py
  2. Update hooks/hooks.json with new hook configuration
  3. Implement hook logic following response format

Adding New Worlds

  1. Update worlds-config.yaml
  2. Create world file: mistaber/ontology/worlds/new-world.lp
  3. Define world accessibility rules
  4. Update encoding-guard VALID_WORLDS set