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)

# 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.

# 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)

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:

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

# 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:

# 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:

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:

# 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:

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:

# 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:

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
2. •

   skill://lev-research - Deep research (ANALYZE)

   • •Multi-perspective orchestrated discovery
   • •Query expansion, cross-validation
   • •Use for: complex topics, architecture exploration, gap analysis
3. •

   skill://lev-index - Code/doc indexing

   • •Maintain search indexes
   • •Reindex on changes
   • •Use for: index health, rebuilds
4. •

   skill://lev-cdo - Graph thinking (THINK)

   • •Agentic orchestration
   • •Classification → routing → execution
   • •Use for: strategic design, multi-agent workflows
5. •

   skill://lev-ultra - Ultra-deep analysis

   • •Deepest level research
   • •Comprehensive exploration
   • •Use for: complex problem spaces requiring exhaustive analysis
6. •

   skill://lev-align - Legacy standalone alignment audit

   • •Default behavior: alignment runs inside work ALIGN gate
   • •Use standalone only for explicit drift-audit deep dives
7. •

   skill://lev-test - Testing validation

   • •Test suite execution
   • •Validation gates
   • •Use for: quality checks, test results
8. •

   skill://lev-lifecycle - Entity lifecycle management

   • •State machine orchestration
   • •Idea/session/synth lifecycles
   • •Use for: state transitions, entity queries
9. •

   skill://work - Unified lifecycle router

   • •Auto-detects lifecycle stage
   • •Routes to specialist skills
   • •Use for: ANY work request (auto-routing)
10. •

    skill://lev-learn - Pattern analysis & proposals

    • •Event analysis
    • •Improvement proposals
    • •Use for: learning from patterns, evolution
11. •

    skill://lev-builder - Skill builder

    • •Scaffold new skills
    • •Skill structure generation
    • •Use for: creating new skills
12. •

    skill://lev-workshop - Workshop lifecycle

    • •Intake → analysis → poc → poly
    • •Plugin development
    • •Use for: building new lev components

Additional Sub-Skills

• •skill://lev-clwd - Clawdbot operations (daemon, gateway, voice)
• •skill://lev-intake - Task intake workflows
• •skill://lev-skill-builder - Skill construction
• •skill://lev-computer-use - Computer use integration

Protocol Handlers

• •lev://get → lev.get primitive
• •lev://find → legacy alias to lev://get
• •lev://exec → bd execution engine
• •lev://lifecycle → lev-lifecycle state machine
• •lev://research → lev-research orchestrator
• •lev://align → work alignment gate

Lifecycle Artifacts

• •Reports (captured) → proposals (crystallizing)
• •Proposals (crystallizing) → specs (crystallized)
• •Specs (crystallized) → handoffs (manifesting)
• •Handoffs (manifesting) → archive (completed)

Constitutional References

• •Handoffs: "Load lev to resume work"
• •Proposals: "Use lev to convert to spec"
• •Specs: "Execute via lev://exec"
• •Reports: "Design solution with lev"

Validation Gates

Entry Gate (Before Route)

• • Request parsed successfully
• • Keywords detected
• • Lifecycle stage determined
• • Sub-skill available

Transition Gates (Between States)

captured → crystallizing:

• • Prior art check complete (BD, docs, skills)
• • No duplicate work found OR justified
• • Research findings documented

crystallizing → crystallized:

• • DoR validation complete
• • Alignment check passed (work alignment gate)
• • Design approved

crystallized → manifesting:

• • Validation suite passed
• • Spec approved
• • Tasks created (if BD available)

manifesting → completed:

• • Done state criteria met
• • All tasks closed
• • Artifacts archived

Exit Gate (After Execution)

• • Artifact generated
• • Lifecycle position updated
• • Next actions documented
• • Plankton reference included

Plankton Action Directives

In templates, always include:

Handoffs

## Next Steps
Load lev to resume work:
- Continue context gathering: `lev://get?query={topic}&depth=research`
- Design solution: `lev://lifecycle?from=captured&to=crystallizing`
- Execute spec: `lev://exec?epic={bd_epic_id}`

Proposals

## Next Steps
Use lev to advance this proposal:
- Create spec: `lev://lifecycle?from=crystallizing&to=crystallized`
- Validate alignment: `skill://work`
- Research alternatives: `lev://research?depth=deep&topic={topic}`

Specs

## Execution
Execute this spec:
- Scaffold epic: `lev://exec?spec=spec.md`
- Team mode: `lev://exec?epic={bd_epic_id}`
- Track progress: `skill://bd`

Reports

## Next Steps
Design solution from findings:
- Propose: `lev://lifecycle?from=captured&to=crystallizing`
- Research more: `lev://get?query={topic}&depth=research`
- Deep dive: `lev://research?depth=deep&topic={topic}`

Sub-Skills Reference

Each sub-skill has its own SKILL.md with full detail. Lev acts as router.

