lithermes-ai 0.6.0 → 0.8.1

package/README.md

@@ -57,7 +57,8 @@ Restart any running Hermes CLI or Hermes gateway process. Then open Hermes and t
 - Interactive install spinner keeps terminal installs lively while redirected or scripted installs stay plain; use `npx lithermes-ai install --yes --no-spinner` for quiet terminal installs.
 - `start-work`: open or dry-run a LitHermes plan inside Hermes.
 - LitHermes workflow skill set: `ai-slop-remover`, `comment-checker`,
-  `debugging`, `deep-interview`, `frontend-ui-ux`, `lsp`, `programming`, `refactor`,
+  `debugging`, `deep-interview`, `frontend-ui-ux`, `git-master`, `init-deep`,
+  `lsp`, `programming`, `refactor`,
   `remove-ai-slops`, `review-work`, `rules`, `start-work`, `lit-plan`,
   `litgoal`, and `litwork` are installed as `lithermes:*` skills.
 - The full plugin payload — the `pre_llm_call` / `subagent_stop` hooks, every

package/README_Ko-KR.md

@@ -57,7 +57,8 @@ npx lithermes-ai install --yes
 - interactive install spinner가 terminal 설치는 더 생동감 있게 보여주고, redirect/script 설치는 기존처럼 plain output을 유지합니다. 조용한 terminal 설치가 필요하면 `npx lithermes-ai install --yes --no-spinner`를 사용합니다.
 - `start-work`: LitHermes plan을 Hermes 작업으로 엽니다.
 - LitHermes workflow skill set: `ai-slop-remover`, `comment-checker`,
-  `debugging`, `deep-interview`, `frontend-ui-ux`, `lsp`, `programming`, `refactor`,
+  `debugging`, `deep-interview`, `frontend-ui-ux`, `git-master`, `init-deep`,
+  `lsp`, `programming`, `refactor`,
   `remove-ai-slops`, `review-work`, `rules`, `start-work`, `lit-plan`,
   `litgoal`, `litwork`가 `lithermes:*` skill로 함께 설치됩니다.
 - 전체 plugin payload — `pre_llm_call` / `subagent_stop`

package/assets/lithermes-plugin/README.md

@@ -15,7 +15,8 @@ first-class Hermes skills:
 - Explicit skills are available as:
   `lithermes:ai-slop-remover`, `lithermes:comment-checker`,
   `lithermes:debugging`, `lithermes:deep-interview`,
-  `lithermes:frontend-ui-ux`, `lithermes:lsp`,
+  `lithermes:frontend-ui-ux`, `lithermes:git-master`,
+  `lithermes:init-deep`, `lithermes:lsp`,
   `lithermes:programming`, `lithermes:refactor`,
   `lithermes:remove-ai-slops`, `lithermes:review-work`,
   `lithermes:rules`, `lithermes:start-work`, `lithermes:lit-plan`,

package/assets/lithermes-plugin/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import functools
 from pathlib import Path
 from typing import Any
 
@@ -30,6 +31,14 @@ PORTED_SKILLS = [
         "frontend-ui-ux",
         "Apply the LitHermes frontend UI/UX review discipline.",
     ),
