Harness-neutral architecture

This page explains the layered geography of forkable templates vs machine-local config so you can copy dev-centr/agent-rules into any local AI harness (Cursor, Claude Code, Hermes, T3code, Windsurf, and others).

Repository

https://github.com/dev-centr/agent-rules

Rules geography

The system is layered, not a personal fork that must stay at HEAD parity with the team template.

Rules geography: shared reference clone, personal overlay fork, harness always-on slot, skill discovery junctions, machine files, and project AGENTS.md
Table 1. Callouts (match the numbered disks on the map)
# What it is

1 Shared reference

Live clone $AGENT_RULES_PATH (usually dev-centr/agent-rules). Canonical skills/, shared portable user.md / general/, and org AGENTS.md / agents/*. Pull this tree on drift (sync-agent-rules).

2 Personal overlay

Optional personal fork: profiles/<machine>.md, personal user.md tweaks, personal-only skills. Deltas only — not a mirror that must track template HEAD.

3 Harness always-on

Where thin preambles are injected (ALWAYS_ON_RULES in $CODE_ROOT/harness.md). Prefer native stacking (user, then org) when the harness allows it.

4 Skill discovery

$SKILLS_DISCOVERY_ROOT/<name>/ junctions or copies that point at skills in (1). Bodies stay canonical in the team clone.

5 This machine

$CODE_ROOT/harness.md, $CODE_ROOT/machine.md, and $LOCAL_RULES_DIR — never committed into forkable templates.

6 Repo under edit

<repo>/AGENTS.md + docs for that project only (additive).

Layered deltas — not HEAD parity

  • Do keep a live team clone as $AGENT_RULES_PATH and sync skills / shared policy from it.

  • Do keep personal customizations in a thin overlay fork (or local compose inputs).

  • Do not treat the personal fork as a full copy of the template and chase rebase parity with upstream main. That is the expensive anti-pattern on the map.

Shared policy changes land as PRs to dev-centr/agent-rules. Personal experiments stay in the overlay until upstreamed.

When to use rules-manager

rules-manager composes personal + org (and related sections) into one watched paste file.

Situation Approach

Harness can stack layers

Paste or point at portable user.md, then org AGENTS.md, then project rules — no compose tool required.

Harness has one undifferentiated always-on field

Use rules-manager (or an equivalent compose step) so layers stay separate on disk but inject as one payload.

Account-synced always-on (e.g. Cursor User Rules)

Keep portable text only; hive paths stay in $LOCAL_RULES_DIR / harness.md / machine.md.

The problem

Forkable templates must not embed:

  • Your CODE_ROOT or drive letters

  • Your GitHub username

  • Where your harness discovers skills

  • Where your always-on rules are injected

Those facts belong on this user’s machine, not in a pull request to upstream.

Layer model

Same geography as the map above, in words:

Forkable templates

Committed in agent-rules. Use placeholders only (REQUIRED_PATH, <your-github-username>, $ISSUES_REPO).

  • Portable baseline: user.md, general/*

  • Org overlay: AGENTS.md, agents/*

  • Canonical skill bodies: skills/<name>/SKILL.md

  • Examples: harness.example.md, machine.example.md, profiles/my-desktop.md

Machine-local (this user’s machine)

Gitignored at $CODE_ROOT (or in your fork’s filled profile). Same human may use multiple harnesses on one machine — record what applies now in harness.md.

File Holds

$CODE_ROOT/harness.md

Harness name, skill discovery root, always-on injection slot, chat/citation behaviors, MCP availability

$CODE_ROOT/machine.md

Workstation facts — tool paths, PATH gaps, hardware quirks

profiles/<machine>.md (your fork)

CODE_ROOT, GITHUB_USER, ENVIRONMENT, ISSUES_REPO

LOCAL_RULES_DIR (from HARNESS)

Per-harness overlay that must not sync (e.g. Cursor %USERPROFILE%\.cursor\rules\*.mdc)

Project layer

Facts about one repository → <repo>/AGENTS.md + docs — not $CODE_ROOT/machine.md.

Layer names vs harness vocabulary

Our filenames describe layers (who owns the file, what lifecycle it has). Harness products use their own labels — often the word rules everywhere. The table below is the teaching translation: same job, different product names.

user.md is not "rules about the human." It is the user-layer policy payload — portable instructions you want on every task before org/project context. Newcomers ask "what rules go in here?" Answer: coding standards, git habits, doc voice, tool preferences — anything forkable that is not machine paths and not org-only. Who it applies to is everyone using your fork; where it lands is recorded in $CODE_ROOT/harness.md (ALWAYS_ON_RULES).

Our layer Repo / path What it holds Common harness names (examples)

User

user.md in agent-rules (paste or compose)

Portable always-on policy — team/personal baseline

Cursor User Rules (Settings, often account-synced); Claude Code user CLAUDE.md; generic system prompt / custom instructions / rules file path you configure

Harness

$CODE_ROOT/harness.md (from harness.example.md)

How this AI runtime is wired on this machine — discovery, injection slot, chat behavior

Not a standard product label; record in ALWAYS_ON_RULES, skill install paths, MCP flags. Cursor: Settings + ~/.cursor/skills + %USERPROFILE%\.cursor\rules

Machine

$CODE_ROOT/machine.md (from machine.example.md)

Workstation facts — tool paths, PATH gaps, hardware; shared across harnesses on same box

Usually no dedicated UI — not User Rules. Sometimes "environment notes" or "dotfiles"; never sync to Cursor User Rules

Org

AGENTS.md + agents/*

Org policy overriding user layer on org repos

Same payload as user layer; stacked after user.md in always-on slot; sometimes repo AGENTS.md only

Project

<repo>/AGENTS.md

This repository only

Cursor Project Rules (.cursor/rules/*.mdc); Claude project CLAUDE.md; GitHub Copilot instructions

Skills

$AGENT_RULES_PATH/skills/<name>/

Heavy on-demand playbooks

Cursor skills (~/.cursor/skills); elsewhere: direct read of SKILL.md only

Payload vs injection (important)

  • user.md = canonical content (Markdown, harness-neutral).

  • ALWAYS_ON_RULES in harness.md = where that content is injected — different per harness.

  • Cursor User Rules sync across machines (account); machine.md and harness.md do not — they stay at $CODE_ROOT.

  • Cursor local %USERPROFILE%\.cursor\rules\*.mdc = harness-local overlay (LOCAL_RULES_DIR), not a substitute for user.md.

Why core files stay .md, not .mdc

.mdc (in Cursor) means Markdown plus YAML frontmatter (description, alwaysApply, globs) — Cursor project/local rule format, not a universal standard.

  • Keep user.md, machine.example.md, harness.example.md as .md — pasteable into any harness; no Cursor-only frontmatter in forkable templates.

  • Use .mdc only in harness adapters — e.g. .cursor/rules/.mdc in this repo for thin always-on reminders; bodies stay in general/ or skills.

  • Optional: rules-manager emits a Cursor .mdc from composed Markdown for local use — still not committed as the canonical portable file.

Other harnesses may adopt similar formats; the portable layer remains plain Markdown until a cross-harness standard exists.

harness.md variables

Copy from harness.example.md. Your agent probes the active harness and writes concrete values.

HARNESS_NAME = cursor | claude-code | hermes | t3code | windsurf | harness | other
ALWAYS_ON_RULES = <where thin preamble is injected>
SKILLS_DISCOVERY_ROOT = <path or none — direct read from $AGENT_RULES_PATH/skills/>
LOCAL_RULES_DIR = <machine-local overlay or none>
SKILLS_INSTALL = junction | copy | harness-native | none
CHAT_FILE_LINKS = markdown-workspace-links | plain-paths | harness-default
CODE_CITATION = line-range-fence | none | harness-default
IDE_PROJECT_RULES = mdc-in-repo | claude-rules | none
MCP_CONTEXT7 = available | unavailable

Skill loading (two paths)

  1. Discovery path — when SKILLS_DISCOVERY_ROOT is set and skills are linked per SKILLS_INSTALL in $harness.md (map callout 4).

  2. Direct read — agent reads $AGENT_RULES_PATH/skills/<name>/SKILL.md with native file tools (works in every harness with filesystem access).

Never paste full skill bodies into always-on rules — one-line pointers only. Shop: Bootstrap agent skills.

Context assembly (one parallel batch)

When user.md or MAIN.md is active, the agent reads simultaneously:

  1. profiles/<machine>.md (constants)

  2. $CODE_ROOT/harness.md

  3. $CODE_ROOT/machine.md

  4. general/harness.md

  5. general/harness-boundary.md

  6. general/global.md, general/environment.md, OS layer, general/creator.md, …

  7. Org pass (on dev-centr/*): AGENTS.md, agents/_MAIN.md, …

Layer precedence (not automatic)

Harnesses do not rank layers for you. On dev-centr/* work, stack always-on rules:

  1. Personal portable user.md

  2. Org AGENTS.md (wins on conflict)

  3. Project <repo>/AGENTS.md (additive)

If the harness cannot stack, compose with rules-manager so org still lands after personal on disk. See Org layer.

Template boundary (agent obligation)

Before editing anything under $AGENT_RULES_PATH:

  • Machine-specific fact? → write harness.md / machine.md / fork profile — do not PR machine paths upstream.

  • Portable or org policy? → edit the template with placeholders.

  • Project-only? → edit <repo>/AGENTS.md.

Full text: general/harness-boundary.md in the repo. Skill: harness-setup.

Cursor example (one harness, not the template)

When HARNESS_NAME = cursor, a typical machine record might look like:

HARNESS_NAME = cursor
ALWAYS_ON_RULES = Cursor Settings User Rules (composed via rules-manager)
SKILLS_DISCOVERY_ROOT = %USERPROFILE%\.cursor\skills
LOCAL_RULES_DIR = %USERPROFILE%\.cursor\rules
SKILLS_INSTALL = junction from $AGENT_RULES_PATH/skills/<name>/
CHAT_FILE_LINKS = markdown-workspace-links
CODE_CITATION = line-range-fence
IDE_PROJECT_RULES = mdc-in-repo
MCP_CONTEXT7 = available

Other harnesses: run harness-setup — do not copy Cursor paths into forkable files.

DevCentr lightweight harness

DevCentr is building its own lightweight agent runtime (T3code-shaped weight, not Cursor-class IDE bulk) — wired to dlang-supplemental for native D infrastructure.

Mixr is the harness’s model router meta-agent (Cursor Auto-shaped): it assigns models per node/job instead of pinning one default for the whole swarm.

See Agent harness for design direction, Mixr routing, OSS integration policy, and cross-org UX contracts (token provenance, actor-model UI from HCI Nerdz).

Setup checklist (new machine)

  1. Clone agent-rules into your hive ($AGENT_RULES_PATH) — the shared reference (map 1).

  2. Optional personal overlay fork for profiles and deltas (map 2) — do not require HEAD parity with (1).

  3. Copy profiles/my-desktop.md → your fork profile; fill CODE_ROOT, ENVIRONMENT, …

  4. Run skill harness-setup → creates $CODE_ROOT/harness.md.

  5. Copy machine.example.md → $CODE_ROOT/machine.md as needed.

  6. Paste user.md (or rules-manager composed file) into always-on slot per $HARNESS.

  7. Install skills per Bootstrap agent skills.

  8. Optional org: stack AGENTS.md after portable rules (or compose).

Polyglot harness use

One workstation, multiple harnesses:

  • Update $CODE_ROOT/harness.md when switching (or maintain a short Harness: cursor / Harness: claude-code section).

  • machine.md is shared across harnesses on the same machine (same tool paths).

  • Skill bodies stay canonical in $AGENT_RULES_PATH — only discovery/install differs.

Optional flowcharts

For readers who want a sequence view of context assembly (the map above is the primary teaching figure):

sequenceDiagram
  participant U as User / harness
  participant A as Agent
  participant T as Forkable templates
  participant M as Machine files
  U->>A: Paste user.md or composed preamble
  A->>M: Read harness.md + machine.md
  A->>T: Parallel read general/* agents/*
  A->>A: Apply layer precedence explicitly

See also