<p align="center"><img src="./cover.png" width="100%" /></p>

<h1 align="center">LazyClaude</h1>
<p align="center">
  <em>Claude Code 안에서 쓰는 LazyClaude 스타일 워크플로우: prompt hook, ultrawork skill, agent, MCP, LSP helper.</em>
</p>
<p align="center">
  <a href="#빠른-시작">빠른 시작</a> · <a href="#ulw-사용법">ULW 사용법</a> · <a href="#명령어">명령어</a> · <a href="./README.md">English</a>
</p>
<p align="center">
  <img src="https://img.shields.io/badge/npm-lazyclaude--ai-cb3837" />
  <img src="https://img.shields.io/badge/version-0.2.1-2ea44f" />
  <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
  <img src="https://img.shields.io/badge/license-MIT-blue" />
</p>

---

[English](./README.md) | **한국어**

---

> [!NOTE]
> LazyClaude는 prompt hook, skill, agent, MCP, LSP, ULW discipline을 위한
> 조용한 Claude Code-native workflow package입니다. `lazyclaude@lazyclaude-ai`로
> 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
> LazyClaude skill과 hook을 불러올 수 있습니다.

현재 checkout은 `lazyclaude-ai@0.2.1` 배포 준비용으로 정리되어 있습니다. 목적은
다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
승인 후에 진행합니다. v0.2.1 release material은 v0.2.0 workflow parity work를
보존하면서 LazyClaude 자체의 표현으로 정리되어 있으며, npm publish가 완료됐다고
주장하지 않습니다.

## 기능

- **자연스러운 Claude 실행** - 한 번 `npx`로 설치한 뒤에는 plain `claude`
- **ULW prompt hook** - `ulw`, `ultrawork`, `$ulw-plan`, `$ulw-loop` 트리거
- **Deep interview mode** - `/deep-interview` 또는 `$deep-interview`로 넓고
  모호한 의도를 먼저 spec으로 정리한 뒤 계획/구현으로 넘김
- **v0.2.0 workflow parity** - package publish가 끝났다고 말하지 않으면서
  `review-work` 5-lane review discipline과 ultragoal runtime 문서를 추가
- **v0.2.1 dynamic workflow readiness** - `/dynamic-workflow`와
  `workflow-check --json`으로 goal, Dynamic workflow, subagent delegation
  readiness를 full QA 전에 확인
- **5-lane review** - `/review-work`가 goal/constraint verification,
  hands-on QA execution, code quality, security, local-first context mining을
  한 번에 점검
- **Native goal guidance** - Claude Code가 `/goal` 또는 `get_goal`,
  `create_goal`, `update_goal` 같은 goal surface를 제공하면 이를 우선
  사용하도록 유도하고, goal tools are unavailable 상황의 fallback도 명시
- **Ultragoal CLI/state** - `plugins/lazyclaude/lib/ultragoal/`가 durable
  criteria, evidence, checkpoint, steering, review blocker를 `.omo/ultragoal/`
  아래에 기록
- **Dynamic workflow/worktree guidance** - 크거나 병렬적인 작업은 Claude
  Code Dynamic workflow, subagent delegation, Dynamic worktree 격리 쪽으로 유도
- **Claude skills** - LazyClaude 스타일을 더 풍부하게 옮긴 corpus:
  `programming`, `debugging`, `refactor`, `ai-slop-remover`, `remove-ai-slops`,
  `review-work`, `frontend-ui-ux`, `comment-checker`, `rules`, `lsp`,
  `ultragoal`, `deep-interview`, `ulw-plan`, `ulw-loop`, `start-work`
- **Auxiliary workflow packs** - `programming/references`,
  `programming/scripts`, `debugging/references`까지 포함해서 언어별,
  런타임별 세부 지침을 보존
- **워크플로우 agents** - planner, executor, verifier, reviewer, librarian, QA runner
- **Local marketplace 등록** - `claude plugin details lazyclaude@lazyclaude-ai`에서 inventory 확인
- **MCP와 LSP helper** - plugin-local stdio MCP와 TypeScript 계열 LSP doctor
- **LazyClaude HUD** - npm install 시 `pretty-claude-hud` 기반의 compact
  Claude Code statusLine을 `[💤LAZYCLAUDE vX.Y.Z]` 브랜드로 자동 설정하고,
  설치 중 눈에 잘 띄는 색상 선택, 즉시 mini-HUD 미리보기, compact context
  bar, 낮은 사용량도 비어 보이지 않는 rate-limit bar, 더 넓은 brand accent
  적용 범위, 간격이 있는 reset countdown을 제공
