# Lev Workshop

> Workshop lifecycle intake→analysis→POC→poly for lev hooks, plugins, and integrations. Use when building or promoting lev capabilities.

- Skill: `lev-os/lev-workshop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lev-os/lev-workshop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lev-os/lev-workshop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Integrations & APIs
- Author: lev-os (https://skillmd.com/u/lev-os)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lev-os/lev-workshop

---


# Lev Workshop

The workshop is where ideas become capabilities. It's the factory floor for building hooks, plugins, and integrations that extend lev's functionality.

## Workshop Lifecycle

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   INTAKE    │ →  │  ANALYSIS   │ →  │     POC     │ →  │    POLY     │
│             │    │             │    │             │    │ INTEGRATION │
│ Raw idea or │    │ Understand  │    │ Build       │    │ Production  │
│ requirement │    │ scope &     │    │ working     │    │ deployment  │
│             │    │ approach    │    │ prototype   │    │ & routing   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     │                   │                   │                   │
     ▼                   ▼                   ▼                   ▼
 config_loader     dependency_checker   checkpoint_manager   quality_gate
 error_handler     progress_reporter    error_handler        success_handler
                   quality_gate         quality_gate         escalation_handler
```

## When to Use

| Trigger | Action |
|---------|--------|
| "workshop this" | Start intake for new capability |
| "analyze for workshop" | Deep-dive on requirements |
| "poc this" | Build proof of concept |
| "integrate to poly" | Promote POC to production |
| "workshop status" | Show items in each phase |
| "what's in poc?" | List active prototypes |

## Phase Details

### Phase 1: Intake

**Purpose:** Capture raw ideas, requirements, or problems that need solving.

**Input:** Natural language description, error message, feature request, or observed pattern.

**Process:**
1. `config_loader` - Load relevant domain context
2. `error_handler` - If intake is from error, parse and classify
3. Classify intake type:
   - `hook` - Lifecycle hook meta-prompt
   - `plugin` - External integration
   - `pattern` - Reusable workflow
   - `fix` - Bug fix or improvement

**Output:** Workshop item in `~/lev/workshop/intake/`

```yaml
# ~/lev/workshop/intake/item-001.yaml
id: ws-001
type: hook
title: "Retry with circuit breaker"
source: "Observed repeated failures in CB3 scraping"
created: "2026-01-13T10:00:00Z"
status: intake
raw_input: |
  CB3 keeps hitting rate limits and retrying forever.
  Need a circuit breaker pattern.
```

### Phase 2: Analysis

**Purpose:** Understand scope, dependencies, and approach before building.

**Process:**
1. `dependency_checker` - What does this need?
2. `progress_reporter` - Track analysis progress
3. Research existing implementations
4. Define success criteria
5. `quality_gate` - Is analysis complete enough to proceed?

**Questions to answer:**
- What existing hooks/plugins does this interact with?
- What's the minimal viable implementation?
- What are the edge cases?
- How will we test it?

**Output:** Analysis document added to workshop item

```yaml
# Updated item-001.yaml
analysis:
  dependencies:
    - error_handler (hook)
    - checkpoint_manager (hook)
  approach: |
    1. Track failure count per operation
    2. Open circuit after N failures
    3. Half-open state for testing
    4. Auto-close after cooldown
  success_criteria:
    - Circuit opens after 3 failures
    - Half-open after 30s
    - Full close after 3 successes
  estimated_complexity: medium
  analysis_complete: true
```

### Phase 3: POC (Proof of Concept)

**Purpose:** Build a working prototype to validate the approach.

**Process:**
1. `checkpoint_manager` - Save state frequently during development
2. Build minimal implementation
3. `error_handler` - Handle development errors
4. Test against success criteria
5. `quality_gate` - Does POC meet criteria?

**Location:** `~/lev/workshop/poc/<item-id>/`

**POC requirements:**
- Must run standalone
- Must have basic tests
- Must document usage
- Must log decisions

**Output:** Working prototype with test results

```yaml
# Updated item-001.yaml
poc:
  location: ~/lev/workshop/poc/ws-001/
  files:
    - circuit_breaker.py
    - test_circuit_breaker.py
    - README.md
  test_results:
    passed: 8
    failed: 0
  demo_command: "python circuit_breaker.py --demo"
  poc_complete: true
```

### Phase 4: Poly Integration

**Purpose:** Promote POC to production across multiple integration targets.

**Process:**
1. `quality_gate` - Final validation before integration
2. Identify integration targets (poly = multiple destinations)
3. `success_handler` - Route to each target
4. `escalation_handler` - Handle integration failures

**Integration targets:**
- **lev-lifecycle** - New hook added to hooks.md
- **claude-agent-sdk** - Pattern added to patterns.md
- **Project-specific** - CB3, TimeTravel, josh-imessage, etc.
- **System** - `~/lev/plugins/` and project hooks for automated workflows

