Rules and instructions

Rules & instructions are the things you would tell an engineer on their first day: the conventions that aren't written down anywhere in the repository. Every session loads the relevant rules before it touches code.

What makes a good rule#

• Use pnpm, never npm.
• All money is stored in minor units as integers.
• New endpoints need an OpenAPI entry and an integration test.
• Don't edit generated files under src/gen/; change the schema instead.
• UI copy is British English.

Keep each rule to one idea. Short, specific rules are applied more reliably than a long style guide.

Account and repository rules#

• Account rules apply to every repository.
• Repository rules apply only to one repository — its conventions, its gotchas.

Standing and triggered rules#

A rule without a trigger is standing: it is always eligible. A rule with a trigger is used only when the session's goal and criteria match it — for example, a migrations rule triggered by migration or schema.

Each session includes a bounded number of rules, preferring the most relevant, so an enabled rule can still not reach a particular session. Keep rules focused and use triggers for specialised ones.

Versions and usage#

• Every edit creates a new version; old versions stay visible.
• A session records the exact version of each rule it used, so an edit made later never changes what a past session was told.
• Each rule shows which sessions used it.

Platform guidance#

Alongside your rules, Ysra applies a small set of built-in guidance of its own. It is read-only and listed under Platform guidance so you can see what it says.