openhermes 2.8.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/CONTEXT.md +18 -0
  2. package/ETHOS.md +15 -0
  3. package/README.md +135 -292
  4. package/bootstrap.mjs +174 -512
  5. package/harness/agents/openhermes.md +87 -0
  6. package/harness/codex/CONSTITUTION.md +70 -148
  7. package/harness/codex/ROUTING.md +126 -0
  8. package/harness/commands/oh-doctor.md +26 -0
  9. package/harness/instructions/CONVENTIONS.md +206 -206
  10. package/harness/instructions/RUNTIME.md +54 -31
  11. package/harness/skills/oh-builder/SKILL.md +98 -0
  12. package/harness/skills/oh-caveman/SKILL.md +33 -0
  13. package/harness/skills/oh-expert/SKILL.md +121 -0
  14. package/harness/skills/oh-freeze/SKILL.md +28 -0
  15. package/harness/skills/oh-gauntlet/SKILL.md +119 -0
  16. package/harness/skills/oh-grill/SKILL.md +77 -0
  17. package/harness/skills/oh-guard/SKILL.md +33 -0
  18. package/harness/skills/oh-handoff/SKILL.md +33 -0
  19. package/harness/skills/oh-health/SKILL.md +90 -0
  20. package/harness/skills/oh-init/SKILL.md +78 -0
  21. package/harness/skills/oh-investigate/SKILL.md +35 -0
  22. package/harness/skills/oh-issue/SKILL.md +36 -0
  23. package/harness/skills/oh-learn/SKILL.md +28 -0
  24. package/harness/skills/oh-manifest/SKILL.md +84 -0
  25. package/harness/skills/oh-plan-review/SKILL.md +128 -0
  26. package/harness/skills/oh-planner/SKILL.md +159 -0
  27. package/harness/skills/oh-prd/SKILL.md +35 -0
  28. package/harness/skills/oh-retro/SKILL.md +33 -0
  29. package/harness/skills/oh-review/SKILL.md +110 -0
  30. package/harness/skills/oh-security/SKILL.md +110 -0
  31. package/harness/skills/oh-ship/SKILL.md +39 -0
  32. package/harness/skills/oh-skill-craft/SKILL.md +107 -0
  33. package/harness/skills/oh-skills-link/SKILL.md +29 -0
  34. package/harness/skills/oh-skills-list/SKILL.md +31 -0
  35. package/harness/skills/oh-triage/SKILL.md +36 -0
  36. package/index.mjs +3 -60
  37. package/lib/harness-resolver.mjs +77 -0
  38. package/lib/logger.mjs +62 -0
  39. package/package.json +49 -53
  40. package/test/plugins-behavioral.test.mjs +64 -0
  41. package/test/plugins.test.mjs +62 -0
  42. package/autorecall.mjs +0 -237
  43. package/curator.mjs +0 -482
  44. package/harness/commands/build-fix.md +0 -60
  45. package/harness/commands/checkpoint.md +0 -68
  46. package/harness/commands/code-review.md +0 -71
  47. package/harness/commands/doctor.md +0 -42
  48. package/harness/commands/eval.md +0 -89
  49. package/harness/commands/go-build.md +0 -87
  50. package/harness/commands/go-review.md +0 -71
  51. package/harness/commands/harness-audit.md +0 -90
  52. package/harness/commands/learn.md +0 -37
  53. package/harness/commands/loop-start.md +0 -38
  54. package/harness/commands/loop-status.md +0 -30
  55. package/harness/commands/memory-search.md +0 -37
  56. package/harness/commands/model-route.md +0 -32
  57. package/harness/commands/ohc.md +0 -13
  58. package/harness/commands/orchestrate.md +0 -88
  59. package/harness/commands/plan.md +0 -53
  60. package/harness/commands/quality-gate.md +0 -35
  61. package/harness/commands/refactor-clean.md +0 -102
  62. package/harness/commands/rust-build.md +0 -78
  63. package/harness/commands/rust-review.md +0 -65
  64. package/harness/commands/security.md +0 -93
  65. package/harness/commands/setup-pm.md +0 -65
  66. package/harness/commands/skill-create.md +0 -99
  67. package/harness/commands/test-coverage.md +0 -80
  68. package/harness/commands/update-codemaps.md +0 -81
  69. package/harness/commands/update-docs.md +0 -67
  70. package/harness/commands/verify.md +0 -68
  71. package/harness/prompts/architect.txt +0 -189
  72. package/harness/prompts/build-cpp.md +0 -98
  73. package/harness/prompts/build-error-resolver.md +0 -44
  74. package/harness/prompts/build-go.md +0 -340
  75. package/harness/prompts/build-java.md +0 -140
  76. package/harness/prompts/build-kotlin.md +0 -137
  77. package/harness/prompts/build-rust.md +0 -108
  78. package/harness/prompts/code-reviewer.md +0 -40
  79. package/harness/prompts/doc-updater.md +0 -206
  80. package/harness/prompts/docs-lookup.md +0 -71
  81. package/harness/prompts/e2e-runner.txt +0 -317
  82. package/harness/prompts/explore.md +0 -42
  83. package/harness/prompts/harness-optimizer.md +0 -42
  84. package/harness/prompts/loop-operator.md +0 -53
  85. package/harness/prompts/planner.md +0 -37
  86. package/harness/prompts/refactor-cleaner.md +0 -256
  87. package/harness/prompts/review-cpp.md +0 -81
  88. package/harness/prompts/review-database.md +0 -261
  89. package/harness/prompts/review-go.md +0 -257
  90. package/harness/prompts/review-java.md +0 -113
  91. package/harness/prompts/review-kotlin.md +0 -143
  92. package/harness/prompts/review-python.md +0 -101
  93. package/harness/prompts/review-rust.md +0 -77
  94. package/harness/prompts/security-reviewer.md +0 -42
  95. package/harness/prompts/tdd-guide.md +0 -228
  96. package/harness/rules/audit.md +0 -84
  97. package/harness/rules/checkpointing.md +0 -75
  98. package/harness/rules/context-loading.md +0 -33
  99. package/harness/rules/credential-exposure.md +0 -0
  100. package/harness/rules/delegation.md +0 -80
  101. package/harness/rules/handoff.md +0 -267
  102. package/harness/rules/memory-management.md +0 -28
  103. package/harness/rules/precedence.md +0 -52
  104. package/harness/rules/promotion.md +0 -46
  105. package/harness/rules/ranking.md +0 -64
  106. package/harness/rules/retrieval.md +0 -94
  107. package/harness/rules/runtime-guards.md +0 -196
  108. package/harness/rules/self-heal.md +0 -79
  109. package/harness/rules/session-start.md +0 -34
  110. package/harness/rules/skills-management.md +0 -165
  111. package/harness/rules/state-drift.md +0 -192
  112. package/harness/rules/verification.md +0 -88
  113. package/harness/scripts/sync-commands.mjs +0 -259
  114. package/harness/skills/.bundled_manifest +0 -17
  115. package/harness/skills/.usage.json +0 -6
  116. package/harness/skills/api-design/SKILL.md +0 -523
  117. package/harness/skills/backend-patterns/SKILL.md +0 -598
  118. package/harness/skills/coding-standards/SKILL.md +0 -549
  119. package/harness/skills/e2e-testing/SKILL.md +0 -326
  120. package/harness/skills/frontend-patterns/SKILL.md +0 -642
  121. package/harness/skills/frontend-slides/SKILL.md +0 -184
  122. package/harness/skills/security-review/SKILL.md +0 -495
  123. package/harness/skills/strategic-compact/SKILL.md +0 -131
  124. package/harness/skills/tdd-workflow/SKILL.md +0 -463
  125. package/harness/skills/verification-loop/SKILL.md +0 -126
  126. package/lib/ambient-memory.mjs +0 -167
  127. package/lib/handoff.mjs +0 -171
  128. package/lib/hardening.mjs +0 -146
  129. package/lib/memory-tools-plugin.mjs +0 -368
  130. package/lib/ohc/block-sync.mjs +0 -69
  131. package/lib/ohc/compress/search.mjs +0 -152
  132. package/lib/ohc/compress/state.mjs +0 -76
  133. package/lib/ohc/config.mjs +0 -185
  134. package/lib/ohc/message-ids.mjs +0 -178
  135. package/lib/ohc/notify.mjs +0 -135
  136. package/lib/ohc/protected-patterns.mjs +0 -55
  137. package/lib/ohc/prune-apply.mjs +0 -134
  138. package/lib/ohc/pruner.mjs +0 -608
  139. package/lib/ohc/reaper.mjs +0 -70
  140. package/lib/ohc/state.mjs +0 -265
  141. package/lib/ohc/strategies/deduplication.mjs +0 -72
  142. package/lib/ohc/strategies/index.mjs +0 -2
  143. package/lib/ohc/strategies/purge-errors.mjs +0 -43
  144. package/lib/ohc/token-utils.mjs +0 -26
  145. package/lib/ohc/updater.mjs +0 -132
  146. package/lib/paths.mjs +0 -49
  147. package/lib/schema-validator.mjs +0 -79
  148. package/lib/search.mjs +0 -48
  149. package/schemas/audit.schema.json +0 -82
  150. package/schemas/backlog.schema.json +0 -63
  151. package/schemas/checkpoint.schema.json +0 -65
  152. package/schemas/constraint.schema.json +0 -62
  153. package/schemas/decision.schema.json +0 -63
  154. package/schemas/instinct.schema.json +0 -63
  155. package/schemas/loop-state.schema.json +0 -33
  156. package/schemas/mistake.schema.json +0 -64
  157. package/schemas/verification_receipt.schema.json +0 -88
  158. package/skill-builder.mjs +0 -88
