Docs / Products / Instructions

Plan

Instructions

Instructions is continuous integration for agent instructions. It reads AGENTS.md, CLAUDE.md, editor rules, skills, hooks, and command configuration as one corpus, normalizes them into atomic rules with their source text intact, resolves scope and precedence, classifies every rule into one of eight canonical states, and compiles the smallest correct pack for the task an agent is about to perform. Internal service identifier: context-compiler.

Last updated August 23, 2026

A compiled rule carries its source file and version, the rule it beat and the rung that decided it, the scope it binds, the rationale kept as verbatim source text, the freshness of the repository fact behind it, the enforcement mechanism that holds it outside the prompt, and a probe that can detect noncompliance. Instructions produces all seven from the observations it is given. It does not collect those observations itself. Read the limitations before relying on a verdict.

What it does

A repository usually holds more than one instruction file, and those files disagree. Instructions reads them as one corpus, keeps human policy and observed repository fact as separate kinds of truth, and produces a pack for one named task rather than a general briefing. Two properties define the output: no line enters the pack without the file, version, and line it came from, and no rule is dropped without a reason that can be read back.

Precedence ladder, in resolution order

1scope-specificity A rule anchored in a deeper directory scope overrides a broader ancestor scope.
2tool-specificity A tool specific instruction source overrides a shared source at the same scope.
3source-authority The source with the higher declared authority wins.
4source-precedence The source with the higher declared precedence rank wins.
5observation-recency The more recently observed source version wins.

The run returns the whole walk, not only the answer: every rung, what it saw, and whether it separated the candidates. When no rung separates them the contest is recorded as tied, the key is withheld from the pack, and a human-required finding is raised.

Use cases

Monorepo instruction drift

A root AGENTS.md, a package level CLAUDE.md, and an editor rule file disagree. Set taskScope to the directory being changed and read the precedence decisions for that scope.

Conflicting guidance

Surface the pair of instructions that cannot both be followed, quoted from both files, before an agent picks one at random.

Stale repository claims

Supply observed repository facts and validation results. A rule that claims a value the repository no longer has is classified Stale with the evidence path in the reason.

New agent tool onboarding

Set targetAgent and compile from one canonical rule graph rather than maintaining a separate instruction file per tool. Tool specific text that cannot be represented canonically is preserved, not dropped.

How it works

Six stages. Each one produces an artifact the next stage can check.

1
Collect
Take every instruction source in the repository as one corpus: AGENTS.md, CLAUDE.md, editor rules, skills, hooks, command configuration, READMEs. Each source is recorded with a path, an exact version, a scope, a declared authority, and the moment it was observed.
Artifact: Versioned instruction sources
2
Parse
Normalize prose into atomic rules, facts, procedures, and validation steps, and keep the verbatim source text beside every one. Human policy and observed repository fact stay separate kinds of truth, because they are verified by different evidence.
Artifact: Typed rules with source text retained
3
Validate
Compare what the instructions claim against what the repository shows. A claim supported by a lockfile, a file read, or a sandboxed command is Verified. A claim nothing admissible supports is Unknown, and Unknown is never rounded up.
Artifact: Repository facts with age and admissibility
4
Resolve and compile
Walk the five rung precedence ladder, record which rung separated the winner from the loser, drop what this task and this agent do not need, and render a pack that fits the budget without ever trimming a critical invariant.
Artifact: Context pack, source map, precedence walk
5
Enforce
Generate a probe for every rule and name the mechanism that holds it outside the prompt: a hook, a command, a test, or a permission boundary. A critical rule with no deterministic probe blocks the drift gate.
Artifact: Compliance probes and enforcement modes
6
Observe
Score which rules were loaded, referenced, followed, violated, or restated by a human mid task. A rule a person keeps repeating is evidence that the rule is unclear, not that the agent is careless, and the report says which enforcement mode would fix it.
Artifact: Rule outcomes and a confusion report

Stages two, four, and five run inside this service. Stages one, three, and six depend on observations the caller supplies: instruction sources, repository facts and validation results, and agent behavior events. Instructions classifies and compiles them. It does not gather them.

Run types

