# LazyClaude Migration

LazyClaude maps workflow disciplines into Claude Code-native surfaces. The goal
is behavior parity where Claude Code exposes the same kind of surface, and a
conservative local fallback where it does not.

| Reference surface | Claude Code surface | LazyClaude implementation |
| --- | --- | --- |
| CLI prompt engineering | Claude Code skills | `plugins/lazyclaude/skills/*/SKILL.md` |
| Auxiliary skill packs | Claude Code skill auxiliary files | `programming/references`, `programming/scripts`, and `debugging/references` are included where portable |
| Ultrawork plan mode | Claude Code skill plus planner agent | `ulw-plan` and `prometheus-planner` |
| Clarification interview | Claude Code skill plus command | `deep-interview` asks one Socratic question per round, persists state under `deep-interview/`, and hands a spec to planning or execution |
| Execution loop | Claude Code skill plus executor agent | `ulw-loop`, `start-work`, and `boulder-executor` |
| 5-lane review | Claude Code command, skill, and agents | `review-work` runs goal/constraint verification, hands-on QA execution, code quality, security, and local-first context mining |
| Durable goal runtime | Package CLI plus local state | `ultragoal` writes criteria, evidence, checkpoints, steering, and blockers under `.omo/ultragoal/` |
| Goal-tool guidance | Claude Code native goal surface | `/goal` when user-selected, or model-facing `get_goal`, `create_goal`, and verified-final `update_goal` guidance when exposed |
| Parallel orchestration | Claude Code Dynamic workflow and Dynamic worktree surfaces | Call `Workflow` for broad independent work when exposed; use `EnterWorktree` or the CLI worktree path for risky or parallel edits |
| Dynamic workflow readiness | Claude Code command plus package diagnostic | `/dynamic-workflow` and `workflow-check --json` verify goal, Dynamic workflow, and subagent delegation surfaces |
| Hooks | Claude Code hooks | `plugins/lazyclaude/hooks/hooks.json` |
| MCP helpers | Claude Code plugin MCP config | `plugins/lazyclaude/.mcp.json` |
| LSP integration | Claude Code plugin LSP config | `plugins/lazyclaude/.lsp.json` |
| Package alias | npm package bin alias | `lazyclaude-ai` |
| Review/research agents | Claude Code agents | `quality-reviewer`, `oracle-verifier`, `librarian-researcher` |

## Local Plugin Flow

Use the local plugin path while developing from this checkout:

```bash
claude --plugin-dir ./plugins/lazyclaude
```

For fresh machines, the quiet npm distribution path is:

```bash
npx --yes lazyclaude-ai install
bunx lazyclaude-ai install
lazyclaude doctor
```

Launch Claude Code normally after install:

```bash
claude
```

The installer writes the user plugin cache, `plugins/installed_plugins.json`,
the `settings.json` `enabledPlugins` entry for `lazyclaude@lazyclaude-ai`, and
a LazyClaude-managed local marketplace entry in `known_marketplaces.json`.
This keeps installation convenient without requiring public repo promotion,
manual `--plugin-dir` launch commands, or a remote Claude marketplace entry.

## Goal And Dynamic Workflow Parity

Reference goal integration is model-facing guidance around goal tools; it does
not type a `/goal` slash command for the user. LazyClaude mirrors that contract:
ULW hook context and ULW skills mention Claude Code's native goal surface, ask
Claude to inspect `get_goal`, create a goal with `create_goal` only when no
matching active goal exists, and defer `update_goal` until the evidence gate has
passed or a real blocker is recorded.

Current Claude Code sessions may not expose model-facing goal tools to the
model. When goal tools are unavailable or not exposed, LazyClaude should not
pretend the native goal was bound. It keeps the local evidence ledger
authoritative and may suggest `/goal <completion condition>` before
long-running ULW execution without repeatedly printing fallback chatter.

When the user explicitly chooses Claude Code `/goal`, that native session goal
remains user-visible and user-controlled. LazyClaude does not auto-type
`/goal`. For multi-lane work, LazyClaude follows the same model-facing tool
principle where Claude Code exposes it: call the `Workflow` tool before serial
execution, bind each lane to criteria and evidence, and use `EnterWorktree` for
isolated model-facing worktree lanes. When only the CLI surface is available,
the concrete isolated-lane launch form is `claude --worktree <short-name> --tmux`.

For v0.2.1, `/dynamic-workflow`, `$dynamic-workflow`, and
`/lazyclaude:dynamic-workflow` consolidate that behavior into one route. The
route keeps `/goal` user-controlled, calls model-facing goal tools only when
exposed, and maps subagent delegation to `prometheus-planner`,
`boulder-executor`, `oracle-verifier`, `qa-runner`, `quality-reviewer`, and
`librarian-researcher`. Operators can verify availability with:

```bash
lazyclaude-ai workflow-check --json
```

## v0.2.0 Review And Ultragoal Parity

The v0.2.0 workflow parity surface is local-first and evidence-bound. It does
not imply that an npm publish or remote marketplace publication has happened.
`/review-work`, `$review-work`, and `/lazyclaude:review-work` run the 5-lane
review contract: goal/constraint verification, hands-on QA execution, code
quality, security, and local-first context mining. Manual-QA channels must
produce artifacts, and all spawned sessions, servers, ports, browser tabs, and
temp directories need a cleanup receipt before completion.

`/ultragoal`, `$ultragoal`, and `/lazyclaude:ultragoal` bind long work to the
ultragoal runtime in `plugins/lazyclaude/lib/ultragoal/`. The local state lives
under `.omo/ultragoal/`, and current docs/test reads are the authority if stale
state contradicts the checkout.

Use these CLI commands for durable state:

```bash
lazyclaude ultragoal create-goals --brief "<brief>" --json
lazyclaude ultragoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
lazyclaude ultragoal checkpoint --status active --note "<progress>" --json
lazyclaude ultragoal steer --kind scope --note "<what changed and why>" --json
```

Malformed evidence JSON, unknown criteria, corrupt state, or invalid steering
kinds must fail with a controlled error.

If OMC/omc is already installed in Claude Code, keep it disabled or start a
separate Claude Code session without OMC while testing LazyClaude. This repo no
longer ships a root marketplace skeleton; direct `--plugin-dir` loading avoids
local marketplace collision. If a user-level OMC plugin still runs, it may
create `.omc/` local state in the checkout; LazyClaude treats that as quarantined
external state and keeps it ignored and outside packaged artifacts.

Reload plugin metadata after changing skills, agents, hooks, MCP, or LSP:

```text
/reload-plugins
```

## Publication Boundary

LazyClaude may be prepared as a quiet public npm package for personal install
convenience, but any `npm publish`, marketplace registration, or remote
distribution step requires explicit user approval. Until that approval exists,
uninstalling is either `lazyclaude uninstall` for npm-installed copies or
removing the local `--plugin-dir` usage and reloading Claude Code.
