feat(hermes): mvp-coverage — 9 skills converted to Hermes format

- mapping.yaml: 7 pending → auto (setup-tasks, using-tasks, setup-wiki, using-wiki, using-projects-meta, using-context7, project-bootstrap, recommend-dont-menu). pending count now 0. - dist-hermes/ populated: software-development: project-bootstrap (+ assets) productivity: recommend-dont-menu, setup-tasks, using-tasks research: setup-wiki, using-wiki mcp: using-context7, using-projects-meta - active-platform replace-rule verified: Windows+PowerShell → Linux+bash in body SKILL.md (frontmatter description unchanged by design). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 09:21:56 +03:00
parent 27026c5e0e
commit 82f82a2036
19 changed files with 2738 additions and 48 deletions
--- a/dist-hermes/research/using-wiki/README.md
+++ b/dist-hermes/research/using-wiki/README.md
@@ -0,0 +1,179 @@
+# using-wiki
+
+Runtime policy for an LLM Wiki built on the
+[Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
+Knowledge is **compiled once and kept current** across three layers, via
+three named operations, with strict file formats that keep the wiki
+parseable and grep-friendly.
+
+`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
+migration to canon are owned by [`setup-wiki`](../setup-wiki/).
+
+> Renamed from `wiki-maintainer` at v1.0.0.
+
+## When it triggers
+
+- User says: "use project wiki", "query the wiki", "ingest this", or the
+  Russian equivalents ("обнови вики", "проверь вики", "запроси вики",
+  "заингесть").
+- Any time the agent modifies a file under `.wiki/` — the workflow and
+  formats below are mandatory.
+- If `.wiki/` is missing or non-canonical, this skill delegates to
+  [`setup-wiki`](../setup-wiki/) before doing anything else.
+
+## Three layers (do not blur)
+
+1. **Raw sources** — `.wiki/raw/` (or external paths registered in
+   `raw/README.md`). **Immutable.** Read, never edit. The only exception is
+   appending a `> Status` blockquote when the user explicitly asks for a
+   status audit.
+2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept /
+   package / source summary pages.
+3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what
+   entities, what packages, naming). Always read it first; it overrides this
+   skill on conflict.
+
+## Three operations
+
+### Ingest
+
+«заингесть X» — pull a raw source into the wiki.
+
+1. Read the raw source fully.
+2. Extract: entities, concepts, packages, cross-cutting patterns.
+3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
+4. For each affected entity / concept / package page: update if exists,
+   create if not. Flag contradictions explicitly with
+   `> **Противоречие:** источник A говорит X, источник B — Y`.
+   **Never silently overwrite.**
+5. Update `index.md`.
+6. Append one line to `log.md`.
+7. Report: what was created, updated, contradicted.
+
+One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.
+
+### Query
+
+A question answered from the wiki.
+
+1. Read `index.md` first, drill into relevant pages.
+2. Answer with citations as markdown links.
+3. **Compound the wiki.** If the answer is a real synthesis, ask the user:
+   "Сохранить как страницу wiki?" Good queries become durable pages under
+   `concepts/` or `analyses/`.
+4. Append one line to `log.md`.
+
+### Lint
+
+«проверь wiki» — health check.
+
+Scan for:
+
+- Contradictions between pages.
+- Orphans (pages with no inbound links).
+- Stale claims (raw source updated after the summary's `ingested:` date —
+  check via `git log -p`).
+- Concepts mentioned in prose but missing their own page.
+- Empty / TODO sections.
+
+Report as a punch list. Don't delete anything automatically. Append one
+line to `log.md` with the findings.
+
+## File formats (mandatory)
+
+### Page frontmatter
+
+```yaml
+---
+title: Человекочитаемое имя
+type: entity | concept | package | source | overview
+tags: [short, tokens]
+sources: [../sources/foo.md, ../sources/bar.md]
+updated: 2026-04-21
+---
+```
+
+Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
+
+### File naming
+
+- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in
+  filenames; keep the original title in H1 + frontmatter.
+- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md`
+  (no `@org/` prefix), `sources/<slug>.md`.
+
+### `log.md` — append-only, grep-parseable
+
+Every entry must start with:
+
+```
+## [YYYY-MM-DD] <operation> | <short description>
+```
+
+Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
+
+Parse with: `grep "^## \[" .wiki/log.md | tail -20`.
+
+### `index.md`
+
+Catalog, not narrative. One line per page: `- [Title](path) — hook.`
+Sections by type. Update on every ingest.
+
+### Cross-references
+
+- Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`.
+- Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`.
+- Wiki → raw: `../raw/<file>`.
+- URL-encode spaces (`%20`) and Cyrillic when needed.
+
+## Quick reference
+
+| Situation | Files touched |
+|---|---|
+| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
+| Query | (read only) + optionally a new wiki page + `log.md` |
+| Lint | (read only) + `log.md` |
+| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) |
+
+## Common mistakes
+
+- **Editing `raw/`.** Don't. Only allowed change: status blockquote on
+  explicit request.
+- **Dumping raw content into `sources/`.** Summaries are summaries. Link to
+  raw, don't copy.
+- **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**`
+  block.
+- **Narrative `log.md`.** "Today I added…" is wrong. Use
+  `## [YYYY-MM-DD] ingest | <what>`.
+- **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate.
+- **Forgetting `index.md`.** Pages not listed there are invisible to future
+  queries.
+- **Improvising layout when canon files are missing.** Hand off to
+  [`setup-wiki`](../setup-wiki/) instead of patching ad-hoc.
+
+## When NOT to use
+
+- The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular
+  documentation, not an LLM Wiki.
+- The user wants a single-file README or ADR — this skill is for persistent,
+  interlinked knowledge bases.
+- One-off questions about code — read files directly, no wiki workflow needed.
+
+## Install
+
+From the repo root:
+
+```bash
+bash scripts/install.sh using-wiki
+```
+
+Works on Windows under git-bash, Linux, macOS.
+
+## See also
+
+- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
+  canon migration.
+- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
+  new projects.
+- Karpathy's LLM Wiki gist:
+  <https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
--- a/dist-hermes/research/using-wiki/SKILL.md
+++ b/dist-hermes/research/using-wiki/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: using-wiki
+version: 1.0.0
+description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0.
+---
+
+# using-wiki
+
+> Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`.
+
+## Prerequisites
+
+This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the four content directories `entities/`, `concepts/`, `packages/`, `sources/`.
+
+If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below.
+
+## Three layers (do not blur)
+
+1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit.
+2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages.
+3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first if present; it overrides this skill when it conflicts.
+
+## First step on every operation
+
+1. Read `.wiki/CLAUDE.md` if it exists.
+2. Read `.wiki/index.md` to locate relevant pages.
+3. Only then act.
+
+If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising.
+
+## Three operations
+
+### Ingest — «заингесть X»
+
+1. Read the raw source fully.
+2. Extract: entities, concepts, packages, cross-cutting patterns.
+3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
+4. For each affected entity/concept/package page:
+   - If it exists → update it. **Flag contradictions explicitly** with `> **Противоречие:** источник A говорит X, источник B — Y`. Don't silently overwrite.
+   - If not → create it.
+5. Update `index.md` — add or move entries.
+6. Append one line to `log.md` (format below).
+7. Report to the user: what created, what updated, what contradictions found.
+
+**One ingest may touch 10–15 pages. This is normal — that's why LLMs do it.**
+
+### Query — вопрос по wiki
+
+1. Read `index.md` first, then drill into relevant pages.
+2. Answer with citations as markdown links to wiki pages.
+3. **Compound the wiki.** If the answer is a real synthesis (comparison, analysis, new connection) — ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/`, `analyses/`, or similar.
+4. Append one line to `log.md`.
+
+### Lint — «проверь wiki»
+
+Scan for:
+- **Contradictions** between pages.
+- **Orphans** — pages with no inbound links.
+- **Stale claims** — git `log -p` on the raw source shows it was updated after the summary's `ingested:` date.
+- **Missing entities** — concepts mentioned in prose but without their own page.
+- **Empty/TODO sections.**
+
+Report as a punch list. Don't delete anything automatically.
+Append one line to `log.md` summarizing the findings.
+
+## File formats (MANDATORY)
+
+### Page frontmatter
+
+```yaml
+---
+title: Человекочитаемое имя
+type: entity | concept | package | source | overview
+tags: [short, tokens]
+sources: [../sources/foo.md, ../sources/bar.md]
+updated: 2026-04-21
+---
+```
+
+Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
+
+### File naming
+
+- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter.
+- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`.
+
+### `log.md` — append-only, grep-parseable
+
+Every entry **must** start with:
+
+```
+## [YYYY-MM-DD] <operation> | <short description>
+```
+
+Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
+
+Parseable with: `grep "^## \[" .wiki/log.md | tail -20`.
+
+### `index.md`
+
+Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources). Update on every ingest.
+
+### Cross-references
+
+- Wiki → wiki: relative markdown links, `[Name](../entities/x.md)`.
+- Wiki → code: relative path from repo root: `[foo.js](../../packages/api/foo.js)`.
+- Wiki → raw: `../raw/<file>`.
+- URL-encode spaces in paths (`%20`) and Cyrillic when needed.
+
+## Quick reference
+
+| Situation | Files touched |
+|---|---|
+| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
+| Query | (read only) + optionally new wiki page + `log.md` |
+| Lint | (read only) + `log.md` |
+| Bootstrap / migrate to canon | (delegated to `setup-wiki`) |
+
+## Common mistakes
+
+- **Editing `raw/`.** Don't. Only allowed: status blockquote when user explicitly asks.
+- **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy it.
+- **Silent overwrites.** When a new source contradicts an existing page, flag it with a `> **Противоречие:**` block; don't just overwrite.
+- **Narrative `log.md`.** `Today I added…` is wrong. Use `## [YYYY-MM-DD] ingest | <what>`.
+- **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate.
+- **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries.
+- **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus.
+- **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc.
+
+## When NOT to use this skill
+
+- Project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular project documentation, not an LLM Wiki.
+- User wants a single-file README or ADR — this skill is for persistent interlinked knowledge bases.
+- One-off questions about code — use regular file reading, not wiki workflow.