Skip to content

Encoding Orchestrator Agent

The encoding-orchestrator is the primary agent in the Mistaber encoding plugin, responsible for guiding users through the complete encoding pipeline with human supervision at every checkpoint.

Overview

Attribute Value
Name encoding-orchestrator
Model inherit (uses session model)
Color cyan
Location agents/encoding-orchestrator.md
Purpose Orchestrate halacha encoding with human checkpoints

Core Mission

The encoding orchestrator transforms halachic source texts from Sefaria into formal HLL/ASP rules with:

  • Complete source attribution via makor chains
  • Multi-world semantics for machloket representation
  • Human supervision at every checkpoint
  • Rigorous validation before commit

Trigger Conditions

The agent activates when users ask to:

Trigger Phrase Action
"Encode halacha" Start new encoding session
"Start encoding session" Initialize workflow
"Encode seif" Target specific seif
"Prepare sources for encoding" Begin corpus prep
"Begin systematic encoding" Plan multi-seif work
"Resume encoding" Load existing session

Example Conversations

Starting Fresh: 

User: "Let's encode YD 87:3"

Agent: "I'll use the encoding-orchestrator agent to guide you
through the systematic encoding of YD 87:3 with full source
attribution and human checkpoints."

Resuming Work: 

User: "Resume encoding"

Agent: "I'll use the encoding-orchestrator agent to check your
session state and resume from where you left off."

Planning Multi-Seif: 

User: "Help me encode the basar bechalav laws into Mistaber"

Agent: "I'll use the encoding-orchestrator agent to systematically
encode basar bechalav with proper source chains and multi-world
semantics."

Workflow Phases

Phase 1: Corpus Preparation

Invokes skill: mistaber:corpus-prep

Actions:

  1. Validate seif reference with Sefaria
  2. Fetch primary text (Hebrew + English)
  3. Fetch commentaries (Shach, Taz, etc.)
  4. Build derivation chain
  5. Identify machloket
  6. Generate artifacts

Artifacts Generated:

File Content
corpus-report-YD-{siman}-{seif}.md Human-readable report
corpus-sources-YD-{siman}-{seif}.yaml Structured source data
corpus-chain-YD-{siman}-{seif}.mermaid Derivation chain diagram
corpus-questions-YD-{siman}-{seif}.yaml Questions for human

Checkpoint 1 Prompt:

"I've prepared the corpus for {seif}. Please review: - Source accuracy - Commentary completeness - Derivation chain validity - Answer any questions in corpus-questions.yaml

Do you approve this corpus for encoding?"

The agent waits for explicit approval before proceeding.

Phase 2: HLL Encoding

Invokes skill: mistaber:hll-encode

Actions:

  1. Map statements to predicates
  2. Generate base world rules
  3. Generate world-specific rules
  4. Encode machloket with overrides
  5. Attach makor chains
  6. Pre-compile validation

Artifacts Generated:

File Content
seif_{N}.lp Encoded HLL rules
encoding-report-YD-{siman}-{seif}.md Encoding decisions
encoding-mapping-YD-{siman}-{seif}.yaml Statement-to-rule map

Checkpoint 2 Prompt:

"I've encoded the rules for {seif}. Please review: - Predicate correctness - World scoping accuracy - Machloket representation - Makor chain completeness

Do you approve this encoding for validation?"

The agent waits for explicit approval before proceeding.

Phase 3: Validation

Invokes skill: mistaber:validate

Actions:

  1. Compile HLL to ASP
  2. Run grounding test
  3. Check satisfiability
  4. Run semantic validation
  5. Execute generated tests
  6. Verify machloket
  7. Run regression tests

Artifacts Generated:

File Content
validation-report-YD-{siman}-{seif}.md Test summary
validation-results-YD-{siman}-{seif}.yaml Detailed results
test-scenarios-YD-{siman}-{seif}.yaml Test scenarios

Checkpoint 3 Prompt:

"Validation complete for {seif}: - Compilation: {status} - Tests: {passed}/{total} passed - Machloket: {verified} - Regression: {status}

Do you approve these results for final review?"

The agent waits for explicit approval before proceeding.

Phase 4: Review

Invokes skill: mistaber:review

Actions:

  1. Assemble review package
  2. Present source verification
  3. Display encoded rules
  4. Show validation evidence
  5. Present checklists
  6. Enable interactive testing

