feat: improve Hermes reusable ops config

.gitignore

@@ -2,6 +2,8 @@
 *.swp
 *.swo
 node_modules/
+__pycache__/
+*.py[cod]
 
 # Copilot CLI session transcripts can leak into the working dir if
 # probe prompts reference filenames. Per `gh copilot -- --help`:

README.md

@@ -5,7 +5,8 @@ HappyVertical shared cross-repo configuration for agent-assisted development.
 This repo is the umbrella for configuration that ≥2 HappyVertical projects
 consume. Today that's organization standards, service registry docs, agent
 instruction snippets, profile-specific commands/skills, and shared
-lint/format/tsconfig bases. Runtime agent behavior is installed as local files;
+lint/format/tsconfig bases. Runtime agent behavior and reusable operational
+scripts are installed as local files;
 Context Forge is consumed as an install-time snapshot by the have-config
 resolver.
 
@@ -19,6 +20,8 @@ resolver.
   (`profiles/`)
 - Agent manifests consumed by the have-config resolver (`hv/manifest.json`,
   `profiles/*/manifest.json`)
+- Reusable operational scripts consumed by ≥2 Hermes/cricket workflows
+  (`reusable-scripts/`)
 - Shared lint / format / tsconfig configs as published npm packages
   (`packages/eslint-config`, `packages/prettier-config`,
   `packages/tsconfig-base`)
@@ -51,6 +54,8 @@ have-config/
 ├── TODO.md                          # planned additions, with consumer count
 ├── hv/
 │   └── manifest.json                # organization source manifest
+├── reusable-scripts/
+│   └── hermes/no-agent/             # reusable scripts for schedulers/watchers
 ├── profiles/
 │   └── hermes/
 │       ├── manifest.json            # Hermes-only commands and skills
@@ -143,6 +148,15 @@ Hermes agents additionally get local generated commands/skills:
 
 - `/check-setup` / `check-setup` — verifies agent access to HappyVertical
   services
+- `hermes-ops` — documents scheduled Vikunja pickup state, blocked-task
+  recovery, and watcher setup
+
+The base manifest also installs reusable no-agent scripts when executable
+script links are managed:
+
+- `hv-hermes-vikunja-task-updates` — polls Vikunja task updates
+- `hv-hermes-github-cricket-issues` — polls GitHub open issues labeled
+  `cricket`
 
 ## Agent resolution model
 
@@ -156,6 +170,8 @@ The have-config installer composes agent behavior in this order:
 
 For command and skill conflicts, later layers win. For AGENTS and CLAUDE
 behavior, sections are cumulative and assembled in layer order.
+Reusable scripts use the same layer priority model and are materialized under
+the generated config tree; executable scripts are linked into `~/.local/bin`.
 
 Context Forge remains the dynamic organization policy source, but it is not a
 runtime dependency for normal agent behavior. Export it into

TODO.md

@@ -14,6 +14,8 @@ that needs it.
       metadata consumed by the resolver
 - [x] `profiles/hermes/` — Hermes-only commands and skills such as
       `check-setup`
+- [x] `reusable-scripts/hermes/no-agent/` — reusable notification scripts for
+      Hermes Vikunja task updates and GitHub `cricket`-labeled issue updates
 - [ ] `claude/` / `codex/` packaged surfaces, only if a future second
       consumer needs marketplace/plugin distribution instead of generated local
       files
@@ -28,6 +30,8 @@ that needs it.
 ## Agent hooks
 
 - [ ] `hooks/` — pre-/post-tool-use hooks consumed by ≥2 repos.
+- [x] `scripts` manifest entries — reusable operational scripts materialized
+      by the resolver and linked into `~/.local/bin` when executable
 
 ## Lint / format / build bases
 
@@ -79,5 +83,7 @@ Pick when the first consumer pair exists, not before.
 - [x] `hv/manifest.json` — source manifest consumed by have-config
 - [x] `profiles/hermes/manifest.json` — Hermes-only defaults such as
       `check-setup`
+- [x] Hermes `hermes-ops` skill — scheduled Vikunja pickup state,
+      blocked-task recovery, and watcher setup
 - [ ] Publish an exporter from Context Forge into the manifest shape expected by
       have-config (`manifest.json` with `skills`, `commands`, and `agent_docs`).

docs/agent-playbook.md

@@ -34,6 +34,21 @@ The command should verify:
 - `context.happyvertical.com` is reachable and the agent is configured for
   prompts, resources, and memory
 
+## Hermes No-Agent Watchers
+
+The base have-config manifest provides reusable scripts for operational
+notifications that can run from cron, systemd user timers, or another local
+scheduler without an active agent session:
+
+- `hv-hermes-vikunja-task-updates` polls recently updated Vikunja tasks.
+- `hv-hermes-github-cricket-issues` polls open GitHub issues labeled
+  `cricket`.
+
+The resolver materializes these scripts into the generated config tree and
+links executable scripts into `~/.local/bin` when that target is managed by
+have-config. Store API tokens in the local environment or approved secret
+source; do not commit them.
+
 ## Secret Handling
 
 - Use Warden as the sharing standard for account passwords and shared secrets.

docs/infrastructure.md

@@ -12,7 +12,7 @@ per user or per agent and must stay out of git.
 | HappyVertical IDP | `https://idp.happyvertical.com` | Identity provider and SSO | Verify through browser/session or available connector |
 | Warden | `https://warden.happyvertical.com` | Password and shared secret access | Credential source; never print secret values |
 | OxiCloud | `https://drive.happyvertical.com` | File sharing | Use WebDAV-capable tooling such as `rclone` |
