litclaude-ai 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.3.9 - 2026-06-19 — hook activation and mode-discipline parity
+
+- Port the LitOpenCode v0.1.17 workflow contract into Claude Code-native surfaces without copying
+  OpenCode-only hooks or permission objects.
+- Rework `UserPromptSubmit` activation so natural language routes `lit`, `litwork`, `lit plan`,
+  `lit review`, `lit research`, `lit goal`, and `lit start work` to distinct mode contracts while
+  ignoring slash commands/mentions, code spans/fences, substrings, and compound tokens.
+- Add safe natural-language `lit start work` behavior: the hook emits a `BLOCKED:` handoff that tells
+  the user to run `/start-work` or `/litclaude:start-work` instead of pretending a prompt hook can
+  switch Claude Code agents.
+- Strengthen prompt contracts across lit-loop, lit-plan, start-work, review-work, litresearch, and
+  litgoal; document primary order as `lit-loop`, `lit-plan`/`prometheus-planner`, then
+  `start-work`/`boulder-executor`.
+- Add installer permission preferences (`safe`, `balanced`, `yolo`) as Claude-native recorded
+  settings. Balanced records routine automation preference while preserving dangerous-shell deny
+  boundaries and planner read-only safeguards.
+
+## 0.3.8 - 2026-06-16 — sibling-parity skill depth + goal/workflow feasibility reflection
+
+- **Deepen eight skills to sibling parity.** A cross-sibling audit found several skill prompts were
+  materially thinner than their counterparts. Re-authored brand-clean, in LitClaude's own Claude Code
+  idiom (no foreign naming):
+  - `refactor` (73 → ~437 lines) — a phased behavior-preserving playbook: intent gate → codebase
+    analysis (LSP + read-only subagents) → codemap/impact zones → coverage-gated strategy
+    (run/add-characterization/PAUSE/BLOCK) → per-step execute-verify-revert with a Failure Recovery
+    Protocol → final regression sweep.
+  - `remove-ai-slops` (52 → ~347) — a 10-category slop taxonomy with KEEP/REMOVE rules, a **test-first
+    behavior-lock** safety invariant (pin behavior green *before* removing), a 5-gate quality table,
+    risk-ordered cleanup, and a "when in doubt, SKIP" rule.
+  - `programming` (106 → ~437) — a language gate that routes to the already-shipped per-language
+    `references/`, a cross-language iron-list table, canonical-library/toolchain tables, a TDD pyramid
+    + Given/When/Then + mock ladder, the 250-LOC ceiling with measurement, and a post-write self-review
+    loop into `refactor` / `remove-ai-slops`.
+  - `debugging` (70 → ~207) — now **activates the previously-orphaned `references/` library** (~1,500
+    lines of runtime/tool/methodology depth) via routing tables, a phase loop with a ≥3-hypothesis
+    floor + oracle-triple escalation, safety invariants, and a `.debug-journal.md` revert discipline.
+  - `litresearch` (148 → ~228) — durable on-disk session journaling (wave digests + expansion-log +
+    `SYNTHESIS.md`) for recovery-after-compaction, a search-craft operator playbook (≥10-query floor,
+    English-first-then-local), and a richer worker roster.
+  - `lit-plan` (125 → ~291) — task-tier classification, explore-first grounding, interview-the-unknowns,
+    an approval gate, a templated success-criteria block, and a pre-finalize two-pass review.
+  - `start-work` (131 → ~252) — LIGHT/HEAVY tiering, a per-checkbox A–E gate loop with a 9-class
+    adversarial-QA taxonomy, a baseline-characterization gate, and an independent-verifier completion
+    contract.
+  - `review-work` (331 → ~519) — a Phase-0 context-gathering preamble, ready-to-paste per-lane launch
+    prompts with fixed output schemas, the QA brainstorm-before-execute scenario method, and an
+    expanded 10-category security checklist.
+- **Add a LIGHT/HEAVY effort tier to `lit-loop`** — classify the task once at bootstrap and size the
+  process to match (ratchet up only; when uncertain, treat as HEAVY). This closes the one litwork-tier
+  gap relative to siblings without adding a duplicate skill.
+- **Reflect the goal / dynamic-workflow feasibility finding.** Investigation confirmed: entering Claude
+  Code's native `/goal` state from a plugin is **functionally impossible** (the host exposes no
+  model-facing goal tools and a hook cannot type a slash command) — the litgoal **autoloop** remains the
+  correct plugin-owned equivalent and is verified working. The Dynamic workflow path, by contrast, was
+  **partially implemented**: the guidance told the model to call `Workflow` unconditionally, but the
+  tool requires explicit user opt-in. The hook context, the `lit-loop` skill, the `dynamic-workflow` /
+  `lit-loop` commands, and the README now **propose a Dynamic workflow and call `Workflow` only once the
+  user opts in** — clarifying that this opt-in gate (not a host limitation) is why a Dynamic workflow
+  starts only after the proposal.
+
 ## 0.3.7 - 2026-06-14 — litresearch skill + LITBURN ignition banner
 
 - Add the **`litresearch`** skill (`plugins/litclaude/skills/litresearch/`) + command

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.7-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.9-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,18 +22,20 @@
 > `litclaude@litclaude-ai`, so normal `claude` launches can load the
 > LitClaude skills and hooks without a long `--plugin-dir` command.
 