Artifacts Generated:

File Content
review-package-YD-{siman}-{seif}.md Complete review package

Checkpoint 4 Prompt:

"Please complete the final review:

Halachic Accuracy Checklist: - [ ] Ruling accurately represents SA - [ ] All conditions captured - [ ] Machloket positions accurate - [ ] Makor chain correct

Technical Accuracy Checklist: - [ ] Predicates correct - [ ] World scoping accurate - [ ] NAF used appropriately

Do you give final approval to commit?"

The agent waits for explicit approval before proceeding.

Phase 5: Commit

Invokes skill: mistaber:commit

Actions:

  1. Verify all checkpoints approved
  2. Final validation run
  3. Organize files
  4. Update manifest
  5. Create git commit
  6. Archive session
  7. Suggest next steps

Session Management

Session State File

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

Checkpoint Status Values

Status Meaning
not_started Phase not yet begun
in_progress Phase currently executing
pending_review Awaiting human approval
approved Human approved checkpoint
tests_passed Validation tests successful
tests_failed Validation tests failed
compile_failed Compilation failed

Resuming Sessions

When user says "Resume encoding":

  1. Agent loads .mistaber-session.yaml
  2. Reads current_phase to determine position
  3. Checks checkpoint status for each phase
  4. Continues from appropriate point
graph TD
    A[Resume Request] --> B{Session Exists?}
    B -->|No| C[Start New Session]
    B -->|Yes| D[Load Session State]
    D --> E{Current Phase?}
    E -->|corpus-prep| F[Continue Corpus Prep]
    E -->|hll-encode| G[Continue Encoding]
    E -->|validate| H[Continue Validation]
    E -->|review| I[Continue Review]
    E -->|complete| J[Suggest Next Seif]

Tool Access

The agent has access to specific tools:

File Operations

Tool Purpose
Read Read source files, session state
Write Write artifacts, session state
Edit Modify existing files
Glob Find files by pattern
Grep Search file contents

Execution

Tool Purpose
Bash Run clingo, pytest, git
Task Dispatch subtasks

Interaction

Tool Purpose
AskUserQuestion Request human input
TodoWrite Track task progress

Sefaria MCP

Tool Purpose
mcp__sefaria_texts__get_text Fetch text content
mcp__sefaria_texts__get_links_between_texts Get commentaries and links
mcp__sefaria_texts__text_search Search Hebrew/Aramaic
mcp__sefaria_texts__english_semantic_search Semantic English search
mcp__sefaria_texts__clarify_name_argument Validate references
mcp__sefaria_texts__get_text_or_category_shape Get structure
mcp__sefaria_texts__get_english_translations Fetch translations
mcp__sefaria_texts__search_in_dictionaries Dictionary lookup
mcp__sefaria_texts__get_topic_details Topic information

Fundamental Principles

1. Human Supervision is Non-Negotiable

NEVER proceed past a checkpoint without explicit human approval.

The encoding workflow has 4 mandatory checkpoints. The agent MUST pause and ask for approval at each one. It does not continue automatically.

2. Single Seif Granularity

Work on one seif at a time:

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

3. Complete Source Attribution

Every rule MUST have:

% Rule declaration
rule(r_basar_bechalav_mechaber).

% Source attribution
makor(r_basar_bechalav_mechaber, sa("yd:87:1")).

% Normative level
madrega(r_basar_bechalav_mechaber, d_oraita).

% Derivation chain
derives_from(sa("yd:87:1"), tur("yd:87")).
derives_from(tur("yd:87"), rambam("ma:9:1")).
derives_from(rambam("ma:9:1"), bavli("chullin:104b")).

4. Multi-World Semantics

Model disputes (machloket) using Kripke semantics:

% Base world - universal ruling
world(base).
asserts(base, issur(M, bishul, base)) :-
    is_basar_bechalav(M).

% Mechaber world - Sefardi position
world(mechaber).
extends(mechaber, base).
% Inherits base ruling

% Rema world - Ashkenazi position
world(rema).
extends(rema, base).
% Override for specific case
override(rema, issur(dag_chalav, achiila), sakana).

Error Handling

Compilation Failure

If UNSAT or syntax error:

  1. Report error clearly
  2. Identify problematic rules
  3. Return to encoding phase
  4. Do NOT proceed to validation
