pstack for Hermes

An independent Hermes-native port of Lauren Tan's (@poteto) pstack plugin. It preserves pstack's workflows and principles while translating Cursor-specific runtime mechanics to supported Hermes primitives.

Important

This is an independent community port, not an official Cursor or Nous Research release. Its authoritative baseline is the official cursor/plugins pstack subtree—not another Hermes port.

Provenance

Field	Value
Original author	Lauren Tan (@poteto)
Official source	cursor/plugins
Upstream version	0.14.5
Frozen commit	6fecddba65801f9b9c08b8b328d998ee5b09d290
License	MIT; retained in LICENSE
Port scope	157 upstream files; 50 registered Hermes skills

This repository is a direct, independently implemented Hermes adaptation of the official upstream files. It is not a fork of, or an improvement layered on top of, somebody else's Hermes port. UPSTREAM.lock.json pins the source identity. PORT-MAP.json records a deterministic copied/adapted/replaced/omitted disposition for every upstream file.

The frozen source includes upstream PR cursor/plugins#275, which moved make-bot-ui into the plugin's directly registered skills tree.

What you get

The plugin registers 50 namespaced skills, including:

• pstack:poteto-mode — select and run the broader pstack engineering playbooks.
• pstack:how — determine how to approach a task.
• pstack:architect — investigate architecture and produce a rationale.
• pstack:interrogate — challenge an implementation before shipping.
• pstack:swarm — independent multi-angle review.
• pstack:tdd — test-driven implementation workflow.
• pstack:make-bot-ui — build a UI around a signed Hermes webhook route.

The principles, personas, guides, playbooks, references, and deterministic support scripts remain traceable to upstream.

Install

Requirements:

• A current Hermes Agent installation.
• Git.
• Python 3 for port verification.
• Bun only if you want to run the bundled Poteto script tests.

Install as a user plugin:

mkdir -p ~/.hermes/plugins
git clone https://github.com/jmporchet/pstack-hermes.git \
  ~/.hermes/plugins/pstack

hermes plugins doctor ~/.hermes/plugins/pstack --ci
hermes plugins enable pstack --no-allow-tool-override
hermes plugins list --user --plain

Restart Hermes or start a fresh session after enabling the plugin. The plugin adds instructions and skills; it does not register tool overrides.

To update later:

git -C ~/.hermes/plugins/pstack pull --ff-only
hermes plugins doctor ~/.hermes/plugins/pstack --ci

Use

Ask Hermes to load a qualified skill by its full namespace:

Load pstack:how and help me choose an implementation approach.

Use pstack:architect to investigate this codebase and write a rationale.

Use pstack:poteto-mode for this bug-fix workflow.

Load pstack:make-bot-ui and design the private application-server integration.

Qualified names are intentional. They prevent collisions with built-in or user skills such as tdd, teach, or architect.

Why the skills may not appear in /skills

/skills is a discovery and management UI, not necessarily a complete view of every skill registered by every enabled plugin. Native plugin skills live behind the plugin manager and retain their namespace. Therefore a skill can be valid, enabled, and resolvable as pstack:how even when /skills does not display it as an unqualified top-level entry.

Use these checks instead:

hermes plugins list --user --plain
hermes plugins doctor ~/.hermes/plugins/pstack --ci

Then request the qualified name explicitly in a fresh session. Do not copy the 50 child skills into ~/.hermes/skills; doing so discards namespacing and risks collisions.

Architecture

flowchart LR
    U[User / Hermes session]
    PM[Hermes plugin manager]
    NS[pstack: namespace\n50 registered skills]
    WF[Skills + playbooks\nprinciples + references]
    DT[delegate_task\nprocess-local workers]
    KB[Kanban goal_mode\ndurable programs]
    CR[cronjob\nunattended schedules]

    UI[Browser UI\nuntrusted input]
    APP[Private application server\nallowlist + validation]
    WH[Hermes webhook\noperator-pinned loopback]

    U --> PM --> NS --> WF
    WF --> DT
    WF --> KB
    WF --> CR

    UI --> APP
    APP -->|HMAC-SHA256\n<timestamp>.<raw-body>\nrequest ID| WH
    WH --> NS

Loading

The browser never receives the Hermes webhook secret. A private application server validates and allowlists actions, serializes the body exactly once, and signs the exact transmitted bytes before forwarding to the operator-pinned loopback listener.

Cursor-to-Hermes translation

