# Lev Align

> [WHAT] Standalone alignment auditor for north-star drift. [HOW] Scans codebase state, compares to canonical docs, classifies drift, proposes corrections. [WHEN] Use only for explicit deep-dive alignment audits. [WHY] Default alignment should run inside `work`; this remains for focused audit sessions. Triggers: "align lev", "check north star", "what's our direction", "audit alignment", "detect drift", "product pivot"

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

---


# Lev Align

> Preferred path: run alignment via `work` (`align/check/scan` routes). Use this skill directly only when you want a dedicated alignment audit.

Strategic alignment. North star management + drift detection + pivot adoption.

## Core Loop

```
1. NORTH STAR EXISTS?
   ├─ NO  → Deep research codebase → Define north star → Save to docs/
   └─ YES → Continue

2. CURRENT STATE ALIGNED?
   ├─ YES → Report "aligned" → Done
   └─ NO  → Detect drift type → Continue

3. DRIFT TYPE?
   ├─ STALE DOCS     → Propose doc updates
   ├─ PRODUCT PIVOT  → Propose north star update OR adopt new direction
   └─ COVERAGE GAP   → Propose additions to north star docs
```

## North Star Discovery

If no canonical north star found, trigger deep research:

```
# Check for north star docs
Expected locations:
- README.md (vision section)
- pm/00-roadmap.md (north star vision)
- docs/vision.md or docs/north-star.md
- NORTH_STAR.md at root

If missing or stale (>30 days):
1. Deep research codebase:
   - Recent git commits (direction of work)
   - BD issues (what's prioritized)
   - ADRs (architectural decisions)
   - Session artifacts (what's being built)

2. Synthesize north star:
   - Vision statement (1 sentence)
   - Key priorities (3-5 items)
   - Success metrics
   - Current phase

3. Propose location + content
4. Save on approval
```

## Drift Types

| Type              | Signal                           | Action                            |
| ----------------- | -------------------------------- | --------------------------------- |
| **Stale Docs**    | Dates old, refs outdated         | Update docs to match reality      |
| **Product Pivot** | Work diverged from stated vision | Update north star OR realign work |
| **Coverage Gap**  | New artifacts not in north star  | Add to north star docs            |
| **Status Drift**  | BD closed but docs say open      | Update doc refs                   |
| **Path Drift**    | Refs point to moved files        | Fix refs                          |

## Pivot Detection

When work diverges from north star:

```
# Signs of pivot
- Recent ADRs contradict roadmap priorities
- BD work doesn't match stated "critical path"
- New concepts emerged not in vision docs
- Energy going to unlisted areas

# Response options
1. ADOPT PIVOT → Update north star to reflect new direction
2. REALIGN WORK → Flag divergent work, recommend refocus
3. SPLIT → Some work is pivot, some is drift - handle separately
```

## Process

### 1. Locate North Star

```
# Primary sources (check in order)
1. README.md - "Vision" or "North Star" section
2. docs/

# Extract
- Vision statement
- Key priorities
- Current phase
- Success metrics
- Last updated date
```

### 2. Gather Current State

```
# What's actually happening
- git log --since="14 days" (recent work)
- bd list --open (active issues)
- bd list --closed --since 14d (recent completions)
- docs/decisions/*.md (recent public decisions)
- skills/ (what capabilities exist)
- Recent session handoffs
```

### 3. Compare & Classify

```
For each north star priority:
  - Is there active work? (BD issues, commits)
  - Is it blocked? (dependencies, decisions)
  - Is it abandoned? (no activity, superseded)

For each recent artifact:
  - Does it advance north star?
  - Does it pivot from north star?
  - Is it coverage gap?
```

### 4. Generate Alignment Report

```markdown
## Alignment Report - {date}

### North Star Status

**Vision**: "{vision statement}"
**Source**: {file} (last updated: {date})
**Freshness**: {fresh|stale|missing}

### Priority Alignment

| Priority           | Status     | Evidence          |
| ------------------ | ---------- | ----------------- |
| LEANN integration  | ⏸️ Stalled | No commits in 30d |
| Dashboard shell    | 🔄 Active  | lev-h7rq open     |
| Prose architecture | ✅ Done    | ADR-060 merged    |

### Drift Detected

1. **Product Pivot**: ADR-060 introduces "Prose Architecture" not in roadmap
   - Recommend: Add to north star as new priority
2. **Stale Docs**: pm/00-roadmap.md dated 2025-12-04 (35 days)

   - Recommend: Update with recent completions

3. **Status Drift**: lev-2598 closed but referenced as open
   - Recommend: Update refs to "superseded by ADR-060"

### Proposed Actions

1. [ ] Update docs/epics
2. [ ] Add "Prose Architecture" to north star priorities
3. [ ] Mark lev-2598 as closed/superseded in docs
4. [ ] Update state-of-the-union with recent work

Execute? [Y/n]
```

### 5. Execute Updates

With human approval:

- Update doc dates
- Add new priorities to north star
- Fix status refs
- Create BD issues for large changes

### 6. Validate

Re-run audit. North star should be current, drift minimal.

## When North Star Missing

If no canonical north star found:

```
Agent: No canonical north star found.

Initiating deep research to define one...

[Analyzing 14 days of commits...]
[Scanning 194 open BD issues...]
[Reading recent ADRs...]
[Checking session handoffs...]

## Proposed North Star

**Vision**: "Autonomous agents that learn, reason, and self-improve
through persistent memory"

**Key Priorities**:
1. Poly-Bridge architecture (performance foundation)
2. LEANN integration (semantic search)
3. Memory activation (learning loop)
4. Dashboard shell (user interface)
5. Prose architecture (system prompt generation)

**Current Phase**: Infrastructure + Alignment

**Save to**: docs/NORTH_STAR.md

Create this north star doc? [Y/n]
```

## Quick Commands

```
"align lev"           → Full alignment audit
"check north star"    → Just verify north star exists and is fresh
"what's drifted"      → Show drift without proposing fixes
"adopt pivot"         → Update north star to match current work direction
"update roadmap"      → Sync pm/00-roadmap.md with current state
```

## Related

- `bd` - Source of truth for issue status
- `lev get` - Deep codebase research
- `lev-learn` - Triggers align on patterns

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