-This checkout is prepared as `litclaude-ai@0.3.7` for personal install
+This checkout is prepared as `litclaude-ai@0.3.9` for personal install
 convenience. The repo can remain quiet; preparing npm package metadata here does
 not imply public repo promotion, marketplace publication, or advertisement.
-Future package releases still require explicit user approval. The v0.3.7
-release materials preserve the v0.2.2 Dynamic workflow hardening work, add the
-lit-family vocab rename and neon HUD on top of v0.2.2, describe LitClaude in
-its own terms, and do not claim that npm publication has completed.
+Future package releases still require explicit user approval. The v0.3.9
+release materials preserve the v0.3.8 skill-depth work and add Claude-native
+hook activation, prompt/mode contract, safe mode-transition, primary-order, and
+installer permission-preference discipline.
 
 ## Features
 
 - **Natural Claude launch** - install once with `npx`, then run plain `claude`
-- **LIT prompt hooks** - type `lit`, `litwork`, `$lit-plan`, or `$lit-loop`
+- **LIT prompt hooks** - type `lit`, `litwork`, `lit plan`, `lit review`,
+  `lit research`, `lit goal`, or `lit start work`; slash commands stay on
+  Claude Code's native command surface and do not double-activate the hook
 - **Deep interview mode** - type `/deep-interview` or `$deep-interview` to
   turn broad intent into a spec before planning or implementation
 - **v0.2.0 workflow parity** - adds `review-work` 5-lane review discipline and
@@ -93,7 +95,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.7 install
+npx --yes litclaude-ai@0.3.9 install
 ```
 
 Validate the installed plugin:
@@ -106,7 +108,7 @@ The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.7] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.9] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from
@@ -160,6 +162,21 @@ the skill and hook inventory in `claude plugin details`.
 Use `CLAUDE_CONFIG_DIR=/some/path` and `LITCLAUDE_HOME=/some/path` only for
 isolated tests.
 
+Installer permission preference can be recorded without copying OpenCode's
+permission model:
+
+```bash
+npx --yes litclaude-ai install --permission-mode safe
+npx --yes litclaude-ai install --permission-mode balanced
+npx --yes litclaude-ai install --yolo
+```
+
+`safe` is conservative. `balanced` records that routine automation guidance is
+acceptable while preserving dangerous-shell deny boundaries and planner
+read-only safeguards. `yolo` records explicit user preference, but the installer
+does not rewrite Claude agent frontmatter or weaken `prometheus-planner`'s
+`permissionMode: plan` boundary.
+
 ## LIT Usage
 
 After install, start Claude Code:
@@ -173,6 +190,11 @@ Then type one of these prompts:
 ```text
 lit
 litwork