Upstream concept	Hermes port
Cursor /name skill	Qualified pstack:name plugin skill
Task, subagent_type, background agents	delegate_task with complete goals and process-local children
Per-child model field	Unsupported; use the active delegation configuration or separately configured profiles/processes
Cursor read-only mode	Behavioral no-write instruction unless a real external sandbox is used
Cursor transcript paths	Parent-owned session_search; bounded excerpts for delegated children
Sticky skill metadata	Unsupported metadata removed; continue from conversation context or reload the qualified skill
Cursor /loop automation	Hermes /loop is a user-invoked recurring in-session timer; the agent cannot invoke slash commands itself. Use /goal for one objective, Kanban goal_mode for durable iteration, and cronjob for unattended restart-safe schedules
Cursor Automations / Grok endpoint	Hermes dynamic webhook subscription with generic HMAC V2
Cloud or multi-day agents	Kanban assigned only to profiles that actually exist

See HERMES-COMPATIBILITY.md for the complete matrix.

Security and authority model

• Delegated children receive no remote credentials.
• The coordinator owns authorized pushes, PR creation and updates, comments, merges, deployments, and third-party messages.
• Every external write must be read back from its exact target before success is claimed.
• Destructive cleanup requires an exact inventory and explicit confirmation.
• A no-write review instruction is not described as a sandbox.
• Webhook secrets stay in Hermes secret handling or the private application server, never in browser code or committed files.
• Webhook V2 signs hexadecimal HMAC-SHA256 over <timestamp>.<raw-body> and uses X-Webhook-Timestamp, X-Webhook-Signature-V2, and a stable unique X-Request-ID for the logical retry sequence.
• UI payloads are untrusted; server actions and fields must be allowlisted.
• For this private UI pattern, the application server posts to 127.0.0.1:<actual-port>. Pin and verify platforms.webhook.extra.host=127.0.0.1; Hermes' default bind is not assumed to be loopback-only.

Deliberate tradeoffs

This port preserves workflow intent, not unsupported Cursor behavior:

• No sticky skill modes from frontmatter.
• No per-child model selector in delegate_task.
• Delegated children are process-local and do not survive parent termination.
• Hermes /loop is useful for recurring work inside a live session, but it is not the durability layer. Use Kanban or cron when restart survival matters.
• Distinct-model panels require deliberately configured profiles or processes; otherwise they are described as multi-angle reviews.
• Coordinator-owned external writes reduce autonomy but prevent unreviewed credential use and remote mutations.
• docs/benny/ is retained for source provenance. The registered Benny skills document the actual Hermes integration boundary; they do not pretend Cursor Automations were recreated.
• make-bot-ui replaces the source-specific automation endpoint with a generic, signed Hermes webhook design. The application server remains your code and responsibility.

Verify the port

For exact provenance validation, prepare the frozen official source:

mkdir -p ~/.hermes/workspace
git clone https://github.com/cursor/plugins.git \
  ~/.hermes/workspace/pstack-upstream
git -C ~/.hermes/workspace/pstack-upstream checkout \
  6fecddba65801f9b9c08b8b328d998ee5b09d290

Run the port checks:

cd ~/.hermes/plugins/pstack

python3 scripts/generate_port_map.py \
  --upstream ~/.hermes/workspace/pstack-upstream/pstack --write
python3 scripts/validate_port.py \
  --upstream ~/.hermes/workspace/pstack-upstream/pstack
python3 -m unittest -v scripts/test_port_tools.py

hermes plugins doctor "$PWD" --ci
hermes plugins list --user --plain

cd skills/poteto-mode/scripts
bun install --frozen-lockfile
bun test
bun run typecheck

The validator checks:

• Frozen upstream origin, exact commit, and clean pstack subtree.
• All 157 sorted, unique source mappings and their hashes.
• Canonical destinations independent of current destination-file existence.
• Exactly 50 registered skills and valid supported frontmatter.
• Local Markdown links and executable script permissions.
• Unsupported source-runtime contracts across skills and adapted guides.
• Coordinator-owned remote writes and conservative worktree cleanup.
• Exact webhook HMAC V2 semantics and fixed reference vectors.

Publication is gated on fresh, independent no-write spec and quality/security reviews of the exact release snapshot. Review outputs are operational evidence, not self-attested source artifacts.

License and attribution

Original pstack copyright and MIT license belong to its upstream contributors, including Lauren Tan (@poteto). This port retains the upstream LICENSE and provides source-level provenance rather than claiming original authorship of pstack itself.

Hermes Agent is a separate project by Nous Research. This community port is not endorsed by Cursor, Lauren Tan, or Nous Research unless they explicitly say so.