sg-handoff

<img src="docs/assets/snowgloves-hero.png" width="100%" alt="Snow Gloves OS — Hand-In-Glove Business Operations Platform" />

Snow Gloves OS

Hand-In-Glove Business Operations Platform

<!-- og:image: docs/assets/snowgloves-og.png (upload via repo Settings → Social preview) -->

<!-- readme-gen:start:badges -->

<!-- readme-gen:end:badges -->

<!-- readme-gen:start:tech-stack --> <img src="https://skillicons.dev/icons?i=py,bash,yaml,rust,tauri,github,githubactions&theme=dark" alt="Tech Stack" /> <!-- readme-gen:end:tech-stack -->

<!-- readme-gen:start:social -->

<!-- readme-gen:end:social -->

Run a business as if a senior team were watching it 24/7. Snow Gloves OS is a reusable, tenant-scoped operations platform. It wraps your tools (G-Stack connectors), your knowledge (NVIDIA embeddings), your judgement (an interpretation layer), and your actions (Hermes + Paperclip orchestration), so events don't get dropped, decisions are auditable, and risky actions are gated. It is agent-agnostic: you pick the runtime (Claude Code, Codex, Cursor, OpenCode, Grok, Hermes, OpenClaw, or any other agent), and Snow Gloves renders its skills, MCP servers, and rules into that runtime's own format.

Docs for new users: snow-gloves-wiki — how to use the app and the ecosystem (install, pick a runtime, onboard, modules, a quiet week). Slides, audio, and video live there. The modules dashboard is the catalog, not the human guide.

The Infrastructure cockpit connects the playable Infra Block city to catalog, agent routing, runtime adapters, connector gates, scoped tenant metadata, wing profiles, activity records and acceptance evidence. Run python3 scripts/infra_cockpit.py and npm --prefix apps/infra-block run dev, then open http://127.0.0.1:18760/. The workspace supports source inspection and gate-checked proposal exports. Private instance metadata requires an explicit --data-root; execution and enablement remain outside this read-only interface.

<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12,13,14&height=2" width="100%" />

✨ Highlights

<table> <tr> <td width="50%" valign="top">

🧤 Hand-In-Glove

Seven specialized agents (CEO, CTO, Chief of Staff, Librarian, Interpreter, Dispatcher, Sentinel) work as one operations team, each with IDENTITY · SOUL · TOOLS · SKILLS · HEARTBEAT · MEMORY · EVOLUTION.

</td> <td width="50%" valign="top">

🧭 Skill Orchestration

A dedicated Chief of Staff routes four native snowgloves: skills via glob-matched hooks so CEO/CTO stay strategic. inference-sh and Explee are catalog packs, not core. Enable a module and it is callable across agents.

</td> </tr> <tr> <td width="50%" valign="top">

🗂 Modules & Catalog

132 catalog cards (skills, MCP servers, plugins, playbooks, connectors) harvested from X, Instagram, Field Theory, founders-kit, and marketingskills — including optional inference-sh and Explee packs. Every card is a pointer with a disposition: add, pointer, hold, or refuse.

</td> <td width="50%" valign="top">

🔀 Runtime Adapters

One adapter.yaml per runtime says where skills, MCP config, and rules live and which question tool drives plan mode. The founder picks the runtime; nothing is hard-wired to one agent.

</td> </tr> <tr> <td width="50%" valign="top">

🔌 G-Stack Connector Fabric

Composio-like scoped connectors (Gmail, Calendar, Drive, Slack, PMS, Accounting, HRIS). Per-capability risk + approval flags. Webhooks signed and verified.

</td> <td width="50%" valign="top">

🧠 NVIDIA Embeddings

Tenant-isolated vector index (nv-embedqa-e5-v5, 1024-dim). Plug into NVIDIA NIM with NVIDIA_API_KEY, or run offline with the deterministic stub backend.

</td> </tr> <tr> <td width="50%" valign="top">

🛰️ Hermes Event Bus

Minimal HTTP listener on port 4100 (scripts/hermes.py). POST /publish, GET /events, POST /test/e2e for end-to-end smoke. Every event is append-logged to _audit/hermes-events.jsonl.