Set runType on the request. Every run type compiles the same rule graph and returns the same envelope. The run type states what the run is for and which part of the output you are reading. The identifiers below come from the service manifest: call GET /api/v1/services/context-compiler/manifest to confirm the exact values your deployment accepts before scripting against them.

compile

Compile context

The default. Resolve sources, apply precedence, and produce a task specific pack under a token budget, with a source map, the precedence walk, conflicts, probes, and a gate verdict.

scan

Scan instruction sources

Discover instruction sources and normalize them into atomic rules with provenance, without narrowing to one task.

lint

Lint the rule graph

Report contradictions, redundancy, overly broad scope, and unverifiable claims across the whole corpus.

validate-facts

Validate repository facts

Compare instruction claims against observed repository facts and validation records, and report age, admissibility, and freshness.

test-compliance

Test rule compliance

Generate deterministic probes and score observed agent behavior against the rules that were loaded.

explain

Explain a decision

Show the precedence ladder and the evidence behind every compiled and excluded rule.

Input contract

Validated by a schema before analysis. An invalid input fails the run rather than compiling a partial pack. Four fields are required. Everything richer is optional, so a caller with only instruction files still gets a pack, and a caller with facts, validations, and telemetry gets states, a gate, and a behavior report as well.

Required

Required Instructions input fields
Field	Type	Meaning
projectId	string	The tenant scoped Symbolic project the run belongs to.
task	string	The task the pack is compiled for. A pack is only correct with respect to a task.
tokenBudget	integer > 0	The budget the compiled pack must fit. The pack is measured as rendered text, not as a sum of fragments.
sources[]	array, at least one	Instruction source observations. Each source is one file, at one observed version.

Optional

Optional Instructions input fields
Field	Type	Meaning
runType	one of the six run types	What the run is for. Every run type compiles the same rule graph and changes which part of the output you read.
taskScope	repo relative directory	The directory the task touches. Rules anchored outside it are excluded with reason out_of_scope. Defaults to the repository root.
targetAgent	claude_code, cursor, codex_cli, copilot, any	The agent the pack is for. Rules written for a different tool are excluded with reason tool_mismatch.
taskCategories	array of rule categories	Narrow the pack to security, tooling, build, testing, architecture, deployment, workflow, style, or documentation. Omit to compile every applicable category.
now	ISO 8601 datetime	The evaluation instant. Fixing it makes freshness, ages, and the gate verdict reproducible.
packVersion	integer > 0	Version number stamped on the emitted pack so successive compiles are comparable.
facts[]	array of repository facts	Observed repository truth: key, value, observation method, evidence path, and observation time. This is how a rule becomes Verified or Stale.
validations[]	array of validation results	Command and path checks with their environment, exit code, output snippet, result, and attestor.
behaviorEvents[]	array of behavior events	What an agent did with a rule: loaded, referenced, followed, violated, or clarified, each with the method that observed it.
waivers[]	array of gate waivers	A named human accepting a specific failing gate check, with a reason, a scope, and an expiry.
evidenceChains[]	array of chains	Declared state transitions for a rule, fact, conflict, pack, or probe, replayed against the published transition table.

Source fields

id, path, authority, observedAt, status: Required. Authority is 0 to 100. A blocked source carries a blocker string and produces a finding rather than shrinking coverage silently.
version: The exact file version parsed, such as a blob sha. It appears in every source quote and pack line.
kind, tool: agents_md, claude_md, cursor_rules, skill, hook, command_config, readme, or other, and the agent the source is written for. Derived from the path when omitted.
scopePath, globs: The directory the source governs. Deeper scope wins the first rung of the precedence ladder.
precedence: A declared rank, 0 to 99, used on the fourth rung when authority does not separate two sources.
preservedBlocks: Tool specific text that cannot be represented canonically. It is carried through instead of being dropped in translation.

Item fields