+lit plan <what you want planned>
+lit review <scope to review>
+lit research <research question>
+lit goal <outcome and criteria>
+lit start work <approved plan>
 $lit-plan <what you want planned>
 /lit-plan <what you want planned>
 $lit-loop <what you want executed with evidence>
@@ -189,15 +211,17 @@ $start-work plans/example-plan.md
 /start-work plans/example-plan.md
 ```
 
-Expected behavior: LitClaude's prompt hook adds `LITWORK MODE ENABLED`
-context for LIT routes and shows `LitClaude lit hook active` as a visible hook
-message. For `/deep-interview`, the hook adds `DEEP INTERVIEW MODE ENABLED`
-context and routes Claude toward `/litclaude:deep-interview` /
-`Skill(deep-interview)`. Plain `lit` still maps to `/litclaude:lit-loop` /
-`Skill(lit-loop)` semantics before ordinary task execution, then the matching
-skill and agent instructions steer Claude toward test-first work, native goal
-handling, manual QA evidence, cleanup receipts, and explicit approval before
-future release steps.
+Expected behavior: LitClaude's prompt hook adds mode-specific `LITWORK MODE
+ENABLED` context for natural LIT routes and shows `LitClaude lit hook active` as
+a visible hook message. Slash commands such as `/lit-plan` are handled by Claude
+Code's native command surface and should not double-activate the hook. Natural
+`lit start work` is a safe handoff: it emits `BLOCKED:` and tells the user to
+run `/start-work` or `/litclaude:start-work` with the approved plan because a
+prompt hook cannot switch Claude Code agents. Plain `lit` still maps to
+`/litclaude:lit-loop` / `Skill(lit-loop)` semantics before ordinary task
+execution, then the matching skill and agent instructions steer Claude toward
+test-first work, native goal handling, manual QA evidence, cleanup receipts, and
+explicit approval before future release steps.
 
 LitClaude does not auto-type `/goal` or send slash command text for you.
 Instead, the hook and LIT skills add run-context guidance: use Claude Code's
@@ -208,8 +232,12 @@ LitClaude keeps the local evidence ledger authoritative and may suggest an
 exact `/goal <completion condition>` before long execution without repeatedly
 printing fallback chatter.
 For large independent work, LitClaude applies the same principle to Claude
-Code's available orchestration surfaces: when `Workflow` is exposed, call the
-`Workflow` tool; when isolated edits need a model-facing worktree lane, use
+Code's available orchestration surfaces: when `Workflow` is exposed and the task
+is broad, risky, parallel, or long-running, LitClaude **proposes a Dynamic
+workflow and calls the `Workflow` tool once you opt in**. The tool can fan out
+many subagents and spend a large token budget, so it asks first — this opt-in
+gate (not a host limitation) is why a Dynamic workflow only starts after the
+proposal. When isolated edits need a model-facing worktree lane, use
 `EnterWorktree`. If only the CLI surface is available for a fresh isolated lane,
 use `claude --worktree <short-name> --tmux`.
 
@@ -280,8 +308,8 @@ namespaced commands when you want explicit LitClaude skill activation:
 Those namespaced commands are shipped as real Claude Code command files under
 `plugins/litclaude/commands/`, so `/litclaude:lit-loop` should load the
 command body, then the matching skill guidance.
-The shorter slash aliases above are also recognized by the prompt hook and
-route to the matching discipline instead of the plain `lit` loop fallback.
+Slash commands and their shorter aliases are handled by Claude Code's native
+command surface; the prompt hook no longer double-activates them.
 
 Use `/deep-interview` before `/lit-plan` when the request is broad,
 underspecified, or missing non-goals and acceptance criteria. It writes a

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.7-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.9-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,19 +26,21 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.7` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.9` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.7 release material은 v0.2.2 Dynamic workflow
-hardening을 보존하고, lit-family vocab rename과 neon HUD를 추가하며,
-LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
-주장하지 않습니다.
+승인 후에 진행합니다. v0.3.9 release material은 v0.3.8 skill-depth 작업을
+보존하고, Claude-native hook activation, prompt/mode contract, safe
+mode-transition, primary-order, installer permission preference discipline을
+추가합니다.
 
 ## 기능
 
 - **자연스러운 Claude 실행** - 한 번 `npx`로 설치한 뒤에는 plain `claude`
-- **LIT prompt hook** - `lit`, `litwork`, `$lit-plan`, `$lit-loop` 트리거
+- **LIT prompt hook** - `lit`, `litwork`, `lit plan`, `lit review`,
+  `lit research`, `lit goal`, `lit start work` 자연어 트리거. slash command는
+  Claude Code native command surface에서 처리되어 hook이 중복 활성화하지 않습니다.
 - **Deep interview mode** - `/deep-interview` 또는 `$deep-interview`로 넓고
   모호한 의도를 먼저 spec으로 정리한 뒤 계획/구현으로 넘김
 - **v0.2.0 workflow parity** - package publish가 끝났다고 말하지 않으면서
@@ -98,7 +100,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.7 install
+npx --yes litclaude-ai@0.3.9 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +113,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.7] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.9] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.
@@ -164,6 +166,20 @@ LitClaude 전용 local marketplace 항목, `known_marketplaces.json`을 함께
 격리 테스트가 필요할 때만 `CLAUDE_CONFIG_DIR=/some/path`와
 `LITCLAUDE_HOME=/some/path`를 지정하세요.
 
+installer permission preference는 OpenCode permission model을 그대로 복사하지
+않고 Claude-native 설정으로 기록합니다.
+
+```bash
+npx --yes litclaude-ai install --permission-mode safe
+npx --yes litclaude-ai install --permission-mode balanced
+npx --yes litclaude-ai install --yolo
+```
+
+`safe`는 보수적 기본값입니다. `balanced`는 routine automation guidance를
+허용한다는 선호만 기록하되 dangerous-shell deny boundary와 planner read-only
+safeguard를 유지합니다. `yolo`도 명시적 선호를 기록할 뿐,
+`prometheus-planner`의 `permissionMode: plan` boundary를 약화하지 않습니다.
+
 ## LIT 사용법
 
 설치 후에는 일반적인 `claude` 명령에서 LitClaude를 사용할 수 있습니다.
@@ -177,6 +193,11 @@ claude
 ```text
 lit
 litwork
