Plugin Installation¶

This guide covers the complete installation, configuration, and verification of the Mistaber encoding plugin for Claude Code.

Prerequisites¶

Before installing the plugin, ensure you have the following components properly configured:

1. Claude Code CLI¶

The Mistaber plugin requires Claude Code CLI version 1.0 or later.

Verify Installation:

claude --version
# Expected: claude 1.0.x or higher

Install if needed:

npm install -g @anthropic-ai/claude-code

2. Mistaber System¶

The plugin requires a working Mistaber installation with the engine and ontology:

# Verify Mistaber is installed
python -c "from mistaber.engine import HsrsEngine; print('Mistaber OK')"

# Verify ontology exists
ls mistaber/ontology/
# Expected: schema/, worlds/, corpus/

Install if needed:

pip install mistaber
# or for development
pip install -e .

3. Clingo ASP Solver¶

The validation skill requires Clingo for grounding and satisfiability checks:

# Verify Clingo
clingo --version
# Expected: clingo version 5.x or higher

Install if needed:

# macOS
brew install clingo

# Ubuntu/Debian
apt-get install gringo clasp

# pip (cross-platform)
pip install clingo

4. Python Dependencies¶

The hook scripts require Python 3.10+ with specific packages:

# Required packages
pip install pyyaml

# Verify
python -c "import yaml; print('PyYAML OK')"

5. Sefaria MCP Server¶

The plugin integrates with Sefaria through MCP (Model Context Protocol):

Verify MCP Configuration:

# Check MCP config exists
cat ~/.config/claude-code/.mcp.json
# or project-level
cat .mcp.json

Configure Sefaria MCP if needed:

Create or update .mcp.json:

{
  "mcpServers": {
    "sefaria-texts": {
      "command": "npx",
      "args": ["-y", "@sefaria/mcp-server"],
      "env": {}
    }
  }
}

Installing the Plugin¶

Option 1: Clone from Repository¶

# Clone the plugin repository
git clone https://github.com/BrainyBlaze/mistaber-skills.git

# Navigate to the plugin directory
cd mistaber-skills

# Verify structure
ls -la
# Expected: .claude-plugin/, skills/, hooks/, agents/, templates/

Option 2: Install as Submodule¶

For projects that want to track the plugin as a dependency:

# Add as submodule
git submodule add https://github.com/BrainyBlaze/mistaber-skills.git mistaber-skills

# Initialize and update
git submodule update --init --recursive

Option 3: Copy Plugin Files¶

For standalone installation:

# Copy plugin directory to your project
cp -r /path/to/mistaber-skills /your/project/mistaber-skills

# Or download directly
curl -L https://github.com/BrainyBlaze/mistaber-skills/archive/main.tar.gz | tar xz
mv mistaber-skills-main mistaber-skills

Plugin Structure Verification¶

After installation, verify the complete plugin structure:

mistaber-skills/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── skills/
│   ├── corpus-prep/
│   │   └── SKILL.md          # Corpus preparation skill
│   ├── hll-encode/
│   │   └── SKILL.md          # HLL encoding skill
│   ├── validate/
│   │   └── SKILL.md          # Validation skill
│   ├── review/
│   │   └── SKILL.md          # Review skill
│   ├── commit/
│   │   └── SKILL.md          # Commit skill
│   └── workflow-guide/
│       └── SKILL.md          # Workflow documentation
├── hooks/
│   ├── hooks.json            # Hook definitions
│   └── scripts/
│       ├── session-init.py
│       ├── phase-gate.py
│       ├── encoding-guard.py
│       ├── sefaria-logger.py
│       ├── validation-handler.py
│       ├── checkpoint-enforcement.py
│       └── git-commit-guard.py
├── agents/
│   └── encoding-orchestrator.md
├── templates/
│   ├── corpus-report.md
│   ├── encoding-report.md
│   ├── validation-report.md
│   └── review-package.md
├── references/
│   └── ...                   # Reference documentation
└── examples/
    └── ...                   # Example encodings