-| Vikunja | `https://todo.happyvertical.com` | Project management | Official CLI is server/container admin only; no remote task CLI selected yet |
+| Vikunja | `https://todo.happyvertical.com` | Project management | Official CLI is server/container admin only; have-config provides a reusable Hermes notification watcher |
 | Stoat | `https://stoat.happyvertical.com` | Chat and collaboration | No standard CLI selected yet |
 | Bifrost | `https://bifrost.happyvertical.com` | Gateway | No standard CLI selected yet |
 | Context Forge | `https://context.happyvertical.com` | Prompts, resources, and memory | Export install-time snapshots |
@@ -32,3 +32,10 @@ Context Forge is the dynamic source for organization prompt and resource policy.
 Installers should materialize snapshots into local generated files and record
 the selected content hash in `agent-lock.json`. Runtime agent behavior should
 not require live Context Forge access.
+
+## Reusable Operational Scripts
+
+have-config can materialize reusable operational scripts declared in
+`hv/manifest.json`. Current Hermes no-agent scripts poll Vikunja task updates
+and GitHub open issues labeled `cricket`; credentials must come from local
+environment variables or approved secret tooling.

hv/manifest.json

@@ -16,6 +16,22 @@
   ],
   "commands": [],
   "skills": [],
+  "scripts": [
+    {
+      "agent": "no-agent",
+      "name": "hv-hermes-vikunja-task-updates",
+      "path": "reusable-scripts/hermes/no-agent/hv-hermes-vikunja-task-updates",
+      "executable": true,
+      "description": "Poll Vikunja task updates for Hermes operators without requiring an agent runtime."
+    },
+    {
+      "agent": "no-agent",
+      "name": "hv-hermes-github-cricket-issues",
+      "path": "reusable-scripts/hermes/no-agent/hv-hermes-github-cricket-issues",
+      "executable": true,
+      "description": "Poll GitHub open issues labeled cricket without requiring an agent runtime."
+    }
+  ],
   "env_requirements": [
     {
       "capability": "happyvertical-identity",
@@ -103,7 +119,7 @@
       "purpose": "Project management.",
       "cli": {
         "status": "server-cli-only",
-        "notes": "The official Vikunja CLI is for server/container administration; no standard remote task CLI is selected yet."
+        "notes": "The official Vikunja CLI is for server/container administration; have-config provides hv-hermes-vikunja-task-updates for notification polling."
       }
     },
     {

profiles/hermes/manifest.json

@@ -22,6 +22,12 @@
       "name": "check-setup",
       "path": "skills/check-setup",
       "description": "Verify HappyVertical service access for this Hermes agent"
+    },
+    {
+      "agent": "codex",
+      "name": "hermes-ops",
+      "path": "skills/hermes-ops",
+      "description": "Operate Hermes scheduled pickup, blocked-task recovery, and no-agent watchers"
     }
   ],
   "env_requirements": [

profiles/hermes/skills/hermes-ops/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: hermes-ops
+description: Use when setting up or recovering Hermes operational watchers, Vikunja pickup state, or blocked task handling.
+metadata:
+  short-description: Hermes operational watcher procedure
+---
+
+# Hermes Operations Procedure
+
+Use this procedure for Hermes agents that pick up scheduled Vikunja work,
+recover blocked tasks, or run no-agent watcher scripts. Do not print or store
+tokens, cookies, passwords, or decrypted secret values.
+
+## Scheduled Vikunja Pickup State
+
+1. Check the current task state in Vikunja before starting work.
+   - Confirm the task is still assigned to this Hermes identity or explicitly
+     available for pickup.
+   - Read the latest task comments and activity before changing status.
+2. Record pickup in Vikunja with a short comment:
+   - agent identity or hostname
+   - intended next action
+   - expected next checkpoint time
+3. Keep state in Vikunja as the source of truth.
+   - Local state files are only watcher cursors.
+   - If local state disagrees with Vikunja, trust Vikunja and refresh the
+     watcher cursor.
+
+## Blocked Task Recovery
+
+1. Re-read the task, linked issue, and latest comments.
+2. Identify the first concrete blocker:
+   - missing credential or environment variable
+   - unavailable service
+   - ambiguous task scope
+   - failing dependency or upstream issue
+3. Add a Vikunja comment that names the blocker and the smallest next action.
+4. If a no-agent watcher is configured, verify it still reports updates after
+   the recovery comment.
+5. Do not mark a task unblocked until the required credential, service,
+   clarification, or dependency is actually available.
+
+## Watcher Setup
+
+The base have-config manifest provides these reusable no-agent scripts when
+the resolver runs:
+
+- `hv-hermes-vikunja-task-updates`
+- `hv-hermes-github-cricket-issues`
+
+The resolver links executable scripts into `~/.local/bin` when that location is
+managed by have-config. Use cron, systemd user timers, or the local scheduler
+already present on the host.
+
+Required local environment:
+
+- `HV_VIKUNJA_TOKEN` for Vikunja polling
+- `HV_VIKUNJA_URL` when not using `https://todo.happyvertical.com`
+- `GITHUB_TOKEN` or `GH_TOKEN` for GitHub polling when rate limits or private
+  repository access matter
+- `HV_HERMES_STATE_DIR` when watcher cursor files should live somewhere other
+  than `$XDG_STATE_HOME/hv` or `~/.local/state/hv`
+
+Recommended cadence:
+
+- Vikunja task updates: every 5 to 15 minutes
+- GitHub cricket-labeled issues: every 10 to 30 minutes
+
+Watcher state files are cursors, not task records. If a cursor is stale or
+corrupt, move it aside and run the watcher once to initialize from the current
+remote state.