Architecture

Architecture

Zeref OS comprises four main layers:

1. AGENTS.md (Source of Truth): Central spec that lists all agents, skills, commands, team packs, and global rules. All harness-specific files (e.g. CLAUDE.md, CURSOR.md) are thin stubs that refer back to this spec.

2. Agents (Always-on): Six background roles that run every session:

   • memory-keeper – Single writer to the flat memory/; handles all reads/writes/logs.
   • privacy-guardian – Enforces PRIVACY.md, REDACT.md, and SHARING_POLICY.md on every operation.
   • sync-coordinator – Manages file permissions and parent-sync when using /sync-parent.
   • evidence-curator – Attaches confidence and provenance tags to memory entries.
   • pattern-observer – Watches memory/patterns/PATTERNS.jsonl for repeats (triggers skill drafts).
   • handoff-orchestrator – On /stop, packages the session for cross-harness handoff.

3. Skills (On-trigger): Ten specialized skills in skills/ (e.g. pattern-to-skill, budget-governor, wiki-maintenance) that execute when their trigger phrases are detected in prompts.

4. Commands: Eight user commands documented in commands/ (such as /start, /stop, /team, /review-skill, etc.) that the user invokes to control Zeref OS.

5. Team Packs (On-demand): Pre-defined multi-agent workflows (solo, build, research, red, audit, ship). For instance, /team audit runs a security audit team with 3 agents, and outputs all findings in team/audit/.

flowchart LR
  User((User)) -->|`/zeref-os:command`| Harness
  Harness -->|reads| AG[AGENTS.md]
  AG --> Agents
  AG --> Skills
  AG --> Commands
  AG --> TeamPacks

  subgraph Agents["6 agents — always-on"]
    MK[memory-keeper]
    PG[privacy-guardian]
    SC[sync-coordinator]
    EC[evidence-curator]
    PO[pattern-observer]
    HO[handoff-orchestrator]
  end

  subgraph Skills["10 skills — on-trigger"]
    PS[project-setup]
    WM[wiki-maintenance]
    CR[contradiction-resolution]
    PA[privacy-abstraction]
    PSY[parent-sync]
    P2S[pattern-to-skill]
    MIE[memory-import-export]
    BG[budget-governor]
    HC[handoff-compiler]
    EG[evidence-grader]
  end

  subgraph Commands["8 commands"]
    C1[start]
    C2[stop]
    C3[status]
    C4[reset-permissions]
    C5[sync-parent]
    C6[review-skill]
    C7[team]
    C8[done]
  end

  subgraph TeamPacks["6 team packs — on-demand"]
    TP1[solo]
    TP2[build]
    TP3[research]
    TP4[red: read-only]
    TP5[audit]
    TP6[ship]
  end

  MK <--> Mem[(memory/ flat)]
  PG -. "enforces policies" .-> Mem
  PO -. "logs patterns" .-> PJ["memory/patterns/PATTERNS.jsonl"]

Loading