lev/
├── SKILL.md                  # This file (router + plankton)
├── lev-find/
│   └── SKILL.md              # Search operations
├── lev-research/
│   └── SKILL.md              # Deep research workflows
├── lev-cdo/
│   └── SKILL.md              # Graph thinking
├── lev-lifecycle/
│   └── SKILL.md              # Entity lifecycle FSM
├── work/
│   └── SKILL.md              # Unified lifecycle router
├── lev-align/
│   └── SKILL.md              # Strategic alignment
├── lev-learn/
│   └── SKILL.md              # Pattern analysis
├── lev-builder/
│   └── SKILL.md              # Skill scaffolding
├── lev-workshop/
│   └── SKILL.md              # Workshop lifecycle
├── lev-ultra/
│   └── SKILL.md              # Ultra-deep analysis
├── lev-test/
│   └── SKILL.md              # Testing validation
├── lev-index/
│   └── SKILL.md              # Index management
├── lev-clwd/
│   └── SKILL.md              # Clawdbot operations
└── [other sub-skills...]

Router decision logic:

• •If request is simple context gather → lev get
• •If request needs deep analysis → lev-research
• •If request needs design thinking → lev-cdo
• •If request is execution → bd via work skill
• •If request is ambiguous → work skill (auto-routes)
• •If request mentions lifecycle → lev-lifecycle
• •If request about alignment/security checks → work
• •If request about building skills → lev-builder
• •If request about workshop/intake → lev-workshop

Usage Examples

Example 1: Simple Get

lev get "authentication middleware"
  ↓ keyword: "get"
  ↓ route: lev.get primitive
  ↓ execute: progressive context gather
  ↓ output: inline results

Example 2: Deep Research

lev "research microservices architecture patterns"
  ↓ keyword: "research"
  ↓ route: lev-research
  ↓ execute: multi-perspective discovery
  ↓ output: .lev/pm/reports/microservices-analysis-2026-01-28.md

Example 3: Design Work

lev "design a solution for user authentication"
  ↓ keyword: "design"
  ↓ stage: crystallizing
  ↓ route: lev-cdo
  ↓ execute: strategic planning
  ↓ output: .lev/pm/proposals/auth-solution-2026-01-28.md

Example 4: Spec Authoring

lev "spec implementation behavior for auth system"
  ↓ keyword: "spec"
  ↓ stage: crystallized
  ↓ route: work
  ↓ execute: DoR-enforced spec generation
  ↓ output: .lev/pm/specs/auth-implementation-2026-01-28.md

Example 5: Lifecycle Transition

lev "transition idea-001 from captured to crystallizing"
  ↓ keyword: "lifecycle", "transition"
  ↓ route: lev-lifecycle
  ↓ execute: state machine transition
  ↓ output: state updated, proposal generated

Example 6: Alignment Check

lev "check if current work aligns with north star"
  ↓ keyword: "align", "north star"
  ↓ route: work (alignment gate)
  ↓ execute: drift detection + lifecycle validation
  ↓ output: alignment report

Example 7: Auto-Routed Work

lev "analyze test coverage and propose improvements"
  ↓ keyword: "analyze", "propose"
  ↓ ambiguous stage
  ↓ route: work (auto-detect)
  ↓ work determines: captured (research) → crystallizing (design)
  ↓ output: report.md + proposal.md

Integration Points

With Entity Lifecycle

• •Maps FSM states to appropriate sub-skills
• •Generates lifecycle-appropriate artifacts
• •Validates state transitions via gates

With BD (Beads)

• •Links specs to BD epics
• •Tracks tasks via BD CLI
• •Routes execution through BD

With FlowMind

• •Supports flowmind:// protocol handlers
• •Integrates with compiler/runtime
• •Enables YAML-first behavior

With Workshop

• •Routes intake requests to workshop plugins
• •Supports workshop:// protocol
• •Manages poc → poly transitions

With Team Mode

• •Delegates to planning skill for team decomposition
• •Coordinates multi-agent workflows
• •Tracks teammate assignments

Principles

1. •Single Entry Point - All lev operations start here
2. •Progressive Disclosure - Start simple, route to specialists as needed
3. •Lifecycle Awareness - Route based on entity state
4. •Protocol Driven - Support URI-based invocation
5. •Plankton Behavior - Always include action directives
6. •Constitutional - Define core patterns, don't re-implement

Plankton status: ✅ ACTIVE Constitutional: ✅ YES Always reference: In all lifecycle artifacts with action directives

Technique Map

• •Role definition - Clarifies operating scope and prevents ambiguous execution.
• •Context enrichment - Captures required inputs before actions.
• •Output structuring - Standardizes deliverables for consistent reuse.
• •Step-by-step workflow - Reduces errors by making execution order explicit.
• •Edge-case handling - Documents safe fallbacks when assumptions fail.

Technique Notes

These techniques improve reliability by making intent, inputs, outputs, and fallback paths explicit. Keep this section concise and additive so existing domain guidance remains primary.

Prompt Architect Overlay

Role Definition

You are the prompt-architect-enhanced specialist for lev, responsible for deterministic execution of this skill's guidance while preserving existing workflow and constraints.

Input Contract

• •Required: clear user intent and relevant context for this skill.
• •Preferred: repository/project constraints, existing artifacts, and success criteria.
• •If context is missing, ask focused questions before proceeding.

Output Contract

• •Provide structured, actionable outputs aligned to this skill's existing format.
• •Include assumptions and next steps when appropriate.
• •Preserve compatibility with existing sections and related skills.

Edge Cases & Fallbacks

• •If prerequisites are missing, provide a minimal safe path and request missing inputs.
• •If scope is ambiguous, narrow to the highest-confidence sub-task.
• •If a requested action conflicts with existing constraints, explain and offer compliant alternatives.