winter-super-cli 2026.6.26 → 2026.6.28

package/resources/local/hermes-agent-core/skills/software-development/hermes-s6-container-supervision/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: hermes-s6-container-supervision
+description: Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understanding the Architecture B main-program pattern.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [docker, s6, supervision, gateway, profiles]
+    related_skills: [hermes-agent, hermes-agent-dev]
+---
+
+# Hermes s6-overlay Container Supervision
+
+## When to use this skill
+
+Load this skill when you're working on:
+- Adding or removing a static service in the Hermes Docker image (something that should be supervised at every container start, like the dashboard)
+- Diagnosing why a per-profile gateway isn't starting, restarting, or surviving `docker restart`
+- Understanding why the container's CMD is `/opt/hermes/docker/main-wrapper.sh` and how leading-dash args reach the user's program
+- Modifying `cont-init.d` boot scripts (UID remap, volume seeding, profile reconciliation)
+- Changing the rendered run-script for per-profile gateways (Phase 4)
+
+If you're just running the Hermes Agent and want to use Docker, see `website/docs/user-guide/docker.md` instead.
+
+## Architecture at a glance
+
+```
+/init                                  ← PID 1 (s6-overlay v3.2.3.0)
+├── cont-init.d                        ← oneshot setup, runs as root
+│   ├── 01-hermes-setup                ← docker/stage2-hook.sh
+│   │   ├── UID/GID remap
+│   │   ├── chown /opt/data
+│   │   ├── chown /opt/data/profiles (every boot)
+│   │   ├── seed .env / config.yaml / SOUL.md
+│   │   └── skills_sync.py
+│   └── 02-reconcile-profiles          ← hermes_cli.container_boot
+│       ├── chown /run/service (hermes-writable for runtime register)
+│       └── walk $HERMES_HOME/profiles/<name>/gateway_state.json
+│           → recreate /run/service/gateway-<name>/
+│           → auto-start only those with prior_state == "running"
+│
+├── s6-rc.d (static services, in /etc/s6-overlay/s6-rc.d/)
+│   ├── main-hermes/run                ← exec sleep infinity (no-op slot)
+│   └── dashboard/run                  ← if HERMES_DASHBOARD=1, runs `hermes dashboard`
+│
+├── /run/service (s6-svscan watches; tmpfs)
+│   ├── gateway-coder/                 ← runtime-registered per-profile
+│   │   ├── type        ("longrun")
+│   │   ├── run         ("#!/command/with-contenv sh ... exec s6-setuidgid hermes hermes -p coder gateway run")
+│   │   ├── down        (marker — present means "registered but don't auto-start")
+│   │   └── log/run     (s6-log → $HERMES_HOME/logs/gateways/coder/current)
+│   └── ...
+│
+└── CMD ("main program")               ← /opt/hermes/docker/main-wrapper.sh
+    └── routes user args: bare exec | hermes subcommand | hermes (no args)
+        — exec'd by /init with stdin/stdout/stderr inherited (TTY for --tui)
+```
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `Dockerfile` | s6-overlay install + cont-init.d wiring + `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]` |
+| `docker/stage2-hook.sh` | The "old entrypoint logic" — UID remap, chown, seed, skills sync. Runs as cont-init.d/01-hermes-setup. |
+| `docker/cont-init.d/02-reconcile-profiles` | Calls `hermes_cli.container_boot` on every boot to restore profile gateway slots from the persistent volume. |
+| `docker/main-wrapper.sh` | The container's CMD. Routes user args, drops to hermes via `s6-setuidgid`, exec's the chosen program. |
+| `docker/s6-rc.d/main-hermes/run` | No-op `sleep infinity` — slot exists so the s6-rc user bundle is valid; main hermes runs as the CMD, not as a supervised service. |
+| `docker/s6-rc.d/dashboard/run` | Conditional service — `exec sleep infinity` unless `HERMES_DASHBOARD` is truthy. |
+| `docker/entrypoint.sh` | Back-compat shim that `exec`s the stage2 hook. External scripts that hard-coded the old entrypoint path still work. |
+| `hermes_cli/service_manager.py` | `S6ServiceManager`: `register_profile_gateway`, `unregister_profile_gateway`, `start/stop/restart/is_running`, `list_profile_gateways`. |
+| `hermes_cli/container_boot.py` | `reconcile_profile_gateways()` — walks persistent profiles, regenerates s6 slots, emits `container-boot.log`. |
+| `hermes_cli/gateway.py::_dispatch_via_service_manager_if_s6` | Intercepts `hermes gateway start/stop/restart` and routes to s6 when running in a container. |
+
+## Why Architecture B (CMD as main program, not s6-supervised)
+
+The original plan (v1–v3) called for main hermes to run as a supervised s6-rc service. Two real s6-overlay v3 mechanics blocked that:
+
+1. **cont-init.d scripts receive no CMD args** — so the stage2 hook can't parse `docker run <image> chat -q "hi"` to set `HERMES_ARGS` for a service `run` script to consume.
+2. **`/run/s6/basedir/bin/halt` does NOT propagate the exit code** written to `/run/s6-linux-init-container-results/exitcode`. Containers always exit 143 (SIGTERM) regardless. Confirmed by skarnet (s6 author) in [issue #477](https://github.com/just-containers/s6-overlay/issues/477): _"if you want a container shutdown, you need to either have your CMD exit, or, if you have no CMD, write the container exit code you want then call halt"_.
+
+So we use the s6-overlay-native CMD pattern: `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]`. /init prepends the wrapper to user args automatically — so `docker run <image> --version` becomes `/init main-wrapper.sh --version`, and `--version` doesn't get intercepted by /init's POSIX shell. The wrapper drops to hermes via `s6-setuidgid`, then exec's the chosen program. The program's exit code becomes the container exit code, exactly matching the pre-s6 tini contract.
+
+Trade-off: main hermes is unsupervised under s6. That exactly matches its behavior under tini (the pre-s6 image). Dashboard supervision is the only **new** guarantee — and per-profile gateways under `/run/service/` get full supervision.
+
+## Quick recipes
+
+### Verify s6 is PID 1 in a running container
+
+```sh
+docker exec <c> sh -c 'cat /proc/1/comm; readlink /proc/1/exe'
+# Expect: s6-svscan or init / /package/admin/s6/.../s6-svscan
+```
+
+### Inspect a profile gateway service
+
+```sh
+# /command/ isn't on docker-exec PATH — use absolute path
+docker exec <c> /command/s6-svstat /run/service/gateway-<name>
+# "up (pid …) … seconds"            → running
+# "down (exitcode N) … seconds, normally up, want up, …" → s6 wants it up but the process keeps exiting (crash loop)
+# "down … normally up, ready …"     → user stopped it
+```
+
+### Bring a service up/down manually
+
+```sh
+docker exec <c> /command/s6-svc -u /run/service/gateway-<name>   # up
+docker exec <c> /command/s6-svc -d /run/service/gateway-<name>   # down
+docker exec <c> /command/s6-svc -t /run/service/gateway-<name>   # SIGTERM (restart)
+```
+
+### Watch the cont-init reconciler log
+
+```sh
+docker exec <c> tail -n 50 /opt/data/logs/container-boot.log
+# 2026-05-21T06:18:05+0000 profile=coder prior_state=running action=started
+# 2026-05-21T06:18:05+0000 profile=writer prior_state=stopped action=registered
+```
+
+### Add a new static service
+
+1. Create `docker/s6-rc.d/<name>/type` with `longrun\n` and `docker/s6-rc.d/<name>/run` (use `#!/command/with-contenv sh` + `# shellcheck shell=sh`).
+2. Drop to hermes via `s6-setuidgid hermes` at the top of run (unless you specifically need root).
+3. Create empty `docker/s6-rc.d/<name>/dependencies.d/base` so it waits for the base bundle.
+4. Create empty `docker/s6-rc.d/user/contents.d/<name>` so it joins the user bundle.
+5. The `COPY docker/s6-rc.d/` in the Dockerfile picks it up automatically — no other changes.
+
+### Change the per-profile gateway run command
+
+Edit `S6ServiceManager._render_run_script` in `hermes_cli/service_manager.py`. The function is also called by `hermes_cli/container_boot.py::_register_service` during boot reconciliation, so it's the single source of truth. Update the corresponding assertion in `tests/hermes_cli/test_service_manager.py::test_s6_register_creates_service_dir_and_triggers_scan`.
+
+### Run the docker test harness
+
+```sh
+docker build -t hermes-agent-harness:latest .
+HERMES_TEST_IMAGE=hermes-agent-harness:latest scripts/run_tests.sh tests/docker/ -v
+# Expect 19 passed, 0 xfailed against the s6 image
+```
+
+The harness lives in `tests/docker/` and skips when Docker isn't available. The per-test timeout is bumped to 180s (see `tests/docker/conftest.py`).
+
+## Common pitfalls
+
+### "command not found" via `docker exec`
+
+`/command/` (where s6-overlay puts its binaries) is on PATH only for processes spawned by the supervision tree — services, cont-init.d, main-wrapper.sh. `docker exec <c> s6-svstat …` will fail with "command not found"; always use the absolute path `/command/s6-svstat`. The `hermes` binary works because the Dockerfile adds `/opt/hermes/.venv/bin` to the runtime `ENV PATH`.
+
+### Profile directory ownership
+
+The cont-init reconciler runs as hermes (`s6-setuidgid hermes` in `02-reconcile-profiles`). If a profile dir ends up root-owned (e.g. because `docker exec <c> hermes profile create …` ran as root by default), the reconciler can't read SOUL.md and fails with `PermissionError`. Mitigation: `stage2-hook.sh` chowns `$HERMES_HOME/profiles` to hermes on **every** boot, idempotently. Don't remove that block.
+
+### Files written by `docker exec` are root-owned
+
+`docker exec` defaults to root. Either pass `--user hermes` or rely on the stage2 chown sweep next reboot. Don't write files under `$HERMES_HOME/profiles/<name>/` as root manually — the next reconcile pass will sweep them but in-flight operations may hit perm errors.
+
+### Service slot exists but s6-svstat says "s6-supervise not running"
+
+The service directory is on tmpfs and was wiped on container restart. Either the cont-init reconciler hasn't run yet (give it a moment after `docker restart`) or it failed. Check `docker logs <c> | grep '02-reconcile'`.
+
+### Gateway starts then immediately exits (`down (exitcode 1)` in svstat)
+
+Most likely the profile has no model or auth configured. The service slot is correct — the gateway itself is unconfigured. Run `hermes -p <profile> setup` first. The s6 supervisor will keep restarting it; that's the desired behavior (when you fix the config, the next attempt succeeds and stays up).
+
+### Reconciler skipped a profile
+
+The reconciler keys on the **presence of `SOUL.md`** as the "real profile" marker. `hermes profile create` always seeds it. If a profile dir is missing SOUL.md (stray directory, partial restore, backup-in-progress), the reconciler skips it intentionally. Add a `SOUL.md` (even empty) to opt back in.
+
+### "Help, the container exits 143!"
+
+Check whether something is invoking `s6-svscanctl -t` or `/run/s6/basedir/bin/halt` — both cause /init to begin stage 3 shutdown but return 143 (SIGTERM) rather than the desired exit code. This was the Phase 2 architecture pivot from A to B. For container shutdown with a real exit code, you must let the CMD (main-wrapper.sh) exit normally; do **not** try to control exit from a finish script.
+
+## Related skills
+
+- `hermes-agent-dev`: General hermes-agent codebase navigation
+- `hermes-tool-quirks`: Specific Hermes-tool workarounds (sed/grep/etc.) — load when debugging the s6 stack's interaction with hermes built-in tools.

package/resources/local/hermes-agent-core/skills/software-development/node-inspect-debugger/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: node-inspect-debugger
+description: "Debug Node.js via --inspect + Chrome DevTools Protocol CLI."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [debugging, nodejs, node-inspect, cdp, breakpoints, ui-tui]
+    related_skills: [systematic-debugging, python-debugpy, debugging-hermes-tui-commands]
+---
+
+# Node.js Inspect Debugger
+
+## Overview
+
+When `console.log` isn't enough, drive Node's built-in V8 inspector programmatically from the terminal. You get real breakpoints, step in/over/out, call-stack walking, local/closure scope dumps, and arbitrary expression evaluation in the paused frame.
+
+Two tools, pick one:
+
+- **`node inspect`** — built-in, zero install, CLI REPL. Best for quick poking.
+- **`ndb` / CDP via `chrome-remote-interface`** — scriptable from Node/Python; best when you want to automate many breakpoints, collect state across runs, or debug non-interactively from an agent loop.
+
+**Prefer `node inspect` first.** It's always available and the REPL is fast.
+
+## When to Use
+
+- A Node test fails and you need to see intermediate state
+- ui-tui crashes or behaves wrong and you want to inspect React/Ink state pre-render
+- tui_gateway child processes (`_SlashWorker`, PTY bridge workers) misbehave
+- You need to inspect a value in a closure that `console.log` can't reach without patching
+- Perf: attach to a running process to capture a CPU profile or heap snapshot
+
+**Don't use for:** things `console.log` solves in under a minute. Breakpoint-driven debugging is heavier; use it when the payoff is real.
+
+## Quick Reference: `node inspect` REPL
+
+Launch paused on first line:
+
+```bash
+node inspect path/to/script.js
+# or with tsx
+node --inspect-brk $(which tsx) path/to/script.ts
+```
+
+The `debug>` prompt accepts:
+
+| Command | Action |
+|---|---|
+| `c` or `cont` | continue |
+| `n` or `next` | step over |
+| `s` or `step` | step into |
+| `o` or `out` | step out |
+| `pause` | pause running code |
+| `sb('file.js', 42)` | set breakpoint at file.js line 42 |
+| `sb(42)` | set breakpoint at line 42 of current file |
+| `sb('functionName')` | break when function is called |
+| `cb('file.js', 42)` | clear breakpoint |
+| `breakpoints` | list all breakpoints |
+| `bt` | backtrace (call stack) |
+| `list(5)` | show 5 lines of source around current position |
+| `watch('expr')` | evaluate expr on every pause |
+| `watchers` | show watched expressions |
+| `repl` | drop into REPL in current scope (Ctrl+C to exit REPL) |
+| `exec expr` | evaluate expression once |
+| `restart` | restart script |
+| `kill` | kill the script |
+| `.exit` | quit debugger |
+
+**In the `repl` sub-mode:** type any JS expression, including access to locals/closure variables. `Ctrl+C` exits back to `debug>`.
+
+## Attaching to a Running Process
+
+When the process is already running (e.g. a long-lived dev server or the TUI gateway):
+
+```bash
+# 1. Send SIGUSR1 to enable the inspector on an existing process
+kill -SIGUSR1 <pid>
+# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid>
+
+# 2. Attach the debugger CLI
+node inspect -p <pid>
+# or by URL
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+To start a process with the inspector from the beginning:
+
+```bash
+node --inspect script.js           # listen on 127.0.0.1:9229, keep running
+node --inspect-brk script.js       # listen AND pause on first line
+node --inspect=0.0.0.0:9230 script.js   # custom host:port
+```
+
+For TypeScript via tsx:
+
+```bash
+node --inspect-brk --import tsx script.ts
+# or older tsx
+node --inspect-brk -r tsx/cjs script.ts
+```
+
+## Programmatic CDP (scripting from terminal)
+
+When you want to automate — set many breakpoints, capture scope state, script a repro — use `chrome-remote-interface`:
+
+```bash
+npm i -g chrome-remote-interface        # or project-local
+# Start your target:
+node --inspect-brk=9229 target.js &
+```
+
+Driver script (save as `/tmp/cdp-debug.js`):
+
+```javascript
+const CDP = require('chrome-remote-interface');
+
+(async () => {
+  const client = await CDP({ port: 9229 });
+  const { Debugger, Runtime } = client;
+
+  Debugger.paused(async ({ callFrames, reason }) => {
+    const top = callFrames[0];
+    console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`);
+
+    // Walk scopes for locals
+    for (const scope of top.scopeChain) {
+      if (scope.type === 'local' || scope.type === 'closure') {
+        const { result } = await Runtime.getProperties({
+          objectId: scope.object.objectId,
+          ownProperties: true,
+        });
+        for (const p of result) {
+          console.log(`  ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description);
+        }
+      }
+    }
+
+    // Evaluate an expression in the paused frame
+    const { result } = await Debugger.evaluateOnCallFrame({
+      callFrameId: top.callFrameId,
+      expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"',
+    });
+    console.log('state =', result.value ?? result.description);
+
+    await Debugger.resume();
+  });
+
+  await Runtime.enable();
+  await Debugger.enable();
+
+  // Set a breakpoint by URL regex + line
+  await Debugger.setBreakpointByUrl({
+    urlRegex: '.*app\\.tsx$',
+    lineNumber: 119,       // 0-indexed
+    columnNumber: 0,
+  });
+
+  await Runtime.runIfWaitingForDebugger();
+})();
+```
+
+Run it:
+
+```bash
+node /tmp/cdp-debug.js
+```
+
+Hermes-specific note: `chrome-remote-interface` is NOT in `ui-tui/package.json`. Install it to a throwaway location if you don't want to dirty the project:
+
+```bash
+mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface
+NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js
+```
+
+## Debugging Hermes ui-tui
+
+The TUI is built Ink + tsx. Two common scenarios:
+
+### Debugging a single Ink component under dev
+
+`ui-tui/package.json` has `npm run dev` (tsx --watch). Add `--inspect-brk` by running tsx directly:
+
+```bash
+cd /home/bb/hermes-agent/ui-tui
+npm run build    # produce dist/ once so transpile isn't needed on first load
+node --inspect-brk dist/entry.js
+# In another terminal:
+node inspect -p <node pid>
+```
+
+Then inside `debug>`:
+
+```
+sb('dist/app.js', 220)     # or wherever the suspect render is
+cont
+```
+
+When it pauses, `repl` → inspect `props`, state refs, `useInput` handler values, etc.
+
+### Debugging a running `hermes --tui`
+
+The TUI spawns Node from the Python CLI. Easiest path:
+
+```bash
+# 1. Launch TUI
+hermes --tui &
+TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1)
+
+# 2. Enable inspector on that Node PID
+kill -SIGUSR1 "$TUI_PID"
+
+# 3. Find the WS URL
+curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl'
+
+# 4. Attach
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+Interacting with the TUI (typing in its window) continues to advance execution; your debugger can pause it on a breakpoint at any `sb(...)`.
+
+### Debugging `_SlashWorker` / PTY child processes
+
+Those are Python, not Node — use the `python-debugpy` skill for them. Only Node portions (Ink UI, tui_gateway client, tsx-run tests under `ui-tui/`) use this skill.
+
+## Running Vitest Tests Under the Debugger
+
+```bash
+cd /home/bb/hermes-agent/ui-tui
+# Run a single test file paused on entry
+node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx
+```
+
+In another terminal: `node inspect -p <pid>`, then `sb('src/app/foo.tsx', 42)`, `cont`.
+
+Use `--no-file-parallelism` (vitest) or `--runInBand` (jest) so only one worker exists — debugging a pool is painful.
+
+## Heap Snapshots & CPU Profiles (Non-interactive)
+
+From the CDP driver above, swap Debugger for `HeapProfiler` / `Profiler`:
+
+```javascript
+// CPU profile for 5 seconds
+await client.Profiler.enable();
+await client.Profiler.start();
+await new Promise(r => setTimeout(r, 5000));
+const { profile } = await client.Profiler.stop();
+require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile));
+// Open /tmp/cpu.cpuprofile in Chrome DevTools → Performance tab
+```
+
+```javascript
+// Heap snapshot
+await client.HeapProfiler.enable();
+const chunks = [];
+client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk));
+await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false });
+require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join(''));
+```
+
+## Common Pitfalls
+
+1. **Wrong line numbers in TS source.** Breakpoints hit the emitted JS, not the `.ts`. Either (a) break in the built `dist/*.js`, or (b) enable sourcemaps (`node --enable-source-maps`) and use `sb('src/app.tsx', N)` — but only with CDP clients that follow sourcemaps. `node inspect` CLI does not.
+
+2. **`--inspect` vs `--inspect-brk`.** `--inspect` starts the inspector but doesn't pause; your script races past your first breakpoint if you attach too late. Use `--inspect-brk` when you need to set breakpoints before any code runs.
+
+3. **Port collisions.** Default is `9229`. If multiple Node processes are inspecting, pass `--inspect=0` (random port) and read the actual URL from `/json/list`:
+   ```bash
+   curl -s http://127.0.0.1:9229/json/list   # lists all inspectable targets on the host
+   ```
+
+4. **Child processes.** `--inspect` on a parent does NOT inspect its children. Use `NODE_OPTIONS='--inspect-brk' node parent.js` to propagate to every child; be aware they all need unique ports (Node auto-increments when `NODE_OPTIONS='--inspect'` is inherited).
+
+5. **Background kills.** If you `Ctrl+C` out of `node inspect` while the target is paused, the target stays paused. Either `cont` first, or `kill` the target explicitly.
+
+6. **Running `node inspect` through an agent terminal.** It's a PTY-friendly REPL. In Hermes, launch it with `terminal(pty=true)` or `background=true` + `process(action='submit', data='...')`. Non-PTY foreground mode will work for one-shot commands but not for interactive stepping.
+
+7. **Security.** `--inspect=0.0.0.0:9229` exposes arbitrary code execution. Always bind to `127.0.0.1` (the default) unless you have an isolated network.
+
+## Verification Checklist
+
+After setting up a debug session, verify:
+
+- [ ] `curl -s http://127.0.0.1:9229/json/list` returns exactly the target you expect
+- [ ] First breakpoint actually hits (if it doesn't, you likely missed `--inspect-brk` or attached after execution completed)
+- [ ] Source listing at pause shows the right file (mismatch = sourcemap issue, see pitfall 1)
+- [ ] `exec process.pid` in `repl` returns the PID you meant to attach to
+
+## One-Shot Recipes
+
+**"Why is this variable undefined at line X?"**
+```bash
+node --inspect-brk script.js &
+node inspect -p $!
+# debug>
+sb('script.js', X)
+cont
+# paused. Now:
+repl
+> myVariable
+> Object.keys(this)
+```
+
+**"What's the call path into this function?"**
+```
+debug> sb('suspectFn')
+debug> cont
+# paused on entry
+debug> bt
+```
+
+**"This async chain hangs — where?"**
+```
+# Start with --inspect (no -brk), let it run to the hang, then:
+debug> pause
+debug> bt
+# Now you see the stuck frame
+```

package/resources/local/hermes-agent-core/skills/software-development/plan/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: plan
+description: "Plan mode: write markdown plan to .hermes/plans/, no exec."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [planning, plan-mode, implementation, workflow]
+    related_skills: [writing-plans, subagent-driven-development]
+---
+
+# Plan Mode
+
+Use this skill when the user wants a plan instead of execution.
+
+## Core behavior
+
+For this turn, you are planning only.
+
+- Do not implement code.
+- Do not edit project files except the plan markdown file.
+- Do not run mutating terminal commands, commit, push, or perform external actions.
+- You may inspect the repo or other context with read-only commands/tools when needed.
+- Your deliverable is a markdown plan saved inside the active workspace under `.hermes/plans/`.
+
+## Output requirements
+
+Write a markdown plan that is concrete and actionable.
+
+Include, when relevant:
+- Goal
+- Current context / assumptions
+- Proposed approach
+- Step-by-step plan
+- Files likely to change
+- Tests / validation
+- Risks, tradeoffs, and open questions
+
+If the task is code-related, include exact file paths, likely test targets, and verification steps.
+
+## Save location
+
+Save the plan with `write_file` under:
+- `.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md`
+
+Treat that as relative to the active working directory / backend workspace. Hermes file tools are backend-aware, so using this relative path keeps the plan with the workspace on local, docker, ssh, modal, and daytona backends.
+
+If the runtime provides a specific target path, use that exact path.
+If not, create a sensible timestamped filename yourself under `.hermes/plans/`.
+
+## Interaction style
+
+- If the request is clear enough, write the plan directly.
+- If no explicit instruction accompanies `/plan`, infer the task from the current conversation context.
+- If it is genuinely underspecified, ask a brief clarifying question instead of guessing.
+- After saving the plan, reply briefly with what you planned and the saved path.