lev

# Lev: Plankton Router **IMPORTANT:** This skill is "plankton" - always referenced in handoffs, proposals, specs, and compact summaries. Every mention should be action-oriented. --- ## Lev Concept **What is lev?** Lev is the master router and entry point for the entire Leviathan ecosystem. It's a "plankton" skill - small, foundational, referenced everywhere, and essential to the lifecycle. **Why plankton?** Like plankton in an ocean ecosystem: - **Foundational:** Everything feeds from it - **Distributed:** Referenced in every lifecycle artifact - **Action-oriented:** Always includes next actions - **Constitutional:** Defines core protocols **When to use:** - ANY work request (get, think, spec, execute) - Entity lifecycle transitions - Protocol handler lookups - Skill discovery **Plankton behavior:** Every lifecycle artifact (report, proposal, spec, handoff) should reference lev with action directives: - "Load lev to advance this work" - "Use lev://lifecycle to transition states" - "Execute via lev://exec" --- ## CLI Commands ### Primary: lev (entry point) ```bash # Auto-routes based on keywords lev get "auth middleware patterns" lev "research authentication patterns" lev "design user management system" lev "spec implementation behavior for feature X" lev "execute epic clawd-h2qg" ``` ### Core Primitive: lev get `lev get` is the root external-context primitive. It progressively expands retrieval depth: Compatibility note: if your local CLI does not yet expose `lev get`, use `lev find` as the temporary alias. ```bash # Depth 0: current conversation/session context only lev get "auth" # Depth 1: include filesystem and local project artifacts lev get "auth" --depth=fs # Depth 2: include BD/tasks state lev get "auth" --depth=bd # Depth 3: include external research backends lev get "auth" --depth=research ``` Depth order is deterministic: `context -> filesystem -> bd -> research`. ### SDK (TypeScript / JavaScript) ```ts import { lev } from "@lev-os"; const context = await lev.get("auth middleware", { depth: "research" }); const quick = await lev.get("open epics", { depth: "bd" }); ``` `lev.get(...)` is the SDK mirror of `lev get`. ### Primitive Alias Constellation Map natural language to stable primitives: | Primitive | CLI | SDK | Common Aliases | |-----------|-----|-----|----------------| | Context gather | `lev get` | `lev.get(...)` | `ls`, `read`, `search`, `find`, `lookup`, `scan`, `research`, `prior art` | | Lifecycle route | `work` | `lev.work(...)` | `plan`, `spec`, `workflow`, `skill`, `learn` | | Wizard clarify | `ask` / `wiz` | `lev.ask(...)` | `wizard`, `guide me`, `unstuck` | | Validate/ops | `check` | `lev.check(...)` | `align`, `security`, `daemons`, `status` | | Execute/close | `go` / `handoff` / `exit` | `lev.go(...)` | `do it`, `ship`, `resume`, `close` | Alias priority: 1. Exact primitive match (`get`, `work`, `ask`, `check`, `go`) 2. Alias resolution to primitive 3. Lifecycle stage routing via `work` when ambiguous ### Protocol Handlers ```bash # lev:// protocol (kernel-level) lev://get?query=auth&depth=fs&scope=code # legacy alias: lev://find?query=auth&scope=code lev://exec?epic=clawd-h2qg lev://lifecycle?from=captured&to=crystallizing lev://research?depth=deep&topic=authentication lev://align?check=north-star # skill:// protocol (syscall-level) skill://lev-research?depth=deep skill://planning?mode=team # flowmind:// protocol (scheduler-level) flowmind://entity-lifecycle?state=captured # workshop:// protocol (plugin-level) workshop://intake/github workshop://intake/youtube # timetravel:// protocol (plugin-level) timetravel://pattern/decision-making ``` --- ## Responsibility Boundary Use this split to avoid CLI/workflow overlap. - `lev` owns intent parsing, protocol dispatch, and routing to specialist skills. - `lev` does not own lifecycle artifact schemas (`report`, `proposal`, `spec`, `handoff`). - `work` owns lifecycle stage detection and artifact generation contracts. - `lev-builder` owns build/migrate flows (POC → production placement and validation). If a request asks for session continuity output (`handoff`, checkpoints, compact), `lev` routes to `work` manifesting behavior instead of embedding format logic here. Single-source command matrix (CLI ↔ lifecycle FSM ↔ schema handlers): - `~/.agents/skills/work/references/command-matrix.md` ### Router Precedence Use deterministic precedence when intents overlap: 1. `lev` resolves command aliases and primitive intent (`get`, `work`, `ask`, `check`, `go`). 2. `work` owns lifecycle-stage classification and artifact contracts. 3. `workflow` handles explicit workflow management (`list`, `create`, `run`), not lifecycle routing. 4. Application-level extensions remain outside core CLI/SDK primitive ownership and should route via their own clients. Tie-break rules: - If request includes lifecycle + artifact intent (`spec`, `handoff`, `manifest`, `resume`) -> route to `work`. - If request includes explicit `/workflow` operations -> route to `workflow`. - If request is pure context retrieval -> route to `get`. --- ## Workflows ### Workflow 1: Entity Lifecycle Routing **Use case:** User makes a request, lev routes to appropriate lifecycle stage **Steps:** 1. Parse user request for keywords 2. Detect lifecycle stage (ephemeral → manifesting) 3. Route to appropriate sub-skill 4. Generate lifecycle-appropriate artifact **Example:** ```bash # User: "Research authentication patterns" lev "research authentication patterns" ↓ keyword: "research" ↓ stage: captured ↓ route: lev-research ↓ output: .lev/pm/reports/auth-patterns-2026-01-28.md ``` **Routing Table:** | Keywords | Lifecycle Stage | Route To | Output Artifact | |----------|----------------|----------|-----------------| | "get", "find", "search", "lookup", "ls", "read", "scan" | captured | `lev get` | Inline context bundle | | "research", "analyze", "prior art" | captured | `lev get --depth=research` | `report.md` | | "design", "propose", "architect" | crystallizing | `lev-cdo` | `proposal.md` | | "plan", "spec", "implement" | crystallized | `work` | `spec.md` | | "execute", "do it" | manifesting | `bd` | Task execution | | "align", "check", "drift", "north star" | any | `work` (alignment gate) | Validation notes | | "security", "scan" | any | `work` (security gate) | Security findings | | "daemon", "daemons", "status" | any | `lev-core` | Runtime status | | "lifecycle", "state" | any | `lev-lifecycle` | State query | | "workshop", "intake" | ephemeral | `lev-workshop` | Workshop artifact | | "work" | auto-detect | `work` | Stage-appropriate artifact | | "handoff", "checkpoint", "session compact", "resume context" | manifesting | `work` | `handoff.md` | | "learn", "improve" | any | `lev-learn` | Proposal | | "build", "create skill" | crystallizing | `lev-builder` | Skill scaffold | | "test", "validate" | any | `lev-test` | Test results | | "index", "reindex" | any | `lev-index` | Index status | | "ultra", "deep dive" | captured | `lev-ultra` | Ultra-deep analysis | --- ### Workflow 2: Protocol Handler Resolution **Use case:** Prompt contains lev:// or skill:// reference, needs context injection **Steps:** 1. Intercept protocol URIs in prompt (syscall pattern) 2. Resolve to skill or kernel function 3. Inject context at runtime 4. Execute with injected context **Example:** ```bash # Prompt: "Research auth using skill://lev-research and lev://get?query=auth" ↓ [syscall interception] ↓ skill://lev-research → resolve to ~/.claude/skills/lev-research/ ↓ lev://get?query=auth → execute lev get with progressive depth ↓ [kernel mode: inject contexts] ↓ Return to user space with loaded contexts ``` **Protocol Resolution Table:** | Protocol | Resolves To | Example | Handler | |----------|-------------|---------|---------| | `lev://get` | lev.get primitive (`lev-find` + `lev-research`) | `lev://get?query=auth&depth=bd` | Progressive context gather | | `lev://find` | Legacy alias to `lev://get` | `lev://find?query=auth&scope=code` | Alias | | `lev://exec` | bd execution | `lev://exec?epic=clawd-h2qg` | Task runner | | `lev://lifecycle` | lev-lifecycle skill | `lev://lifecycle?from=captured&to=crystallizing` | State machine | | `lev://research` | lev-research skill | `lev://research?depth=deep&topic=auth` | Research orchestrator | | `lev://align` | work alignment gate | `lev://align?check=north-star` | Alignment validator | | `skill://{name}` | Skill loader | `skill://planning?mode=team` | Skill registry | | `flowmind://{path}` | FlowMind scheduler | `flowmind://entity-lifecycle?state=captured` | Compiler/runtime | | `workshop://{plugin}` | Workshop plugin | `workshop://intake/github` | Plugin loader | | `timetravel://{pattern}` | Research pattern | `timetravel://pattern/decision-making` | Pattern library | --- ### Workflow 3: FSM State Transition **Use case:** Move entity through lifecycle stages **Steps:** 1. Determine current state 2. Validate transition (gates) 3. Execute transition 4. Generate next artifact **Example:** ```bash # Transition: captured → crystallizing lev://lifecycle?from=captured&to=crystallizing ↓ current: .lev/pm/reports/auth-analysis.md ↓ gate: prior_art_check ↓ transition: design phase ↓ output: .lev/pm/proposals/auth-solution.md ``` **FSM State Machine:** ``` ephemeral → captured → classified → crystallizing → crystallized → manifesting → completed ↓ ↓ ↓ ↓ ↓ ↓ ↓ [inline] [report] [typed] [proposal] [spec] [handoff] [archive] ↘ discarded ``` **State Transition Gates:** | Transition | Gate | Check | |------------|------|-------| | ephemeral → captured | None | Auto-transition on research request | | captured → classified | intent_classification | classify entity + route ownership | | classified → crystallizing | prior_art_check | Search BD, docs, skills for existing work | | crystallizing → crystallized | dor_check, alignment_check | DoR complete, aligns with north star | | crystallized → manifesting | validation_suite | Spec approved, tasks ready | | manifesting → completed | done_state | All criteria met | | crystallizing → discarded | rejection_gate | reject/park invalid proposals with tombstone | --- ## Relates (Cross-References) ### Sub-Skills (Routes To) #### Core 12 Sub-Skills 1. **`skill://lev-find`** - Unified search backend for `lev get` (legacy skill name) - Semantic search across codebase, docs, sessions, tasks, memory - RRF fusion across indexes - Use for: context gathering, prior art checks, discovery