</td> <td width="50%" valign="top">

🛡️ Sentinel Drift Sweep

Daily aggregation of hook usage, fallbacks, escalations, and top skills per agent. Auto-appended to each agent's EVOLUTION.md for self-improving loops.

</td> </tr> </table>

<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12,13,14&height=2" width="100%" />

🚀 Quick Start

git clone https://github.com/Sheshiyer/snow-gloves-os.git
cd snow-gloves-os
./scripts/install.sh              # deps + print next steps (does not go live)
make doctor                       # pre-flight
make smoke                        # bus up, test event, stub embed, Sentinel
make walk                         # machine-check CoS graph + native inner loops
make graph-upgrade                # learning-edge dry-run (constraints; hooks gated)
make onboard-prompt R=claude      # print the plan-mode interview for your runtime
make test                         # pytest

Fleet: three Mac minis

Snow Gloves runs on three office Mac minis by function (marketing, design, coding) over Tailscale. The Coding Mac hosts OmniRoute :20128 and Hermes :4100 for the whole fleet. A brand (tenant) is enabled on a wing (node), and make fleet-render W=<wing> T=<tenant> R=<runtime> writes that brand's modules and the wing's MCPs into the runtime's own files. Start with docs/fleet/README.md; make fleet-doctor tells a mini whether it is wired as its wing says.

New Mac Mini (use the product, do not compile Tauri): docs/MAC-MINI-SETUP.md. Emulate the desktop wizard on a dev Mac with make app-install then make app-dev — apps/onboarding/README.md. The fleet inventory is fleet.yaml in your private data checkout (template: fleet.example.yaml), and each wing's machine profile lives in nodes/ (nodes/<wing>/node.yaml; templates here, the instance copy in the data checkout wins).

Private data

This repository is the platform. Instance data (brand tenants, the fleet inventory and wing profiles, receipts, decisions, planning state) lives in a separate private checkout, snow-gloves-ops. Point the scripts at it:

export SNOWGLOVES_DATA=/path/to/snow-gloves-ops   # tenants/, fleet.yaml, nodes/, _audit/

Unset, everything resolves to this checkout and its public fixtures (_demo, acme, tryambakam-noesis), which the local validation commands use; make smoke and make walk always use the fixtures. The resolver is scripts/lib/paths.py; scripts/onboard.py, node_profile.py, graph_upgrade.py and upgrade.py also take --data DIR. Never commit tenants, fleet.yaml, receipts or planning state here.

Planned fresh-node CLI onboarding: layered setup plan and Claude start prompt. This covers an always-on Mac mini workspace, developer tooling, Temperance/OmniRoute, secrets, and selected brand capabilities. It is a planning candidate; the node bootstrap CLI is not implemented yet.

<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12,13,14&height=2" width="100%" />

<!-- readme-gen:start:architecture -->

🏗 Architecture

