lithermes-ai 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wjgoarxiv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+<p align="center"><img src="./cover.png" width="100%" /></p>
+
+<h1 align="center">LitHermes</h1>
+
+<p align="center">
+  Install evidence-first Litwork commands into Hermes Agent with one <code>npx</code> or <code>bunx</code> command.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/lithermes-ai"><img src="https://img.shields.io/npm/v/lithermes-ai?color=14b8a6" alt="npm version" /></a>
+  <a href="https://github.com/wjgoarxiv/lithermes"><img src="https://img.shields.io/badge/GitHub-lithermes-111827" alt="GitHub repository" /></a>
+  <img src="https://img.shields.io/badge/Hermes-Agent-6366f1" alt="Hermes Agent" />
+  <img src="https://img.shields.io/badge/license-MIT-0f766e" alt="MIT license" />
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#what-you-get">What You Get</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#verify">Verify</a> ·
+  <a href="#telegram-gateway">Telegram Gateway</a> ·
+  <a href="./README_Ko-KR.md">한국어</a>
+</p>
+
+> This is the npm package source for LitHermes. It installs the Hermes plugin that provides `/lit`, `/lit-loop`, `/lit-plan`, and gateway-friendly aliases.
+
+## Quick Start
+
+Run a doctor check first:
+
+```sh
+npx lithermes-ai doctor
+bunx lithermes-ai doctor
+```
+
+Install the plugin:
+
+```sh
+npx lithermes-ai install --yes
+```
+
+Restart any running Hermes CLI or Hermes gateway process. Then open Hermes and try:
+
+```text
+/lit 이 폴더에 뭐가 있는지 정리해줘
+/lit-plan lithermes를 더 안전하게 배포하는 플랜 세워줘
+```
+
+## What You Get
+
+- `/lit`: start an Litwork loop immediately.
+- `/lit-loop`: explicit alias for the same execution loop.
+- `/lit-plan`: create a durable implementation plan.
+- `/litwork-loop` and `/litwork-plan`: longer aliases.
+- `/lit_loop` and `/lit_plan`: gateway-friendly aliases for Telegram dispatch.
+- Native `/goal` binding: Hermes has no model-facing goal tools, so `/lit`, `/lit-loop`, and `/lit-plan` bind the native standing `/goal` via the session goal manager (persists across turns; native evidence-judge decides completion). Criteria + evidence use the durable `goal_*` tools.
+- 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`, `frontend-ui-ux`, `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` /
+  `on_session_start` hooks, every skill, and the durable goal tooling — ships in
+  the bundle exactly as installed, so each release is reproducible and auditable.
+
+## Requirements
+
+- Hermes Agent already installed on the machine.
+- Node.js 18 or newer for `npx`.
+- Bun if you want to use `bunx`.
+- Write access to the Hermes home directory, normally `~/.hermes`.
+
+The default install target is:
+
+```text
+~/.hermes/plugins/lithermes
+~/.hermes/config.yaml
+```
+
+Use `--hermes-home PATH` if your Hermes home is somewhere else.
+
+## Install
+
+Preview changes without writing anything:
+
+```sh
+npx lithermes-ai install --dry-run
+```
+
+Install with npm:
+
+```sh
+npx lithermes-ai install --yes
+```
+
+Install with Bun:
+
+```sh
+bunx lithermes-ai install --yes
+```
+
+Install into a custom Hermes home:
+
+```sh
+npx lithermes-ai install --yes --hermes-home /path/to/.hermes
+```
+
+LitHermes refuses to mutate Hermes config unless you pass `--yes`. If `~/.hermes/plugins/lithermes` already exists but was not created by this installer, installation stops instead of overwriting user files.
+
+## Verify
+
+Check the package and Hermes compatibility:
+
+```sh
+npx lithermes-ai doctor
+bunx lithermes-ai doctor
+```
+
+Check an installed plugin:
+
+```sh
+npx lithermes-ai check --offline
+```
+
+Expected successful output includes:
+
+```text
+LitHermes check PASS
+commands: lit, lit-loop, lit-plan
+```
+
+For gateway compatibility checks:
+
+```sh
+npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent
+```
+
+Expected successful output includes:
+
+```text
+gateway /lit_loop PASS
+gateway /lit_plan PASS
+```
+
+## Hermes Goal Tools
+
+Hermes exposes no model-facing goal tools. LitHermes binds the native standing `/goal` for you through the session goal manager when you start an Litwork run, so it persists across turns and the native evidence-judge decides completion. Success criteria and evidence are tracked with the durable `goal_*` tools and `hermes lithermes goal status`.
+
+That means a recent Hermes Agent can continue the same LitHermes work across turns instead of stopping after the command creates a run directory or plan file.
+
+## Telegram Gateway
+
+LitHermes does not contact Telegram during install. It only installs the Hermes plugin and checks whether the local Hermes gateway source supports plugin command dispatch.
+
+After installing:
+
+1. Restart the Hermes gateway process.
+2. In Telegram, send `/lit_loop your task`.
+3. For planning-only work, send `/lit_plan your task`.
+
+If Telegram does not recognize the command, run:
+
+```sh
+npx lithermes-ai doctor --hermes-repo /path/to/hermes-agent
+```
+
+If `cli payload dispatch`, `tui payload dispatch`, or `gateway underscore dispatch` is not `PASS`, update Hermes or use the patch fallback below.
+
+## Patch Fallback
+
+When LitHermes can find `~/.hermes/hermes-agent`, `install --yes` attempts known compatibility patches automatically and writes backups first. Use the explicit form when Hermes lives elsewhere, or add `--no-patch-installed-hermes` if you only want to copy the plugin.
+
+```sh
+npx lithermes-ai install --yes --patch-installed-hermes --hermes-repo /path/to/hermes-agent
+```
+
+The patch path writes `.lithermes.bak` backups and a rollback manifest under the Hermes home.
+
+Rollback patches:
+
+```sh
+npx lithermes-ai uninstall --yes --rollback-patches
+```
+
+## Uninstall
+
+Remove only manifest-owned LitHermes files and remove the config entry:
+
+```sh
+npx lithermes-ai uninstall --yes
+```
+
+Uninstall intentionally preserves unrelated files in `~/.hermes/plugins`.
+
+## Troubleshooting
+
+### `Hermes installation not found`
+
+Pass the Hermes home explicitly:
+
+```sh
+npx lithermes-ai doctor --hermes-home /path/to/.hermes
+```
+
+### Commands do not appear inside Hermes
+
+Restart Hermes. Plugin discovery is loaded by the running process, so an already-open CLI or gateway may not see a newly installed plugin.
+
+Then check:
+
+```sh
+npx lithermes-ai check --offline
+```
+
+### Telegram `/lit_loop` does not respond
+
+Run:
+
+```sh
+npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent
+```
+
+If the gateway check fails, update Hermes or use the explicit patch fallback.
+
+### Bun local tarball testing
+
+Current Bun versions may not execute a local tarball directly with `bunx ./file.tgz`. For local release testing, install the tarball into a temp project and run the binary:
+
+```sh
+bun init -y
+bun add ./lithermes-*.tgz
+bunx --no-install lithermes doctor
+```
+
+## Release Checklist
+
+```sh
+npm test
+npm pack --dry-run --json
+npm publish --access public
+npx --yes lithermes@latest doctor
+```
+
+Security note: `npx` and `bunx` execute package code. Use `doctor` and `--dry-run` first when installing on a sensitive Hermes host.

package/README_Ko-KR.md

@@ -0,0 +1,245 @@
+<p align="center"><img src="./cover.png" width="100%" /></p>
+
+<h1 align="center">LitHermes</h1>
+
+<p align="center">
+  Hermes Agent에 evidence-first Litwork 명령을 설치하는 <code>npx</code>/<code>bunx</code> 패키지입니다.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/lithermes-ai"><img src="https://img.shields.io/npm/v/lithermes-ai?color=14b8a6" alt="npm version" /></a>
+  <a href="https://github.com/wjgoarxiv/lithermes"><img src="https://img.shields.io/badge/GitHub-lithermes-111827" alt="GitHub repository" /></a>
+  <img src="https://img.shields.io/badge/Hermes-Agent-6366f1" alt="Hermes Agent" />
+  <img src="https://img.shields.io/badge/license-MIT-0f766e" alt="MIT license" />
+</p>
+
+<p align="center">
+  <a href="#빠른-시작">빠른 시작</a> ·
+  <a href="#무엇이-설치되나요">무엇이 설치되나요</a> ·
+  <a href="#설치">설치</a> ·
+  <a href="#확인">확인</a> ·
+  <a href="#텔레그램-게이트웨이">텔레그램 게이트웨이</a> ·
+  <a href="./README.md">English</a>
+</p>
+
+> 이 문서는 LitHermes npm package 사용 설명서입니다. 설치 후 Hermes에서 `/lit`, `/lit-loop`, `/lit-plan`을 사용할 수 있고, Hermes gateway에서는 `/lit_loop`, `/lit_plan` alias도 사용할 수 있습니다.
+
+## 빠른 시작
+
+먼저 현재 Hermes 환경이 LitHermes를 받을 수 있는지 확인합니다.
+
+```sh
+npx lithermes-ai doctor
+bunx lithermes-ai doctor
+```
+
+설치합니다.
+
+```sh
+npx lithermes-ai install --yes
+```
+
+실행 중인 Hermes CLI 또는 Hermes gateway를 재시작합니다. 그 다음 Hermes에서 이렇게 사용합니다.
+
+```text
+/lit 이 폴더에 뭐가 있는지 정리해줘
+/lit-plan lithermes를 더 안전하게 배포하는 플랜 세워줘
+```
+
+## 무엇이 설치되나요
+
+- `/lit`: Litwork loop를 바로 시작합니다.
+- `/lit-loop`: 같은 실행 loop를 명시적으로 호출합니다.
+- `/lit-plan`: 구현 계획을 먼저 세웁니다.
+- `/litwork-loop`, `/litwork-plan`: 긴 이름의 alias입니다.
+- `/lit_loop`, `/lit_plan`: Telegram dispatch에 맞춘 gateway alias입니다.
+- 네이티브 `/goal` 바인딩: Hermes에는 model-facing goal tool이 없으므로 `/lit`, `/lit-loop`, `/lit-plan`은 세션 goal manager를 통해 네이티브 standing `/goal`을 대신 설정합니다(턴을 넘어 유지되고 네이티브 evidence-judge가 완료를 판정). success criteria와 증거는 durable `goal_*` 도구로 추적합니다.
+- 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`, `frontend-ui-ux`, `lsp`, `programming`, `refactor`,
+  `remove-ai-slops`, `review-work`, `rules`, `start-work`, `lit-plan`,
+  `litgoal`, `litwork`가 `lithermes:*` skill로 함께 설치됩니다.
+- 전체 plugin payload — `pre_llm_call` / `subagent_stop` / `on_session_start`
+  hook, 모든 skill, durable goal tooling — 이 설치 상태 그대로 번들에 들어가므로,
+  각 릴리스는 재현 가능하고 감사할 수 있습니다.
+
+## 요구 사항
+
+- Hermes Agent가 이미 설치되어 있어야 합니다.
+- `npx` 사용 시 Node.js 18 이상이 필요합니다.
+- `bunx` 사용 시 Bun이 필요합니다.
+- 보통 `~/.hermes`인 Hermes home에 쓸 수 있어야 합니다.
+
+기본 설치 위치는 다음과 같습니다.
+
+```text
+~/.hermes/plugins/lithermes
+~/.hermes/config.yaml
+```
+
+Hermes home이 다른 위치라면 `--hermes-home PATH`를 사용하세요.
+
+## 설치
+
+실제로 쓰기 전에 변경될 내용을 미리 봅니다.
+
+```sh
+npx lithermes-ai install --dry-run
+```
+
+npm으로 설치합니다.
+
+```sh
+npx lithermes-ai install --yes
+```
+
+Bun으로 설치합니다.
+
+```sh
+bunx lithermes-ai install --yes
+```
+
+Hermes home을 직접 지정합니다.
+
+```sh
+npx lithermes-ai install --yes --hermes-home /path/to/.hermes
+```
+
+LitHermes는 `--yes`가 없으면 Hermes config를 수정하지 않습니다. 또한 `~/.hermes/plugins/lithermes`가 이미 있는데 이 installer가 만든 파일이 아니면, 사용자 파일을 덮어쓰지 않고 멈춥니다.
+
+## 확인
+
+패키지와 Hermes 호환성을 확인합니다.
+
+```sh
+npx lithermes-ai doctor
+bunx lithermes-ai doctor
+```
+
+설치된 plugin을 확인합니다.
+
+```sh
+npx lithermes-ai check --offline
+```
+
+성공하면 다음과 비슷하게 보입니다.
+
+```text
+LitHermes check PASS
+commands: lit, lit-loop, lit-plan
+```
+
+gateway 호환성까지 확인하려면:
+
+```sh
+npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent
+```
+
+성공하면 다음 문구가 포함됩니다.
+
+```text
+gateway /lit_loop PASS
+gateway /lit_plan PASS
+```
+
+## Hermes Goal Tools
+
+Hermes는 model-facing goal tool을 제공하지 않습니다. LitHermes는 Litwork run을 시작할 때 세션 goal manager를 통해 네이티브 standing `/goal`을 대신 설정하며, 이는 턴을 넘어 유지되고 네이티브 evidence-judge가 완료를 판정합니다. success criteria와 증거는 durable `goal_*` 도구와 `hermes lithermes goal status`로 추적합니다.
+
+따라서 최신 Hermes Agent에서는 command가 run directory나 plan file만 만들고 멈추지 않고, 같은 LitHermes 작업을 여러 turn에 걸쳐 이어갈 수 있습니다.
+
+## 텔레그램 게이트웨이
+
+LitHermes 설치 과정은 Telegram에 접속하지 않습니다. 로컬 Hermes plugin을 설치하고, Hermes gateway 소스가 plugin command dispatch를 지원하는지만 확인합니다.
+
+설치 후:
+
+1. Hermes gateway 프로세스를 재시작합니다.
+2. Telegram에서 `/lit_loop 할 일`을 보냅니다.
+3. 계획만 세우고 싶다면 `/lit_plan 할 일`을 보냅니다.
+
+Telegram에서 명령이 동작하지 않으면 다음을 실행하세요.
+
+```sh
+npx lithermes-ai doctor --hermes-repo /path/to/hermes-agent
+```
+
+`cli payload dispatch`, `tui payload dispatch`, `gateway underscore dispatch` 중 하나라도 `PASS`가 아니라면 Hermes를 업데이트하거나 아래 patch fallback을 사용하세요.
+
+## Patch Fallback
+
+LitHermes가 `~/.hermes/hermes-agent`를 찾을 수 있으면 `install --yes` 과정에서 알려진 호환성 patch를 자동으로 시도하고 먼저 백업을 남깁니다. Hermes checkout이 다른 위치에 있으면 아래처럼 명시적으로 지정하세요. plugin만 복사하고 싶다면 `--no-patch-installed-hermes`를 붙이면 됩니다.
+
+```sh
+npx lithermes-ai install --yes --patch-installed-hermes --hermes-repo /path/to/hermes-agent
+```
+
+patch fallback은 `.lithermes.bak` 백업과 Hermes home 아래 rollback manifest를 남깁니다.
+
+patch를 되돌리려면:
+
+```sh
+npx lithermes-ai uninstall --yes --rollback-patches
+```
+
+## 삭제
+
+installer manifest가 소유한 LitHermes 파일만 제거하고 config entry를 지웁니다.
+
+```sh
+npx lithermes-ai uninstall --yes
+```
+
+`~/.hermes/plugins` 안의 관련 없는 파일은 보존됩니다.
+
+## 문제 해결
+
+### `Hermes installation not found`
+
+Hermes home을 직접 지정하세요.
+
+```sh
+npx lithermes-ai doctor --hermes-home /path/to/.hermes
+```
+
+### Hermes 안에서 명령이 보이지 않음
+
+Hermes를 재시작하세요. 이미 실행 중인 CLI나 gateway는 새로 설치된 plugin을 바로 보지 못할 수 있습니다.
+
+그 다음 확인합니다.
+
+```sh
+npx lithermes-ai check --offline
+```
+
+### Telegram `/lit_loop`가 반응하지 않음
+
+다음을 실행하세요.
+
+```sh
+npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent
+```
+
+gateway check가 실패하면 Hermes를 업데이트하거나 명시적 patch fallback을 사용하세요.
+
+### Bun local tarball 테스트
+
+현재 Bun 버전에서는 `bunx ./file.tgz`처럼 local tarball을 바로 실행하는 방식이 일관되게 동작하지 않을 수 있습니다. 로컬 release smoke는 temp project에 tarball을 설치한 뒤 binary를 실행하세요.
+
+```sh
+bun init -y
+bun add ./lithermes-*.tgz
+bunx --no-install lithermes doctor
+```
+
+## Release Checklist
+
+```sh
+npm test
+npm pack --dry-run --json
+npm publish --access public
+npx --yes lithermes@latest doctor
+```
+
+보안 메모: `npx`와 `bunx`는 package code를 실행합니다. 민감한 Hermes host에 설치할 때는 먼저 `doctor`와 `--dry-run`을 사용하세요.

