# conditional-rules

`conditional-rules` injects extra prompt guidance only when the current working set makes it relevant. It runs late in `vera-session-tools`' `pi.extensions` list, after base prompt assembly extensions such as `prompt-rules`, so it appends to the system prompt produced by earlier `before_agent_start` handlers.

## Rule locations

Rules are Markdown files with YAML frontmatter, loaded once on `session_start` from:

- Global agent rules: `agent/rules/conditional/*.md`
- Project rules: `<cwd>/.pi/rules/conditional/*.md`

If a project rule uses the same `name` as a global rule, the project rule wins. Duplicate names within the same layer are skipped with a diagnostic.

## File format

```markdown
---
name: typescript-discipline
globs: ["**/*.ts", "**/*.tsx", "tsconfig.json"]
priority: 50
when: file-accessed
---

# TypeScript Discipline

Guidance to append when this rule activates.
```

Supported frontmatter keys:

- `name` (required): unique rule name; also used as the section header.
- `globs` (required): list of cwd-relative file patterns. Supported glob features are `**`, `*`, `?`, and simple `{a,b}` braces.
- `priority` (optional, default `50`): lower priority rules are injected first; higher priority rules are injected later and therefore take precedence by convention.
- `when` (optional, default `file-accessed`): activation mode.

Unknown frontmatter keys are rejected with a warning to keep rule metadata explicit.

## Activation modes

- `file-accessed`: activates after the agent reads, edits, or writes a matching path during the session.
- `always-if-present`: scans the working tree once on `session_start`; activates if any matching file exists.
- `manual`: reserved for a future manual activation command and is not auto-activated today.

## Adding a rule

Create a new Markdown file under either `agent/rules/conditional/` or `<cwd>/.pi/rules/conditional/`:

```markdown
---
name: markdown-style
globs:
  - "**/*.md"
priority: 40
when: file-accessed
---

# Markdown Style

- Keep headings hierarchical.
- Prefer concise bullet lists for procedural guidance.
```

The rule body will be appended under `## Conditional Rules (activated by working set)` whenever one of its glob patterns matches the session working set.