# Skill

> Etta Cognitive OS — Skill Runtime

- Skill: `bluem-dev/skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bluem-dev/skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bluem-dev/skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bluem-dev (https://skillmd.com/u/bluem-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bluem-dev/skill

---


# Etta Cognitive OS — Skill Runtime

Etta Cognitive OS is a **cognitive control layer** that sits between user input and LLM execution.
It transforms probabilistic LLM reasoning into a structured, deterministic cognitive system.

**Core principle:** Claude thinks → Etta decides → Workspace executes.

---

## System Architecture

```
USER INPUT
    │
    ▼
 LLM Core (Claude)           ← probabilistic reasoning, hypothesis generation
    │  structured JSON output only
    ▼
 Etta Cognitive Layer
    ├── Goal Engine           ← extract & hierarchize intent
    ├── State Engine          ← merge & track cognitive state (versioned)
    ├── Memory Engine         ← multi-tier persistence (fact/obs/decision/failure)
    ├── Decision Engine       ← propose actions with confidence scores
    ├── Critic Engine         ← validate decisions (hard gate — no bypass)
    ├── Compression Engine    ← prune redundant state
    └── Evolution Engine      ← adapt policies from history
    │
    ▼
 Workspace OS                ← sole executor of external effects
    ├── Permission Engine
    ├── Transaction Manager
    ├── Audit Logger
    └── Tool Interface Layer
    │
    ▼
 OUTPUT + STATE UPDATE
```

**Authority hierarchy (highest → lowest):**
Protocol → Workspace OS → Execution Runtime → Etta Cognitive Layer → LLM Core → User Input

---

## Core Execution Loop

Every Etta cycle follows this **strictly ordered** state machine:

```
INIT → LOAD_STATE → PLAN → DECIDE → VALIDATE → EXECUTE → COMMIT → COMPRESS → COMPLETE
```

Steps:
1. Ingest user input
2. Call LLM → get structured JSON output
3. **Goal Engine** → extract `{goal, subgoals, priority, constraints}`
4. **State Engine** → merge into versioned state object
5. **Memory Engine** → inject relevant memory snapshot
6. **Decision Engine** → propose `{actions, rationale, confidence, hypothesis_branch}`
7. **Critic Engine** → validate (HARD GATE — loop until valid or escalate)
8. **Workspace OS** → execute validated action transactionally
9. **State Engine** → commit state update + increment version
10. **Memory Engine** → write decision record (immutable append)
11. **Compression Engine** → prune redundant state
12. Return output

**Invariants — never violate:**
- No execution without Critic approval
- No state mutation outside State Engine
- No memory writes without schema validation
- No LLM → Workspace direct path (always through Etta Runtime)
- All actions must be logged and auditable

---

## Implementation

Read `references/implementation.md` for full Python code covering:
- `ClaudeBridge` — LLM integration with structured JSON output enforcement
- `StateEngine` — versioned state merge and mutation
- `MemoryEngine` — JSONL append-only persistence
- `DecisionEngine` — action proposal with confidence scoring
- `CriticEngine` — validation gate with retry loop
- `WorkspaceOS` — transactional execution layer
- `EttaRuntime` — orchestration loop (`run_cycle()`)
- `main.py` — CLI entrypoint

Read `references/schemas.md` for all canonical data schemas:
- Canonical State Object
- Memory Entry Schema
- Decision Object
- Global Message Envelope
- Event Contract
- Error Contract
- All Engine I/O Contracts

---

## When Implementing Etta as a SKILL/Plugin

### Minimal Viable Etta (context-window only, no persistence)

For LLM agents operating inside a single context window (e.g., Claude SKILL):

```python
# Etta state lives as a structured dict injected into every prompt
etta_state = {
    "goal": "",
    "subgoals": [],
    "hypotheses": {"active": [], "rejected": []},
    "decisions": [],          # append-only
    "memory": {"facts": [], "observations": [], "failures": []},
    "constraints": [],
    "confidence": 1.0,
    "version": 0,
    "execution_state": "INIT"
}
```

Inject state into every LLM system prompt. Enforce JSON-only output.
Run the Critic check inline before acting on any decision.

### As a Claude SKILL

The SKILL prompt instructs Claude to:
1. Always begin a session by loading/initializing Etta state
2. Parse every user turn through the Goal Engine logic
3. Maintain state explicitly in its reasoning (or via tool/storage)
4. Apply Critic validation before outputting any action
5. Log decisions and failures to memory (JSONL or storage API)
6. Compress state when context fills up

### As a Python Plugin / External Agent

Use the full implementation from `references/implementation.md`.
Etta Runtime wraps any LLM call and enforces the cognitive loop externally.

---

## Failure Handling

| Failure | Response |
|---|---|
| Critic rejection | Retry Decision Engine (max 3 iterations, then escalate) |
| Execution failure | Rollback transaction, log to failure memory |
| State desync | Rehydrate from last valid version |
| Memory corruption | Skip entry, log deprecation |
| LLM parse error | Re-prompt with explicit JSON schema |

---

## Key Design Rules

- **Claude outputs JSON only** — never free-text reasoning inside Etta loop
- **State is the single source of truth** — all engines read from and write to state
- **Decisions are immutable** — append-only, never deleted
- **Failures cannot be deleted** — only deprecated (they inform Critic calibration)
- **Workspace is the sole executor** — no engine bypasses it
- **All communication is schema-validated** — reject partial or untyped messages