key, value, kind: Required. Kind is rule, fact, procedure, or validation.
sourceText, sourceLine: The verbatim text and line, kept whenever the normalized value differs from the file. Normalization never destroys the original.
origin: human_policy or repo_fact. The two are different kinds of truth and are verified by different evidence.
criticality: critical or standard. Critical rules are never trimmed to fit a budget.
enforcement: hook, command, test, permission_boundary, review, or prompt_only. Only the first four survive outside the model prompt.
scopePath, intendedScopePaths: Where the rule is anchored, and the narrower scopes the source meant. A rule anchored broader than its intent is classified Overly broad.
assertsFactKey, assertsFactValue: The repository fact the instruction claims, and the value it claims for it. This is what makes a rule falsifiable.
approvedBy: The named human who accepted the item as policy. Human policy is verified by approval, never by repository observation.
owner, reviewDate, deprecated, tools, category, confidence: Ownership, review cadence, deprecation, tool applicability, category, and parse confidence.

Output artifact

One envelope per run. The compiled pack is the artifact an agent consumes. Everything else is what a reviewer needs to trust it.

The pack

packId, packVersion, contentHash

Stable identity for the compiled artifact. The same inputs compile to the same content hash.

content

The rendered pack text, the artifact an agent actually receives.

packLines[]

The source map. Every line of the rendered pack, with its kind, rule id, source path, source version, source line, scope, and token cost.

items[]

The compiled items in the legacy shape, extended with ruleId, state, scopePath, criticality, origin, and enforcement.

sourceMap

Every source id mapped to the keys it offered, including keys that lost and keys from blocked sources.

estimatedTokens, tokensRaw, reductionPct, budgetStatus

The compiled size, the corpus baseline, the reduction, and one of within-budget, compressed, or over-budget. The pack spends tokens on its own header, category headings, conflict notes, and a rule id per line, so on a small corpus the reduction can be negative. It is reported that way rather than hidden, and the run's limitations explain the baseline.

excluded[]

Every rule left out, with one of eight reasons: out_of_scope, tool_mismatch, deprecated, stale, redundant_duplicate, conflict_superseded, blocked_source, or budget.

warnings[]

Conditions the reader must see: unresolved conflict, stale rule excluded, unknown rule included, ignored rule included, budget exceeded by critical rules, blocked source. Each carries a next action and an owner.

The rules

rules[]

The full compiled rule records. Each carries text and verbatim source text, category, scope, intended scope, tools, owner, origin, criticality, enforcement, state, state reason, confidence, source id, path, version and line, authority, precedence rank, token count, duplicate and supersession links, contradiction ids, validation ids, fact keys, and evidence references.

ruleStateCounts

A count for each of the eight canonical states. Unknown is reported, never folded into a pass.

activeRuleCount, verifiedActiveRuleRate

The north star: the share of active rules that are current, non contradictory, correctly scoped, and evidence backed.

criticalRuleIds, unknownRuleIds, blockedSourceIds

The three lists a reviewer checks first.

The decisions

precedence[]

One decision per contested key: the candidates, the winner or null, the deciding rung, the full ladder walk with a detail line per rung, and whether the contest tied.

conflicts[]

Contradictions with kind (command_conflict, direct_negation, scope_conflict, fact_conflict), severity, status, a source quote from both sides with path, version, and line, the winner and loser, the precedence explanation, and the deciding fact key when a repository fact settled it.

facts[]

Each repository fact with its observation method, evidence path, age in days, whether the method is admissible, whether the observation is still fresh, the rules that claim it, and the rules it contradicts.

Enforcement and behavior

probes[]

One generated compliance probe per non deprecated rule: kind, scope, prompt, expected behavior, assertion, command, severity, whether the assertion is deterministic, and the enforcement mode it checks.

behavior

The confusion report: per rule counts of loaded, referenced, followed, violated, and clarified, a compliance rate, a verdict of followed, ignored, mixed, or unobserved, the unobserved rule ids, the denominator description, and its own limitations.

gate

The context drift gate: a status, a decision, a consequence, and one check per condition with a five way state (pass, fail, unknown, waived, not_applicable), an owner, a next action, evidence references, and any waiver.

evidenceChains[]

Replay of declared state transitions against the published transition table, listing which hops applied, which were refused and why, and which states are legal next.

limitations[]

What this specific run could not establish. Read it before treating any verdict as settled.

Rule states

Every rule is classified into exactly one of eight states, and every classification carries a state reason naming the evidence behind it. Unknown is never rounded up to Verified, and no positive state may be assigned from an agent's own claim about its own behavior.

