lev-builder: POC → Formalize → Migrate

Core principle: Build in a workspace POC, prove it works, migrate to ~/lev canonical paths.

Why This Exists

PROBLEM:
- Work happens across mixed workspaces (project-local, workshop, plugins)
- BD issues are in lev (lev-* prefix)
- Need to know WHERE to put things in Leviathan
- Need prior art check before creating new

SOLUTION:
- lev-builder orchestrates the full workflow
- POC in `~/lev/workshop/poc` (or project-local skills) → migrate to `~/lev/core` when proven
- Uses graph operations for decisioning, then applies explicit filesystem patches during migration

The Builder Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    LEV-BUILDER WORKFLOW                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1️⃣ ASSESS (What exists?)                                       │
│  ├─ lev get "topic" --indexes codebase,docs,skills            │
│  ├─ Check ~/lev/core/* for existing modules                    │
│  ├─ Check ~/lev/workshop/poc/* for prior POCs                  │
│  └─ Output: Related code, docs, skills found                   │
│                                                                 │
│  2️⃣ PRIOR ART CHECK (Duplicate prevention)                      │
│  ├─ ./scripts/prior-art-check.sh "topic"                       │
│  ├─ bd search "topic"                                          │
│  ├─ Skill lookup: ~/lev/workshop/poc/lookup/                   │
│  └─ Output: Existing work to patch vs. new work to create      │
│                                                                 │
│  3️⃣ PLACEMENT DECISION (Where does it go?)                      │
│  ├─ Escalate to user if ambiguous                              │
│  │   "Should this be in core/auth or core/vault?"              │
│  ├─ Consult LEVIATHAN_PATHS.md                                 │
│  └─ Output: Target path confirmed                              │
│                                                                 │
│  4️⃣ GRAPH PLAN + FILE PATCH                                     │
│  ├─ Generate graph mutation plan from design doc              │
│  ├─ Materialize approved changes as filesystem patch          │
│  ├─ Apply to target location                                  │
│  └─ Output: Files created/modified                            │
│                                                                 │
│  5️⃣ E2E VALIDATION (Confirm it works)                           │
│  ├─ Run relevant tests                                         │
│  ├─ Typecheck: bun run typecheck                               │
│  ├─ Integration test if applicable                             │
│  └─ Output: Validation results                                 │
│                                                                 │
│  6️⃣ MIGRATE (POC → Production)                                  │
│  ├─ If POC in workshop/project skills: move to lev/core        │
│  ├─ Update skill registry                                      │
│  ├─ Create migration PR/commit                                 │
│  └─ Output: Migration complete                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Leviathan Paths Reference

# Where things go in Leviathan

~/lev/core/
├── harness/          # Agent execution, adapters, Ralph
├── auth/             # Fleet RBAC, permissions (NEW)
├── cdo/              # Graph runtime, state machines
├── commands/         # CLI commands
├── config/            # Configuration system
├── daemons/          # Background services
├── graph/            # Graph primitives
├── lifecycle/        # Entity lifecycle, state transitions
├── memory/           # Memory layer
├── vault/            # Data vault, leases (NEW)
└── ...

~/lev/workshop/
├── intake/           # Ingested external projects
├── poc/              # Proof of concepts
│   └── lookup/       # Skill discovery system
└── ...

Quick Commands

1. Assess Topic

# If `lev get` is not available yet in your CLI build, substitute `lev find`.
# Full assessment
lev get "fleet authorization" --indexes codebase,docs,skills,tasks

# Check core modules
ls ~/lev/core/ | grep -i auth

# Check POCs
ls ~/lev/workshop/poc/ | grep -i auth

# Check skills
ls ~/.agents/skills/ | grep -i auth

2. Prior Art Check

# Deterministic check
./scripts/prior-art-check.sh "data vault leases"

# BD search
bd search "vault" --root-path ~/lev
bd search "lease" --root-path ~/lev

# Skill lookup
node ~/lev/workshop/poc/lookup/cli.js search "authorization"

3. Escalate Decision

# In agent context
escalate({
  type: "PLACEMENT_DECISION",
  question: "Should fleet-rbac.ts go in core/auth or core/permissions?",
  options: [
    { path: "core/auth/fleet-rbac.ts", reason: "Auth is about identity" },
    { path: "core/permissions/fleet-rbac.ts", reason: "RBAC is permissions" }
  ],
  context: "Fleet auth controls who can spawn agents and access data"
})

4. Graph Plan + File Patch

# Generate patch plan from design doc
cat pm/designs/fleet-swarm-authorization.md | \
  ./scripts/design-to-patch.sh > patches/fleet-auth.patch

# Apply patch (preview)
./scripts/apply-patch.sh patches/fleet-auth.patch --dry-run

# Apply patch (execute)
./scripts/apply-patch.sh patches/fleet-auth.patch --target ~/lev/core/auth/

5. Validate E2E

# Typecheck
cd ~/lev && bun run typecheck

# Run tests for module
bun test core/auth/

# Integration test
bun test:integration --filter "fleet"

6. Migrate POC

# Move skill from workshop POC to lev
./scripts/migrate-skill.sh ~/lev/workshop/poc/lev-builder ~/lev/core/builder

# Update registry
./scripts/update-skill-registry.sh

# Commit
cd ~/lev && git add . && git commit -m "feat: migrate lev-builder from POC"

Integration with Other Skills

Common Workflows

Workflow 1: New Feature

USER: "Add fleet authorization to Leviathan"

BUILDER:
1. ASSESS: lev get "fleet\|authorization\|rbac"
   → Found: core/config has some auth, no fleet module
   
2. PRIOR ART: bd search "authorization"
   → Found: lev-qtpq.7 task exists for this
   
3. PLACEMENT: Escalate "core/auth vs core/permissions?"
   → User: "core/auth"
   
4. PATCH: Generate fleet-rbac.ts from design doc
   → Created: ~/lev/core/auth/fleet-rbac.ts
   
5. VALIDATE: bun run typecheck && bun test core/auth/
   → Passed
   
6. MIGRATE: N/A (already in lev/core)

Workflow 2: POC to Production

USER: "Migrate lev-builder skill to production"

BUILDER:
1. ASSESS: ls ~/lev/workshop/poc/lev-builder/
   → Found: SKILL.md, scripts/
   
2. PRIOR ART: ls ~/lev/core/builder/
   → Not found (new module)
   
3. PLACEMENT: "core/builder" (builder is core infra)
   → Confirmed
   
4. PATCH: Copy + adapt for lev structure
   → Created: ~/lev/core/builder/
   
5. VALIDATE: bun test core/builder/
   → Passed
   
6. MIGRATE: git commit, update registry
   → Done

Workflow 3: Assess & Consolidate

USER: "What exists for caching in Leviathan?"

BUILDER:
1. ASSESS: 
   lev get "cache\|caching" --indexes codebase,docs
   → Found: 
     - core/config/cache.ts (config caching)
     - workshop/poc/redis-cache/ (POC)
     - docs/adr/ADR-045-caching.md (decision)
   
2. REPORT:
   "Caching exists in 3 places:
    - Config cache: production (core/config)
    - Redis POC: not migrated (workshop/poc)
    - ADR-045: recommends unified cache layer
    
    Recommend: Consolidate into core/cache/"

3. ESCALATE: "Proceed with consolidation?"

Escalation Patterns

// Decision types that trigger escalation
const ESCALATION_TRIGGERS = [
  "PLACEMENT_DECISION",      // Where to put code
  "CONSOLIDATION_DECISION",  // Merge vs keep separate
  "ARCHITECTURE_DECISION",   // Significant design choice
  "MIGRATION_APPROVAL",      // Moving POC to production
  "DEPENDENCY_ADDITION",     // Adding new dependencies
];

// Escalate via Telegram (approval buttons)
await escalate({
  type: "PLACEMENT_DECISION",
  question: "...",
  options: [...],
  buttons: [
    { text: "Option A", callback_data: "placement:core/auth" },
    { text: "Option B", callback_data: "placement:core/permissions" },
    { text: "Discuss", callback_data: "placement:discuss" },
  ]
});

State Tracking

# .lev/builder/state.jsonl
{"ts":"...","action":"assess","topic":"fleet auth","results":["core/auth","lev-qtpq.7"]}
{"ts":"...","action":"prior_art","topic":"fleet auth","found":true,"matches":1}
{"ts":"...","action":"escalate","type":"PLACEMENT_DECISION","resolved":true,"choice":"core/auth"}
{"ts":"...","action":"patch","target":"core/auth/fleet-rbac.ts","status":"created"}
{"ts":"...","action":"validate","target":"core/auth/","passed":true}

Summary

lev-builder answers:

1. What exists? → Assess with lev get
2. Is there prior art? → Check with lev-patch
3. Where does it go? → Escalate placement decisions
4. How to apply? → Graph plan + explicit filesystem patch
5. Does it work? → E2E validation
6. Ready for production? → Migrate POC to lev/core

Relates

Master Router

• Lev Master Router (lev/SKILL.md) - Routes all lev-* skills Parent skill that dispatches to this skill based on keywords/context

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-builder, 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.