diff --git a/.cursor/rules/lean-ctx.mdc b/.cursor/rules/lean-ctx.mdc new file mode 100644 index 00000000..e8e6bcba --- /dev/null +++ b/.cursor/rules/lean-ctx.mdc @@ -0,0 +1,35 @@ +--- +description: "lean-ctx cli-redirect: prefer lean-ctx CLI commands for token savings" +alwaysApply: true +--- + +# lean-ctx — Context Engineering Layer + + +## Mode: CLI-Redirect (no MCP schema overhead) + +Prefer lean-ctx CLI commands over MCP tools: + +| USE (via Shell/Bash) | INSTEAD OF (MCP) | Why | +|---------------------|-------------------|-----| +| `lean-ctx read [-m mode]` | `ctx_read` | No MCP schema overhead, same caching | +| `lean-ctx -c ""` | `ctx_shell` | Pattern compression (95+ patterns) | +| `lean-ctx grep [path]` | `ctx_search` | Compact results via CLI | +| `lean-ctx ls [path]` | `ctx_tree` | Directory maps via CLI | + +## Read modes + +auto | full | map | signatures | diff | aggressive | entropy | task | reference | lines:N-M + +## Mode selection + +1. Editing? → `full`, then `diff` for re-reads +2. API surface? → `map` or `signatures` +3. Large context-only? → `entropy` or `aggressive` +4. Unsure? → `auto` + +Anti-pattern: never use `full` for files you won't edit. + +## File editing + +Use native Edit/StrReplace. Write/Delete/Glob → use normally. diff --git a/.cursor/rules/lean-ctx.mdc.lean-ctx.1778574588.bak b/.cursor/rules/lean-ctx.mdc.lean-ctx.1778574588.bak new file mode 100644 index 00000000..54dc7304 --- /dev/null +++ b/.cursor/rules/lean-ctx.mdc.lean-ctx.1778574588.bak @@ -0,0 +1,122 @@ +--- +description: "lean-ctx: prefer ctx_read/ctx_shell/ctx_search/ctx_tree over Read/Shell/Grep/ls for token savings" +globs: **/* +alwaysApply: true +--- + +# lean-ctx — Context Engineering Layer + + +PREFER lean-ctx MCP tools over native equivalents for token savings: + +## Tool Mapping + +| PREFER | OVER | Why | +|--------|------|-----| +| `ctx_read` | `Read` | Session caching, 10 read modes, re-reads cost ~13 tokens | +| `ctx_shell` | `Shell` | Pattern-based compression for git, npm, cargo, docker, tsc | +| `ctx_search` | `Grep` | Compact context, token-efficient results | +| `ctx_tree` | `ls`, `find` | Compact directory maps with file counts | + +## ctx_read Modes + +- `auto` — auto-select optimal mode (recommended default) +- `full` — default, cached read (use for files you will edit) +- `map` — dependency graph + exports + key signatures (use for context-only files) +- `signatures` — API surface only +- `diff` — changed lines only (use after edits) +- `task` — task-relevant filtering +- `reference` — quote-friendly minimal excerpts +- `aggressive` — syntax stripped +- `entropy` — Shannon + Jaccard filtering +- `lines:N-M` — specific range + +Re-reads cost ~13 tokens. File refs F1, F2.. persist across the session. + +Set `fresh=true` on ctx_read to bypass cache when spawned as a subagent or after context compaction. + +## Mode Selection + +1. Editing the file? → `full` first, then `diff` for re-reads +2. Need API surface only? → `map` or `signatures` +3. Large file, context only? → `entropy` or `aggressive` +4. Specific lines? → `lines:N-M` +5. Active task set? → `task` +6. Unsure? → `auto` (system selects optimal mode) + +Anti-pattern: never use `full` for files you won't edit — use `map` or `signatures`. + +## File Editing + +Use native Edit/StrReplace when available. If Edit requires native Read and Read is unavailable, +use `ctx_edit(path, old_string, new_string)` — it reads, replaces, and writes in one MCP call. +NEVER loop trying to make Edit work. If it fails, switch to ctx_edit immediately. + +## Session Management + +- `ctx_compress` at >10 turns — creates memory checkpoint +- `ctx_metrics` — hard numbers on what was saved +- `ctx_cost` — per-tool cost + savings breakdown +- `ctx_heatmap` — file-level savings heatmap +- `ctx_benchmark` — find optimal mode for a file +- `ctx_session load` — on new chat, restore previous session +- `ctx_session role` — list/switch agent roles (governance) +- `ctx_session budget` — show budget status vs role limits +- `ctx_session slo` — show SLO status/violations (value=reload|history|clear) +- `ctx_session diff` — compare two sessions (value=" [json]") +- `ctx_session verify` — show output verification statistics +- `ctx_session episodes` — episodic memory (value=record | "search " | "file " | "outcome