package/assets/lithermes-plugin/NOTICE.md

@@ -0,0 +1,37 @@
+# Notice
+
+This plugin is a Hermes-native adaptation of the bundled workflow reference:
+
+- Repository: bundled workflow reference
+- Reference commit inspected for this port:
+  `3fb8802e314dc0a1f23481dd3782cdca26b92dc2`
+
+The runtime implementation here is not a vendored upstream runtime. LitHermes
+re-implements command dispatch against Hermes' plugin, hook, skill, and LSP
+surfaces.
+
+The bundled skill markdown is adapted from MIT-licensed workflow guidance, with
+Hermes-specific command mapping for `/lit`,
+`/lit-loop`, `/lit-plan`, `/lit_loop`, and `/lit_plan`.
+
+## MIT License Notice
+
+Copyright (c) 2026 Yeongyu Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/lithermes-plugin/README.md

@@ -0,0 +1,40 @@
+# lithermes
+
+Hermes-native workflow tools for plan-first execution, evidence ledgers, and
+first-class Hermes skills:
+
+- `/lit-plan` and `/litwork-plan` create durable plans in `plans/`, then forward a
+  goal bootstrap to the Hermes agent instead of stopping at plan creation.
+- `/lit-loop` and `/litwork-loop` create run state under
+  `.hermes/lithermes/runs/` and dispatch the task back to the Hermes agent.
+- `/start-work` opens or dry-runs a plan against a workspace.
+- The `pre_llm_call` hook injects an Litwork directive when the user says
+  `lit` or `litwork`. Hermes has no model-facing goal tools, so a direct
+  `lit <task>` (and the /lit command) binds the native standing `/goal` via the
+  session goal manager; criteria + evidence use the durable `goal_*` tools.
+- Explicit skills are available as:
+  `lithermes:ai-slop-remover`, `lithermes:comment-checker`,
+  `lithermes:debugging`, `lithermes:frontend-ui-ux`, `lithermes:lsp`,
+  `lithermes:programming`, `lithermes:refactor`,
+  `lithermes:remove-ai-slops`, `lithermes:review-work`,
+  `lithermes:rules`, `lithermes:start-work`, `lithermes:lit-plan`,
+  `lithermes:litgoal`, and `lithermes:litwork`.
+- Delegation fans lanes out through the native `delegate_task` tool (children
+  run in parallel, the parent blocks for all); there is no named-agent registry
+  and no per-child model selection.
+
+Enable with:
+
+```yaml
+plugins:
+  enabled:
+    - lithermes
+```
+
+## Reference
+
+The bundled workflow reference is adapted for LitHermes command names and
+Hermes gateway behavior. LitHermes runs entirely on Hermes-native primitives
+(`delegate_task`, the durable `goal_*` tools, and the `pre_llm_call` /
+`subagent_stop` / `on_session_start` hooks) and ships no external
+prompt-runtime installer in the plugin payload.