The architecture has been updated

2026-03-31 23:31:36 +03:00 · 2026-03-31 23:31:36 +03:00 · a01257ead9
commit a01257ead9
parent 805f7a017e
1119 changed files with 226 additions and 352 deletions
--- a/hermes_code/skills/dogfood/SKILL.md
+++ b/hermes_code/skills/dogfood/SKILL.md
@ -0,0 +1,162 @@
+---
+name: dogfood
+description: Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports
+version: 1.0.0
+metadata:
+  hermes:
+    tags: [qa, testing, browser, web, dogfood]
+    related_skills: []
+---
+
+# Dogfood: Systematic Web Application QA Testing
+
+## Overview
+
+This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.
+
+## Prerequisites
+
+- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`, `browser_close`)
+- A target URL and testing scope from the user
+
+## Inputs
+
+The user provides:
+1. **Target URL** — the entry point for testing
+2. **Scope** — what areas/features to focus on (or "full site" for comprehensive testing)
+3. **Output directory** (optional) — where to save screenshots and the report (default: `./dogfood-output`)
+
+## Workflow
+
+Follow this 5-phase systematic workflow:
+
+### Phase 1: Plan
+
+1. Create the output directory structure:
+   ```
+   {output_dir}/
+   ├── screenshots/       # Evidence screenshots
+   └── report.md          # Final report (generated in Phase 5)
+   ```
+2. Identify the testing scope based on user input.
+3. Build a rough sitemap by planning which pages and features to test:
+   - Landing/home page
+   - Navigation links (header, footer, sidebar)
+   - Key user flows (sign up, login, search, checkout, etc.)
+   - Forms and interactive elements
+   - Edge cases (empty states, error pages, 404s)
+
+### Phase 2: Explore
+
+For each page or feature in your plan:
+
+1. **Navigate** to the page:
+   ```
+   browser_navigate(url="https://example.com/page")
+   ```
+
+2. **Take a snapshot** to understand the DOM structure:
+   ```
+   browser_snapshot()
+   ```
+
+3. **Check the console** for JavaScript errors:
+   ```
+   browser_console(clear=true)
+   ```
+   Do this after every navigation and after every significant interaction. Silent JS errors are high-value findings.
+
+4. **Take an annotated screenshot** to visually assess the page and identify interactive elements:
+   ```
+   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
+   ```
+   The `annotate=true` flag overlays numbered `[N]` labels on interactive elements. Each `[N]` maps to ref `@eN` for subsequent browser commands.
+
+5. **Test interactive elements** systematically:
+   - Click buttons and links: `browser_click(ref="@eN")`
+   - Fill forms: `browser_type(ref="@eN", text="test input")`
+   - Test keyboard navigation: `browser_press(key="Tab")`, `browser_press(key="Enter")`
+   - Scroll through content: `browser_scroll(direction="down")`
+   - Test form validation with invalid inputs
+   - Test empty submissions
+
+6. **After each interaction**, check for:
+   - Console errors: `browser_console()`
+   - Visual changes: `browser_vision(question="What changed after the interaction?")`
+   - Expected vs actual behavior
+
+### Phase 3: Collect Evidence
+
+For every issue found:
+
+1. **Take a screenshot** showing the issue:
+   ```
+   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
+   ```
+   Save the `screenshot_path` from the response — you will reference it in the report.
+
+2. **Record the details**:
+   - URL where the issue occurs
+   - Steps to reproduce
+   - Expected behavior
+   - Actual behavior
+   - Console errors (if any)
+   - Screenshot path
+
+3. **Classify the issue** using the issue taxonomy (see `references/issue-taxonomy.md`):
+   - Severity: Critical / High / Medium / Low
+   - Category: Functional / Visual / Accessibility / Console / UX / Content
+
+### Phase 4: Categorize
+
+1. Review all collected issues.
+2. De-duplicate — merge issues that are the same bug manifesting in different places.
+3. Assign final severity and category to each issue.
+4. Sort by severity (Critical first, then High, Medium, Low).
+5. Count issues by severity and category for the executive summary.
+
+### Phase 5: Report
+
+Generate the final report using the template at `templates/dogfood-report-template.md`.
+
+The report must include:
+1. **Executive summary** with total issue count, breakdown by severity, and testing scope
+2. **Per-issue sections** with:
+   - Issue number and title
+   - Severity and category badges
+   - URL where observed
+   - Description of the issue
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Screenshot references (use `MEDIA:<screenshot_path>` for inline images)
+   - Console errors if relevant
+3. **Summary table** of all issues
+4. **Testing notes** — what was tested, what was not, any blockers
+
+Save the report to `{output_dir}/report.md`.
+
+## Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `browser_navigate` | Go to a URL |
+| `browser_snapshot` | Get DOM text snapshot (accessibility tree) |
+| `browser_click` | Click an element by ref (`@eN`) or text |
+| `browser_type` | Type into an input field |
+| `browser_scroll` | Scroll up/down on the page |
+| `browser_back` | Go back in browser history |
+| `browser_press` | Press a keyboard key |
+| `browser_vision` | Screenshot + AI analysis; use `annotate=true` for element labels |
+| `browser_console` | Get JS console output and errors |
+| `browser_close` | Close the browser session |
+
+## Tips
+
+- **Always check `browser_console()` after navigating and after significant interactions.** Silent JS errors are among the most valuable findings.
+- **Use `annotate=true` with `browser_vision`** when you need to reason about interactive element positions or when the snapshot refs are unclear.
+- **Test with both valid and invalid inputs** — form validation bugs are common.
+- **Scroll through long pages** — content below the fold may have rendering issues.
+- **Test navigation flows** — click through multi-step processes end-to-end.
+- **Check responsive behavior** by noting any layout issues visible in screenshots.
+- **Don't forget edge cases**: empty states, very long text, special characters, rapid clicking.
+- When reporting screenshots to the user, include `MEDIA:<screenshot_path>` so they can see the evidence inline.
--- a/hermes_code/skills/dogfood/hermes-agent-setup/SKILL.md
+++ b/hermes_code/skills/dogfood/hermes-agent-setup/SKILL.md
@ -0,0 +1,300 @@
+---
+name: hermes-agent-setup
+description: Help users configure Hermes Agent — CLI usage, setup wizard, model/provider selection, tools, skills, voice/STT/TTS, gateway, and troubleshooting. Use when someone asks to enable features, configure settings, or needs help with Hermes itself.
+version: 1.1.0
+author: Hermes Agent
+tags: [setup, configuration, tools, stt, tts, voice, hermes, cli, skills]
+---
+
+# Hermes Agent Setup & Configuration
+
+Use this skill when a user asks about configuring Hermes, enabling features, setting up voice, managing tools/skills, or troubleshooting.
+
+## Key Paths
+
+- Config: `~/.hermes/config.yaml`
+- API keys: `~/.hermes/.env`
+- Skills: `~/.hermes/skills/`
+- Hermes install: `~/.hermes/hermes-agent/`
+- Venv: `~/.hermes/hermes-agent/venv/`
+
+## CLI Overview
+
+Hermes is used via the `hermes` command (or `python -m hermes_cli.main` from the repo).
+
+### Core commands:
+
+```
+hermes                          Interactive chat (default)
+hermes chat -q "question"       Single query, then exit
+hermes chat -m MODEL            Chat with a specific model
+hermes -c                       Resume most recent session
+hermes -c "project name"        Resume session by name
+hermes --resume SESSION_ID      Resume by exact ID
+hermes -w                       Isolated git worktree mode
+hermes -s skill1,skill2         Preload skills for the session
+hermes --yolo                   Skip dangerous command approval
+```
+
+### Configuration & setup:
+
+```
+hermes setup                    Interactive setup wizard (provider, API keys, model)
+hermes model                    Interactive model/provider selection
+hermes config                   View current configuration
+hermes config edit              Open config.yaml in $EDITOR
+hermes config set KEY VALUE     Set a config value directly
+hermes login                    Authenticate with a provider
+hermes logout                   Clear stored auth
+hermes doctor                   Check configuration and dependencies
+```
+
+### Tools & skills:
+
+```
+hermes tools                    Interactive tool enable/disable per platform
+hermes skills list              List installed skills
+hermes skills search QUERY      Search the skills hub
+hermes skills install NAME      Install a skill from the hub
+hermes skills config            Enable/disable skills per platform
+```
+
+### Gateway (messaging platforms):
+
+```
+hermes gateway run              Start the messaging gateway
+hermes gateway install          Install gateway as background service
+hermes gateway status           Check gateway status
+```
+
+### Session management:
+
+```
+hermes sessions list            List past sessions
+hermes sessions browse          Interactive session picker
+hermes sessions rename ID TITLE Rename a session
+hermes sessions export ID       Export session as markdown
+hermes sessions prune           Clean up old sessions
+```
+
+### Other:
+
+```
+hermes status                   Show status of all components
+hermes cron list                List cron jobs
+hermes insights                 Usage analytics
+hermes update                   Update to latest version
+hermes pairing                  Manage DM authorization codes
+```
+
+## Setup Wizard (`hermes setup`)
+
+The interactive setup wizard walks through:
+1. **Provider selection** — OpenRouter, Anthropic, OpenAI, Google, DeepSeek, and many more
+2. **API key entry** — stores securely in the env file
+3. **Model selection** — picks from available models for the chosen provider
+4. **Basic settings** — reasoning effort, tool preferences
+
+Run it from terminal:
+```bash
+cd ~/.hermes/hermes-agent
+source venv/bin/activate
+python -m hermes_cli.main setup
+```
+
+To change just the model/provider later: `hermes model`
+
+## Skills Configuration (`hermes skills`)
+
+Skills are reusable instruction sets that extend what Hermes can do.
+
+### Managing skills:
+
+```bash
+hermes skills list              # Show installed skills
+hermes skills search "docker"   # Search the hub
+hermes skills install NAME      # Install from hub
+hermes skills config            # Enable/disable per platform
+```
+
+### Per-platform skill control:
+
+`hermes skills config` opens an interactive UI where you can enable or disable specific skills for each platform (cli, telegram, discord, etc.). Disabled skills won't appear in the agent's available skills list for that platform.
+
+### Loading skills in a session:
+
+- CLI: `hermes -s skill-name` or `hermes -s skill1,skill2`
+- Chat: `/skill skill-name`
+- Gateway: type `/skill skill-name` in any chat
+
+## Voice Messages (STT)
+
+Voice messages from Telegram/Discord/WhatsApp/Slack/Signal are auto-transcribed when an STT provider is available.
+
+### Provider priority (auto-detected):
+1. **Local faster-whisper** — free, no API key, runs on CPU/GPU
+2. **Groq Whisper** — free tier, needs GROQ_API_KEY
+3. **OpenAI Whisper** — paid, needs VOICE_TOOLS_OPENAI_KEY
+
+### Setup local STT (recommended):
+
+```bash
+cd ~/.hermes/hermes-agent
+source venv/bin/activate
+pip install faster-whisper
+```
+
+Add to config.yaml under the `stt:` section:
+```yaml
+stt:
+  enabled: true
+  provider: local
+  local:
+    model: base  # Options: tiny, base, small, medium, large-v3
+```
+
+Model downloads automatically on first use (~150 MB for base).
+
+### Setup Groq STT (free cloud):
+
+1. Get free key from https://console.groq.com
+2. Add GROQ_API_KEY to the env file
+3. Set provider to groq in config.yaml stt section
+
+### Verify STT:
+
+After config changes, restart the gateway (send /restart in chat, or restart `hermes gateway run`). Then send a voice message.
+
+## Voice Replies (TTS)
+
+Hermes can reply with voice when users send voice messages.
+
+### TTS providers (set API key in env file):
+
+| Provider | Env var | Free? |
+|----------|---------|-------|
+| ElevenLabs | ELEVENLABS_API_KEY | Free tier |
+| OpenAI | VOICE_TOOLS_OPENAI_KEY | Paid |
+| Kokoro (local) | None needed | Free |
+| Fish Audio | FISH_AUDIO_API_KEY | Free tier |
+
+### Voice commands (in any chat):
+- `/voice on` — voice reply to voice messages only
+- `/voice tts` — voice reply to all messages
+- `/voice off` — text only (default)
+
+## Enabling/Disabling Tools (`hermes tools`)
+
+### Interactive tool config:
+
+```bash
+cd ~/.hermes/hermes-agent
+source venv/bin/activate
+python -m hermes_cli.main tools
+```
+
+This opens a curses UI to enable/disable toolsets per platform (cli, telegram, discord, slack, etc.).
+
+### After changing tools:
+
+Use `/reset` in the chat to start a fresh session with the new toolset. Tool changes do NOT take effect mid-conversation (this preserves prompt caching and avoids cost spikes).
+
+### Common toolsets:
+
+| Toolset | What it provides |
+|---------|-----------------|
+| terminal | Shell command execution |
+| file | File read/write/search/patch |
+| web | Web search and extraction |
+| browser | Browser automation (needs Browserbase) |
+| image_gen | AI image generation |
+| mcp | MCP server connections |
+| voice | Text-to-speech output |
+| cronjob | Scheduled tasks |
+
+## Installing Dependencies
+
+Some tools need extra packages:
+
+```bash
+cd ~/.hermes/hermes-agent && source venv/bin/activate
+
+pip install faster-whisper    # Local STT (voice transcription)
+pip install browserbase       # Browser automation
+pip install mcp               # MCP server connections
+```
+
+## Config File Reference
+
+The main config file is `~/.hermes/config.yaml`. Key sections:
+
+```yaml
+# Model and provider
+model:
+  default: anthropic/claude-opus-4.6
+  provider: openrouter
+
+# Agent behavior
+agent:
+  max_turns: 90
+  reasoning_effort: high    # xhigh, high, medium, low, minimal, none
+
+# Voice
+stt:
+  enabled: true
+  provider: local           # local, groq, openai
+tts:
+  provider: elevenlabs      # elevenlabs, openai, kokoro, fish
+
+# Display
+display:
+  skin: default             # default, ares, mono, slate
+  tool_progress: full       # full, compact, off
+  background_process_notifications: all  # all, result, error, off
+```
+
+Edit with `hermes config edit` or `hermes config set KEY VALUE`.
+
+## Gateway Commands (Messaging Platforms)
+
+| Command | What it does |
+|---------|-------------|
+| /reset or /new | Fresh session (picks up new tool config) |
+| /help | Show all commands |
+| /model [name] | Show or change model |
+| /compact | Compress conversation to save context |
+| /voice [mode] | Configure voice replies |
+| /reasoning [effort] | Set reasoning level |
+| /sethome | Set home channel for cron/notifications |
+| /restart | Restart the gateway (picks up config changes) |
+| /status | Show session info |
+| /retry | Retry last message |
+| /undo | Remove last exchange |
+| /personality [name] | Set agent personality |
+| /skill [name] | Load a skill |
+
+## Troubleshooting
+
+### Voice messages not working
+1. Check stt.enabled is true in config.yaml
+2. Check a provider is available (faster-whisper installed, or API key set)
+3. Restart gateway after config changes (/restart)
+
+### Tool not available
+1. Run `hermes tools` to check if the toolset is enabled for your platform
+2. Some tools need env vars — check the env file
+3. Use /reset after enabling tools
+
+### Model/provider issues
+1. Run `hermes doctor` to check configuration
+2. Run `hermes login` to re-authenticate
+3. Check the env file has the right API key
+
+### Changes not taking effect
+- Gateway: /reset for tool changes, /restart for config changes
+- CLI: start a new session
+
+### Skills not showing up
+1. Check `hermes skills list` shows the skill
+2. Check `hermes skills config` has it enabled for your platform
+3. Load explicitly with `/skill name` or `hermes -s name`
--- a/hermes_code/skills/dogfood/references/issue-taxonomy.md
+++ b/hermes_code/skills/dogfood/references/issue-taxonomy.md
@ -0,0 +1,109 @@
+# Issue Taxonomy
+
+Use this taxonomy to classify issues found during dogfood QA testing.
+
+## Severity Levels
+
+### Critical
+The issue makes a core feature completely unusable or causes data loss.
+
+**Examples:**
+- Application crashes or shows a blank white page
+- Form submission silently loses user data
+- Authentication is completely broken (can't log in at all)
+- Payment flow fails and charges the user without completing the order
+- Security vulnerability (e.g., XSS, exposed credentials in console)
+
+### High
+The issue significantly impairs functionality but a workaround may exist.
+
+**Examples:**
+- A key button does nothing when clicked (but refreshing fixes it)
+- Search returns no results for valid queries
+- Form validation rejects valid input
+- Page loads but critical content is missing or garbled
+- Navigation link leads to a 404 or wrong page
+- Uncaught JavaScript exceptions in the console on core pages
+
+### Medium
+The issue is noticeable and affects user experience but doesn't block core functionality.
+
+**Examples:**
+- Layout is misaligned or overlapping on certain screen sections
+- Images fail to load (broken image icons)
+- Slow performance (visible loading delays > 3 seconds)
+- Form field lacks proper validation feedback (no error message on bad input)
+- Console warnings that suggest deprecated or misconfigured features
+- Inconsistent styling between similar pages
+
+### Low
+Minor polish issues that don't affect functionality.
+
+**Examples:**
+- Typos or grammatical errors in text content
+- Minor spacing or alignment inconsistencies
+- Placeholder text left in production ("Lorem ipsum")
+- Favicon missing
+- Console info/debug messages that shouldn't be in production
+- Subtle color contrast issues that don't fail WCAG requirements
+
+## Categories
+
+### Functional
+Issues where features don't work as expected.
+
+- Buttons/links that don't respond
+- Forms that don't submit or submit incorrectly
+- Broken user flows (can't complete a multi-step process)
+- Incorrect data displayed
+- Features that work partially
+
+### Visual
+Issues with the visual presentation of the page.
+
+- Layout problems (overlapping elements, broken grids)
+- Broken images or missing media
+- Styling inconsistencies
+- Responsive design failures
+- Z-index issues (elements hidden behind others)
+- Text overflow or truncation
+
+### Accessibility
+Issues that prevent or hinder access for users with disabilities.
+
+- Missing alt text on meaningful images
+- Poor color contrast (fails WCAG AA)
+- Elements not reachable via keyboard navigation
+- Missing form labels or ARIA attributes
+- Focus indicators missing or unclear
+- Screen reader incompatible content
+
+### Console
+Issues detected through JavaScript console output.
+
+- Uncaught exceptions and unhandled promise rejections
+- Failed network requests (4xx, 5xx errors in console)
+- Deprecation warnings
+- CORS errors
+- Mixed content warnings (HTTP resources on HTTPS page)
+- Excessive console.log output left from development
+
+### UX (User Experience)
+Issues where functionality works but the experience is poor.
+
+- Confusing navigation or information architecture
+- Missing loading indicators (user doesn't know something is happening)
+- No feedback after user actions (e.g., button click with no visible result)
+- Inconsistent interaction patterns
+- Missing confirmation dialogs for destructive actions
+- Poor error messages that don't help the user recover
+
+### Content
+Issues with the text, media, or information on the page.
+
+- Typos and grammatical errors
+- Placeholder/dummy content in production
+- Outdated information
+- Missing content (empty sections)
+- Broken or dead links to external resources
+- Incorrect or misleading labels
--- a/hermes_code/skills/dogfood/templates/dogfood-report-template.md
+++ b/hermes_code/skills/dogfood/templates/dogfood-report-template.md
@ -0,0 +1,86 @@
+# Dogfood QA Report
+
+**Target:** {target_url}
+**Date:** {date}
+**Scope:** {scope_description}
+**Tester:** Hermes Agent (automated exploratory QA)
+
+---
+
+## Executive Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | {critical_count} |
+| 🟠 High | {high_count} |
+| 🟡 Medium | {medium_count} |
+| 🔵 Low | {low_count} |
+| **Total** | **{total_count}** |
+
+**Overall Assessment:** {one_sentence_assessment}
+
+---
+
+## Issues
+
+<!-- Repeat this section for each issue found, sorted by severity (Critical first) -->
+
+### Issue #{issue_number}: {issue_title}
+
+| Field | Value |
+|-------|-------|
+| **Severity** | {severity} |
+| **Category** | {category} |
+| **URL** | {url_where_found} |
+
+**Description:**
+{detailed_description_of_the_issue}
+
+**Steps to Reproduce:**
+1. {step_1}
+2. {step_2}
+3. {step_3}
+
+**Expected Behavior:**
+{what_should_happen}
+
+**Actual Behavior:**
+{what_actually_happens}
+
+**Screenshot:**
+MEDIA:{screenshot_path}
+
+**Console Errors** (if applicable):
+```
+{console_error_output}
+```
+
+---
+
+<!-- End of per-issue section -->
+
+## Issues Summary Table
+
+| # | Title | Severity | Category | URL |
+|---|-------|----------|----------|-----|
+| {n} | {title} | {severity} | {category} | {url} |
+
+## Testing Coverage
+
+### Pages Tested
+- {list_of_pages_visited}
+
+### Features Tested
+- {list_of_features_exercised}
+
+### Not Tested / Out of Scope
+- {areas_not_covered_and_why}
+
+### Blockers
+- {any_issues_that_prevented_testing_certain_areas}
+
+---
+
+## Notes
+
+{any_additional_observations_or_recommendations}