+lit plan <계획이 필요한 작업>
+lit review <검토할 범위>
+lit research <조사할 질문>
+lit goal <목표와 기준>
+lit start work <승인된 계획>
 $lit-plan <계획이 필요한 작업>
 /lit-plan <계획이 필요한 작업>
 $lit-loop <증거 기반으로 실행할 작업>
@@ -193,15 +214,17 @@ $start-work plans/example-plan.md
 /start-work plans/example-plan.md
 ```
 
-기대 동작은 LitClaude prompt hook이 LIT route에는 `LITWORK MODE ENABLED`
-컨텍스트를 추가하고 `LitClaude lit hook active`라는 visible hook message를
-보여주는 것입니다. `/deep-interview`에는 `DEEP INTERVIEW MODE ENABLED`
-컨텍스트를 추가하고 Claude를 `/litclaude:deep-interview` /
-`Skill(deep-interview)` 쪽으로 라우팅합니다. 또한 plain `lit`는 일반 작업
-실행 전 `/litclaude:lit-loop` / `Skill(lit-loop)` semantics로 처리됩니다.
-그 뒤 skill 및 agent 지시문이 Claude를 test-first 작업, native goal 처리,
-실제 수동 QA 증거, cleanup receipt, 향후 release step의 명시적 승인 쪽으로
-유도합니다.
+기대 동작은 LitClaude prompt hook이 자연어 LIT route별 mode-specific
+`LITWORK MODE ENABLED` 컨텍스트를 추가하고 `LitClaude lit hook active`라는
+visible hook message를 보여주는 것입니다. `/lit-plan` 같은 slash command는
+Claude Code native command surface에서 처리되며 hook을 중복 활성화하지
+않습니다. 자연어 `lit start work`는 안전한 handoff로 `BLOCKED:`를 내고,
+prompt hook이 Claude Code agent를 전환할 수 없으므로 승인된 plan과 함께
+`/start-work` 또는 `/litclaude:start-work`를 실행하라고 안내합니다. plain
+`lit`는 일반 작업 실행 전 `/litclaude:lit-loop` / `Skill(lit-loop)` semantics로
+처리됩니다. 그 뒤 skill 및 agent 지시문이 Claude를 test-first 작업, native
+goal 처리, 실제 수동 QA 증거, cleanup receipt, 향후 release step의 명시적 승인
+쪽으로 유도합니다.
 
 LitClaude는 `/goal`을 대신 입력하거나 slash command text를 자동 전송하지
 않습니다. 대신 hook과 LIT skill이 run context를 보강합니다. Claude Code의
@@ -212,9 +235,10 @@ goal이 없을 때만 `create_goal`을 호출하며, `update_goal`은 검증 완
 로컬 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`를 사용합니다.