Verified

verified

Matches repository truth or approved human policy, on admissible evidence.

Established by: An admissible repository observation, or a named human approval for policy. Never an agent's own claim.

Stale

stale

The referenced repository state no longer exists or has changed.

Established by: A repository fact or validation that refutes the value the rule claims.

Contradictory

contradictory

Two active rules cannot both be followed.

Established by: A conflict pair quoted from both files, with the precedence rung that decided it or the fact that it tied.

Redundant

redundant

Another active rule already expresses the same constraint.

Established by: A canonical text match against a rule binding the same scope.

Overly broad

overly_broad

The scope applies beyond the surface the source intended.

Established by: The rule anchor compared against the narrower scopes its source declared.

Ignored

ignored

Deterministic evidence shows an agent did not follow the loaded rule.

Established by: A pack manifest proving the rule was loaded, plus a fixture assertion or diff inspection of the violation.

Unknown

unknown

No admissible evidence can validate the rule. This is not a pass.

Established by: The absence of admissible evidence. Unknown is reported, never rounded up.

Deprecated

deprecated

Retained for history only and never compiled into a pack.

Established by: An explicit deprecation at the source.

Seven of the eight states are active: they still bind an agent. Deprecated is history only and never compiles into a pack. The share of active rules that are Verified is reported as verifiedActiveRuleRate.

Evidence and findings

Evidence kinds

The service publishes five evidence kinds to the platform ledger. Inside the run, each rule also carries evidence references of seven reference kinds: source, fact, validation, behavior, conflict, pack, and policy, each with a label, a detail line, and the moment it was observed.

context-source

A versioned instruction source that contributed rules to a pack, with its path, authority, observation time, and replay steps.

repository-fact

An observation of the repository, with the method it was observed by and the path it was observed from.

validation

A sandboxed command or path check, with exit code, output snippet, environment, and attestor.

agent-run

Observed agent behavior against a loaded rule: followed, violated, or clarified.

context-pack

A compiled pack with a stable content hash and a line level source map.

Admissibility

Repository facts observed by file read, lockfile, command, static analysis, or directory scan are admissible. A fact whose only method is an agent claim is not.
Validations attested by a sandbox or a named human are admissible. A validation attested by an agent cannot verify a rule, and the state reason says so explicitly.
Behavior observed through a pack manifest, a fixture assertion, a diff inspection, or a human report is deterministic. An agent claim about its own compliance is not.
A repository fact older than the freshness window is reported as not fresh, and the gate raises a fact freshness check rather than trusting it.

Evidence state machine

Raw evidence is immutable and the current state of a subject is the last legal event in its chain. Supply evidenceChains and the run replays them against the published transition table: proposed moves to approved, rejected, or superseded; approved to observed, invalidated, or superseded; observed to verified, failed, blocked, or unknown; verified to stale, regressed, or superseded; failed to repairing, waived, or verified; unknown to observed, blocked, or accepted. An undeclared hop is refused and recorded with the reason, never silently applied.

Finding kinds

contradiction

Two active rules bind the same key in overlapping scopes and cannot both be followed. Both sides are quoted with path, version, and line. The disposition becomes human-required when no rung of the precedence ladder separates them.

stale-rule

A rule describes repository state that no longer exists or has changed. The reason names the evidence path and the value the repository actually has.

redundant-rule

Another active rule already expresses the same constraint for the same scope.

overly-broad-rule

A rule applies beyond the surface its source intended, named against the narrower scopes the source declared.

ignored-rule

Deterministic evidence shows agents did not follow the rule while it was loaded. Raised only from admissible behavior observations, never from an agent's self report.

untested-critical-rule

A declared invariant has no deterministic probe that could detect a violation. The drift gate blocks on this.

unverifiable-rule

No admissible evidence supports the rule. It is compiled as declared intent, not as truth, and is counted in the Unknown state rather than rounded up.

blocked-source

An instruction source could not be read, so the compiled context is incomplete. The blocker text is preserved and the gap stays visible rather than being filled with a guess.

budget-exceeded

Critical invariants alone exceed the token budget for the task. The pack is reported over budget instead of trimming below the critical set.