graph TD
  subgraph Runtime layer
    Ext[3rd-party app] -- signed webhook --> GS[G-Stack /webhook]
    GS -- normalized envelope --> Her[Hermes :4100]
    Her --> CoS[Chief of Staff<br/>skill-hooks.yaml]
    CoS -->|strategy| CEO
    CoS -->|technical| CTO
    CoS --> Lib[Librarian]
    CoS --> Int[Interpreter]
    CoS --> Dis[Dispatcher]
    CoS --> Sen[Sentinel]
    Dis --> PB[Paperclip Bridge<br/>:3100/api/tasks]
    Lib --> EW[NVIDIA Embed Worker]
    EW --> VI[(tenant vector-index.jsonl)]
    Her -- audit --> Log[(_audit/hermes-events.jsonl)]
    Log --> SS[Sentinel Sweep<br/>daily]
    SS --> Evo[(agents/*/EVOLUTION.md)]
  end

  subgraph Catalog and adapter layer
    Cards[catalog/cards/*.md] --> BC[build_catalog.py]
    Agents[agents/*/MANIFEST.yaml] --> BC
    Ad[adapters/*/adapter.yaml] --> BC
    BC --> MJ[(catalog/modules.json)]
    MJ --> Prompt[onboard.py --prompt runtime]
    Prompt --> Harvest[snowgloves-harvest.md]
    Harvest --> Apply[onboard.py --apply-harvest]
    Apply --> En[(tenants/slug/enabled.yaml<br/>runtime.yaml)]
    En --> Render[onboard.py --render-adapter]
    Ad --> Render
    Render --> RT[Runtime files:<br/>skills, MCP config, rules block]
    MJ --> Dash[Tauri dashboard + Pages site]
    En --> Gate[connector-gate]
  end

Four reusable engines

More detail: docs/architecture-overview.md.

<!-- readme-gen:end:architecture -->

🗂 Modules & Catalog

catalog/cards/<id>.md holds one card per third-party skill, MCP server, plugin, connector, or playbook. A card is a pointer, never a copy of upstream code. scripts/build_catalog.py compiles the cards, the agent manifests, the adapters, and the G-Stack connectors into catalog/registry.yaml and catalog/modules.json (schema snowgloves.modules.v1). Run make catalog-check locally to reject stale generated output.

By category: skills 79, playbook 36, plugin 13, mcp 3, connector 1. Optional packs inference-sh-agent-skills and explee-skills are add cards, not core hooks. Card schema: docs/catalog.md. Harvest notes: docs/research/2026-09-29-ecosystem-review.md.

🔀 Runtime Adapters & Onboarding

Snow Gloves does not assume an agent. Each runtime has adapters/<runtime>/adapter.yaml (schema snowgloves.adapter.v1): skill, MCP, and rules paths; file formats; the runtime's question tool; and how to enter plan mode. Shipped adapters: hermes, claude, codex, cursor, opencode, grok, openclaw, muse, generic. Fields nobody has confirmed against the real runtime are marked verify: true and reported on every render. The Muse adapter is a guess throughout.

Onboarding is a plan-mode interview run inside the project the founder has been building:

make onboard-prompt R=cursor                                        # 1. interview → snowgloves-harvest.md
python3 scripts/onboard.py --apply-harvest snowgloves-harvest.md --tenant acme   # 2. apply
python3 scripts/onboard.py --list --category skills                 # 3. adjust
python3 scripts/onboard.py --enable ms-copywriting --tenant acme
python3 scripts/onboard.py --render-adapter cursor --tenant acme    # 4. render (dry run)
python3 scripts/onboard.py --render-adapter cursor --tenant acme --write

The agent asks one decision at a time, takes options only from modules.json, and writes FILL: instead of guessing. See docs/onboarding.md and docs/adapters.md.

🖥 Dashboard

The native Tauri v2 app in apps/onboarding/ gains a Modules dashboard and a guided onboarding flow. Both read the same catalog/modules.json plus each tenant's enabled.yaml. The same data is published as a static site, built with make site (npm run build:site) previously published by GitHub Pages. Automatic publishing is retired; this URL retains its last published content until a separate local publisher is selected:

https://sheshiyer.github.io/snow-gloves-os/

make app-install   # one-time: npm install
make app-dev       # launch in dev mode (hot-reload frontend)
make app-build     # produce a signable release bundle
make site          # build the static Pages site locally

See its README for the IPC surface and capability list.

📦 Release & Upgrade

The root VERSION file (currently 0.2.1) is the platform version. The app's package.json, tauri.conf.json, Cargo.toml, both lockfiles, and distribution.yaml are kept in lockstep with it, and catalog/modules.json embeds it.

make release-dry V=0.2.1    # show every file that would change
make release V=0.2.1        # bump, rebuild catalog, finalize CHANGELOG, commit, tag v0.2.1
make release-push V=0.2.1   # push only; no automatic signing or publication
make upgrade                # dry-run tenant migrations to VERSION
make upgrade T=acme WRITE=1 # apply, rebuild catalog, re-render acme's adapters

The retired hosted release built signed Tauri installers and attached source, catalog, adapter, and checksum assets. Those publication jobs are no longer active. make app-build remains the local app build entry point; signing, cross-platform builds, updater latest.json, and publication require a separately reviewed local procedure. v0.2.0 is a reinstall for 0.1.x (new bundle id). See docs/RELEASING.md and docs/UPGRADING.md.

<!-- readme-gen:start:tree -->

📂 Project Structure

📦 snow-gloves-os
├── 📄 VERSION                  # platform version (0.2.1)
├── 📄 distribution.yaml        # what the platform owns vs what tenants own
├── 📂 .local-jobs/             # explicit local checks; schedules disabled
├── 📂 .specify/                # Spec-Kit templates + workflows
├── 📂 .planning/               # GSD state: local symlink into the private data checkout (gitignored)
├── 📂 agents/                  # 7 agents, each with 8+ md files + MANIFEST
├── 📂 adapters/                # one adapter.yaml per runtime (9)
├── 📂 catalog/                 # SCHEMA.md · cards/ (132) · registry.yaml · modules.json (generated)
├── 📂 prompts/                 # onboard-interview.md (plan-mode interview template)
├── 📂 migrations/              # v0_1_to_v0_2.py (bus rename to Hermes)
├── 📂 apps/onboarding/         # Tauri v2 app: onboarding + Modules dashboard, Pages site
├── 📂 connectors/g-stack/      # Capability registry + auth + webhooks
├── 📂 scripts/                 # hermes · ingest · embed · bridge · sentinel · build_catalog · onboard · release · upgrade
├── 📂 skills/                  # registry.yaml (4 native skills) · connector-gate · sg-onboard · tn-seed · gtm-brief-synthesis
├── 📂 workflows/               # skill-hooks.yaml — Chief of Staff graph
├── 📂 specs/                   # Spec-Kit features
├── 📂 docs/                    # architecture, catalog, adapters, onboarding, releasing, upgrading, research, runbooks
├── 📂 tenants/                 # Fixture tenants only; real tenants live in $SNOWGLOVES_DATA/tenants
├── 📂 nodes/                   # Wing profile templates (marketing, design, coding)
├── 📄 fleet.example.yaml       # Fleet inventory template (the real fleet.yaml is private)
├── 📂 tests/                   # pytest suite
├── 📂 _audit/                  # Append-only event log
├── 📄 config/snowgloves.yaml   # Runtime config (ports, embeddings, scopes)
└── 📄 Makefile                 # make smoke runs the whole loop

<!-- readme-gen:end:tree -->

<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12,13,14&height=2" width="100%" />

<!-- readme-gen:start:health -->

📊 Project Health

Overall: 70% — Stable v0.2.1 platform. Before a live pilot: confirm unverified adapter fields, and wire real connectors, NIM, and Paperclip.

<!-- readme-gen:end:health -->

Open items

• Bundle id (decided). The app id is com.tryambakam.snowgloves.onboarding (was com.thoughtseed.snowgloves.onboarding). v0.2.0 is a new app: existing 0.1.x users must reinstall from the DMG/MSI; OTA will not find 0.2.0.
• distribution.yaml lacks hermes_requires. Nothing declares which Hermes version or port a distribution needs yet. Do not set it in this release.
• Unverified adapter fields. Muse is a guess throughout; the OpenClaw question tool and plan mode, and Codex /plan, are unconfirmed. See docs/adapters.md.

🧪 Spec-Driven Development

This repo uses GitHub Spec-Kit. Available slash commands (in Copilot/Codex chat):

/speckit.constitution    /speckit.specify    /speckit.clarify
/speckit.plan            /speckit.tasks      /speckit.analyze
/speckit.checklist       /speckit.implement  /speckit.taskstoissues

Active feature: specs/001-hand-in-glove-platform.

📜 Constitution

7 principles govern every change:

1. Spec before code
2. Tenant isolation first
3. Interpretation before automation
4. Approval-gated risk
5. Auditability by default
6. Wiki as human control surface
7. Portable domain packs

See .specify/memory/constitution.md.

<!-- readme-gen:start:footer -->

<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,13,14&height=110&section=footer" width="100%" />

Built with ❤️ by Mage Narayan · Tryambakam Noesis

<!-- readme-gen:end:footer -->