Verification Script:

#!/bin/bash
# verify-plugin.sh

PLUGIN_ROOT="${1:-mistaber-skills}"

echo "Verifying Mistaber Plugin Structure..."

# Check plugin manifest
if [ -f "$PLUGIN_ROOT/.claude-plugin/plugin.json" ]; then
    echo "[OK] Plugin manifest found"
else
    echo "[ERROR] Missing .claude-plugin/plugin.json"
    exit 1
fi

# Check skills
for skill in corpus-prep hll-encode validate review commit workflow-guide; do
    if [ -f "$PLUGIN_ROOT/skills/$skill/SKILL.md" ]; then
        echo "[OK] Skill: $skill"
    else
        echo "[ERROR] Missing skill: $skill"
        exit 1
    fi
done

# Check hooks
if [ -f "$PLUGIN_ROOT/hooks/hooks.json" ]; then
    echo "[OK] Hooks configuration found"
else
    echo "[ERROR] Missing hooks/hooks.json"
    exit 1
fi

# Check hook scripts
for hook in session-init phase-gate encoding-guard sefaria-logger validation-handler checkpoint-enforcement git-commit-guard; do
    if [ -f "$PLUGIN_ROOT/hooks/scripts/$hook.py" ]; then
        echo "[OK] Hook script: $hook.py"
    else
        echo "[ERROR] Missing hook script: $hook.py"
        exit 1
    fi
done

# Check agent
if [ -f "$PLUGIN_ROOT/agents/encoding-orchestrator.md" ]; then
    echo "[OK] Agent: encoding-orchestrator"
else
    echo "[ERROR] Missing encoding-orchestrator agent"
    exit 1
fi

echo ""
echo "Plugin structure verification complete!"

Registering the Plugin¶

Method 1: Project-Level Registration¶

Add the plugin path to your project's Claude Code configuration:

# Create or update .claude/settings.json
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "plugins": [
    "./mistaber-skills"
  ]
}
EOF

Method 2: Global Registration¶

For system-wide availability:

# Add to global settings
mkdir -p ~/.config/claude-code
cat >> ~/.config/claude-code/settings.json << 'EOF'
{
  "plugins": [
    "/path/to/mistaber-skills"
  ]
}
EOF

Method 3: Per-Session Registration¶

Load the plugin for a specific session:

claude --plugin ./mistaber-skills

Configuration Options¶

Plugin Configuration¶

The plugin can be configured through environment variables or a configuration file:

Environment Variables:

# Set encoding session directory
export MISTABER_SESSION_DIR=".mistaber-sessions"

# Set artifact directory
export MISTABER_ARTIFACTS_DIR=".mistaber-artifacts"

# Set ontology path
export MISTABER_ONTOLOGY_PATH="./mistaber/ontology"

# Enable verbose logging
export MISTABER_DEBUG=1

Configuration File:

Create .mistaber-config.yaml in your project root:

# .mistaber-config.yaml
session:
  directory: ".mistaber-sessions"
  artifacts_directory: ".mistaber-artifacts"
  auto_archive: true

ontology:
  path: "./mistaber/ontology"
  corpus_subdirectory: "corpus"
  worlds_subdirectory: "worlds"

validation:
  run_regression_tests: true
  performance_threshold_ms: 100
  require_makor: true
  require_madrega: true

hooks:
  encoding_guard:
    enabled: true
    strict_predicate_validation: true
  phase_gate:
    enabled: true
    allow_manual_override: false
  git_commit_guard:
    enabled: true
    require_all_checkpoints: true

sefaria:
  mcp_server: "sefaria-texts"
  log_all_fetches: true
  cache_sources: true

logging:
  level: "INFO"
  log_file: ".mistaber-artifacts/plugin.log"

Hook Configuration¶

Individual hooks can be configured 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
        }
      ]
    }
  ]
}

Configurable Parameters:

Parameter	Description	Default
`timeout`	Maximum execution time in milliseconds	5000
`matcher`	Tool name pattern to match	varies
`type`	Hook type (command or prompt)	command

World Configuration¶

Configure the available worlds for encoding in worlds-config.yaml:

# Kripke world hierarchy
worlds:
  base:
    description: "Universal rulings - all authorities agree"
    parent: null

  mechaber:
    description: "Sefardi positions (Shulchan Arukh)"
    parent: base

  rema:
    description: "Ashkenazi positions"
    parent: base

  gra:
    description: "Vilna Gaon positions"
    parent: base

  sefardi_yo:
    description: "Yalkut Yosef rulings"
    parent: mechaber

  ashk_mb:
    description: "Mishnah Berurah rulings"
    parent: rema

  ashk_ah:
    description: "Aruch HaShulchan rulings"
    parents:
      - rema
      - gra

Post-Installation Verification¶

1. Verify Plugin Loading¶

Start a Claude Code session and check plugin status:

User: "What Mistaber skills are available?"

Expected response: The agent should list all 6 skills:
- mistaber:corpus-prep
- mistaber:hll-encode
- mistaber:validate
- mistaber:review
- mistaber:commit
- mistaber:workflow-guide

2. Verify Hook Execution¶

Start a new session to test session-init hook:

User: [Start new Claude Code session]

Expected: Session initialization message showing:
- "Mistaber Encoding Plugin Active"
- No active encoding session found
- Instructions to start encoding

3. Verify Sefaria MCP Connection¶

Test Sefaria integration:

User: "Fetch the text of Yoreh Deah 87:1"

Expected: The agent should successfully retrieve and display
the Hebrew and English text from Sefaria.

4. Test Complete Workflow¶

Run a simple workflow test:

User: "What is the status of the encoding workflow?"

Expected: The agent should report:
- No active session (if none exists)
- Current phase and checkpoints (if session exists)
- Workflow rules reminder

Updating the Plugin¶

Pulling Updates¶

cd mistaber-skills

# If installed via git clone
git pull origin main

# If installed as submodule
git submodule update --remote --merge

Version Compatibility¶

Check version compatibility:

# Check plugin version
cat mistaber-skills/.claude-plugin/plugin.json | jq '.version'

# Verify compatibility with Mistaber
python -c "import mistaber; print(mistaber.__version__)"

Migration Notes¶

When updating between major versions:

Backup active sessions:

cp -r .mistaber-session.yaml .mistaber-session.yaml.backup
cp -r .mistaber-artifacts .mistaber-artifacts.backup

Review changelog: Check CHANGELOG.md for breaking changes.
Update configuration: Compare your config with the new template.
Test before production: Run verification tests before encoding production content.

Troubleshooting Installation¶

Plugin Not Loading¶

Symptom: Claude Code doesn't recognize Mistaber skills.

Solutions:

Verify plugin path in settings:

cat .claude/settings.json | jq '.plugins'

Check plugin.json validity:

python -c "import json; json.load(open('mistaber-skills/.claude-plugin/plugin.json'))"

Restart Claude Code:
```
claude --reload-plugins
```

Hook Scripts Failing¶

Symptom: Hook scripts produce errors or timeout.

Solutions:

Verify Python availability:
```
which python3
python3 --version
```

Test hooks manually:

cd mistaber-skills
python hooks/scripts/session-init.py

Check PyYAML installation:
```
python3 -c "import yaml; print('OK')"
```

Sefaria MCP Not Connecting¶

Symptom: Cannot fetch texts from Sefaria.

Solutions:

Verify MCP server running:
```
ps aux | grep mcp
```
Check MCP configuration:
```
cat .mcp.json
```
Test MCP directly:
```
npx -y @sefaria/mcp-server --help
```

Next Steps¶

After successful installation:

Review Architecture: Architecture Overview
Learn the Skills: Skills Documentation
Understand Hooks: Hooks Documentation
Start Encoding: Begin with a simple seif using corpus-prep