Every finding whose disposition is not informational produces an action with an owner (agent, human, or external) and a reverification event, so a resolved conflict recompiles rather than closing on an assertion. Call GET /api/v1/services/context-compiler/manifest to read the exact run types, evidence kinds, finding kinds, and tool names your deployment serves before writing an integration against this list.

Quickstart

Open Instructions in the console, provide the task, the token budget, and at least one instruction source, then start an organization scoped run. The console renders the pack, the source map, the precedence decisions, the conflicts, and the evidence. Raw JSON stays behind the Advanced disclosure.

bashReady

POST /api/v1/services/context-compiler/runsAuthorization: Bearer $SYMBOLIC_API_KEYX-Symbolic-Organization: org_123Idempotency-Key: compile-2026-08-23-01{  "runType": "compile",  "projectId": "proj_acme_web",  "environmentId": "development",  "scope": "apps/web",  "agentId": "claude-code",  "args": {    "task": "Add settings persistence to the account page",    "tokenBudget": 1200,    "targetAgent": "claude_code",    "sources": [      {        "id": "agents-root",        "path": "AGENTS.md",        "kind": "agents_md",        "scopePath": ".",        "authority": 100,        "version": "b41c9de",        "observedAt": "2026-08-19T09:12:00.000Z",        "status": "available",        "items": [          {            "key": "database-changes",            "value": "Apply schema changes through reviewed migrations.",            "kind": "rule",            "origin": "human_policy",            "criticality": "critical",            "enforcement": "review",            "approvedBy": "platform-lead"          }        ]      },      {        "id": "readme-root",        "path": "README.md",        "kind": "readme",        "scopePath": ".",        "authority": 20,        "version": "c0198aa",        "observedAt": "2026-08-22T16:02:00.000Z",        "status": "available",        "items": [          {            "key": "database-changes",            "value": "Run prisma db push before starting the dev server.",            "kind": "rule",            "origin": "human_policy"          }        ]      }    ]  }}

This run compiles the AGENTS.md rule and reports one contradiction with README.md quoted as the losing side, resolved on the source-authority rung. Add facts and validations to move rules out of Unknown into Verified or Stale, and behaviorEvents to score compliance. The run is recorded in the shared run graph, so GET /api/v1/runs/:runId returns its findings, evidence, and actions like every other Symbolic product.

Open Instructions

MCP

Connect the endpoint once as described in MCP and agents. Instructions exposes six namespaced tools under symbolic.context_compiler, alongside the shared symbolic.context.run product tool that every Symbolic product carries. Every call is scoped to the organization resolved from the authenticated principal: an organization id in the request body is an echo, and a mismatch is refused rather than honored.

symbolic.context_compiler.scan

Record every agent instruction source for a scope and report what changed since the last scan.

mutation

symbolic.context_compiler.lint

Report contradictions, blocked sources, redundancy, staleness, and budget defects for a scope, worst first.

read

symbolic.context_compiler.compile

Compile an agent context pack for a task under a token budget, with the source map and the precedence walk.

mutation

symbolic.context_compiler.explain

Explain why a rule was selected, excluded, or left unverified.

read

symbolic.context_compiler.test

Generate deterministic compliance probes for the compiled rules.

mutation

symbolic.context_compiler.report_violation

Record observed agent behavior against a loaded rule, so a rule can reach Ignored on evidence rather than on opinion.

mutation

Read tools return summaries before large payloads and support a cursor and a limit. Mutations accept an idempotency key and return a deterministic event id, so a replayed call returns the original event rather than a second one. Call tools/list, or GET /api/v1/services/context-compiler/manifest, to confirm the exact names and run types your deployment serves.

Shared envelopes

Every tool takes one input envelope and returns one output envelope, so an agent writes the plumbing once.

Input

projectId, environmentId, repository, scope, idempotencyKey, evidenceRefs, policyContext (role, environment, high consequence allowance, token and retention ceilings, approval id), agentId, detail, cursor, limit, and the tool specific args.

Output

eventId, tool, schema and contract versions, scope, result, verdict (pass, fail, blocked, unknown, waived, not_applicable), confidence, limitations, invalidationConditions, evidenceRefs with content hashes and replay steps, nextActions, actionPackets, policyDecision, retryability, error, replayOf, nextCursor, and producedAt.