+`Workflow`가 노출되면 먼저 제안하고 사용자 opt-in 또는 이미 허용된 orchestration
+상태에서만 `Workflow` tool을 호출합니다. isolated edit lane이 model-facing
+worktree를 필요로 하면 `EnterWorktree`를 사용합니다. CLI surface만 가능한 새 격리
+lane에서는 `claude --worktree <short-name> --tmux`를 사용합니다.
 
 v0.2.2 Dynamic workflow hardening에서 `/dynamic-workflow`는 넓은 위임 작업을
 위한 통합 bootstrap route입니다. `/goal`은 user-controlled 상태로 두고,

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,13 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.7` is the current release candidate — adds the **`litresearch`** skill +
-command (Claude-native maximum-saturation research orchestrator over the Workflow tool + `litclaude:`
-subagents + `/deep-research`) and a **`🔥 LITBURN IGNITED 🔥`** activation banner shouted on every
-litwork ignition.
-`package.json` is aligned to `0.3.7`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.7`.
+Status: `litclaude-ai@0.3.9` is the current release candidate — a Claude-native
+hook activation and mode-discipline parity pass based on LitOpenCode v0.1.17.
+It routes natural `lit` prompts by mode, blocks natural-language start-work with
+a safe handoff, reinforces planning/execution/review/research/goal contracts,
+documents primary role order, and records installer permission preferences
+without copying OpenCode-only permission objects.
+`package.json` is aligned to `0.3.9`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.9`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -54,8 +56,8 @@ No npm publication is required for this track.
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.7`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.7`.
+- `package.json` version is `0.3.9`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.9`.
 - `plugins/litclaude/commands/dynamic-workflow.md` documents subagent delegation.
 - `node bin/litclaude-ai.js workflow-check --json` reports `status: pass`.
 - `node bin/litclaude-ai.js workflow-check --json` reports
@@ -68,6 +70,8 @@ checkout:
 - `plugins/litclaude/commands/litgoal.md` documents durable goal state.
 - `plugins/litclaude/lib/litgoal/` ships the runtime CLI/state modules.
 - `node bin/litclaude-ai.js litgoal --help` prints durable state commands.
+- `node bin/litclaude-ai.js --dry-run install --permission-mode balanced` reports
+  the balanced preference while preserving dangerous-shell deny boundaries.
 - `npm pack --dry-run --json` includes runtime payloads and excludes local
   `.litclaude/`, `.omc/`, and `evidence/` state.
 - `.litclaude/lit-loop/evidence/v020-red-contracts.txt` or equivalent RED evidence

package/bin/litclaude-ai.js

