@fleetagent/pi-coding-agent 0.0.4 → 0.0.6

package/docs/rules.md

@@ -0,0 +1,102 @@
+# Rules
+
+Rules are on-demand, mandatory instruction files. Use them for constraints and policies that must apply when the current task or files match the rule description.
+
+Rules use progressive disclosure like skills: pi lists available rules in the system prompt, and the agent loads the full file only when applicable.
+
+## Locations
+
+Pi loads rules from:
+
+- Global:
+  - `~/.pi/agent/rules/`
+  - `~/.agents/rules/`
+- Project:
+  - `.pi/rules/`
+  - `.agents/rules/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
+- Packages: `rules/` directories or `pi.rules` entries in `package.json`
+- Settings: `rules` array with files or directories
+- CLI: `--rule <path>` (repeatable, additive even with `--no-rules`)
+
+Discovery rules:
+
+- In `~/.pi/agent/rules/` and `.pi/rules/`, direct root `.md` files are discovered as individual rules
+- In all rule locations, directories containing `RULES.md` are discovered recursively
+- In `~/.agents/rules/` and project `.agents/rules/`, root `.md` files are ignored
+
+Disable discovery with `--no-rules` (explicit `--rule` paths still load).
+
+## How Rules Work
+
+1. At startup, pi scans rule locations and extracts names and descriptions
+2. The system prompt includes available rules in XML format
+3. When a task or file matches, the agent uses `read` to load the full `RULES.md`
+4. Applicable rules are mandatory and constrain normal behavior and skills
+
+Only descriptions are always in context. Full instructions load on demand.
+
+## Rule Commands
+
+Rules register as `/rule:name` commands when skill commands are enabled:
+
+```bash
+/rule:typescript          # Load the rule
+/rule:naming-conventions use for new files
+```
+
+Arguments after the command are appended to the rule content as user text.
+
+## Rule Structure
+
+A rule is a directory with a `RULES.md` file. Everything else is freeform.
+
+```text
+typescript/
+├── RULES.md
+└── references/
+    └── examples.md
+```
+
+### RULES.md Format
+
+```markdown
+---
+name: typescript
+description: Mandatory TypeScript rules. Load before editing *.ts or *.tsx files.
+---
+
+# TypeScript Rules
+
+- No `any` unless absolutely necessary.
+- Use top-level imports only.
+```
+
+Use relative paths from the rule directory:
+
+```markdown
+See [examples](references/examples.md).
+```
+
+## Frontmatter
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Falls back to parent directory name. |
+| `description` | Yes | Max 1024 chars. Defines when the rule applies. |
+| `disable-model-invocation` | No | When `true`, the rule is hidden from the system prompt. Users must use `/rule:name`. |
+
+## Description Best Practices
+
+The description determines when the agent loads the rule. Write applicability, not capability.
+
+Good:
+
+```yaml
+description: Mandatory TypeScript rules. Load before editing *.ts or *.tsx files.
+```
+
+Poor:
+
+```yaml
+description: TypeScript help.
+```

package/docs/sdk.md

@@ -164,7 +164,7 @@ await pi.createAgentSession();
 
 ### Resource loading
 
-Use `DefaultResourceLoader` to override or discover extensions, skills, prompt templates, themes, and context files.
+Use `DefaultResourceLoader` to override or discover extensions, skills, rules, prompt templates, themes, and context files.
 
 ```typescript
 const loader = new DefaultResourceLoader({

package/docs/settings.md

@@ -187,7 +187,7 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 
 ### Resources
 
-These settings define where to load extensions, skills, prompts, and themes from.
+These settings define where to load extensions, skills, rules, prompts, and themes from.
 
 Paths in `~/.pi/agent/settings.json` resolve relative to `~/.pi/agent`. Paths in `.pi/settings.json` resolve relative to `.pi`. Absolute paths and `~` are supported.
 
@@ -196,9 +196,10 @@ Paths in `~/.pi/agent/settings.json` resolve relative to `~/.pi/agent`. Paths in
 | `packages` | array | `[]` | npm/git packages to load resources from |
 | `extensions` | string[] | `[]` | Local extension file paths or directories |
 | `skills` | string[] | `[]` | Local skill file paths or directories |
+| `rules` | string[] | `[]` | Local rule file paths or directories |
 | `prompts` | string[] | `[]` | Local prompt template paths or directories |
 | `themes` | string[] | `[]` | Local theme file paths or directories |
-| `enableSkillCommands` | boolean | `true` | Register skills as `/skill:name` commands |
+| `enableSkillCommands` | boolean | `true` | Register skills and rules as `/skill:name` and `/rule:name` commands |
 
 Arrays support glob patterns and exclusions. Use `!pattern` to exclude. Use `+path` to force-include an exact path and `-path` to force-exclude an exact path.
 

package/docs/usage.md

@@ -50,7 +50,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
+| `/reload` | Reload keybindings, extensions, skills, rules, prompts, and context files |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
 | `/quit` | Quit pi |
@@ -197,6 +197,8 @@ Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
 | `--no-extensions` | Disable extension discovery |
 | `--skill <path>` | Load a skill; repeatable |
 | `--no-skills` | Disable skill discovery |
+| `--rule <path>` | Load a rule; repeatable |
+| `--no-rules` | Disable rule discovery |
 | `--prompt-template <path>` | Load a prompt template; repeatable |
 | `--no-prompt-templates` | Disable prompt template discovery |
 | `--theme <path>` | Load a theme; repeatable |
@@ -272,7 +274,7 @@ pi --tools read,grep,find,ls -p "Review the code"
 
 ## Design Principles
 
-Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, rules, prompt templates, and packages.
 
 It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
 

package/examples/extensions/README.md

@@ -102,7 +102,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 
 | Extension | Description |
 |-----------|-------------|
-| `dynamic-resources/` | Loads skills, prompts, and themes using `resources_discover` |
+| `dynamic-resources/` | Loads skills, rules, prompts, and themes using `resources_discover` |
 
 ### Messages & Communication
 

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/dynamic-resources/RULES.md

@@ -0,0 +1,8 @@
+---
+name: dynamic-rule
+description: Example rule loaded from resources_discover. Use when demonstrating dynamic extension resources.
+---
+
+# Dynamic Rule
+
+This rule is provided by the dynamic-resources extension.

package/examples/extensions/dynamic-resources/index.ts

@@ -8,6 +8,7 @@ export default function (pi: ExtensionAPI) {
 	pi.on("resources_discover", () => {
 		return {
 			skillPaths: [join(baseDir, "SKILL.md")],
+			rulePaths: [join(baseDir, "RULES.md")],
 			promptPaths: [join(baseDir, "dynamic.md")],
 			themePaths: [join(baseDir, "dynamic.json")],
 		};

package/examples/extensions/reload-runtime.ts

@@ -12,7 +12,7 @@ export default function (pi: ExtensionAPI) {
 	// Command entrypoint for reload.
 	// Treat reload as terminal for this handler.
 	pi.registerCommand("reload-runtime", {
-		description: "Reload extensions, skills, prompts, and themes",
+		description: "Reload extensions, skills, rules, prompts, and themes",
 		handler: async (_args, ctx) => {
 			await ctx.reload();
 			return;
@@ -24,7 +24,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "reload_runtime",
 		label: "Reload Runtime",
-		description: "Reload extensions, skills, prompts, and themes",
+		description: "Reload extensions, skills, rules, prompts, and themes",
 		parameters: Type.Object({}),
 		async execute() {
 			pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-with-deps",
 	"private": true,
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/sdk/12-full-control.ts

@@ -40,6 +40,7 @@ const cwd = process.cwd();
 const resourceLoader: ResourceLoader = {
 	getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
 	getSkills: () => ({ skills: [], diagnostics: [] }),
+	getRules: () => ({ rules: [], diagnostics: [] }),
 	getPrompts: () => ({ prompts: [], diagnostics: [] }),
 	getThemes: () => ({ themes: [], diagnostics: [] }),
 	getAgentsFiles: () => ({ agentsFiles: [] }),

package/examples/sdk/README.md

@@ -88,7 +88,7 @@ Most one-off session options can be passed directly to `PiAgent.create()`:
 | `tools` | `[
 "read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
 | `customTools` | `[]` | Additional tool definitions |
-| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, rules, prompts, themes |
 | `settingsManager` | SettingsManager.create(cwd, agentDir) | Settings source |
 | `resolveSessionOptions` | undefined | Per-session override hook for model, tools, and diagnostics |
 

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "@fleetagent/pi-coding-agent",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@fleetagent/pi-coding-agent",
-			"version": "0.0.4",
+			"version": "0.0.6",
 			"license": "MIT",
 			"dependencies": {
-				"@fleetagent/pi-agent-core": "^0.0.4",
-				"@fleetagent/pi-ai": "^0.0.4",
-				"@fleetagent/pi-tui": "^0.0.4",
+				"@fleetagent/pi-agent-core": "^0.0.6",
+				"@fleetagent/pi-ai": "^0.0.6",
+				"@fleetagent/pi-tui": "^0.0.6",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "5.6.2",
 				"cross-spawn": "7.0.6",
@@ -473,11 +473,11 @@
 			}
 		},
 		"node_modules/@fleetagent/pi-agent-core": {
-			"version": "0.0.4",
-			"resolved": "https://registry.npmjs.org/@fleetagent/pi-agent-core/-/pi-agent-core-0.0.4.tgz",
+			"version": "0.0.6",
+			"resolved": "https://registry.npmjs.org/@fleetagent/pi-agent-core/-/pi-agent-core-0.0.6.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"@fleetagent/pi-ai": "^0.0.4",
+				"@fleetagent/pi-ai": "^0.0.6",
 				"ignore": "7.0.5",
 				"typebox": "1.1.38",
 				"yaml": "2.9.0"
@@ -487,8 +487,8 @@
 			}
 		},
 		"node_modules/@fleetagent/pi-ai": {
-			"version": "0.0.4",
-			"resolved": "https://registry.npmjs.org/@fleetagent/pi-ai/-/pi-ai-0.0.4.tgz",
+			"version": "0.0.6",
+			"resolved": "https://registry.npmjs.org/@fleetagent/pi-ai/-/pi-ai-0.0.6.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -509,8 +509,8 @@
 			}
 		},
 		"node_modules/@fleetagent/pi-tui": {
-			"version": "0.0.4",
-			"resolved": "https://registry.npmjs.org/@fleetagent/pi-tui/-/pi-tui-0.0.4.tgz",
+			"version": "0.0.6",
+			"resolved": "https://registry.npmjs.org/@fleetagent/pi-tui/-/pi-tui-0.0.6.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fleetagent/pi-coding-agent",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -39,9 +39,9 @@
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
 	},
 	"dependencies": {
-		"@fleetagent/pi-agent-core": "^0.0.4",
-		"@fleetagent/pi-ai": "^0.0.4",
-		"@fleetagent/pi-tui": "^0.0.4",
+		"@fleetagent/pi-agent-core": "^0.0.6",
+		"@fleetagent/pi-ai": "^0.0.6",
+		"@fleetagent/pi-tui": "^0.0.6",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"chalk": "5.6.2",
 		"cross-spawn": "7.0.6",