harness.os

AI Knowledge Engineering

I manage 6 products with AI agents. This is the system I built to organize what they need to know.

See it working Read the kernel docs
Scroll

The bottleneck was never the model.
It was the knowledge.

When I started using AI for real work across multiple projects, the same thing kept happening. Same questions every session. Same context-setting. Same patterns explained again. The agent wasn't the problem — I just had no good way to organize what it needed to know.

So I built a system for it. Four types of knowledge, five cross-cutting concerns, a clear boundary between what you know and how you run it. That system became harness.os.

Three layers of abstraction

I ended up with three levels. Here's why each one exists.

01 Kernel
The universal system. Four harness types, five cross-cutting concerns, the inner/outer boundary, knowledge flow rules. These are the invariant structures — they apply to every harness, regardless of who runs it.
Like a kernel in an OS — the core that every distribution builds on.
02 Distribution
Your specific setup. Define subtypes — Build:Software, Build:Content, Product:SaaS — that inherit from the kernel's base types. Then fill them in: rules, knowledge, workflows, surfaces, sync patterns, agents. A distribution like "marco.os" is one person's complete harness configuration.
Like a Linux distro — same kernel, your choices on top.
03 Mesh
The running instances inside your distribution. build.ai, cortex.ai, way2do — each is a mesh that connects harnesses at runtime. This is what makes cross-domain reasoning possible — your skydiving harness can talk to your finance harness.
Like running processes in an OS — the live services built on your distro.

Four harness types

I kept running into four kinds of knowledge that needed different treatment.

Build
How you make things
Your creation process. Software development, content production, marketing — each a subtype with its own rules, workflows, and natural access surface.
Product
Why you build and what you ship
Why you build and what you ship. SaaS products, mobile apps, open-source projects — each subtype tracks its own lifecycle, roadmap, and session handoffs.
Operations
How your domain works
How your domain works. Skydiving progression, tax rules, legal compliance — each industry gets its own operations subtype with stable, reusable knowledge.
Domain
Who your users are
Per-user data within those domains. Jump logs, workout history, transactions. The stuff that makes responses specific to a person, not generic.

The mesh in action

Here's what happens when you connect the harnesses together.

"Can I afford this skydive camp next month?"
ops:skydiving
Camp Details
Dates, cost, requirements
ops:finance
Budget Rules
Income, expenses, targets
domain:personal
Your Data
Calendar, jump log, accounts
Mesh Response
The camp costs $1,200 and requires B-license (you have it). After rent and subscriptions, you'll have $1,450 free next month. You can afford it with $250 remaining.

Five cross-cutting concerns

Five things I kept needing to track across all four types.

Build
Product
Operations
Domain
Relational
How entities connect across domains. A skydive camp is also a budget item is also a calendar event.
Governance
Data quality, audit trails, compliance, validation rules.
Causal
The WHY behind decisions. Without this, every new session re-debates settled questions.
Metacognitive
Knowledge about knowledge. What's stale, what works, what needs updating.
Security
Threat models, risk assessment, data protection, access control.

The intelligence survives the runtime

Three architectural zones. The substance lives in the outer harness, the surface determines how you access it, and the adapter connects a specific agent.

Outer Harness (substance)
All the intelligence and process. This is the brain — the part that matters regardless of which agent or surface you use.
  • Knowledge, rules, workflows
  • Decisions and learnings
  • Governance and audit trails
  • Mesh topology
  • Cross-domain relationships
Boundary
Inner Harness (surface)
How the outer harness gets accessed. Three layers inside: the protocol (MCP standard), the interface (tool definitions), and the adapter (agent-specific config like CLAUDE.md or .cursorrules).
  • Files — natural for Build:Software, content work
  • MCP — natural for Product lifecycle, governance
  • Future — REST API, CLI, web UI
Key insight: Different subtypes naturally pair with different surfaces. Build:Software lives in repo files. Product lifecycle lives in MCP. Both are active simultaneously — sync patterns keep them coherent. Swap the agent, swap the surface — the outer harness survives.

How this happened

Six weeks of evenings and weekends, alongside a full-time job. That's how long it took to go from a Claude subscription to this methodology. During the day I was working as a software engineer; after hours I was managing my own products solo, kept hitting the same context problems, and started organizing what the agents needed to know. CLAUDE.md files turned into structured rules, then workflows, then a full knowledge system. Each piece got added because I needed it, not because a diagram said it should exist.

The blog has the full timeline if you're curious how it evolved.

Read the blog