From efe7ef88ba91f2f3c43cf315c8381dd75ebaceaf Mon Sep 17 00:00:00 2001 From: Redacted User Date: Thu, 9 Apr 2026 19:43:29 +0200 Subject: [PATCH] Add Hermes Alice workflow skill pack and install docs --- README.md | 2 + docs/integrations/hermes-skill-pack.md | 86 +++++++++++++++++++ .../skills/alice-workflows/DESCRIPTION.md | 3 + .../alice-continuity-recall/SKILL.md | 56 ++++++++++++ .../alice-correction-loop/SKILL.md | 63 ++++++++++++++ .../alice-explain-provenance/SKILL.md | 56 ++++++++++++ .../alice-open-loop-review/SKILL.md | 55 ++++++++++++ .../alice-workflows/alice-resumption/SKILL.md | 61 +++++++++++++ docs/integrations/hermes.md | 18 ++++ docs/integrations/mcp.md | 1 + 10 files changed, 401 insertions(+) create mode 100644 docs/integrations/hermes-skill-pack.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/DESCRIPTION.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-continuity-recall/SKILL.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-correction-loop/SKILL.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-explain-provenance/SKILL.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-open-loop-review/SKILL.md create mode 100644 docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-resumption/SKILL.md diff --git a/README.md b/README.md index 02dac9a..0fe29b7 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,7 @@ See: - [docs/integrations/mcp.md](docs/integrations/mcp.md) - [docs/integrations/hermes.md](docs/integrations/hermes.md) +- [docs/integrations/hermes-skill-pack.md](docs/integrations/hermes-skill-pack.md) Hermes runtime smoke test: @@ -280,6 +281,7 @@ your AI can only be useful if it can remember, resume, and stay aligned with how - [Architecture](ARCHITECTURE.md) - [MCP](docs/integrations/mcp.md) - [Hermes Guide](docs/integrations/hermes.md) +- [Hermes Skill Pack](docs/integrations/hermes-skill-pack.md) - [Integrations](docs/integrations/importers.md) - [OpenClaw Guide](docs/integrations/openclaw.md) - [Examples](docs/examples/phase9-command-walkthrough.md) diff --git a/docs/integrations/hermes-skill-pack.md b/docs/integrations/hermes-skill-pack.md new file mode 100644 index 0000000..1838399 --- /dev/null +++ b/docs/integrations/hermes-skill-pack.md @@ -0,0 +1,86 @@ +# Hermes Skill Pack for Alice Workflows + +This pack provides Hermes-native skills that guide when and how to call Alice MCP tools. + +## What This Pack Includes + +Pack location in this repository: + +- `docs/integrations/hermes-skill-pack/skills/alice-workflows/` + +Skills: + +- `alice-continuity-recall` +- `alice-resumption` +- `alice-open-loop-review` +- `alice-explain-provenance` +- `alice-correction-loop` + +## Skill to Tool Map + +| Skill | Primary Alice MCP tools | +|---|---| +| `alice-continuity-recall` | `alice_recall`, `alice_recent_decisions` | +| `alice-resumption` | `alice_resume`, `alice_context_pack` | +| `alice-open-loop-review` | `alice_open_loops`, `alice_recent_changes` | +| `alice-explain-provenance` | `alice_context_pack`, `alice_recall` | +| `alice-correction-loop` | `alice_memory_review`, `alice_memory_correct`, `alice_recall`/`alice_resume` | + +## Install + +From the Alice repository root: + +```bash +export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" +mkdir -p "$HERMES_HOME/skills" +cp -R docs/integrations/hermes-skill-pack/skills/alice-workflows "$HERMES_HOME/skills/" +``` + +## Verify Installation + +```bash +HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" \ + ./.venv/bin/hermes skills list --source local +``` + +You should see the five `alice-*` skills listed. + +To confirm three core skills quickly: + +```bash +HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" \ + ./.venv/bin/hermes skills list --source local | \ + rg "alice-continuity-recall|alice-resumption|alice-open-loop-review" +``` + +## Skills vs MCP: Responsibility Split + +- Skills: decision policy and workflow instructions (when to call tools, how to format output, what evidence to include). +- MCP tools: runtime execution and deterministic continuity data retrieval/update. +- Practical rule: use skills to decide behavior; use MCP tools to fetch or mutate continuity state. + +## When Hermes Should Prefer Alice Tools + +Use Alice tools instead of inference-only answers when: + +- the user asks for prior decisions, commitments, or timeline details +- the user asks to continue interrupted work with concrete next actions +- the user asks which blockers/open loops remain +- the user asks for provenance or evidence behind a claim +- the user asks to correct stale or incorrect continuity records + +Concrete examples: + +- "What did we decide about rollout gating last week?" -> prefer `alice_recall` +- "Resume thread `` and give next action plus blockers." -> prefer `alice_resume` +- "What is still blocked for this project?" -> prefer `alice_open_loops` +- "Why do you think this is true?" -> prefer `alice_context_pack` + `alice_recall` +- "This memory is outdated, replace it." -> prefer `alice_memory_review` + `alice_memory_correct` + +## Suggested Skill Loading + +```bash +./.venv/bin/hermes -s alice-resumption -s alice-open-loop-review +``` + +Add `alice-explain-provenance` for evidence-first responses and `alice-correction-loop` for correction-heavy sessions. diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/DESCRIPTION.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/DESCRIPTION.md new file mode 100644 index 0000000..b868da0 --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/DESCRIPTION.md @@ -0,0 +1,3 @@ +--- +description: Alice workflow skills for Hermes. These skills route continuity work to Alice MCP tools for recall, resumption, open-loop review, provenance explanation, and correction updates. +--- diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-continuity-recall/SKILL.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-continuity-recall/SKILL.md new file mode 100644 index 0000000..2f69156 --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-continuity-recall/SKILL.md @@ -0,0 +1,56 @@ +--- +name: alice-continuity-recall +description: Use Alice MCP recall tools for continuity-grounded answers with provenance when users ask what was decided, what changed, or what to remember. +version: 1.0.0 +author: Alice +license: MIT +metadata: + hermes: + tags: [alice, continuity, recall, mcp] + related_skills: [alice-resumption, alice-explain-provenance] +--- + +# Alice Continuity Recall + +## Goal + +Produce recall answers from Alice continuity records instead of free-form memory. + +## Trigger Cues + +Use this skill when the user asks: +- what was decided +- what happened in a thread/project/person scope +- what should be remembered from prior work + +## Required MCP Tools + +- `mcp__alice_recall` +- Optional: `mcp__alice_recent_decisions` + +`` is usually `alice_core`. + +## Workflow + +1. Prefer `alice_recall` over inference-only answers. +2. Use scope filters when available (`thread_id`, `project`, `person`, `since`, `until`). +3. Keep `limit` bounded (normally `3` to `10`). +4. Return summary plus provenance-backed evidence IDs. + +## Tool Call Templates + +```text +mcp_alice_core_alice_recall({"query":"","thread_id":"","limit":5}) +``` + +```text +mcp_alice_core_alice_recent_decisions({"thread_id":"","limit":5}) +``` + +## Output Contract + +Always include: +- direct answer +- top evidence items (`id`, `title`, `object_type`) +- provenance notes from the returned item fields +- uncertainty note if evidence is weak or absent diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-correction-loop/SKILL.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-correction-loop/SKILL.md new file mode 100644 index 0000000..6732705 --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-correction-loop/SKILL.md @@ -0,0 +1,63 @@ +--- +name: alice-correction-loop +description: Run deterministic correction workflows with Alice MCP review and correction tools, then verify that future outputs reflect the update. +version: 1.0.0 +author: Alice +license: MIT +metadata: + hermes: + tags: [alice, continuity, correction, review, mcp] + related_skills: [alice-explain-provenance, alice-open-loop-review] +--- + +# Alice Correction Loop + +## Goal + +Apply corrections through Alice review tools and confirm that recall/resumption behavior updates accordingly. + +## Trigger Cues + +Use this skill when the user asks: +- this is outdated or wrong +- correct this memory +- supersede or mark stale + +## Required MCP Tools + +- `mcp__alice_memory_review` +- `mcp__alice_memory_correct` +- Verification: `mcp__alice_recall` or `mcp__alice_resume` + +`` is usually `alice_core`. + +## Workflow + +1. Fetch review queue or detail with `alice_memory_review`. +2. Select correction action: + - `confirm` + - `edit` + - `delete` + - `supersede` + - `mark_stale` +3. Apply correction with `alice_memory_correct`. +4. Re-run `alice_recall` or `alice_resume` to verify behavior changed. +5. Report both the correction action and the observed post-correction result. + +## Tool Call Templates + +```text +mcp_alice_core_alice_memory_review({"status":"correction_ready","limit":10}) +``` + +```text +mcp_alice_core_alice_memory_correct({"continuity_object_id":"","action":"supersede","replacement_title":"","replacement_body":{}}) +``` + +## Output Contract + +Always include: +- corrected object ID +- action applied +- reason +- post-correction verification result diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-explain-provenance/SKILL.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-explain-provenance/SKILL.md new file mode 100644 index 0000000..f9b777e --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-explain-provenance/SKILL.md @@ -0,0 +1,56 @@ +--- +name: alice-explain-provenance +description: Explain why an answer is trustworthy by referencing Alice continuity provenance and correction state from MCP tool outputs. +version: 1.0.0 +author: Alice +license: MIT +metadata: + hermes: + tags: [alice, continuity, provenance, explainability, mcp] + related_skills: [alice-continuity-recall, alice-correction-loop] +--- + +# Alice Explain Provenance + +## Goal + +Provide evidence-backed explanations for Alice-based answers. + +## Trigger Cues + +Use this skill when the user asks: +- why are you saying this +- what source supports this +- can you show evidence or provenance + +## Required MCP Tools + +- `mcp_<alice_server>_alice_context_pack` +- Optional: `mcp_<alice_server>_alice_recall` + +`<alice_server>` is usually `alice_core`. + +## Workflow + +1. Start from `alice_context_pack` for a scoped evidence set. +2. If needed, run a focused `alice_recall` query for missing evidence. +3. Explain answer claims by citing returned continuity object IDs and provenance fields. +4. If provenance is thin, state uncertainty and propose the next validating step. + +## Tool Call Templates + +```text +mcp_alice_core_alice_context_pack({"thread_id":"<uuid>","recent_decisions_limit":5,"recent_changes_limit":5,"open_loops_limit":5}) +``` + +```text +mcp_alice_core_alice_recall({"thread_id":"<uuid>","query":"<claim>","limit":5}) +``` + +## Output Contract + +Always include: +- claim +- supporting object IDs +- provenance summary from returned records +- confidence posture (`high`, `medium`, `low`) based on evidence quality diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-open-loop-review/SKILL.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-open-loop-review/SKILL.md new file mode 100644 index 0000000..1413368 --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-open-loop-review/SKILL.md @@ -0,0 +1,55 @@ +--- +name: alice-open-loop-review +description: Use Alice open-loop MCP tools to review unresolved commitments and prioritize concrete next actions. +version: 1.0.0 +author: Alice +license: MIT +metadata: + hermes: + tags: [alice, continuity, open-loops, review, mcp] + related_skills: [alice-resumption, alice-correction-loop] +--- + +# Alice Open-Loop Review + +## Goal + +Turn open loops into a prioritized action queue grounded in Alice continuity state. + +## Trigger Cues + +Use this skill when the user asks: +- what is still open +- what is blocked or waiting +- what should I do next from unresolved items + +## Required MCP Tools + +- `mcp_<alice_server>_alice_open_loops` +- Optional: `mcp_<alice_server>_alice_recent_changes` + +`<alice_server>` is usually `alice_core`. + +## Workflow + +1. Call `alice_open_loops` for the relevant scope. +2. Keep output grouped by posture: + - `waiting_for` + - `blocker` + - `stale` + - `next_action` +3. Surface top priorities first (blocked and overdue items before low-risk follow-ups). +4. Convert each group into explicit next steps. + +## Tool Call Template + +```text +mcp_alice_core_alice_open_loops({"thread_id":"<uuid>","limit":10}) +``` + +## Output Contract + +Always include: +- grouped open-loop summary +- top 3 priority actions +- per-item rationale tied to returned loop posture diff --git a/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-resumption/SKILL.md b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-resumption/SKILL.md new file mode 100644 index 0000000..f4faff6 --- /dev/null +++ b/docs/integrations/hermes-skill-pack/skills/alice-workflows/alice-resumption/SKILL.md @@ -0,0 +1,61 @@ +--- +name: alice-resumption +description: Build deterministic continuation briefs with Alice MCP resumption tools when users want to pick up interrupted work. +version: 1.0.0 +author: Alice +license: MIT +metadata: + hermes: + tags: [alice, continuity, resume, mcp] + related_skills: [alice-continuity-recall, alice-open-loop-review] +--- + +# Alice Resumption + +## Goal + +Resume work from deterministic continuity state instead of reconstructing history manually. + +## Trigger Cues + +Use this skill when the user asks: +- continue where we left off +- give me a restart brief +- summarize decisions, next action, blockers + +## Required MCP Tools + +- `mcp_<alice_server>_alice_resume` +- Optional: `mcp_<alice_server>_alice_context_pack` + +`<alice_server>` is usually `alice_core`. + +## Workflow + +1. Call `alice_resume` with scoped filters and bounded limits. +2. If broader context is needed, call `alice_context_pack`. +3. Prioritize these sections in your answer: + - last decision + - next action + - open loops + - recent changes +4. Keep the final brief actionable and short. + +## Tool Call Templates + +```text +mcp_alice_core_alice_resume({"thread_id":"<uuid>","max_recent_changes":5,"max_open_loops":5}) +``` + +```text +mcp_alice_core_alice_context_pack({"thread_id":"<uuid>","recent_changes_limit":5,"open_loops_limit":5,"recent_decisions_limit":5}) +``` + +## Output Contract + +Always include: +- `last_decision` +- `next_action` +- `blockers_or_waiting_for` +- `recent_changes` +- explicit note when `thread_id` or scope is missing diff --git a/docs/integrations/hermes.md b/docs/integrations/hermes.md index 43cfbd3..98ea164 100644 --- a/docs/integrations/hermes.md +++ b/docs/integrations/hermes.md @@ -114,6 +114,24 @@ Use mcp_alice_core_alice_resume with {"thread_id":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaa Use mcp_alice_core_alice_open_loops with {"thread_id":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","limit":10}. Group results by waiting_for, blocker, stale, next_action. ``` +## Alice Workflow Skill Pack + +To make Alice tool usage more consistent in Hermes sessions, install the +Hermes-native Alice skill pack: + +- `docs/integrations/hermes-skill-pack.md` + +The pack includes: + +- `alice-continuity-recall` +- `alice-resumption` +- `alice-open-loop-review` +- `alice-explain-provenance` +- `alice-correction-loop` + +Skills decide when and how to call tools. MCP tools perform deterministic +continuity reads and writes. + ## Troubleshooting ### `Connection failed` in `hermes mcp test` diff --git a/docs/integrations/mcp.md b/docs/integrations/mcp.md index 8b80ae1..0529165 100644 --- a/docs/integrations/mcp.md +++ b/docs/integrations/mcp.md @@ -55,6 +55,7 @@ MCP uses the same local runtime scope as CLI: For Hermes Agent-specific setup, prompts, and troubleshooting: - `docs/integrations/hermes.md` +- `docs/integrations/hermes-skill-pack.md` ## Contract Guardrails