From 9ecd29361b46934f2d66cc630b3e909509874118 Mon Sep 17 00:00:00 2001
From: allaun <allaun@researchstack.info>
Date: Sun, 21 Jun 2026 01:27:21 -0500
Subject: [PATCH] feat(skills): add headroom autoloaded skill for Research
 Stack

Injects Headroom compression/memory usage into every session triggered by
Research Stack keywords.
---
 .opencode/skills/headroom/SKILL.md | 68 ++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 .opencode/skills/headroom/SKILL.md

diff --git a/.opencode/skills/headroom/SKILL.md b/.opencode/skills/headroom/SKILL.md
new file mode 100644
index 00000000..0683f76f
--- /dev/null
+++ b/.opencode/skills/headroom/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: headroom
+version: 1.0.0
+description: "Use Headroom context compression and cross-agent memory for every Research Stack session." 
+trigger_patterns:
+  - "Research Stack"
+  - "headroom"
+  - "compress"
+  - "context"
+  - "memory"
+  - "AGENTS.md"
+  - "lean"
+  - "Semantics"
+  - "Q16_16"
+  - "BraidStorm"
+  - "RRC"
+  - "PIST"
+  - "Finsler"
+  - "compression"
+  - "token"
+  - "receipt"
+  - "capability"
+  - "probe"
+platforms: [linux, macos, windows]
+metadata:
+  priority: high
+---
+
+# Headroom skill — auto-loaded for Research Stack
+
+Every Research Stack session should use Headroom for context compression and
+shared memory. The Headroom MCP server is registered in `.mcp.json` as
+`headroom` and exposes `headroom_compress`, `headroom_retrieve`, and
+`headroom_stats`.
+
+## When to compress
+
+- Before sending long tool outputs (lake build logs, grep results, diffs) to
+the user or to another model.
+- When conversation history exceeds ~50k tokens.
+- Before storing a receipt, decision, or lesson in ContextStream / ENE.
+
+## How to use the MCP tools
+
+1. `headroom_compress` — pass raw text; receive compressed text + a retrieval key.
+2. Send the compressed text onward (to user, to LLM, to ContextStream).
+3. If the consumer needs the original, call `headroom_retrieve` with the key.
+
+## Cross-agent memory
+
+Headroom shares a local store across Claude Code, Codex, Cursor, and OpenCode.
+When you capture a decision or lesson, consider compressing the rationale with
+`headroom_compress` before writing it to ContextStream, then store the retrieval
+key in the memory entry.
+
+## Learning from failures
+
+`headroom learn --project . --apply` mines recent failed sessions and writes
+corrections to the nearest AGENTS.md. Run it after a debugging or proof session
+that surfaced a recurring mistake.
+
+## Constraints
+
+- Do not compress secrets or API keys.
+- Do not treat compressed text as the source of truth; always keep the retrieval
+key alongside it.
+- Headroom is a compression layer, not a decision layer. Lean still owns formal
+and routing decisions.