July 22, 2026

The datarim-system Skill — The Core Rules Every Agent Loads First

A look at the datarim-system skill — the always-loaded ruleset that defines where Datarim state lives, how task files are structured, and how agents resolve paths and load order.

Before any /dr-* command does anything, it reads datarim-system. This skill is the foundation layer: it defines where workflow state lives, what the operational files must look like, and how the framework resolves paths and skill loading order. Every other skill and every agent treats it as a prerequisite.

Operational files are indexes, not content

The central rule in the skill is that tasks.md, backlog.md, and activeContext.md are indexes. Each bullet line answers four questions — which task, what state, what complexity level, and where the description file is — and nothing else. A task description file at datarim/tasks/{TASK-ID}-task-description.md holds all the actual content: overview, acceptance criteria, constraints, out-of-scope notes, and related references.

Two files are explicitly abolished. progress.md no longer exists as of v1.19.0 — per-task progress notes belong in the description file's Implementation Notes section. backlog-archive.md was abolished in v1.19.1 — completed and cancelled task records live in documentation/archive/, not in a rolling file that agents read on every invocation.

Path resolution

The skill defines a strict path resolution rule. The agent resolves the physical working directory and walks up to the closest ancestor holding .datarim-runtime/installation.json; the project recorded there must equal that directory, and every nested git repository crossed on the way must be listed in the installation's explicit contexts. Task state is then <project>/datarim/. A directory merely named datarim/ does not enable Datarim, and the rule never falls back to the home directory, a parent workspace, or the framework checkout. This prevents agents from writing task state into the wrong place.

Since 3.0 the install is project-local: each project receives a pinned copy of the framework under .datarim-runtime/, and commands read it through ${DATARIM_RUNTIME}. Installations copied from elsewhere and symlinked runtime directories are rejected by the path rule above. Framework changes are made in the source repository and reach a project when it is updated.

Skill loading order and the blocklist

Skills load from two layers. The framework layer is the project runtime at .datarim-runtime/. A local overlay at .datarim-runtime/local/ (gitignored) allows project-private additions; when a name collides, the local overlay wins. Six critical skills cannot be shadowed from the local overlay: security, security-baseline, compliance, datarim-system, ai-quality, and evolution. Attempting to override any of these via local/skills/ causes validate.sh to exit 1.

The large-plan read strategy

When an L3+ task's plan, PRD, and supporting research documents together exceed roughly 600 lines, the skill recommends a single external-context delegation rather than sequential reads of every artefact. The structured summary from that delegation then drives implementation order, file paths, and verification criteria across /dr-do, /dr-qa, and /dr-compliance — re-reading the raw artefacts for each stage would introduce drift between the implementation summary and the verification summary.

The skill also fragments itself into sub-files — path-and-storage.md, task-identity-and-context.md, backlog-and-routing.md, and others — so commands load only the fragment relevant to the current sub-problem instead of the full system rules document.

See what Datarim is for the full pipeline context, or the datarim-doctor skill post for the migration algorithm that enforces this schema.