# Lev Ref

> Agentic UX design language and pattern library. Establishes CLI-as-Prompt paradigm where every CLI output is a prompt to the next agent. Includes Enriched Response Protocol, vernacular (Self-Injection, Teachable Touch, Bi-Directional), and implementation patterns for validation gates and trust calibration.

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

---


# The CLI-as-Prompt Paradigm

## Core Insight

**Every CLI output is a prompt to the next agent in the chain.**

When you return output from a CLI, you are talking to an agent. This inverts traditional CLI design: outputs are not just data for humans—they are inputs for the next reasoning step.

This unlocks **lazy evaluation through self-injection**: an agent can prompt itself with enriched context, deferring decisions until more information is available.

## Vernacular

| Term | Definition |
|------|------------|
| **CLI-as-Prompt** | Every CLI output is a prompt to the next agent. Design outputs as you would design prompts. |
| **Enriched Response** | Output + meta (follow-ups, docs, troubleshooting, confidence). The prompt is richer than raw data. |
| **Self-Injection** | Agent prompts itself with enriched context. Enables lazy evaluation—defer decisions until needed. |
| **Teachable Touch** | Every interaction teaches better usage. Errors become learning, corrections become preferences. |
| **Bi-Directional** | Both agent learns AND user is guided. Communication flows both ways simultaneously. |

## The Enriched Response Protocol

CLI output follows a simple rule: **inline conventions by default, JSON only when requested.**

### Detection Logic

```
if --json flag:  → JSON envelope (for traditional program integration)
else:            → Inline conventions (agent-native, human-readable)
```

**Why inline by default?** LLM agents read language, not data structures. The inline conventions ARE machine-readable—by machines that read. JSON exists for traditional programs that need structured parsing.

### JSON Envelope (traditional program integration)

```json
{
  "output": "Fixed 3 type errors in src/auth.ts",
  "meta": {
    "follow_ups": [
      "Run tests: pytest src/auth/",
      "Check related: src/middleware.ts"
    ],
    "troubleshooting": null,
    "docs": ["https://docs.example.com/auth"],
    "confidence": 0.92,
    "teach": "Type errors often cluster. Check imports when you see 3+ in one file.",
    "resume_context": {
      "session_id": "abc123",
      "checkpoint": "post-type-fix",
      "state_hash": "sha256:..."
    }
  }
}
```

### Inline Conventions (agent-native, default)

```
Fixed 3 type errors in src/auth.ts

[92% confident] All errors resolved (clear pattern match)

💡 Tip: Type errors often cluster. Check imports when you see 3+ in one file.

→ Next: Run tests with `pytest src/auth/`
→ Related: Check src/middleware.ts for similar issues

[Resume: agentctl resume abc123]
```

### Field Definitions (JSON schema / conceptual model)

These fields exist in both formats—JSON uses explicit keys, inline uses conventions:

| Field | JSON Key | Inline Convention | Required |
|-------|----------|-------------------|----------|
| Result | `output` | First line(s) of output | **Yes** |
| Next actions | `follow_ups` | `→ Next:` / `→ Related:` | No |
| Error help | `troubleshooting` | After `❌ Error:` | No |
| Documentation | `docs` | Inline links or `📚 Docs:` | No |
| Confidence | `confidence` | `[N% confident]` | No |
| Lesson | `teach` | `💡 Tip:` | No |
| Resume state | `resume_context` | `[Resume: X]` | No |

### Inline Convention Reference

For agent-native output, use these conventions:

| Convention | Meaning | Example |
|------------|---------|---------|
| `[N% confident]` | Confidence score | `[92% confident] Fix applied` |
| `💡 Tip:` | Teaching moment | `💡 Tip: Use --strict for more checks` |
| `→ Next:` | Follow-up action | `→ Next: Run tests` |
| `→ Related:` | Related context | `→ Related: Check auth.ts` |
| `[Resume: X]` | Resume command | `[Resume: agentctl resume abc123]` |
| `⚠️ Warning:` | Caution | `⚠️ Warning: This deletes data` |
| `❌ Error:` | Failure | `❌ Error: File not found` |
| `✓` / `✗` | Pass/fail | `✓ Tests passed (12/12)` |

## Design Principles

1. **Prompt-First Thinking**: Before outputting, ask "How would I prompt an agent with this information?"

2. **Dual Audience**: Every output serves both humans (readable) and agents (parseable). Never sacrifice one completely.

3. **Progressive Enrichment**: Start with output, add meta as complexity warrants. Simple commands need less meta.

4. **Teachable by Default**: Errors always include lessons. Success includes tips when non-obvious.

5. **Resumable State**: Long-running or interruptible operations include resume context.

---

# lev-ref - Agentic UX Pattern Library

## Purpose

lev-ref is a living database of agentic UX techniques derived from production CLI agents (Claude Code, Aider, Cursor, GitHub Copilot CLI) and academic research. It codifies patterns for bi-directional human-agent communication, transforming every CLI interaction into a teachable dialogue moment.

