|
| 1 | +# project-rules |
| 2 | + |
| 3 | +[简体中文](./README_CN.md) |
| 4 | + |
| 5 | +Brings `CLAUDE.md` and path-scoped rule files to ZCode. ZCode reads only `AGENTS.md` from the project root, so a project coming from Claude Code or Cursor loses its `CLAUDE.md` and per-path rules. This plugin adds them back as model context through two hooks. It never blocks, edits, or rewrites a tool call. |
| 6 | + |
| 7 | +## What it does |
| 8 | + |
| 9 | +| Hook | Matcher | What gets injected | |
| 10 | +| --- | --- | --- | |
| 11 | +| `SessionStart` | all sources (startup, resume, clear, compact) | `CLAUDE.md` from the project root, if there is no `AGENTS.md` next to it, plus every rule in `.zcode/rules/*.md` that has no `paths:` | |
| 12 | +| `PreToolUse` | `Read\|Edit\|Write` | Rules whose `paths:` globs match the tool's `file_path`, plus any path-less rule not yet delivered in this session (for example, one that changed or did not fit the SessionStart budget) | |
| 13 | + |
| 14 | +Each rule is delivered once per session. It is delivered again only when its file content changes, or after a new SessionStart (resume, clear, compaction), because the model context starts over then. |
| 15 | + |
| 16 | +The project root is the session's ZCode working directory. |
| 17 | + |
| 18 | +## Rule files |
| 19 | + |
| 20 | +Put Markdown files directly in `.zcode/rules/` at the project root. Frontmatter is optional. |
| 21 | + |
| 22 | +A rule without `paths:` always applies. It is injected at session start: |
| 23 | + |
| 24 | +```markdown |
| 25 | +Run `pnpm test` before finishing a task. |
| 26 | +Never commit generated files under dist/. |
| 27 | +``` |
| 28 | + |
| 29 | +A rule with `paths:` applies when the agent reads, edits, or writes a matching file. For example, `.zcode/rules/typescript.md`: |
| 30 | + |
| 31 | +```markdown |
| 32 | +--- |
| 33 | +paths: src/**/*.ts, src/**/*.tsx |
| 34 | +--- |
| 35 | +Prefer `type` aliases over `interface`. |
| 36 | +Use the logger in src/lib/log.ts instead of console.log. |
| 37 | +``` |
| 38 | + |
| 39 | +`paths:` accepts any of these forms. Cursor's `globs:` key works as an alias, and trailing `# comments` are ignored. |
| 40 | + |
| 41 | +```yaml |
| 42 | +paths: src/**/*.{ts,tsx}, *.proto |
| 43 | +paths: ["src/api/**", "docs/api/"] |
| 44 | +paths: |
| 45 | + - src/db/**/*.sql |
| 46 | + - migrations/ |
| 47 | +globs: *.sql |
| 48 | +``` |
| 49 | +
|
| 50 | +### Glob syntax |
| 51 | +
|
| 52 | +| Pattern | Matches | |
| 53 | +| --- | --- | |
| 54 | +| `*` | any characters except `/` | |
| 55 | +| `?` | exactly one character except `/` | |
| 56 | +| `**` | any number of directories, including none: `src/**/*.ts` matches `src/a.ts` and `src/x/y/a.ts` | |
| 57 | +| `{a,b}` | either alternative: `*.{ts,tsx}` | |
| 58 | +| no `/` in the pattern | the file name at any depth: `*.proto` is the same as `**/*.proto` | |
| 59 | +| leading `/` or `./` | anchored at the project root: `/README.md` | |
| 60 | +| trailing `/` | everything below that directory: `docs/` | |
| 61 | + |
| 62 | +The tool's `file_path` is made relative to the project root (absolute and relative paths both work) and matched with `/` separators, case-sensitively. A `file_path` that is outside the project both as written and after resolving symlinks never matches. Character classes (`[abc]`) and negation (`!`) are not supported. A rule uses its first 32 globs, and a glob longer than 256 characters is ignored. |
| 63 | + |
| 64 | +## Install |
| 65 | + |
| 66 | +From the GitHub repository, which is a standalone marketplace: |
| 67 | + |
| 68 | +```shell |
| 69 | +zcode plugins marketplace add https://github.com/dominiclafleur/zcode-project-rules |
| 70 | +zcode plugins install project-rules@project-rules-marketplace |
| 71 | +zcode plugins enable project-rules@project-rules-marketplace |
| 72 | +``` |
| 73 | + |
| 74 | +In the desktop app, open **Plugin Marketplace -> New**, paste the same URL, then install and enable `project-rules`. |
| 75 | + |
| 76 | +If the plugin is listed in the official marketplace, install it from **Settings -> Plugins** by searching for `project-rules`. |
| 77 | + |
| 78 | +Start a **new session** after installing or enabling it. ZCode takes a snapshot of hooks when a session starts. |
| 79 | + |
| 80 | +Requirements: `node` 16 or newer on `PATH`. There are no npm packages, and the plugin makes no network requests. |
| 81 | + |
| 82 | +## Migrating from Claude Code or Cursor |
| 83 | + |
| 84 | +- **CLAUDE.md**: works as-is when the project root has no `AGENTS.md`. If both exist, ZCode reads `AGENTS.md` and this plugin skips `CLAUDE.md` so the instructions are not loaded twice. Move anything you still need from `CLAUDE.md` into `AGENTS.md`. |
| 85 | +- **Claude Code rules** (`.claude/rules/*.md`): copy them. Their `paths:` frontmatter is read as-is. |
| 86 | + |
| 87 | + ```shell |
| 88 | + mkdir -p .zcode/rules && cp .claude/rules/*.md .zcode/rules/ |
| 89 | + ``` |
| 90 | + |
| 91 | +- **Cursor rules** (`.cursor/rules/*.mdc`): copy them with a `.md` extension. `globs:` is read as `paths:`. Rules without globs become always-on, and Cursor's `alwaysApply` and `description` fields are ignored. |
| 92 | +- **Not carried over**: `@path` imports inside `CLAUDE.md` (they stay as plain text), `CLAUDE.local.md`, `~/.claude/CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.md` files in subdirectories, and subdirectories of `.zcode/rules/`. |
| 93 | + |
| 94 | +## Limits |
| 95 | + |
| 96 | +- **Size**: each rule is cut at 4000 characters and `CLAUDE.md` at 8000. A truncated item ends with a note that tells the model to Read the file for the rest. One injection is capped at 12000 characters and at 30000 bytes of hook output, which keeps it under ZCode's 32 KiB hook stdout limit. Rules that do not fit are deferred to a later Read/Edit/Write call they apply to, and a note names up to five of them. |
| 97 | +- **Timing**: PreToolUse context reaches the model together with the tool result. In the usual Read-then-Edit flow, the model sees a file's rules before it edits that file. A `Write` that creates a new file runs before the model sees the rule, so the rule applies to follow-up edits. |
| 98 | +- **Triggers**: only `Read`, `Edit`, and `Write` calls that carry a `file_path`. Bash, Grep, Glob, and patch-style edits do not trigger path rules. A call whose hook input exceeds 1 MiB (for example a `Write` of a very large file) is skipped. |
| 99 | +- **Discovery**: only `*.md` files directly inside `.zcode/rules/`, up to 200 files of at most 1 MiB each and 2 MiB in total; a file that would pass the total is skipped. Rule files are re-read on every Read/Edit/Write call, so edits apply without restarting. |
| 100 | +- **Root**: `CLAUDE.md` and `.zcode/rules/` are looked up in the ZCode working directory only, not in parent directories. |
| 101 | +- **Cost**: each Read/Edit/Write call starts a short-lived Node process, which usually takes tens of milliseconds. |
| 102 | + |
| 103 | +## Data and side effects |
| 104 | + |
| 105 | +- **Reads**: `CLAUDE.md`, whether `AGENTS.md` exists, and `.zcode/rules/*.md` in the project. Symlinked `CLAUDE.md` or rule files that resolve outside the project are skipped. |
| 106 | +- **Writes**: `${ZCODE_PLUGIN_DATA}/state.json`, or `~/.zcode/project-rules/state.json` when `ZCODE_PLUGIN_DATA` is not set, and a short-lived `state.lock`. The state file holds session ids, rule file paths, and content hashes, and only your user can read it. A session is pruned 7 days after its last state write, which happens at SessionStart and whenever a rule is injected. Nothing is written to the project or to the plugin directory. |
| 107 | +- **No** network access, MCP server, commands, or skills. Besides the `node` process itself, nothing is executed. |
| 108 | +- The hook never returns deny, ask, or rewritten input, and it always exits 0, so tool calls always proceed. On an unexpected error it prints nothing. If the state file cannot be written, SessionStart context is still injected, but PreToolUse injects nothing. |
| 109 | + |
| 110 | +## Troubleshooting |
| 111 | + |
| 112 | +- **Nothing is injected**: start a new session after enabling the plugin. Check that **Settings -> Hooks** lists the two `project-rules` hooks, that rule files end in `.md`, and that each has a non-empty body below the frontmatter. |
| 113 | +- **Diagnostics**: start ZCode with `PROJECT_RULES_DEBUG=1` in its environment, and the hook writes diagnostics to stderr. |
| 114 | +- **Manual run** from your project directory, with `<plugin-dir>` set to the installed plugin path: |
| 115 | + |
| 116 | + ```shell |
| 117 | + printf '%s\n' '{"hookEventName":"PreToolUse","sessionId":"manual","cwd":"'"$PWD"'","toolName":"Read","toolInput":{"file_path":"src/index.ts"}}' \ |
| 118 | + | ZCODE_PLUGIN_DATA=/tmp/project-rules-manual node <plugin-dir>/hooks/rules.js |
| 119 | + ``` |
| 120 | + |
| 121 | +## Development |
| 122 | + |
| 123 | +```shell |
| 124 | +node test/test.mjs |
| 125 | +``` |
| 126 | + |
| 127 | +The self-test needs no ZCode install and no marketplace. It spawns `hooks/rules.js` with SessionStart and PreToolUse payloads and checks the output for these cases: matching and non-matching paths, dedupe, re-injection after a content change, the size and read budgets, hostile globs, symlinks that leave the project, parallel calls, stale and stuck locks, corrupt or oddly shaped state, stale-session pruning, oversized stdin, and an unwritable or unset data directory. |
| 128 | + |
| 129 | +## License |
| 130 | + |
| 131 | +MIT. See [LICENSE](./LICENSE). |
0 commit comments