litclaude-ai 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.3 - 2026-06-14 — port the init-deep skill
+
+- Add the `init-deep` skill (`plugins/litclaude/skills/init-deep/`), a Claude-adapted port of the
+  reference hierarchical AGENTS.md generator: discovery → score → generate → review, with dynamic
+  explore-subagent scaling, a weighted scoring matrix, AGENTS.md templates, and quality gates. All
+  reference orchestration/LSP calls are re-authored to Claude Code surfaces (`Agent`/`Task` background
+  subagents, the `LSP` tool, `Workflow` for parallel generation, `TodoWrite`) — no literal calls to
+  missing tools, no Codex/opencode tokens.
+- Add `plans/litclaude-reference-parity-sdd.md`: a decision-complete SDD plan capturing the full
+  OmO-reference parity audit (all 11 shared skills + both auxiliary packs are byte-identical) and the
+  remaining portable ports (`init-deep` done; `visual-qa` and `lsp-setup` planned), plus a verified
+  deliberate-omission (N/A) registry. Allowlisted as a non-shipped doc-class file.
+
+## 0.3.2 - 2026-06-14 — port the git-master skill
+
+- Add the `git-master` skill (`plugins/litclaude/skills/git-master/`), a Claude-adapted port of the
+  reference git-history specialist: mode-gated COMMIT / REBASE / HISTORY / STATUS workflows, atomic
+  commit grouping with local message-style detection, `--force-with-lease` rebase safety, and
+  `git log -S/-G` / `blame` / `bisect` / `reflog` history investigation. Aligned with LitClaude's
+  publish boundary — no commit/push/history rewrite without explicit user authorization.
+
 ## 0.3.1 - 2026-06-14 — neon-HUD truecolor detection on Windows Terminal / WSL2
 
 - Fix the `[🔥LITCLAUDE]` HUD falling back to flat 256-color magenta in Windows Terminal under WSL2.

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.1-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.3-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,10 +22,10 @@
 > `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.1` for personal install
+This checkout is prepared as `litclaude-ai@0.3.3` 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.1
+Future package releases still require explicit user approval. The v0.3.3
 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.