**Poly routing abstraction:**
```yaml
# Integration targets can register as recipients
integration_targets:
  lev_hooks:
    type: hook
    location: ~/.claude/skills/lev-lifecycle/references/hooks.md
    format: yaml_block

  agent_sdk_patterns:
    type: pattern
    location: ~/.claude/skills/claude-agent-sdk/references/patterns.md
    format: python_code

  cb3_tools:
    type: tool
    location: ~/cb3/src/tools/
    format: python_module

  timetravel_adapters:
    type: adapter
    location: ~/lev/research/timetravel/src/adapters/
    format: typescript_module
```

**Output:** Integrated capability with routing info

```yaml
# Updated item-001.yaml
integration:
  status: complete
  integrated_to:
    - target: lev_hooks
      location: ~/.claude/skills/lev-lifecycle/references/hooks.md
      section: "Hook 11: Circuit Breaker"
    - target: cb3_tools
      location: ~/cb3/src/tools/circuit_breaker.py
  routing_rules:
    - pattern: "error_handler returns retry && retry_count >= 3"
      route_to: circuit_breaker
  post_integration_hooks:
    - update_docs
    - notify_user
```

## Workshop Item Schema

```yaml
id: ws-XXX
type: hook | plugin | pattern | fix
title: string
source: string  # where this came from
created: timestamp
status: intake | analysis | poc | integrating | complete | archived

# Phase outputs
raw_input: string
analysis:
  dependencies: array
  approach: string
  success_criteria: array
  estimated_complexity: low | medium | high
  analysis_complete: boolean

poc:
  location: path
  files: array
  test_results: object
  demo_command: string
  poc_complete: boolean

integration:
  status: pending | in_progress | complete | failed
  integrated_to: array
  routing_rules: array
  post_integration_hooks: array

# Metadata
bd_issue: string  # linked bd bead
related_items: array
tags: array
```

## Process Tracking

Workshop items are tracked in bd for visibility across sessions:

```bash
# Create bd issue for workshop item
bd create "Workshop: Circuit Breaker Hook" -t feature -p 2 \
  -d "Build circuit breaker pattern for retry logic"

# Link workshop item to bd
# In item-001.yaml:
# bd_issue: ws-circuit-breaker-001

# Query workshop status
bd list --label workshop --status open
```

## CLI Commands

```bash
# Start new workshop item
lev workshop intake "Need circuit breaker for retries"

# Check workshop status
lev workshop status

# List items by phase
lev workshop list --phase poc

# Promote to next phase
lev workshop promote ws-001 --to analysis
lev workshop promote ws-001 --to poc
lev workshop promote ws-001 --to integration

# Run POC tests
lev workshop test ws-001

# Integrate to target
lev workshop integrate ws-001 --target lev_hooks

# Archive completed item
lev workshop archive ws-001
```

## Example: Building a New Hook

```bash
# 1. Intake
lev workshop intake "Error handler should support circuit breaker pattern"
# → Creates ws-001 in intake phase

# 2. Analysis
lev workshop analyze ws-001
# Agent asks questions, researches existing hooks
# → Adds analysis section, promotes to analysis phase

# 3. POC
lev workshop poc ws-001
# Agent builds prototype in poc/ws-001/
# → Creates files, runs tests, promotes to poc phase

# 4. Integration
lev workshop integrate ws-001 --target lev_hooks
# Agent adds to hooks.md, updates references
# → Routes to all configured targets

# 5. Complete
lev workshop complete ws-001
# Archives item, updates bd issue
```

## Integration with Claude Agent SDK

Workshop items that involve LLM decision points use the Claude Agent SDK:

```python
from claude_agent_sdk import query, ClaudeAgentOptions

async def analyze_workshop_item(item_id: str):
    """Use agent to analyze workshop item requirements"""
    async for msg in query(
        prompt=f"""
        Analyze workshop item {item_id} for implementation:
        1. Read the raw input
        2. Identify dependencies on existing hooks/plugins
        3. Propose minimal implementation approach
        4. Define success criteria
        5. Estimate complexity
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob"],
            permission_mode="bypassPermissions"
        )
    ):
        if hasattr(msg, "result"):
            return msg.result
```

## Hooks Used Per Phase

| Phase | Hooks | Purpose |
|-------|-------|---------|
| Intake | config_loader, error_handler | Load context, parse errors |
| Analysis | dependency_checker, progress_reporter, quality_gate | Check requirements, track progress, validate completeness |
| POC | checkpoint_manager, error_handler, quality_gate | Save state, handle failures, validate prototype |
| Integration | quality_gate, success_handler, escalation_handler | Final validation, route to targets, handle failures |

## References

- `~/.claude/skills/lev-lifecycle/` - Parent lifecycle skill
- `~/.claude/skills/lev-lifecycle/references/hooks.md` - Hook meta-prompts
- `~/.claude/skills/claude-agent-sdk/` - Agent patterns for LLM integration
- `~/lev/workshop/` - Workshop storage

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