pi-shepherd 0.1.2 → 0.2.0

package/README.en.md

@@ -1,19 +1,23 @@
-[中文文档](README.md) | English
+[中文文档](README.md) | [English](#)
+
+> 📖 **[pi-atelier Guide](https://catlain.github.io/pi-atelier/)** — Learn the pi-atelier ecosystem from scratch
 
 # pi-shepherd
 
-[Source Code](https://github.com/catlain/pi-shepherd) | [npm](https://www.npmjs.com/package/pi-shepherd)
+[Repository](https://github.com/catlain/pi-shepherd) | [npm](https://www.npmjs.com/package/pi-shepherd)
+
+A **rule-driven behavior guardian** for [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — automatically intercepts, notifies, or rewrites operations at key points in the AI workflow: tool calls, AI responses, and session lifecycle events.
 
-Line count guard and behavior rules extension for [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — rule-driven hooks for tool calls, agent end, and session events.
+## What Problem Does It Solve
 
-## What It Does
+AI coding assistants tend to drift during long sessions:
 
-AI agents can go off the rails — generate too much code, forget to commit, ignore coding standards, or produce outputs that are too large. pi-shepherd acts as a **guardrail system** that monitors and enforces behavioral rules:
+- **Tool misuse**: Using grep for symbol searches (should use code-graph), using bash cat to read files (should use read)
+- **Forgot to wrap up**: Not running tests after edits, not committing git, not updating docs
+- **Coding standard violations**: Using spaces in TypeScript (should use tabs), using tabs in Python (should use spaces)
+- **Repeating mistakes**: Same error recurring without checking existing pitfall records
 
-- **Tool call interception** — Inspect and modify tool calls before execution (e.g., enforce line limits)
-- **Tool result inspection** — Check tool results after execution (e.g., flag overly large outputs)
-- **Agent end hooks** — Enforce commit/message rules when the agent finishes
-- **Session lifecycle** — Reset state between sessions
+pi-shepherd provides a **configurable rules engine** that automatically intervenes at these key points, turning best practices into automated guardrails.
 
 ## Installation
 
@@ -21,116 +25,233 @@ AI agents can go off the rails — generate too much code, forget to commit, ign
 pi install git:github.com/catlain/pi-shepherd
 ```
 
-## How It Works
+## Core Concepts
+
+### Hooks
+
+Shepherd inserts hooks at 6 key points in the AI workflow:
+
+| Hook | When | Typical Use |
+|------|------|-------------|
+| `tool_call` | Before tool execution | Block inappropriate calls, rewrite commands |
+| `tool_result` | After tool execution | Check results, trigger follow-up actions |
+| `agent_end` | When AI voluntarily stops | Remind to commit git, update memory |
+| `message_end` | After each AI response | Detect problematic patterns in responses |
+| `session_shutdown` | When session shuts down | Resource cleanup |
+
+### Actions
+
+4 actions available when a rule matches:
 
-pi-shepherd uses a **rules engine** that evaluates configurable patterns against tool calls and results:
+| Action | Effect |
+|--------|--------|
+| `block` | Prevent tool execution, return reason |
+| `notify` | Show reminder, AI can choose to ignore |
+| `steer` | Inject into next turn, forcing AI to respond |
+| `rewrite` | Rewrite tool parameters then continue |
 
+### Condition Matching
+
+**Single condition** (simple cases):
+```json
+{ "pattern": "\\bcat\\b", "flags": "" }
 ```
-Tool Call → Rules Engine → Pass/Block/Modify
-Tool Result → Rules Engine → Pass/Flag/Truncate
-Agent End → Rules Engine → Enforce (commit, summarize, etc.)
+
+**Multiple conditions** (precise control):
+```json
+{
+  "conditions": [
+    { "field": "path", "pattern": "\\.ts$" },
+    { "field": "text", "pattern": "\\n  [\\S ]" }
+  ]
+}
 ```
 
-### Rules Format
+Multiple `conditions` are **AND** by default (all must match). Use `conditionLogic: "or"` for OR.
+
+**Built-in conditions** (no regex needed):
 
-Rules are defined in `rules.json` (or the `shepherd` section of settings):
+| builtin | Checks |
+|---------|--------|
+| `git_dirty` | Has uncommitted changes in tracked files |
+| `git_untracked` | Has untracked files |
+| `has_edits` | edit/write was called this turn |
+| `always` | Always matches |
+
+### Stateful Rules
+
+Track tool call statistics via the `state` field for patterns like "remind after N errors":
 
 ```json
-[
-  {
-    "name": "block-grep-for-code-graph",
-    "pattern": "^grep\\s+.*\\b[A-Z][a-zA-Z]+\\(",
-    "type": "tool_call",
-    "action": "block",
-    "message": "Use code-graph search_symbols instead of grep for symbol names"
-  },
-  {
-    "name": "warn-large-edit",
-    "pattern": "edit",
-    "type": "tool_result",
-    "maxLines": 500,
-    "action": "warn",
-    "message": "Edit result is large, consider breaking into smaller changes"
-  }
-]
+{
+  "comment": "Remind to check memory after repeated errors",
+  "hook": "tool_result",
+  "action": "steer",
+  "state": { "countKind": "errors", "gte": 5 },
+  "reason": "Tool keeps failing — check memory files for known pitfalls"
+}
+```
+
+Three counting modes:
+- `calls`: Tool invocation count
+- `errors`: Consecutive error count
+- `chars`: Tool result character count
+
+Use `resetOn` to reset counters when a specific tool succeeds (e.g., clear error count after tests pass).
+
+## Rule Format
+
+Complete rule fields:
+
+```json
+{
+  "comment": "Rule description (required, also serves as unique ID)",
+  "hook": "tool_call",
+  "tool": "bash",
+  "action": "block",
+  "reason": "Message shown to AI",
+  "pattern": "\\bcat\\b",
+  "conditions": [{ "field": "path", "pattern": "\\.ts$" }],
+  "conditionLogic": "and",
+  "enabled": true,
+  "state": { "countKind": "errors", "gte": 3 },
+  "resetOn": ["bash"],
+  "subagent": false,
+  "requiresTools": ["code_graph_semantic_code_search"],
+  "requireSuccess": true,
+  "stopReason": ["stop"]
+}
 ```
 
-### Rule Types
+**Required fields**: `comment`, `reason`
 
-| Type | When Evaluated | Actions |
-|------|---------------|---------|
-| `tool_call` | Before tool execution | `pass`, `block`, `modify` |
-| `tool_result` | After tool execution | `pass`, `warn`, `truncate` |
-| `agent_end` | When agent finishes | `enforce` |
+**Optional fields**:
+- `enabled`: `false` to disable (default `true`, can be omitted)
+- `subagent`: `false` to skip in subagent sessions
+- `requiresTools`: Only trigger when all listed tools are available
+- `requireSuccess`: `true` to skip `isError` tool_results
+- `stopReason`: For `agent_end` only, limit to specific end reasons
 
-## Built-in Rules
+## Rule Locations
 
-pi-shepherd ships with default rules for common anti-patterns:
+**Global rules**: `~/.pi/agent/extensions/shepherd/rules.json` (applies to all projects)
 
-- Redirect `grep` to `code-graph` for symbol searches
-- Warn on overly large tool results
-- Enforce git commit on agent end
-- Block redundant file reads
+**Project rules**: `{cwd}/.pi/extensions/shepherd-rules.json` (current project only)
+Or `{cwd}/.pi/extensions/shepherd-rules-*.json` (multiple files)
 
-## Configuration
+Project and global rules are merged. Project rules can supplement or override global rules.
+
+## Managing Rules
+
+Use the `shepherd_rules` tool for safe editing (auto-validates, backs up, and verifies):
+
+```
+# List all rules
+shepherd_rules(action: "list")
+
+# Add a rule
+shepherd_rules(action: "add", rule: { comment: "...", hook: "...", ... })
+
+# Update a rule
+shepherd_rules(action: "update", index: 2, changes: { enabled: false })
+
+# Delete a rule
+shepherd_rules(action: "delete", index: 3)
+```
+
+## Practical Examples
+
+### 1. Auto-run tests after editing Python
 
 ```json
 {
-  "shepherd": {
-    "enabled": true,
-    "rulesDir": "~/.pi/agent/shepherd-rules"
-  }
+  "comment": "Run tests after Python edit",
+  "hook": "tool_result",
+  "tool": "edit",
+  "action": "notify",
+  "conditions": [{ "field": "path", "pattern": "\\.py$" }],
+  "reason": "Python file edited — please run ruff check and unit tests"
 }
 ```
 
-## Use Cases
+### 2. Check git status before session ends
 
-| Scenario | Rule Type | Action |
-|----------|-----------|--------|
-| **Enforce coding standards** | `tool_call` | Block tools that don't follow conventions |
-| **Prevent context bloat** | `tool_result` | Truncate large results |
-| **Git discipline** | `agent_end` | Force commit at session end |
-| **Redirect to better tools** | `tool_call` | Block grep, suggest code-graph |
-| **Custom team rules** | All types | Project-specific guardrails |
+```json
+{
+  "comment": "Check git before session end",
+  "hook": "agent_end",
+  "action": "notify",
+  "conditions": [
+    { "builtin": "git_dirty" },
+    { "builtin": "git_untracked" }
+  ],
+  "conditionLogic": "or",
+  "reason": "Git has uncommitted changes — please confirm if commit + push is needed"
+}
+```
 
-## Best Practices
+### 3. Redirect grep to code-graph for code search
 
-### ✅ Recommended
-- Start with built-in rules, then add project-specific ones
-- Use `warn` before `block` — give the agent a chance to learn
-- Keep rule patterns simple and specific — regex is evaluated on every tool call
-- Put project rules in `.pi/shepherd-rules/` for version control
+```json
+{
+  "comment": "Recommend code-graph over grep",
+  "hook": "tool_result",
+  "tool": "grep",
+  "action": "notify",
+  "pattern": ".",
+  "reason": "Use code-graph for code search: semantic_code_search (fuzzy), get_ast_node (exact), find_references (refs)",
+  "requiresTools": ["code_graph_semantic_code_search"]
+}
+```
 
-### ❌ Not Recommended
-- Don't use overly broad patterns — they'll match too many calls and slow things down
-- Don't create contradictory rules (block + allow the same pattern)
-- Don't rely on shepherd for security — it's a guide, not a sandbox
+### 4. Block attribution guessing in AI responses
 
-## Limitations
+```json
+{
+  "comment": "Block attribution guessing",
+  "hook": "message_end",
+  "action": "steer",
+  "pattern": "(probably|might be|guess|likely).*(jiti|cache|toolchain)",
+  "reason": "Don't guess root causes — check your code logic first, search for best practices, verify before concluding"
+}
+```
+
+### 5. Block direct settings.json editing
 
-| Limitation | Detail |
-|------------|--------|
-| Regex only | Patterns use regex, not semantic understanding |
-| No async rules | Rules must evaluate synchronously |
-| Agent can bypass | Determined agents can ignore warnings |
-| No persistence | Rule state resets between sessions |
+```json
+{
+  "comment": "Block direct settings.json editing",
+  "hook": "tool_call",
+  "tool": "edit|write",
+  "action": "block",
+  "conditions": [{ "field": "path", "pattern": "settings\\.json$" }],
+  "reason": "Directly editing settings.json caused config loss before — use settings_patch tool instead"
+}
+```
 
 ## Architecture
 
 ```
 pi-shepherd/
-├── index.ts          # Entry: register hooks + rules engine
-├── rules-engine.ts   # Pattern matching + action dispatch
-├── rules/            # Built-in rule definitions
-│   ├── grep.ts       # Redirect grep → code-graph
-│   ├── line-limit.ts # Warn on large outputs
-│   └── agent-end.ts  # Enforce git commit
-├── types.ts          # Rule type definitions
-└── package.json
+├── index.ts              # Entry: register all hooks
+├── shepherd/
+│   ├── rules.ts          # Rule types + load/compile/match
+│   ├── conditions.ts     # Condition types + builtin matching
+│   ├── state-tracker.ts  # Stateful rule state tracker
+│   ├── tool-hooks.ts     # tool_call / tool_result hook handlers
+│   ├── message-end.ts    # message_end hook handler
+│   ├── rules-tool.ts     # shepherd_rules tool registration
+│   ├── rules-editor.ts   # Safe rule file editing (backup+validate)
+│   ├── rules-validate.ts # Rule format validation
+│   ├── ephemeral.ts      # Warning buffer (pushWarning)
+│   ├── git.ts            # Git status check utilities
+│   └── worktree-check.ts # Worktree environment detection
+├── rules.json            # Default global rules
+└── tests/                # Tests
 ```
 
 **Dependencies**:
-- `@pi-atelier/shared-utils` (bundled) — settings management
+- `@pi-atelier/shared-utils` — Config API, tool output formatting
 - `@earendil-works/pi-coding-agent` — ExtensionAPI (peer)
 
 ## License