Harness-neutral architecture

This page is the illustrated guide for teams copying 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

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

flowchart TB
  subgraph forkable ["Forkable templates (PR upstream)"]
    R[user.md]
    A[AGENTS.md org]
    G[general/*]
    AM[agents/*]
    SK[skills/* bodies]
    EX[*.example.md]
  end
  subgraph machine ["Machine-local (never commit)"]
    H["$CODE_ROOT/harness.md"]
    M["$CODE_ROOT/machine.md"]
    PF["profiles/<machine>.md in your fork"]
    LO["LOCAL_RULES_DIR overlay"]
  end
  subgraph project ["Project (in repo being edited)"]
    PA["<repo>/AGENTS.md"]
    DOC[README / docs]
  end
  R --> G
  A --> AM
  SK -.->|"load on demand"| forkable
  H -->|"SKILLS_DISCOVERY_ROOT"| SK
  M --> R
  H --> R
  PA --> DOC

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 future: rules-manager emits a Cursor .mdc from user.md 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 | 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)

flowchart LR
  CAN["$AGENT_RULES_PATH/skills/<name>/"]
  DISC["$SKILLS_DISCOVERY_ROOT/<name>/"]
  AGENT[Agent]
  CAN -->|"always canonical"| AGENT
  DISC -->|"when installed per HARNESS"| AGENT
  CAN -.->|"SKILLS_INSTALL"| DISC

  1. Discovery path — when SKILLS_DISCOVERY_ROOT is set and skills are linked per SKILLS_INSTALL in $harness.md.

  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, …

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 preamble
  A->>M: Read harness.md + machine.md
  A->>T: Parallel read general/* agents/*
  A->>A: Apply layer precedence explicitly

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)

See Org layer.

Template boundary (agent obligation)

Before editing anything under $AGENT_RULES_PATH:

flowchart TD
  Q{Machine-specific fact?}
  Q -->|Yes| W[Write harness.md or machine.md or fork profile]
  Q -->|No| P{Portable or org policy?}
  P -->|Yes| T[Edit template with placeholders]
  P -->|Project-only| R[Edit repo AGENTS.md]
  W --> X[Do not PR machine paths upstream]

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.

Setup checklist (new machine)

  1. Clone agent-rules into your hive ($AGENT_RULES_PATH).

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

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

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

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

  6. Install skills per Bootstrap agent skills.

  7. Optional org: stack AGENTS.md after portable rules.

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.

See also