@@ -36,6 +36,15 @@ Commands:
   start-work-next Print the next active start-work continuation directive.
   update        Reinstall this package version and refresh the Claude plugin registry.
   uninstall     Remove LitClaude-managed install state.
+
+Install options:
+  --permission-mode <safe|balanced|yolo>
+                Record a Claude-native LitClaude automation preference.
+                safe keeps conservative defaults; balanced allows routine
+                automation guidance while preserving dangerous-shell deny
+                boundaries; yolo records an explicit user preference without
+                weakening planner/read-only agent safeguards.
+  --yolo        Shorthand for --permission-mode yolo.
 `;
 
 const parseArgs = (argv) => {
@@ -71,6 +80,74 @@ const knownExternalLspPlugins = {
 };
 const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const hudAccentThemes = HUD_ACCENT_THEMES;
+const permissionModes = new Set(["safe", "balanced", "yolo"]);
+
+const parsePermissionMode = (value) => {
+  if (!permissionModes.has(value)) fail("--permission-mode must be one of safe, balanced, yolo", 64);
+  return value;
+};
+
+const parseInstallOptions = (rest) => {
+  let permissionMode = parsePermissionMode(process.env.LITCLAUDE_PERMISSION_MODE || "safe");
+  let permissionExplicit = Boolean(process.env.LITCLAUDE_PERMISSION_MODE);
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--permission-mode") {
+      const value = rest[index + 1];
+      if (!value) fail("--permission-mode requires a value", 64);
+      permissionMode = parsePermissionMode(value);
+      permissionExplicit = true;
+      index += 1;
+      continue;
+    }
+    if (arg === "--yolo") {
+      permissionMode = "yolo";
+      permissionExplicit = true;
+      continue;
+    }
+    if (arg === "--permission-prompt" || arg === "--select-permissions") {
+      permissionExplicit = true;
+      continue;
+    }
+    if (arg === "--no-permission-prompt") {
+      continue;
+    }
+    fail(`Unknown install option: ${arg}`, 64);
+  }
+
+  return { permissionMode, permissionExplicit };
+};
+
+const permissionProfile = (mode) => {
+  switch (mode) {
+    case "balanced":
+      return {
+        mode,
+        description: "routine automation guidance allowed; dangerous shell patterns and existing deny rules preserved",
+        routineAutomation: true,
+        dangerousShellDenyPreserved: true,
+        plannerSafeguard: "prometheus-planner remains permissionMode: plan",
+      };
+    case "yolo":
+      return {
+        mode,
+        description: "explicit user preference recorded; Claude agent safeguards are not weakened by the installer",
+        routineAutomation: true,
+        dangerousShellDenyPreserved: true,
+        plannerSafeguard: "prometheus-planner remains permissionMode: plan",
+      };
+    case "safe":
+    default:
+      return {
+        mode: "safe",
+        description: "conservative automation guidance; no permission broadening",
+        routineAutomation: false,
+        dangerousShellDenyPreserved: true,
+        plannerSafeguard: "prometheus-planner remains permissionMode: plan",
+      };
+  }
+};
 
 const printUsage = () => {
   process.stderr.write(usage);
@@ -327,6 +404,9 @@ const uninstallHudStatusLine = (home = claudeHome()) => {
     "statusLineInstalledAt",
     "statusLineUpdatedAt",
     "previousStatusLine",
+    "permissionPreference",
+    "permissionMode",
+    "permissionUpdatedAt",
   ]) {
     delete remainingLitClaude[key];
   }
@@ -356,7 +436,19 @@ const unregisterMarketplace = (home = claudeHome()) => {
   }
 };
 
-const registerClaudePlugin = (installRoot, marketplacePath, home = claudeHome(), hudAccent = "cyan") => {
+const recordPermissionPreference = (mode, home = claudeHome()) => {
+  const settings = readClaudeSettings(home);
+  const existingLitClaude = settings[litClaudeSettingsKey] ?? {};
+  settings[litClaudeSettingsKey] = {
+    ...existingLitClaude,
+    permissionPreference: permissionProfile(mode),
+    permissionMode: mode,
+    permissionUpdatedAt: new Date().toISOString(),
+  };
+  writeClaudeSettings(settings, home);
+};
+
+const registerClaudePlugin = (installRoot, marketplacePath, home = claudeHome(), hudAccent = "cyan", permissionMode = "safe") => {
   const registry = readInstalledPlugins(home);
   const now = new Date().toISOString();
   const existing = registry.plugins[pluginKey]?.[0] ?? {};
@@ -374,6 +466,7 @@ const registerClaudePlugin = (installRoot, marketplacePath, home = claudeHome(),
   writeInstalledPlugins(registry, home);
   registerMarketplace(marketplacePath, home);
   installHudStatusLine(installRoot, home, hudAccent);
+  recordPermissionPreference(permissionMode, home);
 };
 
 const unregisterClaudePlugin = (home = claudeHome()) => {
@@ -440,7 +533,8 @@ const resetCurrentPointer = (home, target) => {
   }
 };
 
-const install = async ({ dryRun }) => {
+const install = async ({ dryRun, rest }) => {
+  const { permissionMode, permissionExplicit } = parseInstallOptions(rest);
   const home = claudeHome();
   const litClaudeHome = litHome();
   const targetPlugin = claudePluginRoot(home);
@@ -454,6 +548,8 @@ const install = async ({ dryRun }) => {
     process.stdout.write(`Would create local marketplace: ${targetMarketplace}\n`);
     process.stdout.write(`Would register Claude plugin: ${pluginKey}\n`);
     process.stdout.write(`Would set Claude statusLine HUD: ${hudCommandForPlugin(targetPlugin)}\n`);
+    process.stdout.write(`Would record permission preference: ${permissionMode}${permissionExplicit ? " (explicit)" : " (default)"}\n`);
+    process.stdout.write(`Permission profile: ${permissionProfile(permissionMode).description}\n`);
     process.stdout.write("Launch with: claude\n");
     return;
   }
@@ -471,7 +567,7 @@ const install = async ({ dryRun }) => {
   progress.step("Marketplace: writing local Claude marketplace");
   const localMarketplace = writeLocalMarketplace(litClaudeHome);
   progress.step("Claude registry: enabling plugin and HUD");
-  registerClaudePlugin(targetPlugin, localMarketplace, home, hudAccent);
+  registerClaudePlugin(targetPlugin, localMarketplace, home, hudAccent, permissionMode);
 
   progress.step("Compatibility cache: refreshing local current pointer");
   const litRoot = versionRoot(litClaudeHome);
@@ -486,6 +582,7 @@ const install = async ({ dryRun }) => {
   process.stdout.write(`Marketplace: ${localMarketplace}\n`);
   process.stdout.write(`Plugin path: ${intendedPluginPath(home)}\n`);
   process.stdout.write(`HUD: LitClaude statusLine installed (${hudAccent})\n`);
+  process.stdout.write(`Permission preference: ${permissionMode} — ${permissionProfile(permissionMode).description}\n`);
   process.stdout.write("Launch with: claude\n");
 };
 
@@ -545,6 +642,9 @@ const doctor = ({ dryRun }) => {
 
   process.stdout.write(`Plugin path: ${pluginPath}\n`);
   const settings = readClaudeSettings();
+  const permissionMode = settings[litClaudeSettingsKey]?.permissionMode ?? "safe";
+  process.stdout.write(`PERMISSION_MODE: ${permissionMode}\n`);
+  process.stdout.write(`PERMISSION_PROFILE: ${permissionProfile(permissionMode).description}\n`);
   if (settings.statusLine?.command === hudCommandForPlugin(pluginPath, settings[litClaudeSettingsKey]?.hudAccent)) {
     process.stdout.write("HUD_STATUSLINE_PASS\n");
   } else {

package/docs/agents.md

@@ -3,6 +3,12 @@
 LitClaude agents map the LitClaude team workflow into Claude Code subagents
 with bounded responsibilities.
 
+Primary order:
+
+1. `lit-loop` — the default execution-loop skill for direct, evidence-driven work.
+2. `lit-plan` → `prometheus-planner` — planning-only, read-only, approval-gated.
+3. `start-work` → `boulder-executor` — approved-plan execution-only; no redesign.
+
 | Agent | Responsibility | Boundary |
 | --- | --- | --- |
 | `prometheus-planner` | Build implementation plans and identify risks. | Read-only tools, no write/edit/bash tools. |

package/docs/hooks.md

@@ -14,41 +14,35 @@ events while keeping execution local and bounded.
 
 ## Workflow Trigger Phrases
 
-The `UserPromptSubmit` hook activates on any of these phrases:
+The `UserPromptSubmit` hook activates on these natural-language phrases and
+legacy dollar shorthands:
 
 ```text
 lit
 litwork
