Facility Rules#
The always-in-context tier of Facility Knowledge
is the set of Markdown rules under the project’s .claude/rules/ directory.
They load into the main agent’s context at the start of every session, the same
way CLAUDE.md does. Several of them carry facility-specific operating
context.
To change a rule, see Changing a rule.
What the demo preset ships#
Rule |
Holds |
Facility-specific |
|---|---|---|
|
The operator’s guidance, a pointer to the on-demand knowledge tools, and
where to read the identity and the facts the build generates
( |
Yes |
|
Which control protocol the deployment’s connector speaks (EPICS Channel
Access, DOOCS, Tango) and the required |
Yes |
|
The facility timezone used to interpret timestamps. |
Yes |
|
Channel-write safety, tool confinement, and data-integrity rules. |
Customizable |
|
Error taxonomy and response protocol for tool failures. |
Customizable |
|
Generic operating rules — artifact reuse, code execution, and task planning/delegation. |
No |
Some rules render conditionally: data-visualization.md is generated only
when the data-visualizer agent is not enabled (the agent carries its own
plotting guidance, and the demo preset enables it — so a
default project has no such rule file), and timezone.md only appears when
system.timezone is set.
A build profile can add rules of its own. Any rule without paths frontmatter
loads unconditionally at session start.
Test IOC port isolation#
test-ioc-safety is a packaged rule the demo preset selects
by default (it renders only where the deployment’s connector speaks Channel
Access). For other profiles, add it to the rules: list when the project runs
an EPICS soft IOC for testing:
rules:
- test-ioc-safety # mandatory port isolation for a test soft IOC
It renders wherever the deployment’s connector speaks Channel Access: an EPICS machine, the served virtual accelerator, the live stand-in. Under any other connector it renders empty and the build drops the file.
The rule exists because EPICS Channel Access broadcasts on UDP by default. A
softIoc started with no port configuration binds to UDP 5064 (server) and
5065 (beacon) and beacons to the broadcast address — where every real IOC on the
network sees it. A test PV whose name collides with a production PV can then
route a read to the wrong value, or a write to real hardware. The rule tells the
agent to refuse any test-IOC action that does not satisfy all six of:
CAS ports outside the 5064–5076 production range (default
59064/59065).Both
EPICS_CAS_SERVER_PORTandEPICS_CAS_BEACON_PORTset — setting one leaves the other on its default.Every CA client overriding
EPICS_CA_SERVER_PORT, stated each time the agent hands over a test PV.Every test PV carrying the test prefix (default
OSPREY:TEST:) — the last line of defense if the ports somehow fail to isolate.softIoclaunched only through a startup script that exports the ports first, never bare at a shell prompt.DB files within the EPICS parser’s limits — DESC fields at most 39 ASCII characters, no multibyte characters, and no
$(...)even inside comments.
The rule carries the startup-script pattern, the client-side environment, a pre-flight validation snippet, and the shutdown sequence, so the agent has a concrete correct procedure rather than a prohibition alone.
Changing a rule#
There are two ways to edit a rule.
Edit the Markdown directly. Each rule the agent loads is a file under
build/.claude/rules/, and build/ is disposable, so edit the copy in
your repo:
The facility description is yours. Edit
rules/facility.mdin your repo.osprey initwrites it there and lists it asrules/facility, so every build copies it into the render.The framework-generated rules are re-rendered.
osprey buildwrites them again from the framework. To keep an edit to one of those, claim it into the profile first withosprey scaffold claim rules/safety(Taking ownership of a framework artifact).
Through the web terminal. osprey web exposes the agent’s .claude/
files in the browser: edit a rule in the setup editor, or use the scaffold
gallery to override a framework-generated rule (which claims it for you). See
Run the Web Terminal.
Answer provenance (verify-first)#
Beyond the .claude/rules/ files, the agent’s answer posture is set by two
framework-generated artifacts — the control-operator output-style and the
generated CLAUDE.md. Both instruct the agent to answer verify-first:
For a factual question it queries the appropriate tool or source first, and leads with that result, naming the source.
Anything it cannot back with a tool is flagged plainly and up front. It never leads confidently with a buried caveat, and never follows an answer with an optional offer to verify.
A multi-tool or research answer closes with an explicit provenance summary: the sources it used and a brief confidence/scope note. Single reads stay terse.
Because it ships in framework-generated artifacts, the claimed-artifact caveat
from Changing a rule applies. A deployment that has osprey scaffold
claim``ed ``CLAUDE.md (claude-md) or the control-operator output-style
keeps its own copy and will not pick up this behavior on the next
osprey build. To adopt it, review the framework version and either merge it
by hand or unclaim and rebuild:
$ osprey scaffold diff output-styles/control-operator # framework vs. yours
$ osprey scaffold unclaim output-styles/control-operator # then: osprey build
See also
- Facility Knowledge
How the always-in-context rules relate to the on-demand OKF bundle.
- Build Profiles
How a build profile carries its own rules into a generated project.