diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index 1edfac4..b601218 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -1,5 +1,5 @@ # Task Board -_Updated: 2026-05-07 (tdd-criteria skill-write + mapping + build-install shipped)_ +_Updated: 2026-05-07 (hermes-flavour-mcp-setups + hermes-installer-skill shipped; hermes-mvp-coverage unblocked)_ diff --git a/dist-hermes/SKIPPED.md b/dist-hermes/SKIPPED.md index 9780f13..c49f831 100644 --- a/dist-hermes/SKIPPED.md +++ b/dist-hermes/SKIPPED.md @@ -18,8 +18,6 @@ Do not edit by hand — edit the mapping and re-run the build. - **project-bootstrap** — Pending hermes-mvp-coverage. Orchestrator — adapts last; CLAUDE.md trigger-lines drop (Hermes auto-discovers). → intended: `mode: auto, category: software-development` - **recommend-dont-menu** — Added 2026-05-06 after the original audit. Cross-agent applicability claimed (response-style rule) — Hermes-side audit not yet done. → intended: `mode: auto, category: productivity` -- **setup-context7** — Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml. → intended: `mode: manual, category: mcp` -- **setup-projects-meta** — Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml plus pre-check + extraheader fallback. → intended: `mode: manual, category: mcp` - **setup-tasks** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: productivity` - **setup-wiki** — Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence. → intended: `mode: auto, category: research` - **using-context7** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: mcp` diff --git a/dist-hermes/mcp/setup-context7/SKILL.md b/dist-hermes/mcp/setup-context7/SKILL.md new file mode 100644 index 0000000..9df61b9 --- /dev/null +++ b/dist-hermes/mcp/setup-context7/SKILL.md @@ -0,0 +1,140 @@ +--- +name: setup-context7 +version: 1.0.0-hermes +description: Hermes-flavour context7 setup. Edits `~/.hermes/config.yaml` to register the official context7 MCP server via stdio (`npx @upstash/context7-mcp`). Requires `CONTEXT7_API_KEY` env var (user sets it manually or you prompt for it). Use when user says "install context7", "setup context7", or whenever `mcp__context7__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing. +--- + +# setup-context7 (Hermes) + +> One-time Hermes skill that registers context7 in `~/.hermes/config.yaml`. Context7 is a third-party MCP server (Upstash); this skill only adds the stdio command entry. + +## When to use + +- User explicitly asks: install / set up / configure context7 on Hermes. +- A `using-context7`-driven task fails because `mcp__context7__*` tools aren't available. + +## Out of scope + +- Creating API keys — user must have a Context7 API key (get it from https://context7.com or via `npx ctx7 setup`). +- Rolling back to manual config. +- Any non-context7 MCP server. + +## Hard rule: don't auto-mutate config + +Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).** + +## Procedure + +### Phase 0 — Environment sanity + +- Confirm Hermes is the current agent. +- Confirm `npx` is on `PATH` (stdio command uses it). + +### Phase 1 — Discovery (read-only) + +**API key.** Check env var `CONTEXT7_API_KEY`. If missing → report MISSING, will ask user. + +**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.context7`. Note if present. + +Report: +``` +API key: +MCP entry: +``` + +### Phase 2 — Plan + confirm + +Present the plan: +``` +API key: +MCP entry: +Config: ~/.hermes/config.yaml +Backup: ~/.hermes/config.yaml.bak- +``` + +If API key is missing → ask: "Set CONTEXT7_API_KEY env var, or paste your key and I'll add it to config.yaml via env." Wait for confirmation before proceeding. + +### Phase 3 — Backup + +```bash +TS=$(date +%Y%m%d-%H%M%S) +cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS +``` + +### Phase 4 — Edit `~/.hermes/config.yaml` + +Add or update the `mcp_servers` section: + +**Option A — user has CONTEXT7_API_KEY env var (recommended):** + +```yaml +mcp_servers: + context7: + command: npx + args: + - -y + - @upstash/context7-mcp + - --api-key + - $CONTEXT7_API_KEY + env: + CONTEXT7_API_KEY: $CONTEXT7_API_KEY +``` + +**Option B — user wants key embedded (not recommended, but acceptable if env var is hard):** + +```yaml +mcp_servers: + context7: + command: npx + args: + - -y + - @upstash/context7-mcp + - --api-key + - +``` + +Use Option A by default. Only Option B if user explicitly says "embed the key" or env vars don't work on their setup. + +Validate YAML: +```bash +python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))" +``` + +If validation fails → restore from `.bak-*` and abort. + +### Phase 5 — Reload MCP + +``` +/reload-mcp +``` + +### Phase 6 — Smoke test + +Call `mcp__context7__resolve-library-id` with a benign query (e.g. `libraryName: "React"`, `query: "smoke test"`). If it returns library IDs → success. + +### Phase 7 — Final report + +``` +✅ Setup complete. context7 registered in ~/.hermes/config.yaml. + +After /reload-mcp: + • mcp__context7__* tools serve from npx @upstash/context7-mcp + • API key from CONTEXT7_API_KEY env var (or embedded) + • Backup saved at ~/.hermes/config.yaml.bak- + +If something breaks: + • Restore from .bak-* and tell me. +``` + +## Rollback procedure + +```bash +cp ~/.hermes/config.yaml.bak- ~/.hermes/config.yaml +/reload-mcp +``` + +## Common mistakes + +- **Forgetting to set CONTEXT7_API_KEY.** The MCP server will fail to start without it. +- **Embedding the key when env var works.** Env var is cleaner for rotation. +- **Forgetting /reload-mcp.** Config changes don't take effect until reload. diff --git a/dist-hermes/mcp/setup-projects-meta/SKILL.md b/dist-hermes/mcp/setup-projects-meta/SKILL.md new file mode 100644 index 0000000..6d4c3aa --- /dev/null +++ b/dist-hermes/mcp/setup-projects-meta/SKILL.md @@ -0,0 +1,152 @@ +--- +name: setup-projects-meta +version: 1.0.0-hermes +description: Hermes-flavour projects-meta setup. Edits `~/.hermes/config.yaml` to register the local `projects-meta-mcp` stdio server. Pre-checks that the binary exists at `~/projects/.common/lib/projects-meta-mcp/dist/server.js` and that `~/.config/projects-mcp/auth.toml` exists — both are shared across Claude Code and Hermes. If pre-checks fail, falls back to git clone (applies extraheader-pattern for safety). Use when user says "install projects-meta", "setup projects-meta", or whenever `mcp__projects-meta__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing. +--- + +# setup-projects-meta (Hermes) + +> One-time Hermes skill that registers `projects-meta-mcp` in `~/.hermes/config.yaml`. The binary and credentials are pre-existing (shared with Claude Code); this skill only adds the MCP server entry. + +## When to use + +- User explicitly asks: install / set up / configure projects-meta on Hermes. +- A `using-projects-meta`-driven task fails because `mcp__projects-meta__*` tools aren't available. +- New Hermes machine where Claude Code's projects-meta is already installed but Hermes config isn't updated. + +## Out of scope + +- Cloning or building `projects-meta-mcp` — that's Claude Code's responsibility. This skill assumes `~/projects/.common/lib/projects-meta-mcp/dist/server.js` already exists. +- Creating or rotating Gitea tokens — assume `~/.config/projects-mcp/auth.toml` exists. +- Running `projects-meta-mcp` itself — Hermes spawns it via `config.yaml`. + +## Hard rule: don't auto-mutate config + +Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).** + +## Procedure + +### Phase 0 — Environment sanity + +- Confirm Hermes is the current agent (need `~/.hermes/config.yaml`). +- Confirm `node` is on `PATH` (the stdio command uses `node`). +- Pick paths: `~/projects/.common/lib/projects-meta-mcp/dist/server.js`, `~/.config/projects-mcp/auth.toml`, `~/.hermes/config.yaml`. POSIX `~/...` resolves on Hermes (Linux). + +### Phase 1 — Discovery (read-only) + +**Binary pre-check.** Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists. + +**Credentials pre-check.** Verify `~/.config/projects-mcp/auth.toml` exists and contains `gitea_token = "..."` (don't echo the token value). + +**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.projects-meta`. Note if present. + +Report: +``` +Binary: +Auth: +MCP entry: +``` + +### Phase 2 — Plan + confirm + +Present the plan: +``` +Binary: +Auth: +MCP entry: +Config: ~/.hermes/config.yaml +Backup: ~/.hermes/config.yaml.bak- +``` + +Wait for explicit confirmation. If auth is missing → stop and ask the user to run Claude Code's `setup-projects-meta` first (it creates `auth.toml`). + +### Phase 3 — Backup + +```bash +TS=$(date +%Y%m%d-%H%M%S) +cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS +``` + +### Phase 4 — Fallback clone (only if binary missing) + +If `~/projects/.common/lib/projects-meta-mcp/dist/server.js` does NOT exist: + +```bash +mkdir -p ~/projects/.common/lib +git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp +cd ~/projects/.common/lib/projects-meta-mcp +npm install +npm run build +``` + +**Security:** before cloning, apply extraheader-pattern to prevent credential leakage: +```bash +git config --global http.https://git.kzntsv.site.extraheader "AUTHORIZATION: Basic ***" +``` + +Verify `dist/server.js` exists after build. If not → abort. + +### Phase 5 — Edit `~/.hermes/config.yaml` + +Add or update the `mcp_servers` section: + +```yaml +mcp_servers: + projects-meta: + command: node + args: + - /home//projects/.common/lib/projects-meta-mcp/dist/server.js + env: + GITEA_TOKEN_FILE: /home//.config/projects-mcp/auth.toml +``` + +**Note:** Hermes supports `GITEA_TOKEN_FILE` env var (projects-meta-mcp reads it and extracts `gitea_token`). This avoids hardcoding the token in args. + +If `mcp_servers.projects-meta` already exists, update `args[0]` to the absolute path. + +Validate YAML syntax: +```bash +python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))" +``` + +If validation fails → restore from `.bak-*` and abort. + +### Phase 6 — Reload MCP + +Tell Hermes to reload MCP servers: +``` +/reload-mcp +``` + +Or invoke the native MCP reload tool if available. + +### Phase 7 — Smoke test + +Call `mcp__projects-meta__meta_status`. If it returns JSON with `synced_at` / `wiki_pages_count` → success. + +### Phase 8 — Final report + +``` +✅ Setup complete. projects-meta registered in ~/.hermes/config.yaml. + +After /reload-mcp: + • mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp + • Credentials from ~/.config/projects-mcp/auth.toml (shared with Claude Code) + • Backup saved at ~/.hermes/config.yaml.bak- + +If something breaks: + • Restore from .bak-* and tell me. +``` + +## Rollback procedure + +```bash +cp ~/.hermes/config.yaml.bak- ~/.hermes/config.yaml +/reload-mcp +``` + +## Common mistakes + +- **Skipping auth.toml pre-check.** If `auth.toml` is missing, the server will fail to start. Don't proceed without it. +- **Hardcoding token in args.** Use `GITEA_TOKEN_FILE` env var instead — `auth.toml` is the source of truth. +- **Forgetting /reload-mcp.** Edits to `config.yaml` don't take effect until MCP reloads. diff --git a/dist-hermes/meta/claude-skills-installer/SKILL.md b/dist-hermes/meta/claude-skills-installer/SKILL.md new file mode 100644 index 0000000..5998ddd --- /dev/null +++ b/dist-hermes/meta/claude-skills-installer/SKILL.md @@ -0,0 +1,161 @@ +--- +name: claude-skills-installer +version: 1.0.0 +description: Recursive bootstrap installer for claude-skills on Hermes. Iterates over `dist-hermes///` and installs each via `skill_manage(action='create')`. Respects `dist-hermes/SKIPPED.md` — skipped skills are not installed. Run once manually to bootstrap (`skill_manage(action='create', from='...')`), thereafter trigger «обнови claude-skills» to refresh all skills. The installer updates itself recursively — no separate update step. +--- + +# claude-skills-installer + +> Bootstrap installer for the claude-skills suite on Hermes. One-time manual registration, then «обнови claude-skills» keeps everything in sync. + +## When to use + +- **Bootstrap phase:** First-time setup on a Hermes machine. Run manually: + ``` + skill_manage(action='create', from='dist-hermes/meta/claude-skills-installer/SKILL.md') + ``` +- **Update phase:** Whenever user says «обнови claude-skills», «refresh claude-skills», or after `git pull` in the claude-skills repo. + +## What it does + +Iterates over `dist-hermes///` (all except `meta/`). For each: + +1. Reads `SKILL.md` (frontmatter: name, version, description). +2. Collects assets (README.md, SECURITY.md, scripts/, etc.) if present. +3. Calls `skill_manage(action='create', category=, name=, content=, assets=<...>)`. + +Skips anything listed in `dist-hermes/SKIPPED.md` (these are intentionally not part of Hermes rollout). + +**Recursive by design:** the installer lives in `meta/` and updates itself along with everything else. + +## Prerequisites + +- `dist-hermes/` tree exists (from `git clone claude-skills` + `python scripts/build-hermes.py`). +- Hermes has `skill_manage()` native tool. +- Working directory is `claude-skills` root (where `dist-hermes/` lives). + +## Procedure + +### Phase 0 — Verify dist-hermes + +```bash +ls dist-hermes/ +``` + +Should list: `software-development/`, `productivity/`, `mcp/`, `meta/`, `SKIPPED.md`. + +If missing → run `python scripts/build-hermes.py` first. + +### Phase 1 — Load SKIPPED.md + +Read `dist-hermes/SKIPPED.md`. Parse the skip list — these categories/names will NOT be installed. + +Example SKIPPED.md entry: +``` +caveman (category: software-development) + Reason: Hermes runs on glm-5.1 (cheap local model); token-compression motive disappears. +``` + +### Phase 2 — Scan dist-hermes + +Walk `dist-hermes///`. Collect: + +``` +category: software-development | productivity | mcp | research +name: +skill_file: dist-hermes///SKILL.md +assets: + - dist-hermes///README.md (if exists) + - dist-hermes///SECURITY.md (if exists) + - dist-hermes///scripts/* (if exists) +``` + +**Skip conditions:** +- `category/name` is in SKIPPED.md +- `name == "claude-skills-installer"` (don't install yourself recursively) + +Report the scan result: +``` +Found N skills to install: + software-development: pulling-before-work, active-platform, project-discipline, tdd-criteria + productivity: using-markitdown + mcp: setup-projects-meta, setup-context7 +Skipped M entries (see dist-hermes/SKIPPED.md) +``` + +### Phase 3 — Confirm + +Ask user: +``` +Will install N skills. Proceed? (y/n) +``` + +Wait for explicit confirmation. This is a bulk operation — permission is required. + +### Phase 4 — Install loop + +For each skill in the scan list: + +``` +skill_manage( + action='create', + category='', + name='', + content='', + assets={ + 'README.md': '', + 'SECURITY.md': '', + 'scripts/*': '