A verdict is never returned without its limitations and the conditions that would invalidate it. An action packet carries the exact scope it may touch, the changes it must not make, the acceptance checks that close it, and the tool call that records the closure. An agent cannot approve its own high consequence exception.

Error taxonomy

Five error kinds, each with a fixed retryability, so an agent knows whether to retry, escalate, or stop.

retryable_infrastructure

A dependency was unavailable. Replaying the same request with the same idempotency key is safe.

retryable

missing_authority

The caller's role, tenant scope, or policy context does not permit this action. Retrying will not help.

not_retryable

missing_human_input

A decision only a named human may make is outstanding. The request is parked, not failed.

retry_after_human

invalid_contract

The request did not satisfy the tool input contract. The message names the offending field.

not_retryable

product_failure

Instructions could not produce a truthful answer. This is recorded as a product failure rather than dressed up as a result.

not_retryable

jsonReady

{  "name": "symbolic.context_compiler.compile",  "arguments": {    "projectId": "proj_acme_web",    "environmentId": "development",    "scope": "apps/web",    "idempotencyKey": "compile-2026-08-23-01",    "agentId": "claude-code",    "detail": "full",    "args": {      "task": "Add settings persistence to the account page",      "tokenBudget": 1200    }  }}

Omit sources and the tool uses the last recorded scan for the scope. Run symbolic.context_compiler.scan first when the instruction files have changed, so the pack rests on a current observation rather than an old one.

Limitations

Read this before you rely on a Instructions verdict. Symbolic does not present a capability as working until reproducible evidence exists for it. Implemented means this service does it. Caller supplied means the service consumes an observation it does not gather. Not built means it does not exist yet.

01
Caller supplied
Instructions does not clone or crawl a repository. It compiles the sources, facts, validations, and behavior events supplied with the run. Only sources supplied with the run are considered: a source that was never discovered cannot be reported, and coverage is therefore bounded by whatever collected it.
02
Caller supplied
No command is executed and no sandbox is provisioned by this service. A validation record carries its environment (sandbox, static, or not_run) and its attestor. A validation attested by an agent can never verify a rule, and the state reason says so by name.
03
Caller supplied
Compliance probes are descriptors. Instructions generates the prompt, the assertion, the command, and whether the assertion is deterministic. Executing the probe against a live agent and returning the result is a separate step.
04
Caller supplied
A rule reaches the Ignored state only from supplied deterministic behavior events. With no telemetry connected, rules are reported unobserved and listed separately, never scored as compliant.
05
Implemented
The analyzer reads no clock. Freshness, ages, and the drift gate are measured against the evaluation instant supplied on the run, or the latest observation in it. Two runs over the same sources at different times only differ if you tell them the time differs.
06
Implemented
Token counts are estimates at four characters per token, measured against the rendered pack rather than a sum of fragments. Treat the number as a budget approximation, not a tokenizer measurement for a specific model.
07
Implemented
Rule normalization is a parse of prose, and the parse can be wrong. The verbatim source text and line are retained beside every rule, and parse confidence is reported per rule, so a human can check the normalization instead of trusting it.
08
Not built
Instructions does not write to your repository. It does not open pull requests, edit instruction files, or commit compiled packs. Generated change review is specified in the product requirements and is not in this build.
09
Not built
Run history is held in process local runtime state unless the Cloudflare execution fabric is configured. A durable tenant scoped read model is a tracked platform gap, recorded in the product depth audit.
10
Implemented
The demo fixture is synthetic and refuses to run unless DEMO_MODE is enabled. Nothing produced by a demo run is evidence about a real repository.

What it does

Use cases

Monorepo instruction drift

Conflicting guidance

Stale repository claims

New agent tool onboarding

How it works

Collect

Parse

Validate

Resolve and compile

Enforce

Observe

Run types

Input contract

Required

Optional

Output artifact

The pack

The rules

The decisions

Enforcement and behavior

Rule states

Evidence and findings

Evidence kinds

Evidence state machine

Finding kinds

Quickstart

MCP

Shared envelopes

Error taxonomy

Limitations