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

facility.md

The operator’s guidance, a pointer to the on-demand knowledge tools, and where to read the identity and the facts the build generates (data/facility_facts.md).

Yes

control-system-safety.md

Which control protocol the deployment’s connector speaks (EPICS Channel Access, DOOCS, Tango) and the required osprey.runtime write path.

Yes

timezone.md

The facility timezone used to interpret timestamps.

Yes

safety.md

Channel-write safety, tool confinement, and data-integrity rules.

Customizable

error-handling.md

Error taxonomy and response protocol for tool failures.

Customizable

artifacts.md, python-execution.md, workflows.md

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:

  1. CAS ports outside the 5064–5076 production range (default 59064/59065).

  2. Both EPICS_CAS_SERVER_PORT and EPICS_CAS_BEACON_PORT set — setting one leaves the other on its default.

  3. Every CA client overriding EPICS_CA_SERVER_PORT, stated each time the agent hands over a test PV.

  4. Every test PV carrying the test prefix (default OSPREY:TEST:) — the last line of defense if the ports somehow fail to isolate.

  5. softIoc launched only through a startup script that exports the ports first, never bare at a shell prompt.

  6. 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.md in your repo. osprey init writes it there and lists it as rules/facility, so every build copies it into the render.

  • The framework-generated rules are re-rendered. osprey build writes them again from the framework. To keep an edit to one of those, claim it into the profile first with osprey 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.