Skip to content

Agents Overview

The Mistaber encoding plugin includes a specialized agent that orchestrates the complete encoding pipeline with human supervision at every checkpoint.

What Are Agents?

In Claude Code, agents are autonomous subprocesses that handle complex, multi-step tasks. Unlike commands (user-initiated) or skills (knowledge resources), agents can:

  • Operate Autonomously: Execute sequences of operations
  • Manage State: Track progress across multiple phases
  • Request Input: Pause for human decisions at checkpoints
  • Coordinate Tools: Invoke multiple tools and skills as needed

The Encoding Orchestrator

The plugin provides one primary agent: the encoding-orchestrator.

Attribute Value
Name encoding-orchestrator
Color cyan
Model inherit (uses session model)
Purpose Orchestrate complete encoding pipeline

Agent Architecture

graph TB
    subgraph "Encoding Orchestrator"
        O[Orchestrator Agent]

        subgraph "Skills"
            S1[corpus-prep]
            S2[hll-encode]
            S3[validate]
            S4[review]
            S5[commit]
        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 "MCP"
            M[Sefaria MCP]
        end
    end

    O --> S1
    O --> S2
    O --> S3
    O --> S4
    O --> S5

    H1 -.-> O
    H2 -.-> O
    H3 -.-> O
    H4 -.-> M
    H5 -.-> O
    H6 -.-> O
    H7 -.-> O

Agent vs. Skills vs. Hooks

Component Triggered By Purpose Example
Agent User request Orchestrate workflow "Encode YD 87:3"
Skill Agent/User Domain knowledge Corpus preparation steps
Hook System events Enforce constraints Block uncommitted writes

When to Use the Agent

The encoding-orchestrator is triggered when users ask to:

  • "Encode halacha"
  • "Start encoding session"
  • "Encode seif"
  • "Prepare sources for encoding"
  • "Begin systematic encoding"
  • "Resume encoding"

Example Triggers:

User Says Agent Action
"Let's encode YD 87:3" Start new session at corpus-prep
"Resume encoding" Load session, continue from last phase
"Encode the basar bechalav laws" Plan multi-seif encoding

Agent Workflow

Session Lifecycle

stateDiagram-v2
    [*] --> SessionStart: User requests encoding
    SessionStart --> CorpusPrep: Initialize session
    CorpusPrep --> Checkpoint1: Artifacts ready
    Checkpoint1 --> HLLEncode: Human approves
    Checkpoint1 --> CorpusPrep: Human rejects
    HLLEncode --> Checkpoint2: Rules encoded
    Checkpoint2 --> Validate: Human approves
    Checkpoint2 --> HLLEncode: Human rejects
    Validate --> Checkpoint3: Tests pass
    Checkpoint3 --> Review: Human approves
    Checkpoint3 --> Validate: Human rejects
    Review --> Checkpoint4: Package ready
    Checkpoint4 --> Commit: Human approves
    Checkpoint4 --> Review: Human rejects
    Commit --> [*]: Session archived

Human Checkpoints

The agent pauses at four mandatory checkpoints:

  1. Corpus Preparation
  2. Review source chain
  3. Verify commentary completeness
  4. Validate derivation chain

  5. Answer clarifying questions

  6. HLL Encoding

  7. Review encoded rules
  8. Verify predicate correctness
  9. Check world scoping

  10. Validate machloket representation

  11. Validation

  12. Review test results
  13. Check compilation status
  14. Verify regression tests

  15. Approve for final review

  16. Review

  17. Complete halachic accuracy checklist
  18. Complete technical accuracy checklist
  19. Give final approval

Agent Configuration

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

---
name: encoding-orchestrator
description: Use this agent when the user asks to "encode halacha"...
model: inherit
color: cyan
tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Task",
        "AskUserQuestion", "TodoWrite",
        "mcp__sefaria_texts__get_text",
        "mcp__sefaria_texts__get_links_between_texts",
        ...]
---

Tool Access

The agent has access to:

Tool Category Tools
File Operations Read, Write, Edit, Glob, Grep
Execution Bash, Task
Interaction AskUserQuestion, TodoWrite
Sefaria MCP get_text, get_links_between_texts, text_search, english_semantic_search, clarify_name_argument, get_text_or_category_shape, get_english_translations, search_in_dictionaries, get_topic_details

Agent Output

Artifacts Generated

The agent coordinates generation of:

Corpus Phase: - corpus-report-YD-{siman}-{seif}.md - corpus-sources-YD-{siman}-{seif}.yaml - corpus-chain-YD-{siman}-{seif}.mermaid - corpus-questions-YD-{siman}-{seif}.yaml

Encoding Phase: - seif_{N}.lp - encoding-report-YD-{siman}-{seif}.md - encoding-mapping-YD-{siman}-{seif}.yaml

Validation Phase: - validation-report-YD-{siman}-{seif}.md - validation-results-YD-{siman}-{seif}.yaml - test-scenarios-YD-{siman}-{seif}.yaml

Review Phase: - review-package-YD-{siman}-{seif}.md

Session State

The agent maintains state in .mistaber-session.yaml:

current_phase: hll-encode
target_seif: "YD:87:3"
started: "2026-01-25T10:00:00Z"
last_activity: "2026-01-25T14:30:00Z"
checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: "2026-01-25T10:30:00Z"
  hll-encode:
    status: in_progress
  validate:
    status: not_started
  review:
    status: not_started

Agent Principles

1. Human Supervision is Non-Negotiable

The agent NEVER proceeds past a checkpoint without explicit human approval. This ensures:

  • Halachic accuracy is verified by humans
  • Technical correctness is reviewed
  • Errors are caught before propagation

2. Single Seif Granularity

The agent works on one seif at a time:

  • Small enough for thorough review
  • Large enough to be meaningful
  • Clear boundaries
  • Tractable validation

3. Complete Source Attribution

Every rule encoded by the agent has:

  • makor/2 facts linking to sources
  • madrega/2 facts specifying normative level
  • Derivation chain to authoritative source

4. Multi-World Semantics

The agent models disputes using Kripke semantics:

  • base world for universal rulings
  • mechaber world for Sefardi positions
  • rema world for Ashkenazi positions
  • override/3 for world-specific modifications

Error Handling

Compilation Failure

If UNSAT or syntax error:

  1. Agent reports error clearly
  2. Identifies problematic rules
  3. Returns to encoding phase
  4. Does NOT proceed to validation

Test Failure

If tests fail:

  1. Agent reports which tests failed
  2. Analyzes failure cause
  3. Returns to appropriate phase
  4. Requires re-approval

Missing Source

If Sefaria returns no results:

  1. Agent tries alternative reference formats
  2. Asks human for guidance
  3. Documents gap in corpus

Debugging

Check Agent Invocation

# Verify agent file exists
ls -la mistaber-skills/agents/encoding-orchestrator.md

# Check agent frontmatter
head -40 mistaber-skills/agents/encoding-orchestrator.md

Check Session State

# View current session
cat .mistaber-session.yaml

# Check checkpoint status
grep -A2 "status:" .mistaber-session.yaml

Manual Skill Invocation

If agent doesn't trigger correctly, invoke skills directly:

Invoke corpus-prep for YD 87:3