- **안전한 uninstall** - LazyClaude가 관리한 상태만 제거

## 빠른 시작

### 설치

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

interactive `npx` 설치에서는 LazyClaude가 HUD brand color 후보를 더 선명한
실제 터미널 색상으로 바로 보여주고, 선택한 accent를 Claude의 managed
`statusLine` command에 저장합니다. animated install에서는 setup, plugin,
marketplace, registry, cache label도 색상으로 구분해서 진행 상황을 더 쉽게
스캔할 수 있습니다. noninteractive install은 deterministic한 plain
`INSTALL_STEP` line을 유지합니다.

현재 위치가 이 저장소 checkout이면, registry package와 같은 package name을
가진 same-name source checkout 안에 있는 상태입니다. 이 경우
`npx --yes lazyclaude-ai@0.1.11 install` 같은 이전 published build가 local
checkout을 먼저 해석해서 `sh: lazyclaude-ai: command not found`로 실패할 수
있었습니다. 현재 checkout build는 local npx shim을 포함하며, 새 폴더에서는
일반 설치 명령이 정상 동작합니다.

```bash
cd /tmp
npx --yes lazyclaude-ai@0.2.1 install
```

설치 상태를 확인합니다.

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

installer는 Claude Code의 `statusLine` command도 packaged LazyClaude HUD로
설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.

```text
[💤LAZYCLAUDE v0.2.1] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
```

`↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.
percentage와는 한 칸 띄워서 읽기 쉽게 만들었고, 낮은 non-zero 사용량도
partial bar glyph로 표시되어 비어 보이지 않습니다. context bar는 3칸,
rate-limit bar는 2칸으로 줄여 Claude Code status-line 공간을 덜 차지합니다.
Claude Code가 제공하는 epoch seconds 형태와 ISO timestamp 형태를 모두
해석합니다.

picker 없이 색상을 지정하려면 설치 전에 `LAZYCLAUDE_HUD_ACCENT`를
`cyan`, `blue`, `teal`, `green`, `lavender`, `rose`, `gold`, `orange`,
`slate`, `gray` 중 하나로 설정하세요.

설치 후에는 일반적인 `claude` 명령으로 Claude Code를 실행합니다.

```bash
claude
```

### 대체 진입점

```bash
bunx lazyclaude-ai install
npm install -g lazyclaude-ai
lazyclaude install
```

현재 checkout처럼 package 이름이 같은 폴더 안에서 `npm exec`를 직접 쓸
때는 registry package와 same-name source checkout이 섞이지 않도록 fresh
prefix를 주는 편이 안전합니다.

```bash
npm exec --prefix "$(mktemp -d)" --yes --package lazyclaude-ai -- lazyclaude install
```

LazyClaude가 관리한 설치 상태만 제거하려면 다음을 사용합니다.

```bash
npx --yes lazyclaude-ai uninstall
```

## 설치 방식

installer는 `lazyclaude@lazyclaude-ai`를 Claude Code user plugin registry
아래의 `~/.claude/plugins`에 등록하고 `settings.json`의 `enabledPlugins`,
LazyClaude 전용 local marketplace 항목, `known_marketplaces.json`을 함께
기록합니다. 이 marketplace metadata가 있어야 Claude가
`claude plugin details`에서 skill과 hook inventory를 해석합니다.

격리 테스트가 필요할 때만 `CLAUDE_CONFIG_DIR=/some/path`와
`LAZYCLAUDE_HOME=/some/path`를 지정하세요.

## ULW 사용법

설치 후에는 일반적인 `claude` 명령에서 LazyClaude를 사용할 수 있습니다.

```bash
claude
```

그다음 Claude Code에 아래 프롬프트 중 하나를 입력합니다.

```text
ulw
ultrawork
$ulw-plan <계획이 필요한 작업>
/ulw-plan <계획이 필요한 작업>
$ulw-loop <증거 기반으로 실행할 작업>
/ulw-loop <증거 기반으로 실행할 작업>
$deep-interview <명확화가 필요한 작업>
/deep-interview <명확화가 필요한 작업>
$dynamic-workflow <병렬 또는 위임할 목표>
/dynamic-workflow <병렬 또는 위임할 목표>
$review-work <검토할 범위>
/review-work <검토할 범위>
$ultragoal <goal operation>
/ultragoal <goal operation>
$start-work plans/lazyclaude-retrofit.md
/start-work plans/lazyclaude-retrofit.md
```

기대 동작은 LazyClaude prompt hook이 ULW route에는 `ULTRAWORK MODE ENABLED`
컨텍스트를 추가하고 `LazyClaude ULW hook active`라는 visible hook message를
보여주는 것입니다. `/deep-interview`에는 `DEEP INTERVIEW MODE ENABLED`
컨텍스트를 추가하고 Claude를 `/lazyclaude:deep-interview` /
`Skill(deep-interview)` 쪽으로 라우팅합니다. 또한 plain `ulw`는 일반 작업
실행 전 `/lazyclaude:ulw-loop` / `Skill(ulw-loop)` semantics로 처리됩니다.
그 뒤 skill 및 agent 지시문이 Claude를 test-first 작업, native goal 처리,
실제 수동 QA 증거, cleanup receipt, 향후 release step의 명시적 승인 쪽으로
유도합니다.

LazyClaude는 `/goal`을 대신 입력하거나 slash command text를 자동 전송하지
않습니다. 대신 hook과 ULW skill이 run context를 보강합니다. Claude Code의
native goal surface가 있으면 `get_goal`을 먼저 확인하고, matching active
goal이 없을 때만 `create_goal`을 호출하며, `update_goal`은 검증 완료 또는
진짜 blocker가 있을 때까지 미루도록 안내합니다. goal tools are unavailable,
즉 model-facing goal tools가 이 Claude Code session에 노출되지 않은 경우에는
로컬 evidence ledger를 기준으로 계속 진행하고, 긴 실행 전에 필요한 경우에만
정확한 `/goal <completion condition>`를 제안합니다. 큰 독립 작업에서는
같은 원칙을 Claude Code가 노출한 orchestration surface에 적용합니다.
`Workflow`가 노출되면 `Workflow` tool을 호출하고, isolated edit lane이
model-facing worktree를 필요로 하면 `EnterWorktree`를 사용합니다. CLI surface만
가능한 새 격리 lane에서는 `claude --worktree <short-name> --tmux`를 사용합니다.

v0.2.1 dynamic workflow readiness에서 `/dynamic-workflow`는 넓은 위임 작업을
위한 통합 bootstrap route입니다. `/goal`은 user-controlled 상태로 두고,
model-facing goal tools가 노출되면 확인하며, 필요하면 정확한 fallback
`/goal <completion condition>`만 제안합니다. subagent delegation은
`prometheus-planner`, `boulder-executor`, `oracle-verifier`, `qa-runner`,
`quality-reviewer`, `librarian-researcher`에 매핑됩니다. Full QA 전에는 다음
package diagnostic을 실행합니다.

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

v0.2.0 workflow parity에서 `review-work`는 전용 review route입니다. 5-lane
review는 goal/constraint verification, hands-on QA execution, code quality,
security, local-first context mining을 포함합니다. 각 lane은
`oracle-verifier`, `qa-runner`, `quality-reviewer`, `librarian-researcher`에
연결되고, 증거를 모아 PASS, FAIL, NEEDS-CONTEXT verdict로 정리합니다.
Manual-QA channels는 artifact를 남겨야 하며 tmux session, server, port,
browser tab, temp directory는 completion 전에 cleanup receipt를 남겨야 합니다.

`ultragoal`은 긴 목표를 위한 durable local state route입니다. runtime은
`plugins/lazyclaude/lib/ultragoal/`에 있고 state는 `.omo/ultragoal/` 아래에
남깁니다. stale state가 checkout과 어긋나면 current docs/test reads를
기준으로 판단합니다. 자주 쓰는 명령은 다음과 같습니다.

```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
```

`record-review-blockers`는 해결되지 않은 review finding을 기록합니다.
malformed JSON, unknown criterion, corrupt state, invalid steering kind는
성공처럼 보이지 않고 controlled error로 실패해야 합니다.

단순히 `ulw`라고 입력하는 것은 hook context activation입니다. Claude Code
history에는 별도 Skill tool invocation이 아니라 hook guidance로 보일 수
있습니다. 명시적인 LazyClaude skill activation을 보고 싶다면 namespaced
command를 사용합니다.

```text
/lazyclaude:ulw-loop <증거 기반으로 실행할 작업>
/lazyclaude:dynamic-workflow <병렬 또는 위임할 목표>
/lazyclaude:ulw-plan <계획이 필요한 작업>
/lazyclaude:deep-interview <명확화가 필요한 작업>
/lazyclaude:review-work <검토할 범위>
/lazyclaude:ultragoal <goal operation>
/lazyclaude:start-work plans/lazyclaude-retrofit.md
```

이 namespaced command들은 `plugins/lazyclaude/commands/` 아래 실제 Claude Code
command file로 배포됩니다. 따라서 `/lazyclaude:ulw-loop`는 command body를 먼저
로드하고, 이어서 대응 skill guidance를 따라가야 합니다.
위의 짧은 slash alias도 prompt hook이 인식하며, plain `ulw` loop fallback이
아니라 대응 discipline으로 라우팅됩니다.

요청이 넓거나 acceptance criteria, non-goal, decision boundary가 부족하면
`/ulw-plan` 전에 `/deep-interview`를 쓰는 것이 안전합니다.
`deep-interview/` 아래 요구사항 artifact를 남기고, 구현은 직접 하지 않은 채
계획 또는 실행 단계로 넘깁니다.

## 명령어

| 명령어 | 용도 |
| --- | --- |
| `npx --yes lazyclaude-ai install` | Claude Code plugin 설치 및 활성화 |
| `npx --yes lazyclaude-ai --version` | packaged LazyClaude version 출력 |
| `npx --yes lazyclaude-ai doctor` | 파일, Claude validation, plugin details 검증 |
| `npx --yes lazyclaude-ai path` | 설치된 Claude plugin 경로 출력 |
| `npx --yes lazyclaude-ai run -- --help` | 설치 상태를 확인한 뒤 plain `claude` 실행 |
| `npx --yes lazyclaude-ai update` | 현재 package version 재설치 |
| `npx --yes lazyclaude-ai uninstall` | LazyClaude가 관리한 설치 상태 제거 |

전역 설치 없이 checkout 내부 bin을 확인할 수도 있습니다.

```bash
node bin/lazyclaude-ai.js --dry-run install
node bin/lazyclaude-ai.js --dry-run doctor
```

## 로컬 개발

이 저장소에서 바로 플러그인을 테스트할 때는 다음처럼 실행합니다.

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

Claude Code 안에서 플러그인 메타데이터를 다시 읽고 싶으면 다음 명령을
사용합니다.

```text
/reload-plugins
```

기존 OMC/omc Claude 플러그인이 설치되어 있다면 테스트 중에는 LazyClaude와
함께 co-load하지 않는 것을 권장합니다. 로컬 checkout 테스트는
`--plugin-dir`로 직접 로드하고, npm 설치는 사용자 홈 아래에 LazyClaude가
관리하는 local marketplace만 만듭니다. root Claude marketplace skeleton은
저장소 checkout에 배포하지 않습니다. user-level OMC가 검증 중 `.omc/`
상태 디렉터리를 만들더라도 LazyClaude는 이를 git 및 npm package surface에서
제외합니다.

## 검증

```bash
npm test
npm run validate:plugin
npm run qa:tmux
npm run qa:portable
npm run pack:dry-run
```

`validate:plugin`과 `qa:tmux`는 로컬 검증용입니다. Claude Code가 없는
환경에서는 smoke harness가 모호한 실패 대신 controlled skip과 version
probe evidence를 남깁니다.

## 안전 모델

- Hook은 Claude Code event JSON을 stdin으로 읽고 제한된 JSON context를 반환합니다.
- Hook은 사용자 프롬프트 텍스트를 실행하지 않습니다.
- ultrawork prompt hook은 고정된 guidance를 반환하며 prompt text를 다시 echo하지 않습니다.
- `.omc/`, `.omo/`, `evidence/` 같은 로컬 상태는 ignore되며 npm 패키지에 포함되지 않습니다.
- planner agent는 read-only이며 edit tool을 갖지 않습니다.
- MCP와 LSP helper는 local stdio command입니다.
- 향후 publish, remote marketplace 변경, 새 package release는 모두 명시적 승인 후 진행합니다.

## 프로젝트 지도

| Surface | Path |
| --- | --- |
| CLI | `bin/lazyclaude-ai.js` |
| Claude plugin | `plugins/lazyclaude/` |
| Skills | `plugins/lazyclaude/skills/` |
| Agents | `plugins/lazyclaude/agents/` |
| Hooks | `plugins/lazyclaude/hooks/hooks.json` |
| MCP | `plugins/lazyclaude/.mcp.json` |
| LSP | `plugins/lazyclaude/.lsp.json` |

영문 설명은 `README.md`, workflow migration 표는 `docs/migration.md`, 현재
compatibility audit은 `docs/workflow-compatibility-audit.md`, release notes는
`CHANGELOG.md`를 참고하세요.