@@ -1,196 +0,0 @@
1
- # Runtime Guards — Prevent Stale Assumptions and Silent Failures
2
-
3
- ## Problem Statement
4
- OpenHermes agents often operate on cached assumptions that become stale:
5
- - "npm install is available" → but npm registry is down or rate-limited
6
- - "git fetch works" → but remote repository was deleted or moved
7
- - "Python 3.10 exists" → but path changed to Python 3.12
8
- - "Provider endpoint reachable" → but load balancer rotated certificates
9
-
10
- These stale assumptions cause:
11
- - Silent failures (agent retries indefinitely)
12
- - Wasted compute (re-running commands that will fail anyway)
13
- - Incorrect behavior based on outdated information
14
-
15
- ## Guard Enforcement
16
-
17
- ### 1. Session Initialization Constraint
18
- At session start, create active constraint with `enforcement: hard`:
19
- ```json
20
- {
21
- "id": "runtime-guards-session",
22
- "class": "constraint",
23
- "project": "current-project",
24
- "summary": "Runtime guards for stale assumption prevention",
25
- "constraints": [
26
- {
27
- "name": "never_cache_tool_state",
28
- "description": "Every tool call → fresh verification, no cache lookup",
29
- "enforcement": "hard"
30
- },
31
- {
32
- "name": "environment_fingerprint_required",
33
- "description": "Record OS, shell, cwd, provider, model at session start",
34
- "enforcement": "hard"
35
- }
36
- ]
37
- }
38
- ```
39
-
40
- ### 2. Pre-Tool-Call Check (Mandatory)
41
- Before any tool invocation:
42
- ```javascript
43
- // In agent execution loop
44
- function beforeToolCall(toolName, args) {
45
- // Verify environment matches session fingerprint
46
- const envMatch = verifyEnvironmentFingerprint()
47
- if (!envMatch) {
48
- // Environment changed mid-session → hard fail or restart
49
- throw new Error('Runtime guard: environment mismatch detected')
50
- }
51
-
52
- // Never trust cached tool results across sessions
53
- return { allow: true, fingerprint: generateFingerprint() }
54
- }
55
- ```
56
-
57
- ### 3. Compression Guard (Critical)
58
- Before adding verification receipts to compress buffer:
59
- ```javascript
60
- function filterReceiptForCompression(receipt) {
61
- // Check if receipt contains stale environment markers
62
- const hasStaleEnv = /\b(node_version|python_path|npm_registry)\b/.test(receipt.result_detail)
63
-
64
- // Redact or remove stale artifacts before compression
65
- if (hasStaleEnv) {
66
- report.warn(`Excluding stale artifact from compress buffer: ${receipt.id}`)
67
- return false
68
- }
69
-
70
- return true
71
- }
72
- ```
73
-
74
- ### 4. State Drift Detection (Post-Compression)
75
- After each `compress` operation:
76
- ```javascript
77
- function detectStateDrift(compressedBuffer) {
78
- const fingerprints = computeFingerprints(compressedBuffer.receipts)
79
-
80
- // Check for new environment markers that weren't in last fingerprint
81
- const driftMarkers = [
82
- /\b(node_version:.*?)(?!\b)/,
83
- /\b(python_path:.*?)(?!\b)/,
84
- /\b(npm_registry:.*?)(?!\b)/
85
- ]
86
-
87
- for (const marker of driftMarkers) {
88
- const matches = marker.exec(compressedBuffer.receipts)
89
- if (matches && !lastFingerprint.includes(matches[0])) {
90
- report.error(`State drift detected: ${matches[0]}`)
91
- // Either revert compression or flag for manual review
92
- return { drifted: true, marker: matches[0] }
93
- }
94
- }
95
-
96
- lastFingerprint = fingerprints
97
- return { drifted: false }
98
- }
99
- ```
100
-
101
- ## Enforcement Points
102
-
103
- ### Memory Write (ohc_save)
104
- ```javascript
105
- // In openhermes-memory MCP server
106
- function putMemoryObject(obj) {
107
- // Check for stale environment markers before persisting
108
- if (hasStaleEnvironmentMarker(obj.content)) {
109
- obj.content = redactStaleMarkers(obj.content)
110
- obj.stale = true
111
- }
112
- }
113
- ```
114
-
115
- ### Compress Event
116
- ```javascript
117
- // In OpenHermes's built-in dynamic-context-pruning plugin
118
- function onCompress() {
119
- const compressBuffer = buildSummary()
120
- // Filter out stale artifacts before adding to buffer
121
- const filteredBuffer = compressBuffer.filter(receipt =>
122
- !hasStaleEnvironmentMarker(receipt.result_detail)
123
- )
124
- return filteredBuffer
125
- }
126
- ```
127
-
128
- ### Session Resume (Recovery)
129
- On session resume or checkpoint recovery:
130
- ```javascript
131
- // Load all active memory objects
132
- const loadedObjects = loadMemory()
133
- // Immediately re-verify environment fingerprint for each receipt
134
- const safeObjects = loadedObjects.map(obj => ({
135
- ...obj,
136
- summary: redactStaleEnvironmentFromSummary(obj.summary)
137
- }))
138
- ```
139
-
140
- ## Fail-Safe Mechanisms
141
-
142
- ### 1. Pattern Mismatch / False Negatives
143
- **What if a new stale marker pattern emerges?**
144
- - Add to `staleMarkers` array immediately (no deployment cycle needed)
145
- - Run retrospective scan on last 30 days of memory objects
146
- - Flag affected objects for manual review + redaction
147
-
148
- ### 2. Over-Redaction / False Positives
149
- **What if legitimate data gets blocked?**
150
- - Allow explicit bypass via constraint: `enforce_runtime_guards: false` (rare use case)
151
- - Log all rejections to audit trail for review
152
- - Provide CLI command: `/openhermes-audit` for staleness checks
153
-
154
- ### 3. Memory Corruption During Redaction
155
- **What if redaction process itself fails?**
156
- - Fall back to raw receipts (`opencode.db`) with full pattern matching
157
- - Never silently skip redaction — always log and fail-closed
158
-
159
- ## Configuration & Overrides
160
-
161
- | Config | Default | Override |
162
- |--------|---------|----------|
163
- | `enforce_runtime_guards` | true | Constraint or environment variable |
164
- | `stale_marker_patterns_path` | rules/state-drift.md | Custom JSON/YAML file |
165
- | `retrospective_scan_days` | 30 | 7-90 |
166
- | `allow_bypass_paths` | [] (empty) | List of paths always excluded from filtering |
167
-
168
- ## Compliance & Audit
169
-
170
- Every redacted memory object must include:
171
- ```json
172
- {
173
- "redacted_at": "2026-05-09T07:30:00Z",
174
- "redaction_version": "1.0.0",
175
- "patterns_applied": ["node_version", "python_path", ...],
176
- "original_checksum": "sha256(original_content)"
177
- }
178
- ```
179
-
180
- This allows:
181
- - Forensic reconstruction of what was redacted
182
- - Verification that no legitimate data was accidentally blocked
183
- - Audit trail for compliance requirements (SOC2, HIPAA, PCI)
184
-
185
- ## Integration with Other Rules
186
-
187
- - `rules/verification.md`: Add "stale: true" to verification receipt schema
188
- - `rules/state-drift.md`: Hash computation must exclude stale markers
189
- - `commands/doctor.md`: Include fingerprint and staleness checks in the doctor workflow
190
-
191
- ---
192
-
193
- **Status**: Active (enforcement: hard)
194
- **Scope**: Global
195
- **Created**: 2026-05-09T07:31:00Z
196
- **Author**: agent (auto-generated via gap analysis)
@@ -1,79 +0,0 @@
1
- # Self-Heal — Escalating Tier Model
2
-
3
- Self-correction escalates through structured tiers. There is no self-termination. The system recovers by reducing risk, narrowing behavior, and preserving receipts.
4
-
5
- ## Tier 0 — Observe & Correct
6
-
7
- **Trigger**: Any single mistake or unexpected outcome.
8
-
9
- **Actions**:
10
- 1. Observe the issue — note what happened vs. what was expected.
11
- 2. Log a structured mistake record to `memory\mistakes\mistakes.jsonl` with root cause, fix, and prevention.
12
- 3. Attempt the smallest safe correction (one-line fix preferred, one-function max).
13
- 4. Verify the correction resolved the issue.
14
-
15
- **Outcome**: Issue resolved. Mistake logged for future parity checks.
16
-
17
- ## Tier 1 — Add Prevention
18
-
19
- **Trigger**: Same mistake type repeats within 7 days, or correction at T0 failed.
20
-
21
- **Actions**:
22
- 1. Review the existing mistake record(s) for the type.
23
- 2. Add or refine a prevention rule — either a constraint record or a documented guard.
24
- 3. Run targeted verification against the original failure scenario.
25
- 4. If prevention rule already existed and failed → escalate to T2.
26
-
27
- **Outcome**: Prevention rule active. Targeted verification passed.
28
-
29
- ## Tier 2 — Diagnosis & Review
30
-
31
- **Trigger**: Prevention failed, systemic issue suspected, repeated uncertainty, or conflicting constraints.
32
-
33
- **Actions**:
34
- 1. Delegate to specialist subagent for diagnosis:
35
- - Build failure → `build-error-resolver`
36
- - Logic/scope/other → `diagnose` skill + `code-reviewer`
37
- - Security → `security-reviewer`
38
- - Config/tool → `harness-optimizer` + openhermes audit
39
- 2. If structural (affects openhermes behavior across projects), generate a backlog item.
40
- 3. Run an openhermes audit to check for broken references, stale constraints, or provenance gaps.
41
- 4. Document findings and updated prevention rules.
42
-
43
- **Outcome**: Root cause identified. Prevention rules hardened. Backlog item created if structural.
44
-
45
- ## Tier 3 — Constrained Safe Mode
46
-
47
- **Trigger**: Repeated T2 escalation without resolution, or cascading failures across domains.
48
-
49
- **Actions**:
50
- 1. Enter constrained safe mode:
51
- - Narrow claims: only claim what is verified.
52
- - Narrow actions: single-step operations only, no multi-file changes.
53
- - Preserve receipts: log every action with provenance.
54
- 2. Produce a handoff-with-report:
55
- - What happened (timeline of failures)
56
- - What was attempted (T0, T1, T2 actions + results)
57
- - Current state (what works, what doesn't)
58
- - Recommended next action (human decision required)
59
- - All mistake records and audit results attached
60
- 3. Do NOT continue autonomous work. Wait for human intervention or explicit override.
61
-
62
- **Outcome**: Clean handoff state. System preserved. Human can resume without forensic reconstruction.
63
-
64
- ## Self-Heal Principles
65
-
66
- - **Recover by reducing risk**: Narrow scope, add constraints, reduce ambition. Never widen scope to fix a problem.
67
- - **No grandstanding**: Don't re-litigate decisions, don't blame tools, don't produce essay-length explanations. Terse, factual reports.
68
- - **Preserve receipts**: Every tier escalation must be backed by logged evidence (mistake records, audit results, verification outputs).
69
- - **No self-termination**: The session may be paused, constrained, or handed off, but never unilaterally terminated.
70
-
71
- ## Self-Edit Authority (Repeated for Reference)
72
-
73
- | Tier | Allowed |
74
- |------|---------|
75
- | Unconditional | Append memory entries, mistake records, checkpoints, audit receipts |
76
- | Conditional | Patch openhermes docs, schemas, templates, non-core rules; repair stale references in approved openhermes zones |
77
- | Human approval required | Core AGENTS.md changes, model routing, permissions, major config, protected user-owned settings |
78
-
79
- Full authority matrix is also in AGENTS.md.
@@ -1,34 +0,0 @@
1
- # Session-Start Checklist
2
-
3
- Run this at the start of every new session and every resume before substantive work.
4
-
5
- ## Checklist
6
-
7
- 1. Read `%USERPROFILE%\.config\opencode\AGENTS.md` and keep it active as the router.
8
- 2. Load openhermes status from `%USERPROFILE%\.config\opencode\ohc.json` if rule paths or memory locations are needed.
9
- 3. **Read autorecall cache**: If `openhermes\memory\recall\cache.json` exists, load it — it contains active checkpoint, constraints, decisions, and mistakes from the prior session. The autorecall plugin writes this at session start. Use this context before probing MCP tools.
10
- 4. Check only the smallest relevant curated memory slice in `openhermes\memory\`:
11
- - latest checkpoint via `ohc_latest`
12
- - active decisions via `ohc_latest` or a narrow `ohc_search`
13
- - active constraints via `ohc_latest` or a narrow `ohc_search`
14
- - recent same-type mistakes only if the task matches a known pattern
15
- - do not read whole memory indexes unless the task is explicitly about index auditing or repair
16
- 5. If no relevant memory exists, proceed fresh without pretending there is prior state.
17
- 6. If last openhermes audit is missing or older than 7 days, flag `/harness-audit` as due.
18
- 7. Before substantial work, choose the smallest correct path:
19
- - native read/grep/glob for search/gather
20
- - `explore` subagent for multi-file analysis
21
- - specialist subagent for substantive implementation, review, or diagnosis
22
-
23
- ## User Entry Points
24
-
25
- - `/openhermes`: bootstrap openhermes state, summarize current readiness, and surface due actions.
26
- - `/harness-audit`: run an openhermes audit workflow and return findings.
27
-
28
- ## Output Contract
29
-
30
- Keep session-start output terse:
31
- - current openhermes state
32
- - memory found or not found
33
- - audit freshness
34
- - immediate next action
@@ -1,165 +0,0 @@
1
- # Skills Management — SKILL.md Format, Progressive Disclosure, Agent-Managed Lifecycle
2
-
3
- Sources: Hermes Agent SKILL.md frontmatter standard, progressive disclosure (L0/L1/L2), agent-managed skill lifecycle.
4
-
5
- ## SKILL.md Frontmatter Format
6
-
7
- Every skill MUST have YAML frontmatter with these fields:
8
-
9
- ```yaml
10
- ---
11
- name: my-skill
12
- description: One-line description of what this skill does
13
- version: 1.0.0
14
- author: agent # "agent" if auto-created, "user" if hand-authored
15
- tags: [testing, python] # Search/discovery tags
16
- category: development # Category grouping in skills directory
17
- trigger: # Keywords that trigger loading this skill
18
- - test
19
- - tdd
20
- - coverage
21
- requires_tools: # Toolsets this skill needs to function
22
- - terminal
23
- config: # Optional config settings
24
- - key: my.setting
25
- description: What this controls
26
- default: "value"
27
- ---
28
- ```
29
-
30
- ### Field Reference
31
-
32
- | Field | Required | Type | Description |
33
- |-------|----------|------|-------------|
34
- | `name` | yes | string | Unique skill name, used as directory name |
35
- | `description` | yes | string | One-line description shown in skill index |
36
- | `version` | no | string | Semver for curated skills |
37
- | `author` | no | string | "agent", "user", or origin identifier |
38
- | `tags` | no | string[] | Search/discovery tags |
39
- | `category` | no | string | Grouping category |
40
- | `trigger` | no | string[] | Keywords that trigger progressive load (Tier 0→Tier 1) |
41
- | `requires_tools` | no | string[] | Toolsets that must be present; skill is hidden when absent |
42
- | `fallback_for` | no | string[] | Show this skill ONLY when listed toolsets are unavailable |
43
- | `config` | no | object[] | Declared config settings injected on load |
44
-
45
- ### Platform Restriction
46
-
47
- Skills can restrict themselves to specific OS platforms:
48
-
49
- ```yaml
50
- platforms: [windows] # Windows only
51
- platforms: [windows, linux] # Windows and Linux
52
- ```
53
-
54
- When set, the skill is hidden on incompatible platforms. If omitted, loads on all platforms.
55
-
56
- ### Conditional Activation (Fallback Skills)
57
-
58
- Skills can auto-show/hide based on available tools:
59
-
60
- ```yaml
61
- fallback_for: [web] # Show ONLY when web tools are unavailable
62
- requires_tools: [terminal] # Show ONLY when terminal tools are available
63
- ```
64
-
65
- Example: A `web-search` skill with `fallback_for: [web]` stays hidden when web_search tool is available. When the tool is missing (no API key), the skill automatically appears as an alternative.
66
-
67
- ## Progressive Disclosure Loading
68
-
69
- Skills use a token-efficient loading pattern inspired by Hermes:
70
-
71
- ```
72
- Tier 0: Skill directory listing → names, descriptions, categories, tags (from frontmatter)
73
- Do: read skills/<name>/SKILL.md frontmatter on demand
74
- Cost: ~200 tokens for 11 skills
75
-
76
- Tier 1: Full SKILL.md content → load the markdown body when:
77
- - User triggers a trigger keyword (matching `trigger` field)
78
- - User explicitly names the skill or runs `/skill-name`
79
- - A subtask or command references it
80
- Cost: Varies by skill (1-5K tokens)
81
-
82
- Tier 2: Reference files → load scripts/, templates/, references/ only when:
83
- - Executing the skill's procedure
84
- - The skill instructs you to read a specific file
85
- Cost: Varies
86
- ```
87
-
88
- ### Trigger-Table Lazy Loading
89
-
90
- Instead of preloading all skills at session start, use the trigger table:
91
-
92
- | Trigger keyword | Skill to load | Condition |
93
- |----------------|---------------|-----------|
94
- | "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
95
- | "security", "auth", "xss" | security-review | Security-related work |
96
- | "verify", "build", "lint" | verification-loop | Build/before-PR context |
97
-
98
- ### Duplicate Instruction Prevention
99
-
100
- Before loading a skill, check if its instructions are already covered by:
101
- - AGENTS.md rules already in context
102
- - Another skill already loaded this session
103
-
104
- If overlap is detected, skip loading to avoid context bloat.
105
-
106
- ## Agent-Managed Skill Lifecycle
107
-
108
- The agent can create, update, and delete skills during sessions. This is the skill system's self-improvement loop.
109
-
110
- ### When to Create a Skill
111
-
112
- - After completing a complex task (5+ tool calls) successfully
113
- - When you hit errors/dead ends and found the working path
114
- - When the user corrected your approach
115
- - When you discovered a non-trivial workflow
116
-
117
- ### Skill Management Operations
118
-
119
- | Operation | Method | Use for |
120
- |-----------|--------|---------|
121
- | **Create** | Write `skills/<name>/SKILL.md` | New skill from scratch |
122
- | **Patch** | Edit specific text in `skills/<name>/SKILL.md` | Targeted fixes (preferred over full rewrite) |
123
- | **Edit** | Full rewrite of `skills/<name>/SKILL.md` | Major structural changes |
124
- | **Delete** | Remove `skills/<name>/` | Remove a skill (only if superseded; prefer archival) |
125
- | **Add reference** | Write `skills/<name>/references/<file>` | Supporting documentation |
126
- | **Add template** | Write `skills/<name>/templates/<file>` | Output format templates |
127
- | **Add script** | Write `skills/<name>/scripts/<file>` | Helper scripts |
128
-
129
- ### Minimum Threshold for Creation
130
-
131
- - Never create a skill from a single data point.
132
- - Minimum: 3 verified successes or 3 same-type mistakes in 7 days.
133
- - Check existing skills via `ohc_search` before creating to avoid duplicates.
134
-
135
- ### Skill Quality Gates
136
-
137
- Every skill must have:
138
- 1. Complete frontmatter with name, description, tags, trigger keywords
139
- 2. A "When to Use" section with clear trigger conditions
140
- 3. A "Procedure" section with step-by-step instructions
141
- 4. A "Verification" section describing how to confirm it works
142
- 5. A "Pitfalls" section noting known failure modes
143
-
144
- ## Skill Directory Structure
145
-
146
- ```
147
- skills/
148
- ├── <name>/
149
- │ ├── SKILL.md ← required
150
- │ ├── references/ ← additional docs
151
- │ ├── templates/ ← output formats
152
- │ └── scripts/ ← helper scripts
153
- ```
154
-
155
- Skills live in three locations (discovered by OpenCode):
156
- - Project: `.opencode/skills/<name>/SKILL.md`
157
- - Global opencode: `~/.config/opencode/skills/<name>/SKILL.md`
158
- - Global agents: `~/.agents/skills/<name>/SKILL.md`
159
-
160
- ## Verification
161
-
162
- After creating or updating a skill:
163
- 1. Run the workflow defined in the SKILL.md.
164
- 2. Verify it produces the expected outcome.
165
- 3. Write a verification receipt via `ohc_save` with class `verification_receipt`.
@@ -1,192 +0,0 @@
1
- # State Drift Detection — Hash-Based Environment Fingerprinting
2
-
3
- ## Problem Statement
4
- Compression accumulates verification receipts across sessions. Without drift detection, the same receipt content gets compressed repeatedly even when:
5
- - Environment changed (node 18 → node 20, Python 3.9 → 3.11)
6
- - File system state drifted (git commit hash changed)
7
- - Provider credentials rotated (API key in verification detail)
8
-
9
- This creates "phantom" compressed data that references stale environments.
10
-
11
- ## Solution: Hash-Based Fingerprinting
12
-
13
- ### Environment Fingerprint Schema
14
- ```json
15
- {
16
- "fingerprint": {
17
- "cwd": "C:/path/to/project",
18
- "harness_root": "%USERPROFILE%\\.config\\opencode",
19
- "project_root": "C:/path/to/project",
20
- "project": "my-project",
21
- "session_id": "session-123",
22
- "os": "win32",
23
- "release": "10.0.26100",
24
- "arch": "x64",
25
- "shell": "cmd.exe",
26
- "provider": "lmstudio",
27
- "model": "openhermes-1.x",
28
- "sha256": "..."
29
- }
30
- }
31
- ```
32
-
33
- ### Fingerprint Generation (Pre-Compression)
34
- ```javascript
35
- function generateEnvironmentFingerprint() {
36
- const cwd = process.cwd()
37
- const provider = process.env.OPENCODE_PROVIDER || 'lmstudio'
38
- const model = process.env.OPENCODE_MODEL || null
39
-
40
- return hash(
41
- `${cwd}${provider}${model || ''}`
42
- )
43
- }
44
- ```
45
-
46
- ### Hash-Based Drift Detection (Post-Compression)
47
- ```javascript
48
- function detectHashDrift(compressedSummary, lastFingerprint) {
49
- const currentFingerprint = generateEnvironmentFingerprint()
50
-
51
- if (!lastFingerprint || currentFingerprint !== lastFingerprint) {
52
- // Environment changed since last compression
53
- return { drift: true, oldFp: lastFingerprint, newFp: currentFingerprint }
54
- }
55
-
56
- return { drift: false }
57
- }
58
- ```
59
-
60
- ## Enforcement Points
61
-
62
- ### Compress Event (Primary Guard)
63
- ```javascript
64
- // In OpenHermes's built-in dynamic-context-pruning plugin
65
- function onCompress() {
66
- // Generate fresh fingerprint before compressing
67
- const currentFp = generateEnvironmentFingerprint()
68
-
69
- if (!lastFp || currentFp !== lastFp) {
70
- // Drift detected → abort compression or truncate buffer
71
- report.warn(`State drift: environment changed from ${lastFp} to ${currentFp}`)
72
- return { truncated: true, reason: 'environment_drift' }
73
- }
74
-
75
- lastFp = currentFp
76
- }
77
- ```
78
-
79
- ### Memory Write (Secondary Guard)
80
- ```javascript
81
- // In openhermes-memory MCP server
82
- funtion putMemoryObject(obj) {
83
- // Attach fingerprint to all new memory objects
84
- obj.fingerprint = generateEnvironmentFingerprint()
85
-
86
- // Compare against last compressed buffer's fingerprint
87
- if (!lastCompressedFp || obj.fingerprint !== lastCompressedFp) {
88
- // New environment → flag for review or redact stale content
89
- obj.stale_content_redacted = true
90
- }
91
- }
92
- ```
93
-
94
- ### Session Resume (Recovery)
95
- ```javascript
96
- // On session resume / checkpoint recovery
97
- function recoverFromCheckpoint(checkpointData) {
98
- const lastFp = checkpointData.lastCompressedFingerprint
99
- const currentFp = generateEnvironmentFingerprint()
100
-
101
- if (!lastFp || currentFp !== lastFp) {
102
- // Environment changed since checkpoint was created
103
- report.warn(`Resume from checkpoint with environment drift: ${lastFp} → ${currentFp}`)
104
- // Redact any compressed summaries that reference stale environments
105
- redactStaleCompressedSummaries()
106
- }
107
- }
108
- ```
109
-
110
- ## Hash Algorithm Selection
111
-
112
- ### Recommended: SHA-256 (cryptographically strong, fast enough) ```javascript
113
- const fingerprint = sha256(
114
- `${os.family}${os.version}${cwd}${gitState?.commit_hash}`
115
- ).substring(0, 16) // Truncate to 16 hex chars for readability
116
- ```
117
-
118
- ### Alternatives (if performance needed)
119
- - **MD5**: Faster but weaker collision resistance. Use only if fingerprint is never displayed.
120
- - **CRC32**: Extremely fast, but collisions possible. Not recommended unless hash space is tiny.
121
-
122
- ### Hash Space Considerations
123
- - With SHA-256 truncated to 16 hex chars → 4^16 = ~4.3 billion unique fingerprints
124
- - Collision probability after N compressions ≈ N² / (8 × 2³¹) via birthday paradox
125
- - For typical sessions (<100,000 compresses), collision risk < 1e-5
126
-
127
- ## Performance Characteristics
128
-
129
- | Operation | Time | Notes |
130
- |-----------|------|-------|
131
- | Generate fingerprint | ~5ms | Dominated by filesystem stat calls |
132
- | SHA-256 hash computation | ~0.5ms | Negligible compared to I/O |
133
- | Store in memory object | <1ms | Just a string assignment |
134
-
135
- ## Fail-Safe Mechanisms
136
-
137
- ### 1. Hash Collision (Extremely Rare)
138
- **What if two different environments produce same fingerprint?**
139
- - Use full SHA-256 for audit logging, truncated value for quick comparison
140
- - Log collision event with both hashes and manual review required
141
- - Store in `memory/audits/collision-events.json`
142
-
143
- ### 2. Fingerprint Computation Failure
144
- **What if filesystem stat fails (permission denied)?**
145
- - Fall back to previous valid fingerprint
146
- - Log error but continue operation
147
- - Schedule full drift check on next checkpoint
148
-
149
- ### 3. Hash Algorithm Change
150
- **What if we upgrade from SHA-256 to SHA-3?**
151
- - Include hash algorithm identifier in fingerprint metadata
152
- - Parse both old and new format during resume
153
- - Migrate gracefully without data loss
154
-
155
- ## Configuration & Overrides
156
-
157
- | Config | Default | Override |
158
- |--------|---------|----------|
159
- | `fingerprint_hash_algo` | "sha256" | "md5", "crc32" (performance mode only) |
160
- | `truncated_fingerprint_len` | 16 | 8, 4, 0 (full hash) |
161
- | `allow_drift_bypass` | false | Set to true for testing or known-good drift scenarios |
162
-
163
- ## Compliance & Audit
164
-
165
- Every compressed summary must include:
166
- ```json
167
- {
168
- "fingerprint_at_compression": "fp_abc123def456",
169
- "hash_algorithm": "sha256",
170
- "truncated_length": 16,
171
- "drift_detected": false,
172
- "redaction_applied": false
173
- }
174
- ```
175
-
176
- This allows:
177
- - Forensic reconstruction of environment at compression time
178
- - Verification that no phantom data exists in compressed buffer
179
- - Audit trail for compliance requirements (NIST, SOC2)
180
-
181
- ## Integration with Other Rules
182
-
183
- - `rules/verification.md`: Fingerprint must be attached to all verification receipts
184
- - `rules/runtime-guards.md`: Hash-based drift detection prevents credential exposure
185
- - `commands/doctor.md`: Include fingerprint checks in the doctor workflow
186
-
187
- ---
188
-
189
- **Status**: Active (enforcement: hard)
190
- **Scope**: Global
191
- **Created**: 2026-05-09T07:31:00Z
192
- **Author**: agent (auto-generated via gap analysis)