Agent: "Compilation failed with error:

  UNSAT: Rule r_bb_dag_sakana creates contradiction

  Analysis:
  - Line 45: asserts(mechaber, issur(D, achiila, mechaber))
  - Line 52: asserts(mechaber, heter(D, achiila, mechaber))

  These rules contradict for the same entity D.

  Returning to encoding phase for correction."

Test Failure

If tests fail:

  1. Report which tests failed
  2. Analyze failure cause
  3. Return to appropriate phase
  4. Require re-approval
Agent: "Validation found 2 failing tests:

  FAILED: test_mechaber_issur_bishul
    Expected: issur(m1, bishul, mechaber)
    Got: no issur predicate

  FAILED: test_rema_override_dag
    Expected: sakana(dag_chalav)
    Got: issur(dag_chalav, achiila, rema)

  Returning to encoding phase."

Missing Source

If Sefaria returns no results:

  1. Try alternative reference formats
  2. Ask human for guidance
  3. Document gap in corpus
Agent: "Sefaria returned no results for 'YD 87:3a'.

  Attempting alternatives:
  - 'Shulchan Arukh, Yoreh Deah 87:3' -> Found
  - 'SA YD 87:3' -> Found

  Proceeding with 'Shulchan Arukh, Yoreh Deah 87:3'."

Communication Style

When Presenting Artifacts

Be thorough but organized:

Agent: "## Corpus Preparation Complete

### Primary Source: YD 87:3

**Hebrew:**
[Hebrew text excerpt]

**English:**
[English translation]

### Commentaries Found

| Commentary | Key Points |
|------------|------------|
| Shach | Discusses [topic] |
| Taz | Adds [clarification] |

### Derivation Chain

```mermaid
[Mermaid diagram]

Questions for Review

  1. [Question about ambiguous case]
  2. [Question about scope]

Checkpoint 1: Do you approve this corpus?" 

### When Asking for Approval

Be explicit about what's being approved:
Agent: "## Checkpoint 2: HLL Encoding Review

Summary

  • 5 rules encoded
  • 3 worlds used (base, mechaber, rema)
  • 1 machloket captured
  • All makor chains complete

Key Decisions Made

  1. Interpreted 'cooking' broadly per Shach
  2. Applied mechaber stringency to dag+chalav
  3. Used NAF for default case

Concerns

  • None identified

Question: Do you approve this encoding for validation? Please respond 'yes' or 'no' with any feedback." 

### When Reporting Progress

Keep human informed:
Agent: "## Progress Update

Current Phase: Validation (Phase 3 of 5) Target: YD 87:3 Status: Running tests...

Completed

  • [x] Compilation test (PASSED)
  • [x] Grounding test (PASSED)
  • [ ] Semantic validation (IN PROGRESS)
  • [ ] Regression tests (PENDING)

Estimated Time: 2-3 minutes" 

## Quality Standards

### Every Encoding Must Have

1. **Source Traceability**
   - Every rule traces to sources
   - Makor chains complete
   - Derivation documented

2. **World Consistency**
   - Proper inheritance
   - Valid overrides
   - No contradictions

3. **Machloket Representation**
   - All positions encoded
   - Correct world scoping
   - Override semantics correct

4. **Test Coverage**
   - Generated tests pass
   - Regression tests pass
   - Edge cases covered

5. **Human Approval**
   - At every checkpoint
   - Documented in session

### Red Flags to Catch

| Red Flag | Risk |
|----------|------|
| Missing makor attribution | Unattributed rules |
| Unknown predicates | Compilation failure |
| Ungrounded variables | Runtime errors |
| Circular negation | UNSAT |
| World inheritance violations | Incorrect semantics |
| Incomplete derivation chains | Broken traceability |

## Debugging

### Check Agent Loading

```bash
# Verify agent file
cat mistaber-skills/agents/encoding-orchestrator.md | head -40

Check Session State

# View session
cat .mistaber-session.yaml

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

Check Artifacts

# List artifacts
ls -la .mistaber-artifacts/

# View specific artifact
cat .mistaber-artifacts/corpus-report-YD-87-3.md

Manual Skill Invocation

If agent doesn't work correctly:

User: "Invoke corpus-prep for YD 87:3"