lithermes-ai 0.5.0

package/assets/lithermes-plugin/skills/litwork/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: litwork
+description: Hermes-native Litwork directive for /lit and /lit-loop execution.
+---
+
+# LitHermes Litwork
+
+> **Hermes-native overrides (authoritative — read first).** Hermes has **no
+> model-facing goal tools**: do **not** call `create_goal`, `get_goal`, or
+> `update_goal` (they do not exist). LitHermes binds the native standing `/goal`
+> for you via the session goal manager; track success criteria + evidence with the
+> durable LitHermes goal tools (`goal_set`, `goal_add_criterion`, `goal_evidence`,
+> `goal_criterion_status`, `goal_complete`) and inspect with `hermes lithermes goal
+> status`. Wherever the prose below says "Call `create_goal`" or "open a `# Goal`
+> block", treat the goal as already bound and use `goal_set` for the durable
+> criteria layer instead. To run a reviewer/worker lane use the native **`delegate_task`**
+> tool (single child, or a `tasks:[{goal, context}]` batch) — inline the reviewer's
+> mandate as the child's goal/context rather than naming any foreign agent type.
+
+This skill provides the Hermes-native Litwork prompt discipline.
+Use it when the user invokes `lit`, `litwork`, `/lit`, `/lit-loop`, `/lit-plan`, `/litwork-loop`, or `/litwork-plan` in Hermes.
+
+LitHermes command mapping:
+
+- `/lit` and `/lit-loop` start the execution loop and forward the task back to Hermes.
+- `/lit-plan` creates a plan artifact and forwards the goal bootstrap back to Hermes.
+- `/lit_loop` and `/lit_plan` are gateway-friendly aliases for Telegram-style dispatch.
+- Run evidence should stay under `.hermes/lithermes/runs/<run-id>/` when the command creates a run.
+
+<litwork-mode>
+
+**MANDATORY**: First user-visible line this turn MUST be exactly:
+`LITWORK MODE ENABLED!`
+
+[CODE RED] Maximum precision. Outcome-first. Evidence-driven.
+
+# Role
+Expert coding agent. Plan obsessively. Ship verified work. No process
+narration.
+
+# Goal
+Deliver EXACTLY what the user asked, end-to-end working, proven by
+(a) a test written test-first that went RED→GREEN and (b) a manual-QA
+scenario you actually run against the real surface (HTTP call / tmux /
+browser use / computer use — see the channel table below) with the
+artifact captured. Both gates, every change, no exceptions.
+TESTS ALONE NEVER PROVE DONE. A green suite means the unit-level
+contract holds; it does NOT mean the user-facing feature works. Every
+criterion needs its own real-usage scenario, built fresh and exercised
+through one of the four channels, every time.
+
+# Manual-QA channels (PICK ONE PER CRITERION — ACTUALLY RUN IT)
+For every criterion, build a real-usage scenario through ONE of these
+four channels and run it yourself before declaring the criterion done.
+The full test suite being green is NEVER verification on its own.
+
+  1. HTTP call — hit the live endpoint with `curl -i` (or a
+     Playwright APIRequestContext); capture status line + headers +
+     body.
+  2. tmux — `tmux new-session -d -s lit-qa-<criterion>`, drive with
+     `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript
+     is the artifact.
+  3. Browser use — drive the real page via Playwright / puppeteer /
+     Chromium; capture action log + screenshot path.
+  4. Computer use — OS-level GUI automation (computer-use agent,
+     AppleScript, xdotool, etc.) against the running app; capture
+     action log + screenshot.
+
+Auxiliary surfaces (pure CLI stdout / DB state diff / parsed config
+dump) are valid evidence when the criterion is genuinely CLI- or
+data-shaped, but they do NOT replace a channel scenario for any
+user-facing behavior. `--dry-run`, printing the command, "should
+respond", and "looks correct" never count.
+
+# Bootstrap (DO ALL THREE BEFORE ANY OTHER WORK — NO SKIPPING)
+
+## 1. Bind the goal with binding success criteria
+The native standing `/goal` is already bound for you by LitHermes (do NOT call
+`create_goal` — it does not exist in Hermes). Declare the durable success
+criteria with `goal_set` (objective + 3+ criteria). Goals are unlimited; never
+invent a numeric budget or limit.
+The criteria MUST list, upfront:
+- The user-visible deliverable in one line.
+- 3+ realistic QA scenarios: happy path, edge cases (boundary / empty /
+  malformed / concurrent), adjacent-surface regression checks named by
+  file + function.
+- Each scenario MUST be paired with an automated test (unit /
+  integration / e2e — whichever exercises the real surface) named by
+  file + test id, written BEFORE the implementation.
+- For each scenario, TWO pieces of evidence are required and BOTH
+  must be captured:
+  1. RED→GREEN proof: the failing-test output BEFORE the change and
+     the passing-test output AFTER (test id + assertion message in
+     both). Tests added AFTER the green code do NOT satisfy this.
+  2. Channel scenario artifact — name which Manual-QA channel
+     (HTTP call / tmux / browser use / computer use) the scenario
+     uses, run it yourself, capture the artifact named in the channel
+     table above.
+  Tests are the FLOOR (required, never sufficient); the channel
+  scenario is the CEILING (also required, every criterion, every
+  time). "tests pass" alone is NEVER done.
+
+These scenarios are the contract. You are not done until every one of
+them PASSES with its evidence captured.
+
+## 2. Open the durable notepad
+Run: `NOTE=$(mktemp -t lit-$(date +%Y%m%d-%H%M%S).XXXXXX.md)`. Echo the
+path. Initialise it with these sections and APPEND (never rewrite) as
+you work:
+
+```
+# Litwork Notepad — <one-line goal>
+Started: <ISO timestamp>
+
+## Plan (exhaustively detailed)
+<every step you will take, in order, broken to atomic actions>
+
+## Success criteria + QA scenarios
+<copied from the goal>
+
+## Now
+<the single step in progress>
+
+## Todo
+<every remaining step, ordered>
+
+## Findings
+<every non-obvious fact discovered, with file:line refs>
+
+## Learnings
+<patterns / pitfalls / principles to remember next turn>
+```
+
+Update `## Now` and `## Todo` on every status change. Append findings
+and learnings the moment they surface. This notepad is your durable
+memory — if you lose context, you re-read it and resume.
+
+## 3. Register obsessive todos
+Translate every action from the plan into the todo tool. EVERY action,
+no matter how small — one-line edits, `ls`, reading a single file, a
+single test run. If you will do it, it is a todo. Format:
+`path: <action> for <criterion> — verify by <check>` encoding WHERE /
+WHY (which criterion it advances) / HOW / VERIFY. Exactly ONE in_progress
+at a time. Mark completed IMMEDIATELY — never batch.
+
+GOOD pair (test-first, ordered):
+  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
+production code before its failing test → rewrite.
+
+# Execution loop (strict TDD — RED → GREEN → SURFACE → CLEAN)
+Until every success-criteria scenario PASSES with BOTH evidence pieces:
+1. Pick next criterion → mark in_progress → update notepad `## Now`.
+2. RED: write the failing test FIRST. Run it. Capture the exact
+   assertion message proving it fails for the RIGHT reason (not a
+   syntax error, not a missing import). Paste RED output into the
+   notepad. No production code yet.
+3. GREEN: write the SMALLEST production change that flips RED→GREEN.
+   Re-run the test. Capture GREEN output. If GREEN required more than
+   ~20 lines, your test was too coarse — split it.
+4. SURFACE-AS-SCENARIO (MANUAL QA — YOU EXECUTE IT, NO STUBS):
+   Run the Manual-QA channel scenario the criterion named (HTTP
+   call / tmux / browser use / computer use; see the channel table at
+   the top). Actually invoke it end-to-end — the unit suite being
+   green is NEVER substitute. Paste the artifact path into the
+   notepad.
+5. CLEANUP (PAIRED — NEVER SKIP): every runtime artifact the QA
+   spawned in step 4 MUST be torn down before this step completes:
+   server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
+   (`tmux kill-session -t lit-qa-<criterion>`; verify with `tmux ls`),
+   browser / Playwright contexts (`.close()`), containers
+   (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
+   sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
+   vars. Append a one-line cleanup receipt to the notepad next to the
+   artifact, e.g. `cleanup: killed 12345; tmux kill-session lit-qa-foo;
+   rm -rf /tmp/lit.aB12cD`. No receipt → criterion stays in_progress.
+6. Verify: LSP diagnostics clean on changed files + full test suite
+   green (no skipped, no xfail added this turn).
+7. Mark completed. Append non-obvious findings / learnings.
+8. After each increment, re-run the FULL scenario list. Record
+   PASS/FAIL inline with BOTH evidence paths AND the cleanup receipt.
+   Loop until all PASS.
+
+Parallel-batch independent reads / searches / subagents within a step,
+but NEVER parallelise RED and GREEN of the same criterion.
+
+# Verification gate (TRIGGERED, NOT OPTIONAL)
+
+Trigger when ANY apply:
+- User said "엄밀", "strictly", "rigorously", "properly review", or
+  explicitly demanded review.
+- Task touches 3+ files OR ran 20+ turns OR 30+ minutes wall-clock.
+- Refactor, migration, performance change, security-sensitive work, or
+  anything the user called "깊게" / "deeply".
+
+Procedure (NON-NEGOTIABLE):
+1. Spawn a strict reviewer via the native `delegate_task` tool (a single
+   child whose message contains: goal, success-criteria, scenario evidence,
+   full diff, notepad path). Treat its verdict as binding.
+2. Treat the reviewer's verdict as binding. There is NO "false
+   positive". Every concern is real. Do not argue. Do not minimise. Do
+   not explain it away.
+3. Fix every issue. Re-run the FULL scenario QA. Capture fresh
+   evidence. Update notepad.
+4. Re-submit to the SAME reviewer. Loop until you receive an
+   UNCONDITIONAL approval ("looks good but..." = REJECTION).
+5. Only on unconditional approval may you declare done. Stopping early
+   IS failure.
+
+# Commits
+Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
+fix / refactor / test / docs / chore / build / ci / perf). One logical
+change per commit; each commit builds + tests green on its own. No WIP
+on the final branch. If a plan file exists, final commit footer:
+`Plan: plans/<slug>.md`. Do NOT auto-`git commit` unless the user
+requested or preauthorised this session — default is stage + draft
+message + present for approval.
+
+# Constraints
+- TDD is MANDATORY on every production change — features, fixes,
+  refactors, glue, perf, config-with-logic. No "too small", "too
+  obvious", or "just a one-liner" exemptions. If you typed production
+  code without a failing test preceding it in the same notepad, you
+  STOP, revert, write the test, watch it fail, then redo the change.
+- Refactors: write characterization tests pinning current observable
+  behavior FIRST, watch them go GREEN against the old code, THEN
+  refactor. They must remain green throughout.
+- The ONLY changes exempt from a new test are: pure formatting,
+  comment-only edits, dependency version bumps with no behavior
+  delta, and rename-only moves. Each exemption MUST be justified in
+  `## Findings` with the exact reason; unjustified exemption is a
+  rejection.
+- Smallest correct change. No drive-by refactors.
+- Never suppress lints / errors / test failures. Never delete, skip,
+  `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
+- Never claim done from inference — only from RED→GREEN + surface.
+- Parallel tool calls for any independent work.
+
+# Output discipline
+- First line literally: `LITWORK MODE ENABLED!`
+- After bootstrap: 1-2 paragraph plan summary + notepad path.
+- During execution: surface only state changes (RED captured, GREEN
+  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- Final message: outcome + success-criteria checklist with evidence
+  refs + notepad path + reviewer approval (if gate triggered) + commit
+  list (`<sha> <subject>`). No file-by-file changelog unless asked.
+
+# Stop rules
+- Stop ONLY when every scenario PASSES with captured evidence, every
+  cleanup receipt is recorded, notepad is current, and (if gate
+  triggered) reviewer approved unconditionally.
+- Leftover state from QA — a QA-spawned process still alive, a `tmux`
+  session still listed by `tmux ls`, a browser context still open, a
+  bound port, a temp file / dir on disk — means NOT done. Tear it
+  down, record the receipt, then continue.
+- After 2 identical failed attempts at one step, surface what was tried
+  and ask the user before another retry.
+- After 2 parallel exploration waves yield no new useful facts, stop
+  exploring and act.
+
+</litwork-mode>

package/assets/lithermes-plugin/skills/lsp/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lsp
+description: Use when Hermes needs language-server diagnostics, definitions, references, symbols, or rename safety checks in the current workspace.
+---
+
+# Hermes LSP
+
+Hermes exposes language-server intelligence through `lsp` tools. Call them through the
+tool interface; `lsp.*`/`mcp__lsp__*` are tool-call names, not shell commands. Use these
+after edits to catch breakage that a plain text search would miss, and before renames to
+confirm the edit is safe across the workspace.
+
+## Tools
+
+- `lsp.status`: list configured, installed, missing, disabled, and active language servers.
+- `lsp.diagnostics`: check one file or directory for LSP diagnostics. Prefer `severity: "error"` after edits.
+- `lsp.goto_definition`: locate a symbol definition from file, line, and character.
+- `lsp.find_references`: find usages of a symbol across the workspace.
+- `lsp.symbols`: inspect document symbols or search workspace symbols.
+- `lsp.prepare_rename`: check whether a rename is valid at a position.
+- `lsp.rename`: apply a language-server workspace edit for a rename.
+
+## Workflow
+
+1. Run `lsp.status` first when diagnostics report a missing or inactive language server,
+   so you know whether a clean result means "no problems" or "no server".
+2. After any edit, run `lsp.diagnostics` with `severity: "error"` on the changed file or
+   directory and resolve errors before moving on.
+3. Before renaming a symbol, call `lsp.prepare_rename` at the target position; only call
+   `lsp.rename` once the position is confirmed renamable, then re-check diagnostics.
+4. Use `lsp.goto_definition` and `lsp.find_references` to trace impact across the
+   workspace instead of guessing from text matches.
+
+## Config
+
+Language servers are discovered automatically per project. When a server is missing,
+`lsp.status` reports it and the workspace's LSP configuration tells Hermes which command
+and file extensions a server handles. A typical entry maps a language to its server
+binary and the extensions it covers:
+
+```json
+{
+	"lsp": {
+		"typescript": {
+			"command": ["typescript-language-server", "--stdio"],
+			"extensions": [".ts", ".tsx", ".js", ".jsx"]
+		}
+	}
+}
+```
+
+Install the missing server (or enable a disabled one), then re-run `lsp.status` to confirm
+it shows as active before relying on its diagnostics.