## 설치
`@litfamily/litclaude`는 scoped package입니다. Node.js/npm과 Claude Code가 필요합니다.
로컬 검증을 할 때는 먼저
[별도 체험 프로필](./docs/migration.md#separate-trial-profile)을 준비하세요.
다음은 기본 safe 권한 모드에서 사용할 명령입니다.
```bash
npm exec --yes --package @litfamily/litclaude@latest -- litclaude install --yes
```
`--yes`는 설치 질문을 건너뜁니다. 다른 Claude 설정은 보존하며,
권한·HUD 색상·출력 스타일은 필요할 때 명시적으로 선택합니다.
[설치 상세](#설치-상세)에서 옵션과 버전 고정 방법을 확인하세요.
## 빠른 시작
Claude Code를 실행합니다.
```bash
claude
```
Claude Code 안에서 다음을 입력합니다.
```text
lit
```
활성화 안내가 나온 뒤 작은 작업 하나를 맡겨보세요.
```text
외부 의존성 없이 HTML 파일 하나로 할 일 목록을 만들어줘.
추가·완료·삭제 동작을 구현하고, 확인한 내용과 다음 행동을 남겨줘.
```
생성된 HTML을 직접 열어 세 동작을 확인하세요. 파일을 만들었다고 동작까지 확인한 것은
아닙니다. 브라우저를 사용할 수 없다면 화면과 상호작용은 미확인으로 남겨달라고 하세요.
로고는 활성화 표시이며 작업 완료를 뜻하지 않습니다.
다음 작업에는 아래 주요 route를 사용하세요. Bare prompt route는 hook이 처리하고,
namespaced slash command는 Claude Code native command surface에서 처리되므로
hook을 중복 활성화하지 않습니다. 명시적으로 skill을 실행하려면
`/litclaude:lit-loop` 같은 route를 사용하세요.
## 주요 기능
불씨를 건네받았다. 이제, 당신의 작업에 옮길 차례다.
고치고 싶은 버그 하나. 만들고 싶은 화면 하나. 끝내고 싶은 프로젝트 하나.
시작은 짧은 한 줄이면 됩니다. 어려운 건 그다음입니다. 대화가 길어지고 세션이 바뀌면,
어디까지 했는지부터 다시 짚어야 합니다. 어떤 결정을 내렸는지, 무엇을 확인했는지,
다음에는 무엇을 해야 하는지.
**LIT은 그 불씨를 남깁니다.** 목표와 계획, 확인한 결과, 다음에 할 일을 프로젝트에
기록합니다. 다음 세션에서 그 기록을 읽고 작업을 이어갈 수 있도록.
**대화가 끝난 자리에서, 다음 작업이 시작되도록.**
LitClaude는 Claude Code에 증거 기반 실행, 계획, 조사, 검토 흐름을 더합니다.
플러그인과 HUD를 한 번 설치하면 일반 `claude` 세션에서 사용할 수 있습니다.
## 주요 라우트
### 작은 lit 작업부터 시작하기
프롬프트 끝에 `lit`을 붙이면 Claude Code hook이 작업 루프를 시작합니다. hook은 경로 안내를 보내고 실제 작업은 Claude Code가 수행합니다.
| 프롬프트 또는 경로 | 효과 |
| --- | --- |
| `lit` | 현재 Claude Code 대화에서 근거 중심 작업 루프를 시작합니다. |
| `handoff` | 확인한 결과와 다음 할 일을 다음 세션으로 건넵니다. |
| `lit-plan` | 구현 전에 범위와 확인 기준이 있는 계획을 만듭니다. |
| `/litclaude:start-work <승인된 계획>` | 이미 승인한 계획을 실행합니다. |
| `review-work` | 변경과 근거를 읽고 남은 일을 보고합니다. |
| `litresearch` | 출처를 남기는 조사 경로로 사실과 불확실성을 나눕니다. |
hook의 표시는 작업 진입을 뜻하며 작업이나 브라우저 확인이 끝났다는 증거는 아닙니다.
포스터를 선택하면 선택형 Ignition 영상을 엽니다. README에서 자동 재생하지 않습니다.
### 작업 이어가기
```text
계획하기 → 만들기 → 확인하기 → 다음 작업에 건네기
```
| 할 일 | Claude Code에서 입력할 내용 | 남길 것 |
| --- | --- | --- |
| 범위 정하기 | `lit plan ` | 계획과 성공 기준 |
| 승인한 계획 실행하기 | `/litclaude:start-work`에 승인한 계획 전달 | 변경과 확인 결과 |
| 결과 검토하기 | `lit review ` | 확인한 점과 남은 문제 |
| 세션 마무리하기 | `/litclaude:lit-handoff` | 다음 세션에 건넬 파일과 경로 |
목표를 연결하면 프로젝트의 `.litclaude/litgoal/`에 작업 기록을 남깁니다.
마지막에는 handoff가 알려준 **실제 파일 경로**를 보관하세요. 다음 세션에서 같은
프로젝트를 열고 그 파일을 읽어 현재 상태와 다음 행동을 확인해달라고 요청하세요.
그 뒤 이어갈 범위를 지정하세요. [목표와 기록 안내](./docs/migration.md#review-and-litgoal-parity)에
기록 명령과 호스트 경계가 정리되어 있습니다.
“꺼지지 않는 불”은 프로그램이 끝없이 돌아간다는 뜻이 아닙니다.
**세션이 끝나도, 이어갈 작업을 남긴다는 뜻입니다.** 재개할 때는 새 세션에서 기록을
읽고 현재 파일 상태와 대조해야 합니다.
### 전체 경로 표
| 입력 | 용도 |
| --- | --- |
| `lit`, `litwork` | 증거 우선·test-first 실행 loop. `$lit-loop`, `/lit-loop`, `/litclaude:lit-loop`도 지원합니다. |
| `lit plan ` | 계획만 작성합니다. `$lit-plan`, `/lit-plan`도 지원합니다. |
| `lit review ` | 계획 또는 완료한 작업을 검토합니다. `$review-work`, `/review-work`도 지원합니다. |
| `lit research ` | 인용 가능한 public-source 조사입니다. `$litresearch`, `/litclaude:litresearch`도 지원합니다. |
| `lit search ` | Public-source retrieval |
| `lit query ` | durable local state에서 근거를 조회합니다. |
| `lit goal ` | 하나의 목표와 검증 가능한 기준을 연결합니다. `$litgoal`, `/litgoal`도 지원합니다. |
| `lit workflow ` | 넓은 위임 작업을 위한 Dynamic workflow를 제안합니다. |
| `lit team`, `lit teammates` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`이고 사용자가 승인한 경우에만 native agent team을 제안합니다. |
| `$deep-interview`, `/deep-interview` | 모호한 요청을 결정 가능한 brief로 정리합니다. |
| `lit recap`, `litrecap`, `$lit-recap`, `/lit-recap`, `/litclaude:lit-recap` | Read-only session recap |
| `handoff`, `/litclaude:lit-handoff` | 검증된 continuation packet을 작성합니다. |
| `lit-scientific-visualization` | 출판용 figure를 준비합니다. `/litclaude:lit-scientific-visualization`도 지원합니다. |
| `litclaude wikify ` | 검토 기반 local structured knowledge를 관리합니다. |
| `browser-drive`, `$browser-drive` | 외부 driver capability probe가 확인된 뒤에만 실제 page를 조작합니다. fetch로 대체하지 않으며 credential 사용과 승인 없는 설치를 하지 않습니다. |
이름으로 호출하는 주요 스킬은 `lit-crucible`(계획 검토), `lit-init`(저장소 지침),
`lit-commit`(Git 이력), `lit-team`(네이티브 팀), `lit-burnoff`(변경 묶음 정리),
`lit-burnoff-file`(단일 파일 정리), `lit-korean`(한국어 문장),
`lit-code`(구현 규율)입니다. 프롬프트 앞에 이름 또는 `$`를 입력합니다.
이전 이름은 한 릴리스 동안 안내 문구와 함께 새 스킬로 연결됩니다.
[이름 이전 표](./docs/migration.md#one-release-rename-aliases)를 참고하세요.
## 문제 해결
기존 설치에서 `INSTALL_OWNERSHIP_CONFLICT`가 나왔다면 반복 설치나 폴더 이동을 멈추고
[소유권 충돌 안내](./docs/migration.md#ownership-conflicts)를 확인하세요.
### 검증 및 제거
설치된 package는 다음 관리 명령을 제공합니다.
```bash
npm exec --yes --package @litfamily/litclaude@latest -- litclaude doctor
npm exec --yes --package @litfamily/litclaude@latest -- litclaude --version
npm exec --yes --package @litfamily/litclaude@latest -- litclaude path
npm exec --yes --package @litfamily/litclaude@latest -- litclaude workflow-check --json
npm exec --yes --package @litfamily/litclaude@latest -- litclaude update
npm exec --yes --package @litfamily/litclaude@latest -- litclaude uninstall
```
`uninstall`은 LitClaude가 관리한 plugin, HUD, permission, local state만
제거하며 다른 Claude 설정은 제거하지 않습니다. 수정되었거나 소유권을 확인할 수 없는
설치는 보존하고 거절합니다. [충돌 안내](./docs/migration.md#ownership-conflicts)를 따르세요.
별도 프로필 체험을 마쳤다면 해당 세션과 터미널을 닫고 원래 환경의 터미널로 돌아가면
됩니다. 이전 설치를 지우거나 재설치할 필요는 없습니다.
## 링크
- [운영 참고](#운영-참고)
- [Hook trigger와 activation boundary](./docs/hooks.md)
- [Agent와 orchestration 안내](./docs/agents.md)
- [Workflow migration 표](./docs/migration.md)
- [Native `/goal` surface matrix](./docs/native-goal-surface.md)
- [Workflow compatibility audit](./docs/workflow-compatibility-audit.md)
- [Release checklist](./RELEASE_CHECKLIST.md)
- [Release history](./CHANGELOG.md)
- [English README](./README.md)
### LITFAMILY
추가 흐름과 제품 참고
## 실제 경로와 편집 이미지
`lit`은 근거 중심 루프를 시작하고, `handoff`는 확인한 작업을 다음 세션으로 넘깁니다. `lit-plan`은
범위와 기준이 있는 계획을 작성하며, `/litclaude:start-work <승인된 계획>`은 승인한 계획을 실행합니다.
`review-work`는 변경과 근거를 검토하고, `litresearch`는 출처와 불확실성을 나누어 기록합니다. 각 경로는
프로젝트 기록에 기대한 효과를 남기며 새 슬래시 경로를 만들지 않습니다. 호스트 한계상 hook과 모델 실행은
Claude Code가 담당하지만 권한, 브라우저 접근, 화면 확인은 호스트의 능력입니다. hook 표시나 정적 편집
이미지는 완료 증거가 아닙니다.
소스 트리의 `docs/assets/cover.svg`는 편집 가능한 저대역폭 대체 표지로 남아 있으며, 위 WebP는 제품 강조 표지입니다.
## Claude Code 안에서의 흐름
짧은 prompt와 slash command는 서로 다른 입구를 사용합니다. hook은 route 안내와
편집 후 검사 안내를 Claude Code에 전달하고, Claude가 해당 skill을 따라 작업합니다.
```mermaid
flowchart TD
P["lit prompt"] --> H["UserPromptSubmit hook route 안내"]
C["/litclaude:* command"] --> S["Claude Code가 해당 skill을 읽음"]
H --> S
R["SessionStart 프로젝트 rules"] --> S
S --> W["계획 · 승인된 작업 실행 · 검토"]
T["PreToolUse / PostToolUse 권한 검사 / 편집 후 안내"] -.-> W
W --> F["프로젝트 파일과 확인 결과"]
W --> L["목표를 연결한 경우 litgoal CLI → .litclaude/litgoal/"]
F --> Q["요청한 lit-handoff"]
L --> Q
Q --> N["다음 세션에 건넬 파일"]
N -. "사용자가 새 세션에서 읽도록 요청" .-> S
```
hook 안내만으로 skill 실행이 입증되지는 않습니다. 다음 세션에서는 남긴 파일을
읽고 실제 상태를 확인해야 합니다. 자세한 경계는 [hook 안내](./docs/hooks.md)와
[목표 기록 안내](./docs/migration.md#review-and-litgoal-parity)를 참고하세요.
LITFAMILY · 다섯 아머드 머신
LitClaude, LitHermes, LitCodex, LitOpenCode, LitGrok을 아머드 머신으로 그린 콘셉트 아트입니다.
각 제품은 자신의 호스트에서 따로 동작합니다.
## 안전 모델
- Hook은 제한된 Claude Code event JSON을 읽고 사용자 prompt text를 실행하지
않습니다.
- Planner agent는 read-only입니다. Review route는 근거를 검사하지만 검토한
작업을 직접 구현하지 않습니다.
- `public-read`는 localhost, private-network, non-HTTP(S) target을 거부하고
site credential 없이 authentication과 paywall 경계에서 중단합니다.
- 프로젝트 로컬 LitClaude 상태와 evidence 디렉터리는 gitignore되며 npm 패키지에서
제외됩니다.
- Interactive update는 사용자에게 보이는 단계로 동작하며 unknown, rollback,
verification failure에서는 fail closed합니다. `--no-auto-update`,
`LITCLAUDE_NO_AUTO_UPDATE`, `NO_UPDATE_NOTIFIER`,
`LITCLAUDE_NO_UPDATE_CHECK`로 automatic lane을 끌 수 있습니다.
- Publish, version 변경, tag, remote marketplace 변경은 명시적 승인이
필요합니다.
모델 선택은 Claude Code가 담당합니다. Native `Workflow`와 실험적 agent team은
명시적인 opt-in이 필요합니다. Native goal tool이 없으면 local `litgoal` ledger를
기준으로 사용하며, LitClaude가 사용자를 대신해 `/goal`을 전송하지 않습니다.
## GPT 모델 기준과 LitClaude의 경계
OpenAI 모델 라우팅을 지원하는 제품은 새로 설치할 때 GPT-6를 기본으로 사용합니다. 계획·검토·리드 역할에는
`gpt-6-astra`, 코딩 리드 대안에는 `gpt-6-sol`, helper·일반 작업자에는 `gpt-6-luna`를 사용합니다.
GPT-6 Luna는 `xhigh`를 지원하지만 `ultra` effort는 지원하지 않습니다. 호스트 카탈로그에는 이전 세대
`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`가 계속 표시되며 세 모델 모두 선택할 수 있습니다.
이들에 대한 지원 종료일 메타데이터는 없습니다. 카탈로그에서 `gpt-5.6-luna`도 `xhigh`를
지원하지만, LitClaude의 기존 정책 전용 제한은 이 조합을 계속 차단합니다.
`gpt-6-luna`의 `xhigh`는 카탈로그에서 지원되며, 일반 작업자 경로의 기본 effort는 `max`입니다.
일반 설치와 업데이트는 이미 설정된 모델을 바꾸지 않습니다.
이 기준이 LitClaude가 OpenAI 경로를 적용한다는 뜻은 아닙니다. LitClaude에는 OpenAI 모델
카탈로그가 없고 Claude Code가 모델을 선택합니다. `tools/check-model-routing.mjs`는 지원하지
않는 Claude Code 경로를 차단하는 참조용 검사입니다.
### 모델 카탈로그 참조 갱신
LitClaude 저장소에는 생성되는 OpenAI 모델 카탈로그가 없습니다. 공유 Codex 호스트 카탈로그의
캐시 파일은 `~/.codex/models_cache.json`이며, 현재 카탈로그를 새로 읽어 출력하려면
`codex debug models`를 실행합니다 (`--bundled`를 지정하면 번들 데이터만 출력합니다).
LitClaude의 정책 참조는 `tools/check-model-routing.mjs`에 있고, 경계 검사는
`node --test test/model-routing.test.mjs`로 고정합니다. 배포하는 `SKILL.md`의 모델 안내를
바꾸면 `npm run gen:skill-resources`로 리소스 맵을 다시 만들고
`npm run check:skill-resources`로 확인합니다.
운영 참고 — 설치 옵션, 학습, 호스트 경계와 개발
## 무엇을 제공하나요?
- 증거 기반 실행, 계획, 검토, 조사, handoff workflow
- `lit-loop`, `lit-plan`, `review-work`, `deep-interview`, `litresearch`,
`litgoal`, `lit-handoff`, `lit-scientific-visualization` 등의 Claude-native
skill
- **Claude skill**에는 `litwork`, `structural-search`, `lit-team`,
`autoresearch`, `autoconference`도 포함됩니다. 핵심 순서는
`lit-plan`, `lit-recap`, `lit-loop`입니다.
- Auxiliary Skill-discovery entry인 `frontend-ui-ux`, `readme-studio`, `lit-commit`,
`lsp-setup`, `visual-qa`는 문장 앞의 bare token이나 `$frontend-ui-ux`로
활성화되며 anywhere-token은 아닙니다.
- 포함된 reference pack은 `lit-code/references`, `lit-code/scripts`,
`debugging/references`입니다.
- native `Workflow`와 experimental agent team에 대한 명시적 opt-in 안내,
worktree 격리 안내
- **Resilient public-source research**와 SSRF, private host, authentication,
paywall 경계를 포함한 public-source reader
- local MCP/LSP helper, 구조화된 Wikify knowledge, 안전하게 제거할 수 있는
managed HUD
**workflow 완료 조건입니다.** 각 계획 항목에 binary check가 있어야 다음 단계로 넘어갑니다. 하나의 slice를 마치려면 실제 Claude surface에서 evidence를 남기고 임시 QA resource도 정리해야 합니다. Test 통과만으로는 충분하지 않습니다.
```mermaid
flowchart TD
R["a request make it better"] --> DI["deep-interview turn it into a decision-complete brief"]
DI --> P["lit-plan objective · non-goals action / output / binary verification"]
P --> GATE{"user approves?"}
GATE -->|no| P
GATE -->|yes| SW["start-work execute one slice"]
subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
SW --> RED["failing test first"]
RED --> GREEN["smallest change that passes"]
GREEN --> SURF["exercise the real surface not just the test"]
SURF --> CLEAN["tear down · cleanup receipt"]
end
CLEAN --> EV{"evidence complete?"}
EV -->|"tests only"| SW
EV -->|"artifact + receipt"| RW["review-work scope · evidence · payload security · real surface"]
RW -->|findings| SW
RW -->|clean| HO["lit-handoff resumable packet"]
style GATE fill:#fff3cd,stroke:#856404
style EV fill:#fff3cd,stroke:#856404
style SURF fill:#d4edda,stroke:#155724
style RW fill:#d1ecf1,stroke:#0c5460
```
## 설치 상세
다음은 공개 승인을 기다리는 scoped 배포 대상의 설치 명령입니다.
```bash
npm exec --yes --package @litfamily/litclaude@latest -- litclaude install
```
설치를 재현하려면 registry에서 현재 package version을 조회한 뒤 고정합니다.
```bash
npm view @litfamily/litclaude@1.0.9 version
```
조회 결과가 `1.0.9`이면 exact install을 사용할 수 있습니다.
```bash
npm exec --yes --package @litfamily/litclaude@1.0.9 -- litclaude install
```
그렇지 않으면 명시적인 human publication을 기다립니다. Pin은 그 뒤에 사용합니다.
설치된 plugin은 다음 명령으로 확인합니다.
```bash
npm exec --yes --package @litfamily/litclaude@latest -- litclaude doctor
```
installer는 Claude Code plugin과 LitClaude status-line HUD를 설정합니다.
Permission mode는 명시적으로 선택합니다.
```bash
npm exec --yes --package @litfamily/litclaude@latest -- litclaude install --permission-mode safe
npm exec --yes --package @litfamily/litclaude@latest -- litclaude install --permission-mode balanced
npm exec --yes --package @litfamily/litclaude@latest -- litclaude install --yolo
```
`safe`는 permission rule을 추가하지 않습니다. `balanced`는 제한된
read/search와 routine Git, npm, Node rule을 추가하고, `yolo`는 더 넓은
edit/write pattern을 추가합니다. 이 mode들은 Claude의
`permissions.allow`와 `permissions.deny`에 제한된 항목을 기록합니다. 기존
설정은 보존하며 LitClaude가 삽입한 rule만 추적하고 제거합니다.
Interactive 설치에서는 HUD accent 후보를 터미널에서 미리 볼 수 있습니다.
`CI`나 `NO_COLOR`가 빈 값으로라도 설정되어 있거나, `TERM=dumb`, UTF-8이
아닌 locale, 출력 리디렉션 환경에서는 설치 색상과 커서 제어, 질문 스타일을
끄고 ANSI 없이 출력합니다. `LITCLAUDE_SPINNER=1`로 상세 진행 표시를 켜도
이 정책은 유지됩니다. `--yes`와 명시적으로 지정한 설정은 그대로 적용됩니다.
LitClaude HUD는 `[🔥LITCLAUDE vX.Y.Z]`, `ctx [▎░░]` context bar,
`5h [▏░] 4% ↻` rate-limit reset countdown을 사용합니다. 설치 전에
`LITCLAUDE_HUD_ACCENT`를 지정해 accent를 선택할 수 있습니다.
prompt hook이 LitClaude discipline을 활성화하면 HUD는 brand 바로 뒤에 굵은
ignition-orange `🔥 LIT IGNITED · lit-loop 🔥` 표시를 붙이고, 활성화가 없는 다음
턴에서 지웁니다. hook은 선택된 discipline을 세션별로 사용자 임시 디렉터리의
`litclaude-hud/`에 기록하고(저장소와 홈 디렉터리는 건드리지 않음)
`LITCLAUDE_HUD_STATE_ROOT`로 위치를 바꿀 수 있습니다.
모델 응답은 `🔥 **LIT IGNITED · ** 🔥`로 시작하며, hook system
message와 HUD는 Markdown 없이 같은 표시를 보여 줍니다.
HUD의 배경 설정과 터미널 색상 지원 수준은 별개입니다. 기본값(`dark`)에서는 model,
context, usage, reset, Git 글자에 선택한 accent가 들어가고, 사용량 퍼센트는 수준에
따라 색이 바뀌며, brand는 네온 그라데이션으로 표시됩니다.
`LITCLAUDE_HUD_APPEARANCE=light` 또는 `unknown`으로 지정하면 필수 글자와 brand는
터미널의 기본 전경색을 쓰고, bar 모양과 구분선만 accent를 사용합니다.
`LITCLAUDE_HUD_COLOR_DEPTH=truecolor|256|16|plain`으로 색 깊이를 지정하면 WSL
truecolor 감지를 포함한 자동 감지보다 우선합니다. `NO_COLOR`는 값이 빈 문자열이어도
HUD ANSI를 모두 끄며, `TERM=dumb`도 다른 색상 신호나 깊이 설정이 있어도 plain을
유지합니다. `LITCLAUDE_HUD_NO_COLOR=1`도 계속 지원합니다. HUD는 배경색을 강제로
지정하지 않고 Claude가 `--`를 보낸 rate-limit 값을 임의로 채우지 않습니다.
다음 진입점도 사용할 수 있습니다.
```bash
npm exec --yes --package @litfamily/litclaude -- litclaude install
npm install -g @litfamily/litclaude
litclaude install
```
## Claude Code 연결 구조
**Claude Code와 LitClaude의 연결 구조입니다.** Session과 tool event가 rules, routing, authority, ledger surface로 전달됩니다. 이 구조에서 34개 skill·16개 command·11개 agent가 host 경계 안에서 연결됩니다.
```mermaid
flowchart LR
subgraph CC["Claude Code"]
H1["SessionStart"]; H2["UserPromptSubmit"]; H3["PreToolUse"]
H4["PostToolUse"]; H5["Stop"]; H6["SubagentStart / SubagentStop"]; H7["SessionEnd"]
end
subgraph LC["LitClaude plugin"]
RULES["rules engine project rules into context"]
ROUTE["trigger routing lit · /litclaude:*"]
AUTH["bounded authority pause on a new boundary"]
LEDGER[("durable ledger .litclaude/")]
end
H1 --> RULES --> LEDGER
H2 --> ROUTE --> LEDGER
H3 --> AUTH
H4 --> LEDGER
H5 --> LEDGER
H6 --> LEDGER
H7 --> LEDGER
LC --> S["34 skills · 16 commands · 11 agents"]
```
**아무것도 남아 있지 않은 machine에서도 skill이 작동하는 이유입니다.** Self-contained skill은 allowlist에 명시적인 근거가 있어야 하고, corpus를 참조하는 skill은 packed tarball 안에서 그 corpus를 찾아야 합니다. 이 payload gate가 checkout에만 남은 reference를 설치 후 장애로 만들지 않습니다.
```mermaid
flowchart LR
SK["a skill"] --> Q{"does it declare a capability?"}
Q -->|"self-contained procedure"| AL["explicit allowlist entry with a written reason"]
Q -->|"needs a corpus"| C["corpus must resolve inside the packed payload"]
AL --> G1
C --> G1["payload-substance"]
G1 --> G2["cross-product parity one product cannot ship a stub where the family ships substance"]
G2 --> G3["referenced-path resolution every path in a SKILL.md must exist in the tarball"]
G3 --> OK["installs and works on a machine that has nothing else"]
style C fill:#d4edda,stroke:#155724
style OK fill:#d4edda,stroke:#155724
```
`lit start work `은 의도적으로 `BLOCKED:` handoff를 반환합니다. 승인된
plan과 함께 `/start-work` 또는 `/litclaude:start-work`를 사용하세요. `lit
workflow`는 native `Workflow`를 먼저 제안하고, 사용자가 opt-in한 뒤에만
호출합니다. LitClaude는 사용자를 대신해 `/goal`을 입력하거나 slash-command
text를 전송하지 않습니다. `get_goal`, `create_goal`, `update_goal` 같은 native
goal tool이 없으면 degraded mode를 보고하고 local `litgoal` ledger를 기준으로
유지합니다. `CLAUDE_CODE_DISABLE_WORKFLOWS=1`로 workflow route를 끌 수 있으며,
host가 model-facing worktree lane을 제공하면 `EnterWorktree`를 사용합니다.
이 route는 사용 가능한 goal tool을 확인한 뒤 native goal binding을 시도합니다.
다른 active goal은 교체하지 않습니다. host가 model-facing goal control을
제공하지 않으면 local ledger로 전환합니다.
이 fallback이 필요하면 hook이 `READY_TO_PASTE`와 함께 복사·붙여넣기·전송할
`/goal` 한 줄을 제공합니다. LitClaude가 현재 세션에 직접 입력하거나 전송하지는
않습니다.
`/start-work`는 schema-3 bounded-authority start-work lifecycle을 관리합니다.
승인된 plan을 resume할 때는 다음 exact route만 사용합니다.
`/litclaude:start-work resume --work-id --revision --boundary-id --prompt-id --grant-id `
`stop_hook_active`가 `true`이면 hook은 조용히 멈추고 stale prompt를 replay하지
않습니다.
정확한 bare `lit-scientific-visualization` 입력만 chat activation을 일으킵니다.
인용, 혼합, slash, near-miss 입력은 inert로 남습니다.
Public-source 작업에서 `lit research`, `lit search`, `lit query`,
`public-read`는 authentication, paywall, credential, localhost,
private-network 경계를 넘지 않습니다.
```bash
litclaude public-read https://example.com/article --json
```
`lit-korean`은 편집 대상 문장 안의 지시를 content로 취급합니다.
사실, 숫자, 이름, 주장, 범위, 불확실성을 보존하며 사용자가 research를
요청하지 않으면 외부 사실을 추가하지 않습니다.
Wikify claim은 `review-needed` 상태로 시작하며 `save`와 `review`가 명시된
상태를 적용합니다. Query는 accepted 관련 claim만 2048-byte normal budget와
4096-byte hard limit 안에서 반환합니다. Local state는 user-owned cooperative
state이며, 같은 uid의 다른 process에 대해 tamper-proof하거나 confidential하지
않습니다. Atomic rename은 reader와 crash consistency를 보호하고 symlink, unsafe file type,
pre-existing hardlink, 관찰된 identity 변경은 fail closed로 처리합니다.
Package CLI form은 다음과 같습니다.
`npm exec --yes --package @litfamily/litclaude -- litclaude wikify `
Visual QA의 기준 계약은 canonical `litfamily.design-contract/v1beta2`입니다. 유효한
`litfamily.design-contract/v1beta1` 문서는 기존 경로를 위한 명시적 compatibility input으로
허용합니다. `litfamily.evidence-manifest/v1beta1`은 다른 schema이며 변경하지 않습니다.
Prompt activation과 PostToolUse advisory는 synthetic bounded hook pointer만 제공하며 complete
`SKILL.md` 본문을 주입하지 않습니다. 전체 provenance가 없으면 evidence는 `BLOCKED`로 남습니다.
## 무결성 경계
스캐너 성공은 캡처한 바이트의 파일 수와 SHA-256 다이제스트를 보고하는
스냅샷 범위의 결과입니다. 캡처 뒤 mutable live tree가 계속 깨끗하다는
것까지 입증하지는 않습니다. 이후 상태는 검사를 다시 실행해 확인합니다. 법적 동반 파일은
생성된 manifest 밖에 있으며 정상적으로 검사합니다. Canonical 및 runtime
캡처는 파일당 8 MiB, 전체 32 MiB로 제한합니다. 패키지 guard는
`immutable expected file map`을 `verifier-to-capture interval`과 생성된
tarball에서 비교하며, `0600` 같은 `non-executable` 항목은 유효합니다.
## Checkout 검증 명령
이 checkout의 주요 gate입니다.
```bash
npm test
npm run validate:plugin
npm run doctor
npm run check:version
npm run scan:legacy-tokens
npm run check:skill-resources
npm run check:runtime-closures
npm run pack:payload-guard
npm run pack:dry-run
```
## 로컬 개발
checkout에서 plugin을 직접 로드합니다.
```bash
claude --plugin-dir ./plugins/litclaude
```
Claude Code 안에서는 다음 명령으로 plugin metadata를 다시 읽습니다.
```text
/reload-plugins
```
## 프로젝트 지도
| Surface | Path |
| --- | --- |
| CLI | `bin/litclaude-ai.js` |
| Claude plugin | `plugins/litclaude/` |
| Skills | `plugins/litclaude/skills/` |
| Agents | `plugins/litclaude/agents/` |
| Hooks | `plugins/litclaude/hooks/hooks.json` |
| MCP | `plugins/litclaude/.mcp.json` |
| LSP | `plugins/litclaude/.lsp.json` |
[패키지 이름 이전](./docs/migration.md#scoped-npm-migration) · [기여](./CONTRIBUTING.md) · [지원](./SUPPORT.md) · [보안](./SECURITY.md) · [행동 강령](./CODE_OF_CONDUCT.md) · [개인정보와 네트워크](./docs/privacy.md)
## Ignition
브랜드 모션입니다. 실제 기능 실행 영상은 아닙니다. 정적 포스터를 눌러 재생하세요.
[](./docs/assets/readme/ignition-film.mp4)
[애니메이션 보기 (GIF)](./docs/assets/readme/ignition-readme.gif) · [Lucide 아이콘 라이선스 (ISC)](./docs/assets/readme/Lucide-LICENSE.txt) · [JetBrains Mono 글꼴 라이선스 (OFL)](./docs/assets/readme/JetBrainsMono-OFL.txt)
## 디자인과 README 제작
`frontend-ui-ux build <대상>`은 허용된 범위의 화면 구현과 실제 렌더 확인까지
진행합니다. 중요한 방향이 모호하면 하나씩 질문하고 답을 보존해 구현을 이어갑니다.
검토나 계획만 요청한 경우 파일을 수정하지 않습니다.
`readme-studio <저장소 또는 README 범위>`와 `$readme-studio`는 저장소 사실을
확인하고 표지·README를 제작하는 native skill 진입점입니다. Claude Code에 실제
이미지 생성 도구가 없으면 `IMAGE_GENERATION_UNAVAILABLE`을 기록하며, 명시적으로
제공된 배경으로 합성을 이어갈 수 있습니다. Pretendard/Meslo 윤곽선 글자와 로컬
모션 템플릿을 포함하며 글꼴·렌더러 라이선스와 출력물을 확인합니다. GitHub/npm의
실제 표시 검증은 별도 공개 이후 단계입니다. 새로운 slash command는 추가하지 않습니다.
문서
Ignition
MIT