@quandev104/pi-rules

Pi extension for path-scoped project rules. It discovers .pi/rules/**/*.md, matches rules to the files an agent is working on, injects relevant guidance, and lets agents recommend rule updates for user approval.

---

Install

pi install npm:@quandev104/pi-rules

Bootstrap rules for a project:

/pi-rules:init

Rules live in:

.pi/rules/**/*.md

---

Quick example

---
paths:
  - "src/api/**/*.ts"
summary: API handler conventions
triggers:
  - "create endpoint"
  - "add route"
priority: 10
guard: true
---

# API Rules

- Validate input with Zod.
- Return `Result<T>`; do not throw from handlers.
- Wrap authenticated routes with `withAuth()`.

When the agent works on src/api/login.ts, this rule can be injected into context. If guard: true and write guard is enabled, write/edit is blocked until the rule has been shown to the agent.

---

Config

Config files are optional.

Scope	Path
Global	~/.pi/agent/pi-rules/config.json
Project	.pi/pi-rules/config.json

Precedence:

defaults < global config < project config < env vars < CLI flags

Recommended low-noise setup in .pi/pi-rules/config.json:

{
  "mode": "static",
  "dynamicInjection": "off",
  "writeGuardEnabled": true
}

Config fields

Field	Type	Default
disabled	boolean	false
mode	"static" | "dynamic" | "both" | "off"	"both"
dynamicInjection	"off" | "full"	"full"
writeGuardEnabled	boolean	false
recommendationEnabled	boolean	true
widgetEnabled	boolean	true
appliedWidgetEnabled	boolean	true
maxRuleChars	number	12000
maxContextChars	number	40000
maintainerLogLines	number	100

Environment variables

Variable	Description
PI_RULES_DISABLED=1	Disable extension
PI_RULES_WRITE_GUARD=1	Enable write/edit guard
PI_RULES_DYNAMIC_INJECTION=off|full	Control dynamic rule injection
PI_RULES_MAX_RULE_CHARS=12000	Per-rule body cap
PI_RULES_MAX_CONTEXT_CHARS=40000	Total context cap per injection
PI_RULES_MAINTAINER_LOG_LINES=100	Maintainer log tail length
PI_RULES_RECOMMENDATIONS_DISABLED=1	Disable rule recommendations
PI_RULES_APPLIED_WIDGET=1|0	Force-enable (1) or disable (0) the applied-rules chat annotation (on by default)

CLI flags

--pi-rules-disabled
--pi-rules-mode static|dynamic|both|off
--pi-rules-dynamic-injection off|full
--pi-rules-write-guard
--pi-rules-recommendations
--pi-rules-widget
--pi-rules-applied-widget

---

Applied-rules chat annotation

On by default: when an injection contains rules not already shown for the current agent run, a dim annotation is appended to the chat transcript:

├─ core/csharp.md       **/*.cs
└─ architecture/module-structure.md  src/Modules/**

Each line shows the rule file and how it matched (alwaysApply, a glob pattern, or a trigger phrase). Repeated injections of the same rule in one agent run are shown only once; newly discovered rules add a compact entry. The annotation persists in the session — it is display-only and never sent to the model context. Requires pi >=0.80.4 (custom entry renderers). To turn it off, set appliedWidgetEnabled: false in the config file or PI_RULES_APPLIED_WIDGET=0.

---

Injection model

Mode	Behavior
static	Inject matching rules at the start of the agent turn.
dynamic	Inject matching rules after tool results.
both	Static + dynamic. Default.
off	Do not inject rules.

Dynamic injection can be muted independently:

{
  "dynamicInjection": "off"
}

This still tracks touched paths, but avoids appending full rules during exploration.

Write guard

Enable:

{
  "writeGuardEnabled": true
}

Then mark critical rules:

guard: true

Flow:

agent calls edit/write
→ pi-rules matches target path
→ if a guarded rule has not been injected: block tool call + show rule
→ agent retries with the rule in context

Currently guarded tools:

write, edit

---

Rule frontmatter

---
paths:
  - "src/auth/**/*.ts"
ignorePath:
  - "docs/**"
summary: Auth conventions
triggers:
  - "login flow"
alwaysApply: false
priority: 10
kind: rules
guard: true
---

Field	Type	Description
paths	string | string[]	Glob patterns matched against project-relative paths.
ignorePath	string | string[]	Glob patterns excluded from matching. The rule is skipped when every target path matches one of these patterns (e.g. alwaysApply rules that should stay silent while editing docs/).
summary	string	One-line routing summary.
triggers	string | string[]	Prompt phrases that should load the rule.
alwaysApply	boolean	Inject on every code-related turn. Use sparingly.
priority	number	Higher priority rules are injected first.
kind	"rules" | "inventory"	rules are injected; inventory files are listed as available.
guard	boolean	Require this rule before write/edit when write guard is enabled.
description	string	Human-readable description; not used for matching.

Parent/child behavior

When parent and child rules both match, child rules are injected fully and parent rules are summarized.

.pi/rules/api/api.md          → summary only
.pi/rules/api/auth/auth.md    → full body

Ignoring paths (ignorePath)

ignorePath excludes target paths from a rule. A rule is skipped when every target path of the turn matches one of its ignorePath patterns — useful for alwaysApply rules that would otherwise be injected (and waste tokens) while the agent only edits docs/.

---
paths:
  - "**/*"
alwaysApply: true
summary: Code conventions (skipped while editing docs)
ignorePath:
  - "docs/**"
  - "README.md"
---

Two strictness levels:

• alwaysApply: true + ignorePath — still injected on signal-less turns (no path tokens in prompt, no tool activity yet) that are code-related.
• paths: ["**"] + ignorePath — strictest: never injected when the turn carries no path signals at all, and skipped when all targets are ignored. Prefer this when the rule only matters for real code work.

Additionally, alwaysApply + ignorePath rules are suppressed entirely on non-code turns that carry no path signals (e.g. "improve the wording in the documentation"), since there is no target for the ignore check to evaluate.

---

Commands

Command	Description
/pi-rules:init [...prompt]	Bootstrap .pi/rules/.
/pi-rules:status	Show rules, diagnostics, and pending recommendations.
/pi-rules:mode [static|dynamic|both|off]	Set project injection mode; opens a selector when no arg is passed.
/pi-rules:write-guard [on|off]	Configure project write/edit guard; opens a selector when no arg is passed.
/pi-rules:doctor	Rule discovery diagnostics.
/pi-rules:context	Show last injected rules.
/pi-rules:cleanup	Show recommendation storage location.

---

Tools

Tool	Description
create_rule	Create a .pi/rules/*.md rule file.
pi_rules_recommend	Queue a rule update recommendation for user approval.

---

Recommendations

Agents do not rewrite rules directly. They create recommendations, and the user approves them.

agent identifies a convention
→ pi_rules_recommend creates pending recommendation
→ user reviews and approves through the pi-rules TUI
→ maintainer skill updates the rule

Recommendation state is stored under:

.pi/.pi-rules/recommendations.json

---

Architecture

shared → domain → features → app → pi

extension-src/pi-rules/
├── shared/     path, fs, hash, glob, frontmatter
├── domain/     parser, scanner, matcher, formatter, engine
├── features/   recommendations, watcher, tool path extraction
├── app/        config, runtime state
└── pi/         Pi event handlers, commands, tools

Layer boundaries are enforced by dependency-cruiser.

---

Development

npm install
npm run typecheck
npm run lint
npm run depcruise
npm test
npm run build
npm run check

Current test suite: 223 tests.

---

License

MIT