+lit plan
+lit review
+lit research
+lit goal
+lit start work
 $lit-plan
-/lit-plan
-/litclaude:lit-plan
 $lit-loop
-/lit-loop
-/litclaude:lit-loop
 $deep-interview
-/deep-interview
-/litclaude:deep-interview
 $dynamic-workflow
-/dynamic-workflow
-/litclaude:dynamic-workflow
 $review-work
-/review-work
-/litclaude:review-work
 $litgoal
-/litgoal
-/litclaude:litgoal
 $start-work
-/start-work
-/litclaude:start-work
 ```
 
 When a LIT trigger is present, the hook returns additional context containing
 `LITWORK MODE ENABLED` and a visible `LitClaude lit hook active` system
-message. For `/deep-interview`, it returns `DEEP INTERVIEW MODE ENABLED` while
-still routing to `/litclaude:deep-interview` / `Skill(deep-interview)`.
-That context is guidance for Claude Code; it is not executed as a command. The
-guidance tells Claude to treat plain `lit` as `/litclaude:lit-loop` /
-`Skill(lit-loop)` semantics before ordinary task execution.
+message. That context is guidance for Claude Code; it is not executed as a
+command. Slash commands and slash-command mentions are native Claude Code
+surfaces and do not activate this prompt hook; code spans, code fences,
+substrings, and compound tokens are also ignored. Natural `lit start work`
+returns a `BLOCKED:` handoff that tells the user to run `/start-work` or
+`/litclaude:start-work` with the approved plan, because a prompt hook cannot
+switch Claude Code agents.
 
 LitClaude follows the LitClaude goal pattern as model-facing run context, not
 as slash-command injection. If Claude Code exposes the native goal surface, the
@@ -63,9 +57,9 @@ the hook context keeps the local evidence ledger authoritative. It may suggest
 fallback chatter on every LIT turn.
 
 For broad work, the same context ports the LitClaude model-facing principle to
-Claude Code's exposed orchestration surfaces: if `Workflow` is available, call
-the `Workflow` tool before serial execution and bind every lane to evidence and
-cleanup. If isolated edits need a model-facing worktree lane, use
+Claude Code's exposed orchestration surfaces: if `Workflow` is available,
+propose it first and call the `Workflow` tool only after user opt-in or existing
+session permission, binding every lane to evidence and cleanup. If isolated edits need a model-facing worktree lane, use
 `EnterWorktree`; when only the CLI surface is available, the actionable launch
 form is `claude --worktree <short-name> --tmux`.
 
@@ -86,9 +80,7 @@ ledger, Boulder state, and `git status --short` before edits.
 
 Plain `lit` therefore activates hook context, not a visible Skill tool call.
 For a visible LitClaude command/skill invocation, use the namespaced Claude
-Code commands. The shorter slash aliases above are also recognized by the prompt
-hook so they route to the same discipline instead of falling through to plain
-`lit` loop activation:
+Code commands:
 
 ```text
 /litclaude:lit-loop <goal>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {