# Core Framework

> The markdown spec in this directory maps to the TypeScript engine in `src/`.
> This file tells you what each module does, which phase it maps to, and how to use it.

---

## Mapping: Markdown Spec → TypeScript Engine

| Phase | Markdown (PHASES/) | TypeScript (src/) |
|-------|-------------------|-------------------|
| 1 | `phase-01-session-engine.md` | `tier1-foundation/session-engine.ts` |
| 2 | `phase-02-context-manager.md` | `tier1-foundation/context-manager.ts` |
| 3 | `phase-03-tool-orchestrator.md` | `tier1-foundation/tool-orchestrator.ts` |
| 4 | `phase-04-feedback-loop.md` | `tier2-primitives/loops/feedback-loop.ts` |
| 5 | `phase-05-state-accumulator.md` | `tier2-primitives/loops/state-accumulator.ts` |
| 6 | `phase-06-convergence-check.md` | `tier2-primitives/loops/convergence-check.ts` |
| 7 | `phase-07-workflow-graph.md` | `tier2-primitives/workflows/workflow-graph.ts` |
| 8 | `phase-08-adaptive-router.md` | `tier2-primitives/workflows/adaptive-router.ts` |
| 9 | `phase-09-recovery-handler.md` | `tier2-primitives/workflows/recovery-handler.ts` |
| 10 | `phase-10-skill-registry.md` | `tier2-primitives/routines/skill-registry.ts` |
| 11 | `phase-11-execution-engine.md` | `tier2-primitives/routines/execution-engine.ts` |
| 12 | `phase-12-routine-evolution.md` | `tier2-primitives/routines/routine-evolution.ts` |
| 13 | `phase-13-state-repository.md` | `tier3-compounding/state-repository.ts` |
| 14 | `phase-14-skill-sharpener.md` | `tier3-compounding/skill-sharpener.ts` |

## Upgrades

| Module | Markdown | TypeScript (src/upgrades/) |
|--------|----------|--------------------------|
| Dreaming System | Dream cycle (every 3 goals) | `dreaming-system.ts` |
| Self-Validation | Phase output validation | `self-validator.ts` |
| Multi-Agent | Orchestrator → specialists | `multi-agent.ts` |
| Rubric Engine | N-criteria evaluation | `rubric-engine.ts` |
| Persistent Memory | Episodic/semantic/procedural | `persistent-memory.ts` |
| Enhanced Meta-Agent | Dream → Act → Validate → Codify | `enhanced-meta-agent.ts` |
| Vision Self-Check | Visual output verification | `vision-self-check.ts` |
| Safety Boundary | Model routing + blocked detection | `safety-boundary.ts` |
| Routine Scheduler | Cron-like scheduled runs | `routine-scheduler.ts` |
| Goal Queue | Persistent priority queue | `goal-queue.ts` |
| Daemon Engine | 24/7 autonomous operation | `daemon-engine.ts` |
| PAI Adapter | PAIMM / TELOS / LifeOS | `pai-adapter.ts` |

## Executors

| Executor | TypeScript (src/examples/executors/) | Used For |
|----------|--------------------------------------|----------|
| Sonnet | `sonnet-executor.ts` | Direct Anthropic API |
| OpenAI | `openai-executor.ts` | GPT-4.1 / o3 |
| Local | `local-executor.ts` | Ollama, vLLM, open models |
| Composite | `composite-executor.ts` | Route phases to different models |
| Weak-to-Strong | `weak-to-strong.ts` | Bootstrap skills from weak models |

## Usage

The system runs two ways:

### 1. TypeScript CLI (structured execution)
```bash
fable-agent run "<goal>" --loop 10
fable-agent daemon start
fable-agent skills list
```

### 2. Agent-driven (agent reads markdown files)
1. Load AGENT.md — understands the system
2. Read CONFIG.md — knows what models are available
3. Read STATE.md — loads current state
4. Read relevant PHASES/ — understands the current phase
5. Read relevant SKILLS/ — applies accumulated knowledge
6. Execute using the TS CLI or direct work
7. Write back to STATE.md and sharpen SKILLS/

Both approaches converge on the same architecture. The engine and the spec are the same system.