HARNESS-SPEC Reference
Location:
~/.claude/HARNESS-SPEC.md
Current Version: 3.1
Format: Markdown with YAML/JSON/ASCII code blocks
What Is HARNESS-SPEC?
HARNESS-SPEC is the single canonical configuration document that describes every component of the godotz.ai harness on a given machine. It is a point-in-time snapshot of the full fleet node configuration: packages, plugins, hooks, agents, skills, model routing, optimization layers, memory backends, and tooling.
The document is not generated — it is authored and maintained by hand (or by the harness-legacy-scan workflow) and lives at ~/.claude/HARNESS-SPEC.md. When a session agent loads it, it has authoritative ground truth about what is installed, what version, and why each design decision was made.
It serves three purposes:
- Fleet baseline — establishes the exact state of a node so drift from this baseline can be detected
- Onboarding reference — lets a new session agent (or engineer) reconstruct full context without interrogating the filesystem
- Decision log — records design rationale in Section 24 so future changes have provenance
Section Overview
HARNESS-SPEC v3.1 contains 27 sections:
| § | Title | What it covers |
|---|---|---|
| 1 | Package Registry | Core packages: godotz.ai, OMC, Claude Code, Caveman, gstack, Knowledge Gardener, GLM Plan Usage, context7, Graphify — with versions and install commands |
| 2 | Configuration Files | All settings files: ~/.claude/settings.json (global), settings.local.json (local permissions), .omc-config.json (OMC runtime), project-level settings.json, godotz.ai agent/config.yml (hardcore preset), and 6 auxiliary config files |
| 3 | Plugins | 9 installed Claude Code plugins with IDs, versions, scope, and marketplace source |
| 4 | Hooks | All hook points: 5 global hooks, 2 project hooks, 24 OMC hook scripts across 11 event types, 3 Knowledge Gardener hooks, and the Caveman hook state |
| 5 | CLAUDE.md | Global context file structure — operating principles, delegation rules, model routing, Tier-0 skills, keyword triggers, kill switches |
| 6 | Agents | 32 total agents: 1 user-defined (evaluator), 20 OMC built-in, 3 Caveman (cavecrew-builder/investigator/reviewer), 8 godotz.ai Swarm agents across two workloads |
| 7 | Rules | TDD rule at ~/.claude/rules/tdd.md — RED-GREEN-REFACTOR, scope, exceptions |
| 8 | Workflows | 2 workflows: harness-legacy-scan.md (7-agent read-only audit) and harness-diet.md (low-risk cleanup) |
| 9 | 12-Layer Optimization Stack | Full architecture diagram + per-layer detail: preset toggle (L1), confidence-gate cascade (L2), pheromone routing (L3), semantic cache (L4), plan cache (L5), context engineering (L6), EMA tracker (L7), budget control (L8), regression gate (L9), context hydration (L10), Graphify knowledge graph (L11), orchestrate keyword (L12) |
| 10 | Model Architecture | Conversation models (Antigravity: opus/sonnet/gemini), worker models (GLM: glm-5.1/4.7/4.5-air), concurrency limits per model, vision fallback, swarm constraints, local GPU model |
| 11 | Swarm System | Two completed swarm workloads with DAG topology, phase descriptions, and execution results |
| 12 | Skills | 128 total skills: 27 user-defined, 41 OMC built-in (including 37 core + 4 additional), 60 gstack sub-skills with category breakdown |
| 13 | MCP Servers | 7 active MCP servers with tool counts: chrome (15), context7 (2), OMC bridge (49), web-reader (1), web-search-prime (1), zai-mcp-server (8), zread (3) |
| 14 | HUD | Status line configuration — command path, file size, helper library location |
| 15 | Memory System | All active memory backends: Mnemopi (SQLite + WAL), auto-resume, session mental model (8K tokens), Knowledge Vault (~/vault, 9 folders), session capture, auto-recap |
| 16 | Tool Scripts | 11 godotz.ai optimization scripts in ~/.local/bin/ with language, path, and purpose |
| 17 | Data Files | 17 data files in ~/.omp/ — JSON/YAML/SQLite — with types and contents |
| 18 | Kernel Tuning | 5 sysctl parameters tuned at /etc/sysctl.d/99-claude-optimization.conf |
| 19 | Daemons & Sessions | Claude Code daemon paths, session logs, history, background jobs, task state |
| 20 | Active Project | Current project (omp-playground): tech stack, source tree, and generated artifacts |
| 21 | Directory Tree | Full annotated directory listing of ~/.claude/, ~/.omp/, ~/.local/bin/, and project root |
| 22 | Execution Flow | End-to-end hook sequence diagram from session start through tool use, subagent lifecycle, compaction, and session end |
| 23 | Benchmark Results | 10 graded performance metrics (S/A grades) from the 12-layer optimization stack |
| 24 | Design Decisions | 8 architectural decisions with rationale — model split, compaction strategy, pheromone evaporation rate, etc. |
| 25 | Known Limitations | 8 documented limitations: Antigravity concurrency unknown, GPU excluded from subagents, pheromone DB test bias, regression placeholder tests, plan cache exact-match only, budget enforcement external only, cascade manual, config ceiling reached |
| 26 | Roadmap | 7 future items with status and dependencies: Self-Evaluating Controller, Adaptive Router, Prompt Evolution, Cross-Session Intelligence, Cost-Quality Pareto, A2A Protocol, large codebase testing |
| 27 | Statistics Summary | Aggregate counts across all categories — packages, plugins, agents, skills, hooks, rules, workflows, MCP servers, optimization scripts |
How to Read HARNESS-SPEC
Start with Section 27 (Statistics Summary) for a numeric inventory of what is present. This tells you the scale before diving into specifics.
Navigate by need:
- Troubleshooting a hook firing unexpectedly → Section 4
- Understanding why a model was chosen → Sections 10 and 24
- Adding a new plugin → Sections 3 and 2 (check marketplace sources)
- Auditing optimization scripts → Sections 9 and 16
- Inspecting memory behavior → Section 15
- Understanding execution order → Section 22 (execution flow diagram)
Code blocks are authoritative. The YAML in Section 2.5 (~/.omp/agent/config.yml) is the actual file content, not a summary. JSON blocks in Section 2 reproduce real settings.
Design decisions are documented in Section 24. Before changing a setting that seems arbitrary (e.g., pheromone evaporation rate = 0.05, compaction threshold = 180K tokens), check Section 24 first — the reasoning is there.
Relationship to Fleet Baseline Snapshots
HARNESS-SPEC is the fleet baseline snapshot format for godotz.ai nodes. Each time the configuration changes materially (new plugin, model update, optimization layer added), the spec is re-authored and the version number increments (v1.0 → v3.0 → v3.1).
Baseline drift detection works by diffing the current node state against the spec:
- Plugin versions in Section 3 vs.
installed_plugins.json - Model versions in Section 2.5 vs.
~/.omp/agent/config.yml - Script presence in Section 16 vs.
~/.local/bin/contents
The harness-legacy-scan workflow (Section 8) runs a 7-agent read-only audit that compares live state against the spec and surfaces drift, dead code, and overlap. The output informs harness-diet.md cleanup passes.
Multi-node fleets use per-node copies of HARNESS-SPEC. The document begins with a hardware/OS header (see v3.0: Linux x64, i9-12900K, RTX 3080, 30Gi RAM) that identifies the specific node. Diffing two HARNESS-SPEC documents reveals exactly what differs between fleet nodes.
Updating the Spec
HARNESS-SPEC is updated manually after significant configuration changes. The convention is:
- Run
harness-legacy-scanto get a current-state audit - Update the affected sections with exact values (versions, paths, counts)
- Add a row to Section 24 if the change reflects a design decision
- Increment the patch version in the document header
- Update the
Statistics Summary(Section 27) aggregate counts
The spec is not auto-generated because agent-authored prose in the design decisions, known limitations, and roadmap sections requires human judgment to keep accurate.