3.4. What a turn is shown
A registered project is not context everywhere. Each turn starts from its workspace — the registered project, or, for a tree nobody registered, that tree alone, which inherits nothing from the project next to it or the one used before — and is given only:
what its request class calls for: the coding rules, workspace knowledge (Workspace knowledge), procedures and build commands for a change; the standard and its tools, and no implementation material, for a question about the standard; for a general question, the rules that name the
generalclass, workspace knowledge and read-only external capabilities. A MIXED change is selected once per pass;material of this workspace, or material explicitly declared generic;
a rule scoped to paths only when the request names such a path.
The decision is deterministic — no model, no embedder — and recorded in the
audit trail with the reason for every item kept or left out
(context_selected, context_rejected, toolset_selected). It is never
shown to the model. When the context window is tight, optional material is left
out by priority; the request, the runtime’s own constraints and the constraint
packet never are.
The tool family follows the same decision, at the family level only: a change gets the coding core’s six tools, a normative question the standard’s tools, and the MIXED post-check none. A turn on the coding core may also be offered the external capabilities its workspace admits (External capabilities).
3.4.1. Rules and skills are files
Rules (rules.d/*.md) and skills (skills/*.md) are a deployment’s
content, not code: the repository ships the two directories with a README, and
each deployment fills them. Typical fragments look like this:
Fragment |
Content |
|---|---|
|
How to add a package to the target root filesystem. |
|
Coding conventions, including the copyright header rule. |
|
How the project documentation is built. |
|
Procedure for a failing build. |
|
The BitBake-specific variant. |
|
Refactoring guidance for C. |
Keeping these as files rather than as strings in rag_chat.py means the
behaviour of the assistant can be adjusted without touching code, and the
diff of a behavioural change is readable. Each one says where it applies — a
rule in its header, a skill in its scope — and one that says nothing is
not used. Where the two directories live is
Directory layout.
3.4.1.1. Rules declare where they apply
A rule file in rules.d/ opens with a header saying where it applies. A
rule without one applies nowhere: a rule is generic because it says so, not
because nobody scoped it.
---
scope: global every workspace: the only generic scope
scope: corpus acme-firmware this registered project, or one of its parts
scope: family acme-bsp every registered project declaring that family
scope: path /srv/src/acme workspaces whose tree lies under this directory
tasks: implementation, mixed the request classes it serves (the default);
also normative, general
paths: doc/** only when the request names such a path
priority: 80 kept longer when the window is tight
---
Build the documentation with `make -C doc html` and treat warnings as errors.
A skill is held to the same rule: its scope: must name the project or a
family ([family:acme-bsp]), or say [any] to be generic. /recall
rules are generic by what that command means. A project’s own
orientation map belongs to that project only.
3.4.1.2. The skill library
skill_library.py owns the format, and the directory is the only source:
each turn is offered every skill whose scope admits its workspace and whose
required commands exist, read from the files at that moment, so a skill added,
edited or deleted by hand takes effect on the next turn. Which of them fits
the request is left to the model, which is told to follow one only when it
does. A library is expected to stay small; past eight skills for one
workspace, the rest are left out and the audit trail says so.
A skill may open with a SKILL.md frontmatter block – the convention
agentskills.io and Hermes Agent use – which the harness reads and the model
never sees, because it is stripped before injection:
---
name: debug-buildsystem-build
description: Read the failing bitbake task log.
scope: [bsp-a, bsp-b]
requires: [bitbake]
version: 3
created: 2026-06-23T13:26:00
updated: 2026-09-07T15:12:41
---
descriptionOne line saying what the procedure is for, shown with it.
/skillslists it, and a skill that declares none is listed by its body’s first line.scopeThe registered projects the procedure belongs to – a bitbake procedure has no business in an LVGL session – or
family:<name>for every project declaring that family.[any]makes it generic, and must be written: a skill that states no scope is used nowhere. A file saved bysave_skillalways states one.requiresCommands that must exist for the procedure to be runnable. A skill whose requirement is absent is withheld rather than injected, and
/skillssays which command is missing: why a procedure was not used is worth more than the fact that it exists.version/created/updatedWritten by the harness. An overwrite bumps the version and keeps the first stamp, so a procedure the model rewrote three times says so. A rewrite that does not restate
scopeorrequiresinherits them: the model rewriting a body must not silently widen what an operator narrowed.
A file with no frontmatter, or with a block this reader does not understand, is a valid skill whose body is the whole file. Losing a procedure to a stray colon would be worse than ignoring metadata nobody set.
3.4.2. Orientation maps
Each corpus may have a short prose map — where user apps live, which build command to run, what never to edit — injected into the system prompt of every request that changes or asks about that corpus’s code. It is the highest-leverage context the assistant has, and the one most easily wrong: a stale path in it sends the model looking for a script that no longer exists, while a stale chunk would merely be outranked.
Maps live in $SPEAR_RULES_DIR/corpora/<corpus>.md (client/rules.d/corpora/ by
default), not in the tree
they describe. Two reasons:
they say how the assistant should work, which is this repository’s concern, not the product’s — a prompt tweak should not go through a product’s review;
an in-tree file is easily lost: a blanket
.*line in a tree’s.gitignoreswallows it, and whoever clones that tree gets no map and never knows.
An in-tree .edgem-rules.md still wins when present: a tree someone else
owns may carry its own map, and theirs should beat ours. Nothing is invented
for a corpus that has neither.
3.4.3. What the assistant learns, and when it takes effect
Layer |
Takes effect |
Where |
|---|---|---|
workspace knowledge ( |
next turn, one workspace |
|
learned rules ( |
next turn, every corpus |
|
orientation map |
next turn, one corpus |
|
skills ( |
next turn, scope and prerequisite gated |
|
rules (project conventions) |
next turn, scope gated |
|
tool behaviour rules |
next launch |
|
retrieval corpus |
after |
|
history search (cross-session recall) |
continuous |
the history archive collection |
Choosing between the first three is the usual question. /remember records
a fact about this tree, not a rule; the orientation map says where things
live in one corpus and what never to edit there; /recall records a working
rule true everywhere.
/recall exists for rules such as never rewrite an existing copyright
header, only extend its year range: that is true in every tree alike, and
written per corpus it would be invisible in all the others. A recalled line
is dated and appended to rules-learned.md, which is injected after the
rules.d rules on every request that changes or asks about a tree – not on
a question about a bound standard, which no working rule bears on.
That reach is also the cost, so it is budgeted rather than unbounded: the whole
injected rule set is checked against RULES_BUDGET (8 000 characters) and
both the write and the load say so when it is exceeded. Nothing is truncated
silently — the operator is told to trim, because deciding which rule stops
being injected is not a decision to take automatically. /recall with no
argument prints what has been taught so far.
See also
Projects and corpora · Workspace knowledge · External capabilities