+    (
+        "git-master",
+        "Run the LitHermes git-history specialist for commits, rebases, blame, and bisect.",
+    ),
+    (
+        "init-deep",
+        "Generate a hierarchical AGENTS.md knowledge base with the LitHermes onboarding workflow.",
+    ),
     (
         "lsp",
         "Use Hermes' native LSP diagnostics with LitHermes LSP guidance.",
@@ -107,6 +116,16 @@ def _handle_lithermes_cli(args) -> int:
     return 1
 
 
+def _ignited(handler):
+    """Wrap a slash-command handler so its display prints the LITBURN banner."""
+
+    @functools.wraps(handler)
+    def wrapped(user_args):
+        return core.ignite(handler(user_args))
+
+    return wrapped
+
+
 def register(ctx) -> None:
     base = Path(__file__).resolve().parent
 
@@ -114,6 +133,9 @@ def register(ctx) -> None:
     ctx.register_hook("pre_llm_call", _pre_llm_call)
     # Record each delegate_task child (review lanes, reviewer gate) to the ledger.
     ctx.register_hook("subagent_stop", core.subagent_stop)
+    # Force the LITBURN banner onto a bare-`lit` keyword turn's response (that
+    # path has no deterministic display channel; slash commands print it directly).
+    ctx.register_hook("transform_llm_output", core.transform_llm_output)
 
     # Model-facing litgoal tools (durable criteria/evidence/checkpoint/steering/gate).
     litgoal_tools.register_tools(ctx)
@@ -128,55 +150,55 @@ def register(ctx) -> None:
 
     ctx.register_command(
         "lit-plan",
-        core.command_lit_plan,
+        _ignited(core.command_lit_plan),
         description="Create a durable Litwork implementation plan",
         args_hint='"what to build"',
     )
     ctx.register_command(
         "litwork-plan",
-        core.command_lit_plan,
+        _ignited(core.command_lit_plan),
         description="Alias for /lit-plan",
         args_hint='"what to build"',
     )
     ctx.register_command(
         "lit",
-        core.command_lit,
+        _ignited(core.command_lit),
         description="Start an Litwork run and execute the task immediately",
         args_hint='"task" [--completion-promise TEXT] [--strategy reset|continue]',
     )
     ctx.register_command(
         "lit-loop",
-        core.command_lit_loop,
+        _ignited(core.command_lit_loop),
         description="Start an Litwork run and execute the task immediately",
         args_hint='"task" [--completion-promise TEXT] [--strategy reset|continue]',
     )
     ctx.register_command(
         "litwork-loop",
-        core.command_lit_loop,
+        _ignited(core.command_lit_loop),
         description="Alias for /lit-loop",
         args_hint='"task" [--completion-promise TEXT] [--strategy reset|continue]',
     )
     ctx.register_command(
         "litgoal",
-        core.command_litgoal,
+        _ignited(core.command_litgoal),
         description="Open or inspect the LitHermes litgoal durable runtime",
         args_hint='["objective"] [--worktree PATH]',
     )
     ctx.register_command(
         "review-work",
-        core.command_review_work,
+        _ignited(core.command_review_work),
         description="Run the LitHermes 5-lane review orchestrator on the current diff",
         args_hint="[--base REF]",
     )
     ctx.register_command(
         "start-work",
-        core.command_start_work,
+        _ignited(core.command_start_work),
         description="Open or dry-run a LitHermes plan against a workspace",
         args_hint="[plan-name] [--worktree PATH] [--dry-run]",
     )
     ctx.register_command(
         "deep-interview",
-        core.command_deep_interview,
+        _ignited(core.command_deep_interview),
         description="Run the LitHermes Socratic clarity gate before planning/execution",
         args_hint="[--quick|--standard|--deep] <idea>",
     )

package/assets/lithermes-plugin/core.py

@@ -33,9 +33,22 @@ DIRECT_LIT_PATTERN = re.compile(r"^\s*(?:lit|litwork)\b\s+(?P<task>.+?)\s*$", re
 MAX_TASK_LEN = 4000
 _SLUG_PATTERN = re.compile(r"[^a-z0-9]+")
 
+# Deterministic ignite banner. Printed verbatim on every LitHermes slash-command
+# display (the only user-visible plugin channel); also instructed into LIT_CONTEXT
+# for the bare-`lit` keyword path (best-effort — that path only reaches the model).
+LITBURN_BANNER = "🔥 LITBURN IGNITED 🔥"
+
+# Session ids whose CURRENT turn triggered the litwork keyword path. The bare
+# `lit` keyword has no deterministic display channel (pre_llm_call only reaches
+# the model), so pre_llm_call flags the turn here and transform_llm_output forces
+# the banner onto that turn's response before the user sees it. Consumed once.
+_PENDING_IGNITE: set[str] = set()
+
+
 LIT_CONTEXT = "\n".join(
     [
         "<lithermes-litwork>",
+        f"FIRST, open your reply with this exact line so the user sees Litwork engage: {LITBURN_BANNER}",
         "The user invoked Litwork/LitHermes. Operate in a durable, evidence-first loop:",
         "- restate the concrete completion promise before changing files;",
         "- keep the implementation scoped to the current repository and existing Hermes patterns;",
@@ -210,9 +223,57 @@ def _extract_run_context_task(message: str) -> str:
     return _clamp_task(m.group("task")) if m else ""
 
 
+# Slash-command handlers are dispatched as handler(user_args) with NO session_id,
+# so they cannot bind the native /goal themselves. They instead embed this marker
+# in their agent_message; pre_llm_call (which DOES receive session_id) reads it and
+# performs the bind. /lit & /lit-loop bind via the run-context block; /litgoal &
+# /lit-plan declare an objective and bind via this marker.
+_BIND_GOAL_PATTERN = re.compile(
+    r"<lithermes-bind-goal>(?P<obj>.+?)</lithermes-bind-goal>", re.DOTALL
+)
+
+
+def _extract_bind_goal(message: str) -> str:
+    m = _BIND_GOAL_PATTERN.search(message)
+    return _clamp_task(m.group("obj")) if m else ""
+
+
+def bind_goal_marker(objective: str) -> str:
+    """Render the bind-goal marker a command embeds so pre_llm_call binds /goal."""
+    objective = (objective or "").strip()
+    return f"<lithermes-bind-goal>{objective}</lithermes-bind-goal>" if objective else ""
+
+
+def ignite(result: str | dict[str, str]) -> str | dict[str, str]:
+    """Prepend the LITBURN banner to a command result's user-visible display.
+
+    ``display`` is the one channel Hermes prints to the user verbatim
+    (cli.py _cprint), so the banner deterministically fires on every LitHermes
+    slash command. agent_message (model-facing) is left untouched.
+    """
+    if isinstance(result, dict):
+        display = result.get("display")
+        if display and not str(display).startswith(LITBURN_BANNER):
+            return {**result, "display": f"{LITBURN_BANNER}\n{display}"}
+        return result
+    if isinstance(result, str) and result.strip() and not result.startswith(LITBURN_BANNER):
+        return f"{LITBURN_BANNER}\n{result}"
+    return result
+
+
 def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
     user_message = str(kwargs.get("user_message") or "")
     session_id = str(kwargs.get("session_id") or "")
+    # Clear any stale ignite flag from an interrupted previous turn so it can't
+    # leak the banner onto this turn's response. Re-added below only if THIS turn
+    # is a keyword-lit turn — keeping the flag scoped to the current turn.
+    _PENDING_IGNITE.discard(session_id)
+    # /litgoal & /lit-plan declare an objective via the bind-goal marker. Bind it
+    # (we have session_id here) and stop — those messages are self-contained.
+    bind_obj = _extract_bind_goal(user_message)
+    if bind_obj:
+        bind_native_goal(session_id, bind_obj)
+        return None
     # The /lit command injects a run-context message. Bind the native goal from
     # it (we have session_id here), then skip re-injecting context.
     if "<lithermes-run-context>" in user_message:
@@ -240,9 +301,31 @@ def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
         session_id=session_id,
         platform=str(kwargs.get("platform") or ""),
     )
+    # Flag this turn so transform_llm_output forces the banner onto the response
+    # (the keyword path has no deterministic display channel like slash commands).
+    if session_id:
+        _PENDING_IGNITE.add(session_id)
     return {"context": LIT_CONTEXT + run_context}
 
 
+def transform_llm_output(**kwargs: Any) -> str | None:
+    """Force the LITBURN banner onto a keyword-`lit` turn's response.
+
+    Hermes replaces the user-visible response with the first non-empty string a
+    transform_llm_output hook returns. Returning None leaves the text unchanged.
+    We only act on turns pre_llm_call flagged, consume the flag once, and dedup so
+    a model that already opened with the banner is not double-bannered.
+    """
+    session_id = str(kwargs.get("session_id") or "")
+    if session_id not in _PENDING_IGNITE:
+        return None
+    _PENDING_IGNITE.discard(session_id)
+    response_text = str(kwargs.get("response_text") or "")
+    if response_text.lstrip().startswith(LITBURN_BANNER):
+        return None  # model already emitted it — leave unchanged
+    return f"{LITBURN_BANNER}\n\n{response_text}"
+
+
 def subagent_stop(**kwargs: Any) -> None:
     """Record each delegate_task child (e.g. a review lane) to the LitHermes ledger.
 
@@ -629,6 +712,7 @@ def build_plan_agent_message(brief: str, plan: Path, workspace: Path) -> str:
             "goal tools (goal_set / goal_add_criterion / goal_evidence / goal_complete) and inspect",
             "with `hermes lithermes goal status`.",
             "</lithermes-plan-context>",
+            bind_goal_marker(brief),
         ]
     )
 
@@ -799,6 +883,12 @@ def command_litgoal(raw_args: str) -> dict[str, str]:
         "Load the lithermes:litgoal skill for the full discipline.",
         "</lithermes-litgoal-command>",
     ]
+    # When an objective is given, bind the native /goal too (pre_llm_call reads
+    # this marker — slash handlers have no session_id). Inspect-only /litgoal
+    # (no objective) leaves any active goal untouched.
+    marker = bind_goal_marker(objective)
+    if marker:
+        agent_lines.append(marker)
     return {
         "display": f"{intro}\nState dir: {lithermes_dir(workspace) / 'litgoal'}",
         "agent_message": "\n".join(agent_lines),

package/assets/lithermes-plugin/payload-version.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-06-14T02:25:40.475Z",
+  "syncedAt": "2026-06-14T05:53:21.695Z",
   "source": "source-reference",
-  "sourceHash": "09f07fa73866ccb4c0a7dc271d4d1ce45a9ac662ff911fab6f4a6d6e7db73c07",
+  "sourceHash": "f07cf5a5062f904d4eed678ebf24314e773ca3f92e5c2d1f95c981437e0c5a5a",
   "files": [
     {
       "path": "NOTICE.md",
@@ -9,15 +9,15 @@
     },
     {
       "path": "README.md",
-      "sha256": "32bbef20afd99f774502c2b4cbf2e2326d40c4e4cd71108645849dddcc2608c4"
+      "sha256": "e0bc7d60f61a8d35df9f6287876e236e59e80e871261558701375a12cc4e4feb"
     },
     {
       "path": "__init__.py",
-      "sha256": "e545ac92efb1a8d50c467b21b180eb41dad5e9a19379a8cbe5086956c21c3654"
+      "sha256": "9a0b19060eb12799bf76b15b729fcbab4388d74aac9e888b40369b809fd54669"
     },
     {
       "path": "core.py",
-      "sha256": "c8cac49c17e573dabc59c4d5aa56402a71320f62145fabf9552e7fdb648f340a"
+      "sha256": "6b9d8b488d5905232d170f78943d2b5f9b9a4bde564e01a816c4fcc45098a7df"
     },
     {
       "path": "litgoal/__init__.py",
@@ -49,7 +49,7 @@
     },
     {
       "path": "plugin.yaml",
-      "sha256": "e90d47b24dc2cb5340d9485929ba40e62b2b5d6858951992c414701f015286fe"
+      "sha256": "e8ab5e17a3812c1caf91d98e2fb3cf72f2c7d4a429723f0887b6eb3abd736648"
     },
     {
       "path": "skills/ai-slop-remover/SKILL.md",
@@ -143,6 +143,14 @@
       "path": "skills/frontend-ui-ux/SKILL.md",
       "sha256": "914667044f135563658ceac733a085a6bbdd71a00a5f4030f73d43444e0388f7"
     },
+    {
+      "path": "skills/git-master/SKILL.md",
+      "sha256": "31d59a91767423094fd84ed668c8b8c7e14d515cd17e3845d91a0ce4aa0144c8"
+    },
+    {
+      "path": "skills/init-deep/SKILL.md",
+      "sha256": "f571334ad9150fd93ef57fcc9dd85d240812649975811e63045ff2a72e84260b"
+    },
     {
       "path": "skills/lit-plan/SKILL.md",
       "sha256": "1f09901f9bb8f19b92add59c3613231228c8b5b7adbefae1cb3eb5cf7c3c61dc"

package/assets/lithermes-plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: lithermes
-version: 0.6.0
+version: 0.8.1
 description: "Hermes-native workflow toolkit: litgoal durable runtime, 5-lane review orchestrator, Litwork commands, skills, and prompt steering."
 author: "Hermes Agent"
 kind: standalone
@@ -7,3 +7,4 @@ auto_load: true
 hooks:
   - pre_llm_call
   - subagent_stop
+  - transform_llm_output

package/assets/lithermes-plugin/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 LitHermes git-history specialist for Hermes. 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.
+
+## LitHermes publish boundary
+
+Commit, push, force-push, and history rewrites are outward-facing or hard-to-reverse
+operations. Per LitHermes 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/assets/lithermes-plugin/skills/init-deep/SKILL.md

@@ -0,0 +1,198 @@
+---
+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 Hermes, onboard a codebase, generate AGENTS.md guidance (reading any existing CLAUDE.md for context), or map an unfamiliar repo. Adapted for Hermes: discovery and parallel generation via delegate_task children + Hermes lsp tools."
+---
+
+# Init-Deep — hierarchical AGENTS.md generator (Hermes)
+
+Generate hierarchical `AGENTS.md` files: a root knowledge base plus complexity-scored subdirectory
+files. This is the LitHermes onboarding/knowledge-base skill, re-authored for Hermes surfaces:
+read-only `delegate_task` children for discovery, Hermes' `lsp` tools for the code map, and parallel
+`delegate_task` fan-out for generation. (`AGENTS.md` is the file Hermes loads natively as project
+context — see the `lithermes:rules` skill.)
+
+## 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) — read-only `delegate_task` children + local bash structure +
+   `lsp` code map + 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 explicitly and report each one `pending → in_progress → completed` as you go
+(Hermes has no TodoWrite tool; keep the running state in your reply or a working note).
+
+## Phase 1 — Discovery + analysis (concurrent)
+
+Mark "discovery" in_progress.
+
+### Fan out read-only discovery children immediately
+
+Dispatch the discovery lanes as read-only `delegate_task` children — pass a `tasks` array so they run
+concurrently and the parent blocks until all return. Each child is self-contained (goal + scope +
+"read-only, return findings only"). Suggested lanes (one child 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 scaling** — after the bash pass below, add MORE `delegate_task` children based on project
+scale (never a static count):
+
+| Factor | Threshold | Additional children |
+|--------|-----------|---------------------|
+| 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, split the fan-out across several `delegate_task` batches rather than one giant
+batch, but keep every child read-only.
+
+### Main session: concurrent local analysis
+
+While the discovery children 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 code map (if available)** — use Hermes' `lsp` tools: `lsp.status` to list configured servers,
+then `lsp.symbols` for entry-point/workspace symbols (`class` / `interface` / `function`) and
+`lsp.find_references` on the top exports to gauge centrality. If no server is configured, fall back to
+the discovery children + plain search. (See the `lithermes:lsp` skill.)
+
+Merge bash + LSP + existing + child 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 | child |
+| 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, edit it in place; if not,
+create it. NEVER overwrite 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 — dispatch one writing `delegate_task` child per location
+(batch them in one `delegate_task` call). 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 child count** — vary discovery `delegate_task` children by project size/depth (see the scaling table).
+- **Sequential execution** — run discovery children + 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lithermes-ai",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "description": "npx/bunx installer for the LitHermes Hermes plugin",
   "license": "MIT",
   "repository": {