ravi-rules

name	ravi-rules
description	Use when creating, reviewing, or debugging `.ravi/rules` runtime prompt rules: - adding workspace/fleet rules that must be injected into built system prompts - diagnosing missing or duplicated `## Ravi Rules` sections - changing runtime prompt assembly around rules, AGENTS.md, or provider fallbacks - deciding whether a rule belongs in `.ravi/rules`, AGENTS.md, a spec, or an agent prompt

Ravi Rules

.ravi/rules is the Ravi-owned source for workspace runtime rules that must be injected into the built system prompt.

Before changing this area, read the normative spec:

bin/ravi specs get runtime/prompt-rules --mode rules --json

Mental Model

• AGENTS.md describes workspace development instructions.
• .ravi/rules describes runtime/fleet rules that should be injected into session prompts.
• Agent systemPromptAppend specializes one configured agent.
• Provider settings such as ~/.claude/rules are not the Ravi source of truth.
• Provider folders such as .claude/rules and .agents/rules are import sources only. Runtime prompt assembly must read .ravi/rules.

The runtime loads rules from the effective session cwd:

<session-cwd>/.ravi/rules/

Each non-empty supported file is rendered under one final prompt section:

## Ravi Rules

### some-rule.md

...

Loader Contract

• Read recursively.
• Emit deterministic relative-path order.
• Ignore hidden entries such as .gitkeep and .DS_Store.
• Ignore empty files.
• Accept .md, .markdown, .txt, and extensionless text files.
• Do not inject binary files or arbitrary generated artifacts.
• Keep one top-level ## Ravi Rules section.
• Place the section after Workspace Instructions and before Agent Instructions.
• Preserve trace metadata as id=ravi.rules.

Import Contract

Use the CLI to migrate rules from provider-owned folders into Ravi-owned rules:

ravi rules sources all --json
ravi rules import all --write --json

Supported import sources:

• project Claude rules: <cwd>/.claude/rules
• project agents-folder rules: <cwd>/.agents/rules
• user Claude rules: ~/.claude/rules only with --include-user
• user agents-folder rules: ~/.agents/rules only with --include-user

Imported files must land under:

<cwd>/.ravi/rules/imported/<provider>/<scope>/<relative-rule-path>

Rules:

• Import dry-runs unless --write is passed.
• User-level imports require --include-user.
• Existing imported files are skipped unless --force is passed.
• Import summaries must not print raw rule content in JSON.
• Import uses the same hidden/empty/unsupported/binary filtering as runtime loading.

Editing Guidance

Put a rule in .ravi/rules when it is:

• operational behavior expected across sessions in that workspace;
• stable enough to be reviewed as repository content;
• useful in both task sessions and direct sessions;
• not specific to a single agent identity.

Put it somewhere else when:

• it is a codebase contributor convention: use AGENTS.md;
• it is a durable architectural invariant: use .ravi/specs;
• it is specific to one agent: use that agent's prompt/config;
• it is private user preference: keep it out of the repo.

Never store secrets, tokens, private keys, or credentials in .ravi/rules.

Validation

After changing loader behavior or prompt ordering, run:

bun test src/runtime/runtime-system-prompt.test.ts src/runtime/codex-provider.test.ts src/runtime/session-trace.test.ts
bun test src/cli/commands/rules.test.ts
bun run typecheck
bun run build

If task behavior is involved, also run:

bun test src/tasks/service.test.ts src/tasks/profiles.test.ts