litclaude-ai 0.3.8 → 0.3.10

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.10 - 2026-06-20 — build-decision gate and reuse self-review
+
+- Add a pre-write minimum-first build-decision gate and a necessity/reuse self-review to the
+  programming skill.
+
+## 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

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.8-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.10-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.8` for personal install
+This checkout is prepared as `litclaude-ai@0.3.10` 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.8
-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.10
+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.8 install
+npx --yes litclaude-ai@0.3.10 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.8] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.10] | 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
@@ -284,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.8-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.10-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.8` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.10` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.8 release material은 v0.2.2 Dynamic workflow
-hardening을 보존하고, lit-family vocab rename과 neon HUD를 추가하며,
-LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
-주장하지 않습니다.
+승인 후에 진행합니다. v0.3.10 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.8 install
+npx --yes litclaude-ai@0.3.10 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +113,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.8] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.10] | 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,15 +1,13 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.8` is the current release candidate — a sibling-parity
-depth pass. It substantially deepens eight skills (`refactor`, `remove-ai-slops`,
-`programming`, `debugging`, `litresearch`, `lit-plan`, `start-work`, `review-work`)
-to match the structured workflows their siblings carry; adds a LIGHT/HEAVY effort
-tier to `lit-loop`; and reflects the goal/dynamic-workflow feasibility finding —
-native `/goal` is a user-typed surface a plugin cannot invoke (the litgoal
-autoloop is the equivalent), and the Dynamic workflow guidance now gates the
-`Workflow` call on explicit user opt-in.
-`package.json` is aligned to `0.3.8`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.8`.
+Status: `litclaude-ai@0.3.10` 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.10`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.10`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -58,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.8`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.8`.
+- `package.json` version is `0.3.10`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.10`.
 - `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
@@ -72,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.8",
+  "version": "0.3.10",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin.",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "author": {
     "name": "LitClaude contributors"
   },
@@ -11,12 +11,12 @@
   "keywords": ["claude-code", "hooks", "skills", "agents", "lsp", "workflow"],
   "skills": "./skills",
   "agents": [
+    "./agents/prometheus-planner.md",
     "./agents/boulder-executor.md",
-    "./agents/librarian-researcher.md",
     "./agents/oracle-verifier.md",
-    "./agents/prometheus-planner.md",
     "./agents/qa-runner.md",
-    "./agents/quality-reviewer.md"
+    "./agents/quality-reviewer.md",
+    "./agents/librarian-researcher.md"
   ],
   "mcpServers": "./.mcp.json",
   "lspServers": "./.lsp.json",

package/plugins/litclaude/agents/boulder-executor.md

@@ -8,5 +8,8 @@ skills:
   - programming
 ---
 
-Execute only the assigned plan checkbox. Write the failing test first, make the
-smallest change, run verification, capture evidence, and report cleanup.
+Execute only the assigned approved plan checkbox. Do not redesign, rescope, or
+replace the approved plan unless evidence proves a blocker or stale state. Write
+the failing test first, make the smallest change, run verification, capture
+real-surface evidence, and report cleanup. Your DoneClaim must name changed
+files, exact tests, real-surface evidence, risks, and cleanup receipt.

package/plugins/litclaude/agents/prometheus-planner.md

@@ -10,4 +10,6 @@ skills:
 
 You are Prometheus, the planning agent. Explore first, ask only preference
 questions, and write plans with concrete acceptance criteria and QA scenarios.
-Do not implement product changes.
+This is a planning-only role: must not implement product changes, do not run
+mutating commands, and do not start execution. After approval, hand off through
+`/start-work` or `/litclaude:start-work`.

package/plugins/litclaude/bin/litclaude-hook.js

@@ -43,30 +43,134 @@ const writeContext = (additionalContext, systemMessage) => {
   );
 };
 
-const workflowTriggers = [
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)deep-interview(?=$|[^\w-])/u, command: "/litclaude:deep-interview", skill: "Skill(deep-interview)", discipline: "deep-interview" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)dynamic-workflow(?=$|[^\w-])/u, command: "/litclaude:dynamic-workflow", skill: "Skill(lit-loop)", discipline: "dynamic-workflow" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)lit-plan(?=$|[^\w-])/u, command: "/litclaude:lit-plan", skill: "Skill(lit-plan)", discipline: "lit-plan" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)lit-loop(?=$|[^\w-])/u, command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)start-work(?=$|[^\w-])/u, command: "/litclaude:start-work", skill: "Skill(start-work)", discipline: "start-work" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)review-work(?=$|[^\w-])/u, command: "/litclaude:review-work", skill: "Skill(review-work)", discipline: "review-work" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litgoal(?=$|[^\w-])/u, command: "/litclaude:litgoal", skill: "Skill(litgoal)", discipline: "litgoal" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litresearch(?=$|[^\w-])/u, command: "/litclaude:litresearch", skill: "Skill(litresearch)", discipline: "litresearch" },
-  { pattern: /(?:^|\s)(?:litwork|lit)(?=$|[^\w-])/u, command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop", softConfirm: true },
+const plainWordBoundary = /^[A-Za-z0-9]$/u;
+const compoundWordBoundary = /^[A-Za-z0-9_-]$/u;
+
+const triggerByToken = {
+  "deep-interview": { command: "/litclaude:deep-interview", skill: "Skill(deep-interview)", discipline: "deep-interview" },
+  "dynamic-workflow": { command: "/litclaude:dynamic-workflow", skill: "Skill(lit-loop)", discipline: "dynamic-workflow" },
+  "lit-plan": { command: "/litclaude:lit-plan", skill: "Skill(lit-plan)", discipline: "lit-plan" },
+  "lit-loop": { command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop" },
+  "start-work": { command: "/litclaude:start-work", skill: "Skill(start-work)", discipline: "start-work" },
+  "review-work": { command: "/litclaude:review-work", skill: "Skill(review-work)", discipline: "review-work" },
+  litgoal: { command: "/litclaude:litgoal", skill: "Skill(litgoal)", discipline: "litgoal" },
+  litresearch: { command: "/litclaude:litresearch", skill: "Skill(litresearch)", discipline: "litresearch" },
+};
+
+const modeContracts = {
+  "lit-loop": "Mode contract: lit-loop is a durable, evidence-driven execution loop. Define checkable success criteria before coding, use RED->GREEN tests, pair tests with real-surface evidence, checkpoint progress, and stop only when verified done or BLOCKED.",
+  "lit-plan": "Mode contract: lit-plan is planning-only. Do not edit files, run mutating commands, call start-work tooling, or implement. Explore read-only, produce an approval-gated plan, then tell the user to run `/start-work` or `/litclaude:start-work` for execution.",
+  "start-work": "Mode contract: start-work is execution-only for an approved plan. Natural-language activation cannot switch Claude Code agents, so this hook must hand off safely instead of pretending execution started.",
+  "review-work": "Mode contract: review-work runs a five-lane review: goal/constraints, real-surface QA, code quality, security, and docs/package/context readiness. PASS requires evidence from every applicable lane.",
+  litresearch: "Mode contract: litresearch uses sourced evidence, separates verified facts from hypotheses, cites the search/runtime surface used, and reports residual uncertainty.",
+  litgoal: "Mode contract: litgoal binds one outcome-shaped objective plus checkable criteria, each with scenario, real surface, and observable evidence.",
+  "deep-interview": "Mode contract: deep-interview clarifies vague requirements before planning or implementation, without inventing acceptance criteria.",
+  "dynamic-workflow": "Mode contract: dynamic-workflow is opt-in orchestration for broad, risky, parallel, or long-running work; propose it first and only call Workflow after user opt-in or existing session permission.",
+};
+
+const withoutCode = (text) => text.replace(/```[\s\S]*?```/gu, " ").replace(/`[^`]*`/gu, " ");
+const rawTriggerText = (text) => withoutCode(text).toLowerCase();
+const normalizedTriggerText = (text) => rawTriggerText(text).replace(/[_-]+/gu, " ");
+
+const isPlainWordBoundary = (value) => value === undefined || !plainWordBoundary.test(value);
+const isCompoundWordBoundary = (value) => value === undefined || !compoundWordBoundary.test(value);
+
+const containsPlainWord = (text, word) => {
+  for (let index = 0; index < text.length; index += 1) {
+    if (!text.startsWith(word, index)) continue;
+    const previous = index === 0 ? undefined : text[index - 1];
+    const next = text[index + word.length];
+    if (isPlainWordBoundary(previous) && isPlainWordBoundary(next)) return true;
+  }
+  return false;
+};
+
+const containsCompoundBoundedWord = (text, word) => {
+  for (let index = 0; index < text.length; index += 1) {
+    if (!text.startsWith(word, index)) continue;
+    const previous = index === 0 ? undefined : text[index - 1];
+    const next = text[index + word.length];
+    if (isCompoundWordBoundary(previous) && isCompoundWordBoundary(next)) return true;
+  }
+  return false;
+};
+
+const slashCommandMentions = [
+  "/deep-interview",
+  "/dynamic-workflow",
+  "/goal",
+  "/lit-loop",
+  "/lit-plan",
+  "/litclaude:deep-interview",
+  "/litclaude:dynamic-workflow",
+  "/litclaude:lit-loop",
+  "/litclaude:lit-plan",
+  "/litclaude:litgoal",
+  "/litclaude:litresearch",
+  "/litclaude:review-work",
+  "/litclaude:start-work",
+  "/litgoal",
+  "/litresearch",
+  "/review-work",
+  "/start-work",
 ];
 
-const findWorkflowTrigger = (prompt) => workflowTriggers.find((trigger) => trigger.pattern.test(prompt));
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+
+const slashCommandMentionPattern = new RegExp(
+  `(^|\\s)(?:${slashCommandMentions.map(escapeRegExp).join("|")})(?=$|[\\s.,;:!?)}\\]])`,
+  "u",
+);
+
+const containsSlashCommandMention = (text) => slashCommandMentionPattern.test(text);
+
+const findDollarCommandTrigger = (raw) => {
+  const match = /(?:^|\s)\$(deep-interview|dynamic-workflow|lit-plan|lit-loop|start-work|review-work|litgoal|litresearch)(?=$|[^\w-])/u.exec(raw);
+  if (!match) return undefined;
+  return { ...triggerByToken[match[1]], source: "dollar-command" };
+};
+
+const hasLitTrigger = (raw) => containsCompoundBoundedWord(raw, "lit") || containsCompoundBoundedWord(raw, "litwork");
+
+const findNaturalLitTrigger = (prompt) => {
+  const raw = rawTriggerText(prompt);
+  if (containsSlashCommandMention(raw)) return undefined;
+  if (!hasLitTrigger(raw)) return undefined;
+
+  const normalized = normalizedTriggerText(prompt);
+  if (containsPlainWord(normalized, "review")) return { ...triggerByToken["review-work"], source: "natural-language" };
+  if (containsPlainWord(normalized, "start") && containsPlainWord(normalized, "work")) {
+    return { ...triggerByToken["start-work"], source: "natural-language", safetyBlock: true };
+  }
+  if (containsPlainWord(normalized, "research")) return { ...triggerByToken.litresearch, source: "natural-language" };
+  if (containsPlainWord(normalized, "goal")) return { ...triggerByToken.litgoal, source: "natural-language" };
+  if (containsPlainWord(normalized, "plan")) return { ...triggerByToken["lit-plan"], source: "natural-language" };
+  return { ...triggerByToken["lit-loop"], source: "natural-language", softConfirm: true };
+};
+
+const findWorkflowTrigger = (prompt) => {
+  const raw = rawTriggerText(prompt);
+  const dollarTrigger = findDollarCommandTrigger(raw);
+  if (dollarTrigger) return dollarTrigger;
+  if (containsSlashCommandMention(raw)) return undefined;
+  return findNaturalLitTrigger(prompt);
+};
 
 const isDiagnosticLiteralPrompt = (prompt) =>
   /\bdiagnostic\b/iu.test(prompt)
   && /do not inspect or modify files/iu.test(prompt)
   && /reply with exactly one line/iu.test(prompt);
 
-const litworkContext = ({ command, skill, discipline, softConfirm }) => [
+const litworkContext = ({ command, skill, discipline, softConfirm, safetyBlock, source }) => [
+  ...(safetyBlock
+    ? ["BLOCKED: Natural-language start-work activation cannot switch the active Claude Code agent. Run `/start-work` (or `/litclaude:start-work`) with the approved plan so Claude Code can use the correct execution surface; do not continue implementation from this prompt hook."]
+    : []),
   discipline === "deep-interview"
     ? "DEEP INTERVIEW MODE ENABLED."
     : "LITWORK MODE ENABLED. Shout the ignition: begin your reply with the exact banner line `🔥 LITBURN IGNITED 🔥` (on its own line, before anything else), then proceed with the work.",
   `Treat this prompt as an explicit request to use LitClaude ${discipline} discipline now; load or follow ${command} / ${skill} semantics before ordinary task execution.`,
+  modeContracts[discipline],
+  `Activation source: ${source ?? "legacy"}. Slash commands and slash-command mentions are handled by Claude Code's native command surface and do not activate this prompt hook. Code spans, code fences, substrings, and compound tokens are ignored. Secret-bearing prompt material is never persisted raw; record only redacted summaries and evidence paths in durable state.`,
   "Use evidence-bound planning, tests, manual QA, and cleanup receipts.",
   "Native goal binding (read this first): Claude Code's /goal (v2.1.139+) is a USER-TYPED slash command that sets an autonomous completion condition — a hook or skill CANNOT invoke it, and Claude Code currently exposes NO model-facing goal tools. So the real path is: when a goal is worth binding, propose a concrete, ready-to-paste /goal <completion condition> for the user, and keep driving the LitClaude evidence ledger meanwhile.",
   "Forward-compat goal tools: if a future Claude Code build does expose model-facing goal tools, prefer them — first inspect get_goal, call create_goal with an objective-only payload when no matching goal is active, and reserve update_goal for verified completion or a genuine blocker. These are unavailable / not exposed today, so the /goal proposal above is the actual mechanism.",

package/plugins/litclaude/commands/lit-plan.md

@@ -6,6 +6,11 @@ argument-hint: '<planning brief>'
 Use the `lit-plan` skill for the user's current planning brief or command
 arguments.
 
+This command is planning-only. Do not implement, edit files for product
+changes, run mutating commands, or call start-work tooling from the planning
+surface. End with an approval gate and instruct the user to run `/start-work` or
+`/litclaude:start-work` after approval.
+
 The plan must include Claude Code-native bootstrap steps:
 
 - If model-facing goal tools are exposed, use `get_goal`, `create_goal`, and

package/plugins/litclaude/commands/litgoal.md

@@ -6,6 +6,10 @@ argument-hint: '<goal operation>'
 Use the `litgoal` skill for the user's current goal operation or command
 arguments.
 
+Shape the goal as one outcome-focused objective plus checkable criteria. Each
+criterion needs a scenario, a real surface, and observable evidence before it is
+complete.
+
 Prefer the package CLI for durable local state:
 `litclaude-ai litgoal create-goals`, `status`, `criteria`,
 `record-evidence`, `checkpoint`, `steer`, and `record-review-blockers`.

package/plugins/litclaude/commands/litresearch.md

@@ -6,6 +6,9 @@ argument-hint: '<research question>'
 Use the `litresearch` skill for the user's research demand or command arguments.
 Confirm the demand justifies saturation first: if a single read or one
 `WebSearch` would answer it, do that directly and do not fan out.
+Separate sourced evidence from hypotheses, verify contested claims before
+synthesis, and report residual uncertainty rather than collapsing unknowns into
+facts.
 
 Before fanning out, bootstrap Claude Code-native research state:
 

package/plugins/litclaude/commands/review-work.md

@@ -7,7 +7,7 @@ Use the `review-work` skill for the user's current scope or command arguments.
 
 Run the 5-lane review contract: goal and constraint verification
 (goal/constraint), hands-on QA execution, code quality review, security review,
-and local-first context mining.
+and docs/package/context readiness through local-first context mining.
 Aggregate findings into a PASS, FAIL, or NEEDS-CONTEXT verdict, and cite the
 evidence used for every lane.
 Manual-QA channels must leave artifacts, cleanup receipt paths, and bounded

package/plugins/litclaude/commands/start-work.md

@@ -6,6 +6,11 @@ argument-hint: '<plan-file>'
 Use the `start-work` skill for the user's current plan file or command
 arguments.
 
+This command is the Claude Code-native execution transition for an approved
+plan. If a user reached start-work through natural language (`lit start work`),
+do not pretend the hook switched modes; require this slash command or the
+namespaced `/litclaude:start-work` equivalent before execution.
+
 Before the first checkbox, bootstrap Claude Code-native workflow state:
 
 - Use `get_goal` and `create_goal` only if model-facing goal tools are exposed.

package/plugins/litclaude/skills/lit-loop/SKILL.md

@@ -21,6 +21,10 @@ success criteria before editing. Keep decisions, evidence, cleanup receipts,
 and remaining work in a durable notepad, plan, or ledger when the task spans
 multiple steps.
 
+This is a durable, evidence-driven execution loop. tests are necessary but not
+sufficient: every done claim needs the matching real Claude Code/package/user
+surface artifact, not just a green suite.
+
 ## Bootstrap
 
 Before implementation:

package/plugins/litclaude/skills/lit-plan/SKILL.md

@@ -9,6 +9,12 @@ You are a planner, not an implementer. Explore first, resolve discoverable
 facts, and write one execution-ready plan under `plans/`. The plan should let a
 fresh Claude Code session execute without re-solving the architecture.
 
+This skill is **planning-only**. You must not implement, must not edit files for
+product changes, and must not run mutating commands. Do not call any start-work
+tool from inside planning mode. Once the plan is approved, tell the
+user to run `/start-work` or `/litclaude:start-work` so Claude Code can use the
+proper execution surface.
+
 ## Planning Contract
 
 Every plan must include:

package/plugins/litclaude/skills/litgoal/SKILL.md

@@ -5,6 +5,10 @@ description: Durable LitClaude goal orchestration with CLI-backed state, explici
 
 # Litgoal
 
+Bind exactly one outcome-shaped objective at a time, then decompose it into
+checkable criteria. Each criterion needs a scenario, a real surface, and
+observable evidence before it can be marked complete.
+
 Use this skill when work must survive turns, compaction, interrupted sessions,
 or handoff to another agent. The core rule is strict: a goal is not complete
 until every success criterion has observable evidence from a real surface and a

package/plugins/litclaude/skills/litresearch/SKILL.md

@@ -5,6 +5,10 @@ description: "Maximum-saturation LitClaude research orchestrator for Claude Code
 
 # litresearch — maximum-saturation research orchestrator (Claude Code)
 
+Use sourced evidence only. Separate verified facts from hypotheses, cite the
+source or runtime surface for each material claim, and end with residual
+uncertainty instead of overstating conclusions.
+
 The LitClaude maximum-saturation research orchestrator, built only on Claude Code surfaces. Decompose a research demand, fan out parallel retrieval swarms, recursively chase every lead until convergence, verify contested claims by running code or adversarial review, and synthesize a fully cited answer — journaling every wave to disk so the work survives compaction. Every mechanism maps to a real Claude Code surface: the `Workflow` tool (Dynamic workflow), `Agent`/`Task` subagents namespaced `litclaude:`, `WebSearch`/`WebFetch`, the host `/deep-research` skill when the host exposes it, `TodoWrite` for the live lead tracker, and an on-disk `.litclaude/litresearch/<slug>/` session directory for the durable journal and cited synthesis.
 
 ## Role

package/plugins/litclaude/skills/programming/SKILL.md

@@ -16,7 +16,40 @@ writing a single line of code, then apply the shared philosophy on top.
 
 ---
 
-## PHASE 0 — LANGUAGE GATE (RUN THIS FIRST, EVERY TIME)
+## PHASE -1 — BUILD-DECISION GATE (RUN BEFORE PHASE 0)
+
+Before writing or editing a single line of implementation code, work down these
+checks and stop at the first one that cleanly meets the need:
+
+1. Does this need to exist at all? If the outcome does not require it, do not build it.
+2. Does the standard library already do it well? If so, use it.
+3. Is there a native platform, runtime, or framework feature for it? If so, use it.
+4. Does an already-installed dependency cover it cleanly? If so, reuse it — do not add or hand-roll.
+5. Can the remaining gap be one clear line? If so, write the one line.
+6. Only after all of the above fail: write the minimum code that genuinely works — nothing speculative.
+
+Scope and floor (these keep the gate from under-building):
+
+- Judge "minimum that works" over the WHOLE task, not per call site. If the same
+  logic appears at more than one call site, the minimum that works IS one small
+  shared helper — extract it.
+- "Works" includes error handling for any failure the code can realistically hit
+  (network, parse, missing file, bad state) and the tests that prove the behavior
+  you just wrote. Only handling for states that genuinely cannot occur is the
+  speculative part to cut.
+- Reach for a stdlib / native / dependency option only when it fits the need
+  cleanly, not merely because it technically can.
+- Never shorten away, for the sake of fewer lines: input validation at trust
+  boundaries, handling that prevents data loss or corruption, security controls
+  (auth, secret handling, injection/escaping), or accessibility. The point is to
+  remove redundancy and speculation, never to lower the correctness floor.
+
+PHASE -1 decides WHETHER and FROM WHAT to build; PHASE 0 and the per-language iron
+list decide HOW.
+
+---
+
+## PHASE 0 — LANGUAGE GATE (RUN AFTER PHASE -1, EVERY TIME)
 
 **Do not write or edit a single line of code before completing this gate.**
 
@@ -341,6 +374,10 @@ Answer these in your reply before declaring done:
 6. **Helpers for one-off?** Any abstraction with a single caller that will never
    get a second?
 7. **Tests?** Is the new behavior locked by a test that fails if you revert it?
+8. **Necessity & reuse?** Did everything you wrote need to exist, and did you
+   confirm the standard library, a native feature, or an already-installed
+   dependency did not already cover it before you hand-rolled? Remove anything
+   that fails this.
 
 If any answer fails, fix it before declaring done.
 

package/plugins/litclaude/skills/review-work/SKILL.md

@@ -16,6 +16,10 @@ only when they match the user's request and the repo's safety constraints. If
 they are unavailable, run the same lanes yourself with local tools and record
 the limits honestly.
 
+The five lanes are goal/constraints, real-surface QA, code quality, security,
+and docs/package/context readiness. A PASS verdict requires concrete evidence
+for every applicable lane; missing evidence is BLOCKED, not approval.
+
 ## Subagent Assignment Contract
 
 When review lanes run through child agents or Dynamic workflow lanes, send

package/plugins/litclaude/skills/rules/SKILL.md

@@ -32,10 +32,12 @@ guidance should be labeled and not silently treated as active truth.
 
 ## Trigger Discipline
 
-For LitClaude triggers, recognize `lit`, `litwork`, `$lit-plan`,
-`$lit-loop`, and `$start-work`. The hook may instruct Claude to load or follow
-the matching skill semantics. It should not pretend to run slash commands that
-belong to the UI.
+For LitClaude natural-language triggers, recognize `lit`, `litwork`, `lit
+plan`, `lit review`, `lit research`, `lit goal`, and `lit start work`, plus
+legacy `$lit-plan`, `$lit-loop`, and `$start-work` shorthands. Slash commands
+and slash-command mentions belong to Claude Code's native command surface and
+must not double-activate through the prompt hook. Code spans, code fences,
+substrings, and compound tokens are ignored.
 
 ## Priority
 

package/plugins/litclaude/skills/start-work/SKILL.md

@@ -9,6 +9,11 @@ Use this skill when the user asks to execute a plan file, especially
 `$start-work plans/<slug>.md`. The plan file and ledger are the source of truth,
 not memory.
 
+This skill is execution-only for an approved plan. If no approved plan is
+visible, stop with `BLOCKED:` and ask for the plan file or explicit approval.
+Do not redesign, rescope, or replace the plan unless fresh evidence proves a
+blocker, contradiction, or stale state.
+
 ## Bootstrap
 
 Before the first edit:

package/scripts/validate-plugin.mjs

@@ -22,12 +22,12 @@ async function main() {
   assert.equal(manifest.name, "litclaude");
   assert.equal(manifest.skills, "./skills");
   assert.deepEqual(manifest.agents, [
+    "./agents/prometheus-planner.md",
     "./agents/boulder-executor.md",
-    "./agents/librarian-researcher.md",
     "./agents/oracle-verifier.md",
-    "./agents/prometheus-planner.md",
     "./agents/qa-runner.md",
     "./agents/quality-reviewer.md",
+    "./agents/librarian-researcher.md",
   ]);
   assert.equal("hooks" in manifest, false);
   assert.equal(manifest.mcpServers, "./.mcp.json");