@@ -93,7 +93,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.1 install
+npx --yes litclaude-ai@0.3.3 install
 ```
 
 Validate the installed plugin:
@@ -106,7 +106,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.1] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.3] | 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

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.1-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.3-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,11 +26,11 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.1` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.3` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.1 release material은 v0.2.2 Dynamic workflow
+승인 후에 진행합니다. v0.3.3 release material은 v0.2.2 Dynamic workflow
 hardening을 보존하고, lit-family vocab rename과 neon HUD를 추가하며,
 LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
 주장하지 않습니다.
@@ -98,7 +98,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.1 install
+npx --yes litclaude-ai@0.3.3 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +111,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.1] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.3] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.

package/RELEASE_CHECKLIST.md

@@ -1,9 +1,9 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.1` is the current release candidate — a patch that fixes neon-HUD truecolor
-detection on Windows Terminal / WSL2 (and other 24-bit terminals that do not export `COLORTERM`).
-`package.json` is aligned to `0.3.1`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.1`.
+Status: `litclaude-ai@0.3.3` is the current release candidate — ports the reference `init-deep` skill
+(Claude-adapted hierarchical AGENTS.md generator) and lands the reference-parity SDD plan.
+`package.json` is aligned to `0.3.3`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.3`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -52,8 +52,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.1`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.1`.
+- `package.json` version is `0.3.3`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.3`.
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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.1",
+  "version": "0.3.3",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/skills/git-master/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: git-master
+description: "MUST USE whenever a task needs a commit or git-history investigation. Covers atomic commits, staging, commit-message style, rebase, squash, fixup/autosquash, blame, bisect, reflog, git log -S/-G, and questions like who wrote this or when was this added. Do not use for ordinary code edits unless the user asks for git work."
+---
+
+# Git Master
+
+The LitClaude git-history specialist for Claude Code. Use this skill when the user
+asks you to operate on Git history or answer a Git-history question. Be exact,
+conservative, and evidence-led. Read the repository state before you infer anything.
+
+## LitClaude publish boundary
+
+Commit, push, force-push, and history rewrites are outward-facing or hard-to-reverse
+operations. Per LitClaude discipline, do **not** commit, push, force-push, reset,
+stash-pop, or rewrite history unless the user explicitly authorized that exact
+operation. Investigative requests report findings and stop.
+
+## Mode Gate
+
+Classify the request first:
+
+- `COMMIT`: stage and commit local changes.
+- `REBASE`: rebase, squash, fixup, autosquash, reorder, split, or otherwise rewrite branch history.
+- `HISTORY`: answer when, where, who, why, or which commit changed something.
+- `STATUS`: inspect branch, diff, or working-tree state without changing it.
+
+If the request is only investigative, report findings and stop.
+
+## Ground Truth
+
+Gather independent facts first (these are read-only and safe to run in parallel):
+
+```bash
+git status --short
+git diff --stat
+git diff --staged --stat
+git branch --show-current
+git log -30 --oneline
+git rev-parse --abbrev-ref @{upstream}
+git merge-base HEAD origin/main
+git merge-base HEAD origin/master
+```
+
+Missing upstream or missing `main`/`master` is normal. Fall back to the best
+available branch or report the missing fact. Never treat a failed lookup as proof.
+
+## Commit Mode
+
+Commit only the user's requested changes. Preserve unrelated dirty work.
+
+1. Detect message style from recent history (`git log -30 --pretty=format:%s`). Use the
+   dominant local pattern, language, and casing. Do not default to Conventional
+   Commits unless the repo already uses them.
+2. Inspect the full diff, not only filenames. Separate unrelated user edits from the
+   requested commit.
+3. Build atomic groups by behavior, module, and revertability. Keep implementation and
+   its direct tests together.
+4. Prefer multiple commits for unrelated concerns. A single commit is acceptable only
+   when the changed files form one indivisible behavior or the user explicitly asks for one.
+5. Stage by path or hunk so each commit contains only its atomic group.
+6. Before each commit, verify `git diff --staged --stat` and enough staged diff to prove
+   the group is right.
+7. Commit with the detected style. After each commit, verify `git log -1 --oneline`.
+
+Grouping rules:
+
+- Split different features, modules, generated artifacts, config, docs, and test-only
+  changes unless they are inseparable.
+- Keep generated files with the source change that produced them when omitting them
+  would leave the repo inconsistent.
+- Never hide failing or unrelated changes inside a broad commit.
+- Follow the user's git conventions (e.g. no AI/co-author attribution when the repo or
+  the user's rules forbid it).
+
+Final report: list commit hashes, messages, and any remaining uncommitted files.
+
+## Rebase Mode
+
+History rewriting is a shared-impact operation.
+
+- Never rebase or rewrite `main`, `master`, `dev`, release branches, or a protected
+  branch unless the user explicitly named that exact operation.
+- If commits may already be pushed, ask before force-pushing. Use `--force-with-lease`,
+  never plain `--force`.
+- If the worktree is dirty, preserve it intentionally before rebasing. Do not stash-pop
+  over conflicts without checking what changed.
+- For fixups, prefer `git commit --fixup=<hash>` then
+  `GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <base>`.
+- For conflicts, read the conflicting files and resolve by intent. Do not choose
+  ours/theirs blindly.
+- If a rebase goes wrong, run `git rebase --abort` first. Use reflog only after
+  explaining the recovery path.
+
+After rewriting, run the relevant tests or at least the project's cheapest smoke check,
+then show the new branch log from base to HEAD.
+
+## History Mode
+
+Choose the Git tool by the question:
+
+- `git log -S "text"`: when the count of an exact string changed.
+- `git log -G "regex"`: when diffs touched lines matching a pattern.
+- `git blame -L start,end -- file`: who last changed specific lines.
+- `git log --follow -- file`: history across renames for one file.
+- `git show <hash>`: inspect the commit that appears relevant.
+- `git bisect`: find the first bad commit when there is a deterministic pass/fail
+  command and known good/bad bounds.
+- `git reflog`: recover or explain recent local history movement.
+
+Always cite the exact command evidence in the answer: commit hash, subject, file path,
+and line or diff context when relevant. If the evidence is ambiguous, say what remains
+unproven.
+
+## Safety Checks
+
+Before any write to Git history:
+
+- Current branch is known.
+- Dirty work is accounted for.
+- Upstream/pushed status is known or explicitly unknown.
+- The operation matches an explicit user request and authorization.
+- Recovery path is known (`rebase --abort`, reflog hash, or untouched worktree).
+
+Before finishing:
+
+- Run the most relevant verification available for the changed behavior or history
+  operation (Manual QA evidence where a behavior changed).
+- Report commands that passed and any command you could not run.
+- Leave the worktree state explicit.

package/plugins/litclaude/skills/init-deep/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: init-deep
+description: "Initialize a hierarchical AGENTS.md knowledge base for a repository — a root AGENTS.md plus complexity-scored subdirectory files. Use when the user wants to bootstrap or refresh project knowledge for Claude Code, onboard a codebase, generate AGENTS.md/CLAUDE.md guidance, or map an unfamiliar repo. Adapted for the Claude Code host: discovery via background explore subagents + the LSP tool, parallel generation via Dynamic workflow."
+---
+
+# Init-Deep — hierarchical AGENTS.md generator (Claude Code)
+
+Generate hierarchical `AGENTS.md` files: a root knowledge base plus complexity-scored subdirectory
+files. This is the LitClaude onboarding/knowledge-base skill, re-authored for Claude Code surfaces
+(`Agent`/`Task` subagents, the `LSP` tool, `Workflow` for parallel generation, `TodoWrite`).
+
+## Usage
+
+```
+init-deep                 # Update mode: modify existing AGENTS.md + create new where warranted
+init-deep --create-new    # Read existing → remove all → regenerate from scratch
+init-deep --max-depth=2   # Limit directory depth (default: 3)
+```
+
+## Workflow (high level)
+
+1. **Discovery + analysis** (concurrent) — background explore subagents + local bash structure + LSP
+   codemap + read existing AGENTS.md.
+2. **Score & decide** — determine AGENTS.md locations from merged findings.
+3. **Generate** — root first, then subdirectories in parallel.
+4. **Review** — deduplicate, trim, validate.
+
+Track all four phases with `TodoWrite` and flip each `pending → in_progress → completed` in real time.
+
+## Phase 1 — Discovery + analysis (concurrent)
+
+Mark "discovery" in_progress.
+
+### Fire background explore subagents immediately
+
+Spawn read-only explore subagents with the `Agent` tool (`subagent_type: "explore"`,
+`run_in_background: true`) so they run while the main session works. Claude notifies you when each
+finishes; collect their final messages before scoring. Launch independent agents in one message so
+they run concurrently. Suggested lanes (one agent each):
+
+- **Structure** — predict standard patterns for the detected language; report deviations only.
+- **Entry points** — find main/entry files; report non-standard organization.
+- **Conventions** — find config files (`.eslintrc`, `pyproject.toml`, `.editorconfig`, …); report
+  project-specific rules.
+- **Anti-patterns** — find `DO NOT` / `NEVER` / `ALWAYS` / `DEPRECATED` markers; list forbidden patterns.
+- **Build/CI** — find `.github/workflows`, `Makefile`, `Taskfile`; report non-standard patterns.
+- **Tests** — find test configs and structure; report unique conventions.
+
+**Dynamic subagent scaling** — after the bash pass below, spawn ADDITIONAL explore agents based on
+project scale (never a static count):
+
+| Factor | Threshold | Additional agents |
+|--------|-----------|-------------------|
+| Total files | >100 | +1 per 100 files |
+| Total lines | >10k | +1 per 10k lines |
+| Directory depth | ≥4 | +2 for deep exploration |
+| Large files (>500 lines) | >10 files | +1 for complexity hotspots |
+| Monorepo | detected | +1 per package/workspace |
+| Multiple languages | >1 | +1 per language |
+
+```bash
+total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
+total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {c++} END {print c+0}')
+max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)
+```
+
+For very broad repos, run the discovery fan-out as a Dynamic workflow (call the `Workflow` tool when
+Claude Code exposes it) instead of many manual `Agent` calls.
+
+### Main session: concurrent local analysis
+
+While background agents run, the main session does:
+
+**1. Bash structural analysis**
+```bash
+# Directory depth distribution
+find . -type d -not -path '*/.*' -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+# Files per directory (top 30)
+find . -type f -not -path '*/.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+# Existing knowledge bases
+find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null
+```
+
+**2. Read existing AGENTS.md** — for each file found, `Read` it and extract key insights,
+conventions, and anti-patterns into an EXISTING map. With `--create-new`, read ALL existing files
+first (preserve context), THEN delete, THEN regenerate.
+
+**3. LSP codemap (if available)** — use the Claude `LSP` tool: list configured servers, then request
+document symbols for entry points and workspace symbols for `class` / `interface` / `function`, and
+references for the top exports to gauge centrality. If no server is configured, fall back to the
+explore subagents + plain search.
+
+Merge bash + LSP + existing + explore findings. Mark "discovery" completed.
+
+## Phase 2 — Scoring & location decision
+
+Mark "scoring" in_progress.
+
+### Scoring matrix
+
+| Factor | Weight | High threshold | Source |
+|--------|--------|----------------|--------|
+| File count | 3× | >20 | bash |
+| Subdir count | 2× | >5 | bash |
+| Code ratio | 2× | >70% | bash |
+| Unique patterns | 1× | has own config | explore |
+| Module boundary | 2× | has `index.ts`/`__init__.py` | bash |
+| Symbol density | 2× | >30 symbols | LSP |
+| Export count | 2× | >10 exports | LSP |
+| Reference centrality | 3× | >20 refs | LSP |
+
+### Decision rules
+
+| Score | Action |
+|-------|--------|
+| Root (`.`) | ALWAYS create |
+| >15 | Create AGENTS.md |
+| 8–15 | Create if it is a distinct domain |
+| <8 | Skip (parent covers it) |
+
+Mark "scoring" completed.
+
+## Phase 3 — Generate AGENTS.md
+
+Mark "generate" in_progress.
+
+**File-writing rule:** if `AGENTS.md` already exists at the target path, use `Edit`; if not, use
+`Write`. NEVER `Write` over an existing file — check existence first (via the discovery results or a
+`Read`).
+
+### Root AGENTS.md (full treatment)
+
+```markdown
+# PROJECT KNOWLEDGE BASE
+**Generated:** {TIMESTAMP}  **Commit:** {SHORT_SHA}  **Branch:** {BRANCH}
+
+## OVERVIEW
+{1–2 sentences: what + core stack}
+
+## STRUCTURE
+{tree with non-obvious purposes only}
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+
+## CODE MAP
+{from LSP — skip if unavailable or project <10 files}
+
+## CONVENTIONS
+{ONLY deviations from standard}
+
+## ANTI-PATTERNS (THIS PROJECT)
+{explicitly forbidden here}
+
+## COMMANDS
+{dev / test / build}
+
+## NOTES
+{gotchas}
+```
+
+Quality gate: 50–150 lines, no generic advice, no obvious info.
+
+### Subdirectory AGENTS.md (parallel)
+
+Generate each non-root location in parallel — spawn one writing subagent per location with the `Agent`
+tool, or run them as a Dynamic workflow. Each child gets a `TASK:` line plus `DELIVERABLE` (the
+AGENTS.md), `SCOPE` (this directory only), and `VERIFY` (30–80 lines, never repeats parent content;
+sections: OVERVIEW 1 line, STRUCTURE if >5 subdirs, WHERE TO LOOK, CONVENTIONS if different,
+ANTI-PATTERNS). Wait for all. Mark "generate" completed.
+
+## Phase 4 — Review & deduplicate
+
+Mark "review" in_progress. For each generated file: remove generic advice, remove parent duplicates,
+trim to the size limits, verify telegraphic style. Mark "review" completed.
+
+## Final report
+
+```
+=== init-deep complete ===
+Mode: {update | create-new}
+Files: [OK] ./AGENTS.md (root, {N} lines) · [OK] ./src/hooks/AGENTS.md ({N} lines)
+Dirs analyzed: {N} · Created: {N} · Updated: {N}
+Hierarchy: ./AGENTS.md └── src/hooks/AGENTS.md
+```
+
+## Anti-patterns
+
+- **Static agent count** — vary explore subagents by project size/depth (see the scaling table).
+- **Sequential execution** — run explore + LSP concurrently; generate subdirectories in parallel.
+- **Ignoring existing** — ALWAYS read existing AGENTS.md first, even with `--create-new`.
+- **Over-documenting** — not every directory needs an AGENTS.md.
+- **Redundancy** — a child file never repeats its parent.
+- **Generic content** — remove anything that applies to all projects.
+- **Verbose style** — telegraphic or die.