Kernel Reference
The universal structure behind harness.os. Four harness types, five cross-cutting concerns, the inner/outer boundary, and how subtypes specialize the theory for specific use cases.
Overview
This is the reference for the harness.os kernel. It defines four harness types, five cross-cutting concerns, the inner/outer boundary, and how subtypes specialize the theory for specific use cases. None of this is prescriptive — it's a framework I arrived at after three years of managing multiple products with AI.
The kernel is the part that doesn't change when you swap databases, switch AI providers, or reorganize your projects. Everything else — your specific rules, your domain knowledge, your tool configuration — sits on top of it as your distribution.
If you're looking for implementation specifics, see the Scale 1 (Files) or Scale 2 (MCP) docs. This page covers the theory those implementations are built from.
Three Conceptual Layers
The architecture separates into three layers. Each one can change independently without breaking the others.
Kernel
The layer you're reading about now. Four base harness types, five cross-cutting concerns, the inner/outer boundary, session lifecycle, knowledge flow patterns. You could implement this with sticky notes on a wall. You'd be slower, but the principles would still apply.
Distribution
A specific application of the kernel. My distribution (marco.os) includes an 8-phase development workflow, TDD as a default, hexagonal architecture, and specific domains like skydiving, fitness, and finance. Someone else's distribution would look entirely different. A marketing team might have a 5-phase content workflow, A/B testing as a default, and domains like brand voice, audience segments, and campaign performance. Distributions are portable — forkable — you could take mine, strip out the domains, keep the dev workflow, and have a working starting point in an afternoon.
Mesh
A running network of harness instances. My mesh is six apps connected through their harnesses, with knowledge flowing between them. Your mesh would be your apps, your connections, your knowledge. Apps are on a mesh, not the mesh. The mesh is the running network — it's what makes cross-domain queries possible.
The kernel is universal. The distribution is personal. The mesh is operational. Change any layer without breaking the others.
Four Base Harness Types
I needed four categories because knowledge doesn't sort into one bucket. How you build something is different from what you're building, which is different from the domain rules it operates under, which is different from per-user data within those domains.
The creation process
Not just software. Software, content, marketing — anything about making digital things. How code is structured, how tests are written, how content is drafted. The process of building, regardless of what's being built.
The lifecycle process
Discovery, building, maintaining, archived. The WHY and the WHAT. Product requirements, feature specs, roadmaps, user stories, competitive analysis. What you're building and why it matters, independent of how it's built.
Domain-specific rules
Changes completely by industry. Skydiving license requirements, tax filing deadlines, legal document workflows, fitness programming principles. The real-world knowledge an AI needs to be useful in a specific domain.
Per-user data
Personal records within domains. Your jump log, your tax returns, your case files, your training history. What makes responses specific to you instead of generic. The data that turns general domain knowledge into personal answers.
Each type has the same internal structure: knowledge chunks, rules, workflows, learnings, decisions. The structure is uniform; the content is completely different. A build rule might say "use hexagonal architecture." An operations rule might say "Class C skydiving licenses require 200 jumps." Same structure, different universe of content.
Subtype Inheritance
A distribution specializes base types into concrete subtypes. This is where the kernel becomes specific to your work.
Each subtype inherits the base type's structure and adds specifics:
- Knowledge domains — Build:Software knows about code patterns; Build:Content knows about editorial guidelines
- Rules — Product:SaaS has deployment checklists; Product:Mobile has App Store submission rules
- Workflows — Ops:Legal has case intake processes; Ops:Fitness has program design templates
- Natural surface preference — Build:Software gravitates toward files; Domain:User gravitates toward MCP
- Concern emphasis — Ops:Finance weights governance heavily; Build:Software weights causal reasoning heavily
These are my subtypes. Someone else's distribution might have Build:Hardware, Build:Research, Ops:Manufacturing — completely different subtypes, same base types, same kernel.
Subtypes are distribution, not kernel. The kernel defines four base types. Your distribution defines which subtypes exist. The base type guarantees structural compatibility; the subtype carries the actual substance.
Five Cross-Cutting Concerns
Concerns cut across all four types. They're not additional categories — they're lenses that apply to every type simultaneously.
Relational
How entities connect across domains. A user's jump log connects to their fitness training connects to their financial spending. Cross-domain links that no single type owns.
Governance
Data quality, audit, compliance, validation. Are the rules being followed? Is the knowledge still accurate? Are handoffs meeting quality standards?
Causal
The WHY behind decisions. Not just what was decided, but the rationale. Architectural choices, scope tradeoffs, domain interpretations — the reasoning chain that future sessions need to understand past choices.
Metacognitive
Knowledge about knowledge. What's stale, what's missing, what's been validated, what needs review. The harness knowing what it knows and what it doesn't.
Security
Threat models, data protection, access control. Who can access which knowledge, how agent authentication works, what budget limits apply, where sensitive data boundaries are.
The key insight: each concern manifests differently depending on the harness type. Governance in Build:Software means code review gates and test coverage thresholds. Governance in Product means handoff quality validation. Governance in Operations means compliance tracking against regulatory requirements.
| Concern | Build | Product | Operations | Domain |
|---|---|---|---|---|
| Relational | Shared libraries, cross-repo deps | Feature dependencies across products | Cross-domain entity links | User identity across domains |
| Governance | Code review, test gates | Handoff quality, spec completeness | Compliance, audit trails | Data accuracy, staleness |
| Causal | Architecture decisions | Scope tradeoffs, pivot rationale | Rule interpretations | Preference reasoning |
| Metacognitive | Knowledge gaps in build process | Unvalidated assumptions | Domain knowledge staleness | Missing user context |
| Security | Secret management, CI/CD access | Feature flag access, staging | PII handling, jurisdictional rules | User data isolation |
Concerns also apply to both the inner and outer harness independently:
- Governance in the outer harness — data quality, knowledge validation, rule consistency
- Governance in the inner harness — session tracking, tool call logging, handoff completeness
- Security in the outer harness — who accesses which knowledge, what gets shared across meshes
- Security in the inner harness — agent authentication, budget limits, tool permissions
Three Architectural Zones
The harness splits into two primary zones — outer and inner — with surfaces bridging between them.
Outer Harness (substance)
- Knowledge chunks and domains
- Rules and behavioral constraints
- Workflows and process templates
- Decisions and rationale
- Learnings and patterns
- Governance and audit data
- Mesh topology
Inner Harness (surface)
- Agent context window
- Session lifecycle
- Tool call orchestration
- Adapter configuration
- Budget and token tracking
- Permission boundaries
The outer harness is the brain. All intelligence lives there — knowledge, rules, workflows, the accumulated decisions and learnings from every session. It persists across sessions, across agents, across time.
The inner harness is how agents access the outer harness. It has three layers:
Push intelligence outward. If you're encoding process knowledge in agent-specific config, it should be a rule in the outer harness instead. The adapter should be thin — a pointer, not a copy.
The outer harness enforces behavior on connection. Connecting IS participating. Session tracking, guardrails, governance — all activate automatically when an agent starts a session. There's no opt-in. If you're connected, you're governed.
Multiple surfaces coexist
The inner harness isn't one thing — it's multiple surfaces that access the same outer harness through different protocols:
- Files (Scale 1) — natural for Build:Software, Build:Content. Any agent that reads files can use it.
- MCP (Scale 2) — natural for Product, Domain, Governance. Structured queries, session lifecycle, audit trails.
- Future — REST API, CLI, web UI. The outer harness doesn't care how it's queried.
Surfaces and Sync Patterns
Different subtypes pair naturally with different surfaces. Build:Software lives in files because that's where code lives. Product lifecycle data lives in MCP because it's structured and queryable. This isn't a problem — it's the architecture working correctly.
The challenge is that the same knowledge sometimes needs to be accessed through multiple surfaces. Four sync patterns handle this:
Promote on learning
A pattern discovered in a repo during a build session gets promoted to the MCP knowledge store. Repo discovery flows upward into structured storage.
Inject on session start
When an agent starts a session, relevant MCP knowledge gets injected into the agent's context. Structured storage flows downward into the working session.
Governance audit sweep
A periodic process reads repos to check compliance against outer-harness rules. MCP reads files for validation, not to duplicate them.
Push-triggered indexing
A git push triggers an audit agent that reads the changes and updates MCP metadata. The push event is the sync trigger; the MCP server owns the indexing logic.
These are inter-surface communication patterns, not workarounds. Each pattern has a clear direction: which surface initiates, which stores, and what triggers the flow. The sync triggers live in the MCP server, not in agent-specific hooks — because the outer harness owns the process.
Knowledge Flow
The kernel defines specific operations that move knowledge through the harness. Here's what happens during the key ones.
Loads last handoff, project state, active rules, and available knowledge domains. The agent gets continuity from the previous session and constraints for the current one. Governance activates: session is tracked, tool calls are logged.
Validates handoff quality, stores a summary with next steps, creates continuity for the next session. Governance checks: did the session log decisions? Are there open questions? Is the handoff actionable?
Queries across knowledge domains with concern filtering. A search for "deployment" in the governance concern returns different results than the same search in the causal concern. The concern is a lens, not a filter.
Captures an architectural or workflow choice with its rationale. Feeds the causal concern directly. Future sessions can query why a decision was made, not just what was decided.
The pattern across all operations: the outer harness accumulates intelligence over time. Each session leaves it slightly richer — one more decision logged, one more learning captured, one more handoff creating continuity. The compound effect is the point.