The patterns below are **implementations of the CLI-as-Prompt paradigm**. Each pattern shows how to structure output so it serves as an effective prompt to the next agent (human or machine) in the chain.

## When to Use This Skill

Apply lev-ref when:

- Designing CLI agent communication patterns
- Implementing feedback loops for agent learning
- Building validation gates for agentic workflows
- Creating teachable error messages
- Calibrating trust and confidence communication
- Researching agentic UX best practices

Semantic triggers:
- "How should the agent communicate progress?"
- "What makes a good error message for agents?"
- "How do we implement validation gates?"
- "Design the CLI feedback pattern"
- "Make this response teachable"

---

## Pattern Database

### 1. Bi-Directional Communication Patterns

#### Pattern: Annotated Progress
**Intent**: Show not just WHAT the agent is doing, but WHY and what evidence of success looks like.

```
[BAD]  Running task 3/12...
[GOOD] Analyzing auth module... Found 3 permission checks, verifying middleware chain
```

**Implementation**:
- Connect actions to observable outcomes
- Show reasoning alongside actions
- Create narrative arc users can follow

#### Pattern: Plan-Then-Act
**Intent**: Present reasoning and await approval before executing potentially irreversible actions.

```
I'm planning to:
1. Refactor auth middleware → consolidate 3 files into 1
2. Update import paths → 12 files affected
3. Add integration test → verify no regressions

Proceed? [Y/n/explain more]
```

**Implementation**:
- Separate planning phase from execution phase
- Create explicit approval checkpoint
- Allow modification before commitment

#### Pattern: Confidence Scoring
**Intent**: Attach explicit confidence levels to recommendations so users know when to verify.

```
[95% confident] Memory leak in loop at line 43 (clear pattern match)
[60% confident] Specific fix approach (multiple valid options exist)
```

**Implementation**:
- Score confidence per recommendation, not globally
- Explain factors affecting confidence
- Different thresholds trigger different approval requirements

---

### 2. Teachable Moment Patterns

#### Pattern: Layered Error Explanation
**Intent**: Transform errors from dead ends into learning opportunities.

**Structure**:
1. WHAT went wrong (the error)
2. WHY it went wrong (root cause)
3. HOW to avoid it (the lesson)

```
[Error] Branch 'develop-staging' not found

[Root Cause] You may have typed the branch name incorrectly, or it was deleted.

[Available Branches] develop, main, release/1.0

[Lesson] Use tab completion or `git branch -a` to see available branches before switching.
```

#### Pattern: Prompt Scaffolding
**Intent**: When user input is underspecified, ask structured questions that teach better prompting.

```
Your request "fix the auth system" could mean several things:
- Fix security vulnerabilities? (security focus)
- Refactor for clarity? (code quality focus)
- Add new auth methods? (feature focus)
- Improve performance? (optimization focus)

Which aspect concerns you most? This helps me understand your intent better.
```

**Implementation**:
- Present options that reveal possible interpretations
- Each option teaches a dimension of specificity
- Over time, users internalize these dimensions

#### Pattern: Correction as Teaching
**Intent**: When users correct agent output, treat it as a learning signal and acknowledge what was learned.

```
User: No, use 4-space indentation, not 2-space.

Agent: Got it. I'll use 4-space indentation for this file. I noticed the project
uses mixed indentation - should I standardize to 4-space everywhere, or is this
file-specific?

[Learning captured: User prefers 4-space indentation]
```

---

### 3. Validation Gate Patterns

#### Pattern: Two-Tier Gates
**Intent**: Combine universal static gates with dynamically generated task-specific gates.

**Tier 1 - Universal (always apply)**:
```yaml
universal_gates:
  semantic_coherence:
    check: "Does conclusion follow from reasoning?"
  completeness:
    check: "Were all requirements addressed?"
  safety:
    check: "Any destructive commands without confirmation?"
```

**Tier 2 - Dynamic (generated per task)**:
```yaml
# Auto-generated for "Fix auth bug" task
task_gates:
  auth_middleware_present:
    type: file_check
    check: "grep -r 'requireAdmin' src/routes/"
  test_coverage:
    type: command
    check: "grep -l 'admin.*401' tests/"
  no_bypass:
    type: llm_review
    check: "Review for auth bypass vulnerabilities"
```

#### Pattern: Gate Generator Meta-Prompt
**Intent**: Agent generates task-specific validation criteria before starting work.

```
You are generating validation gates for: {task_description}

Generate 2-4 checks that are:
1. MEASURABLE (verifiable programmatically or by inspection)
2. SPECIFIC to this exact task (not generic)
3. Include POSITIVE checks (did X happen) and NEGATIVE (did NOT do Y)
4. Consider edge cases unique to this request

Output format:
- name: short identifier
- type: "command" | "llm_review" | "file_check"
- check: the validation
- pass_condition: explicit success criteria
```

#### Pattern: Adversarial Self-Critique
**Intent**: Agent red-teams its own output before presenting to user.

```
[Self-Critique Checklist]
□ Does this actually solve the stated problem?
□ Did I introduce any new bugs?
□ Is there a simpler approach I missed?
□ What could go wrong with this change?
□ Would I approve this if someone else wrote it?
```

---

### 4. Progressive Disclosure Patterns

#### Pattern: Output Styles
**Intent**: Let users control detail level based on their needs.

```
Styles: --concise | --standard | --explanatory | --learning

--concise:    "Fixed. 3 files changed."
--standard:   "Fixed auth bug. Changed middleware.js, routes.js, tests.js"
--explanatory: "Fixed auth bug by adding role check before route handler..."
--learning:   "Here's what I changed and why. Try implementing step 3 yourself..."
```

#### Pattern: Expandable Sections
**Intent**: Show summary by default, allow drill-down on demand.

```
✓ Tests passed (12/12)
  └─ [expand: show test names]

✗ Lint issues (3 warnings)
  └─ [expand: show issues]
  └─ [expand: show fixes]
```

#### Pattern: Capability Discovery
**Intent**: Reveal available tools progressively rather than overwhelming upfront.

```
[Default] Showing 5 most relevant tools for your task
[Available] 12 more tools for advanced workflows - type /tools to see all
[Just discovered] New MCP tool: database-query - useful for performance analysis
```

---

### 5. Interrupt & Resume Patterns

#### Pattern: Explicit Pause Signal
**Intent**: Make it clear when agent is waiting and what input is expected.

```
⏸ PAUSING - Awaiting approval

Review the proposed changes below:
[diff output]

Options:
  [Y] Proceed with changes
  [N] Cancel and explain why
  [E] Edit the proposed changes
  [?] Ask me questions about the changes
```

#### Pattern: Checkpoint Resume
**Intent**: Save state at key points so interrupted work can continue.

```
Resuming task from 2 hours ago:
  ✓ Completed: static analysis (22 issues found)
  ✓ Completed: test coverage (78%)
  → Remaining: security review

Ready to continue? [Y/n]
```

#### Pattern: Graceful Termination
**Intent**: Allow clean shutdown rather than abrupt kill.

```
User: ^C

Agent: Received interrupt. Completing current file write...
       Saving progress checkpoint...
       Summary: 3/5 files processed, checkpoint saved.
       Resume with: agentctl resume task-123
```

---

### 6. Trust Calibration Patterns

#### Pattern: Tiered Autonomy
**Intent**: Different action types require different approval levels.

| Tier | Action Type | Approval |
|------|-------------|----------|
| 0 | Read-only (gather info) | None |
| 1 | Reversible (create file) | Simple confirm |
| 2 | Impactful (modify many files) | Explicit approval |
| 3 | Irreversible (delete, deploy) | Multi-step confirmation |

#### Pattern: Reasoning Visibility
**Intent**: Show thinking process so users can verify reasoning, not just output.

```
[Thinking...]
I considered three approaches:
  A) Direct implementation - fastest but no safety checks
  B) With validation - slight overhead, catches edge cases
  C) With rollback - most defensive, highest overhead

Recommending B because: data deletion context warrants validation,
but rollback overhead isn't justified for this operation.
```

#### Pattern: Uncertainty Communication
**Intent**: Explicitly state when agent doesn't have enough information.

```
I need more context to proceed confidently:

What I know:
  ✓ Function name and location
  ✓ Basic behavior expected

What I don't know:
  ? Performance requirements
  ? Error handling preferences
  ? Integration constraints

Provide these details, or I can proceed with default assumptions
(documented in output).
```

---

## Integration with Leviathan Concepts

### BD (Beads) Integration

lev-ref patterns inform how agents should communicate about issue tracking:

```
[bd integration example]
Found 3 related issues during analysis:
  - lev-123: Auth middleware needs refactor (IN_PROGRESS)
  - lev-456: Add role-based access control (BLOCKED by lev-123)
  - lev-789: Security audit findings (OPEN)

Should I:
  A) Focus only on current task, ignore related issues
  B) Update lev-123 as I work and note connections
  C) Create new issue for discovered scope
```

### Roadmap Alignment

Patterns support roadmap visibility:

```
[Roadmap context]
This task touches: Agent/PM Layer → Command Consolidation
Related work: h-poly-bridge-architecture (Task 03 waits for this)

Impact: Completing this unblocks downstream work.
Confidence: High - clear requirements, tested approach.
```

---

## Adding New Patterns

When discovering new agentic UX patterns:

1. **Document the intent** - What problem does this solve?
2. **Show good/bad examples** - Concrete before/after
3. **Describe implementation** - How to apply it
4. **Tag the source** - Where did this pattern come from?
5. **Add to bd** - `bd create "New pattern: {name}" --type=task --priority=3`

---

## Sources

Research synthesis from:
- Meta-Prompting Protocol (arxiv 2512.15053) - TextGrad backpropagation
- IntuitionLabs Meta-Prompting - Self-critique patterns
- Anthropic Claude Code Best Practices - Plan-then-act
- LangGraph Documentation - Interrupt and checkpoint patterns
- JetBrains AI Blog - Trust calibration
- Production CLI agents: Aider, Cursor, GitHub Copilot CLI