Repository navigation
feat: inline skills in .ruler and add agent maintenance + orchestration pipeline #202
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| --- | ||
| name: abstraction-police | ||
| allowed-tools: Read, Bash, Edit, Write, Grep, Glob | ||
| description: Find leaky abstractions - internals escaping through interfaces, callers reaching around APIs, boundaries that force callers to know implementation details - and fix one leak per PR. Narrow mechanical maintenance routine intended to run on a schedule. | ||
| --- | ||
|
|
||
| # /abstraction-police - Fix leaky abstractions | ||
|
|
||
| A leak is when a caller must know how something works to use it. Find leaks, | ||
| fix the boundary, one leak per PR. | ||
|
|
||
| ## Leak patterns to scan for | ||
|
|
||
| - **Reach-around**: callers importing from `foo/internal/*`, `foo/lib/*`, or | ||
| deep paths when `foo` has an index/public surface. | ||
| `rg "from ['\"].*/(internal|lib|dist)/" --type ts` | ||
| - **Type leakage**: public function signatures exposing internal types (ORM | ||
| entities, raw API response shapes, third-party client types) instead of | ||
| domain types. | ||
| - **Config leakage**: callers passing implementation-specific options through | ||
| a supposedly generic interface (`{ redisTtl }` on a generic cache). | ||
| - **Error leakage**: raw driver/library errors crossing a boundary uncaught, | ||
| forcing callers to catch `PrismaClientKnownRequestError` and friends. | ||
| - **Sibling knowledge**: module A grepping/parsing module B's files, env | ||
| vars, or storage format instead of calling B. | ||
| - **Boolean/mode flags** that make one function behave as two | ||
| (`doThing(x, true, false)`), forcing callers to know internal branches. | ||
|
|
||
| Rank by blast radius: leaks on boundaries with the most callers first. | ||
|
|
||
| ## Fix | ||
|
|
||
| For the top leak: | ||
|
|
||
| 1. Define the honest interface: what callers actually need, in domain terms. | ||
| 2. Fix the boundary - wrap the internal type, translate the error, narrow | ||
| the config, export the missing public function. | ||
| 3. Migrate every call site. A fix that leaves both the leak and the new path | ||
| alive is worse than no fix; finish the migration or split it across | ||
| sequential PRs with the leak marked deprecated in the first. | ||
| 4. Enforce where cheap: an eslint `no-restricted-imports` rule, an | ||
| `@internal` tag, or a lint on the deep-import pattern, so the leak cannot | ||
| silently return. | ||
| 5. Verify: typecheck, lint, tests of every touched package. | ||
|
|
||
| ## Hard rules | ||
|
|
||
| - Behavior-preserving. Error translation must preserve information (cause | ||
| chaining), not swallow it. | ||
| - No speculative interfaces. Fix the leak that exists; do not design for | ||
| hypothetical future backends. | ||
| - If the "leak" is load-bearing (perf escape hatch, intentional low-level | ||
| API), skip it and record it below. | ||
| - Max one boundary per PR, ~300 changed lines. Large migrations become a | ||
| deprecation PR followed by call-site PRs on later runs. | ||
|
|
||
| ## PR conventions | ||
|
|
||
| - Branch: `chore/abstraction-<slug>` | ||
| - Commit: `refactor: seal <boundary> leak (<pattern>)` | ||
| - Labels: `refactor` + `agent:mechanical` | ||
| - PR body: the leak pattern, list of offending call sites, the new | ||
| interface, and the enforcement added. | ||
|
|
||
| ## Tuning | ||
|
|
||
| This file is the routine. When a PR is rejected, record the case below and | ||
| adjust the patterns or hard rules. | ||
|
|
||
| Intentional leaks (do not touch): | ||
|
|
||
| - (none yet) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| name: dead-code-remover | ||
| allowed-tools: Read, Bash, Edit, Write, Grep, Glob | ||
| description: Remove statically unreachable code immediately, and instrument suspected-but-unproven dead code with probe logging so a later run can confirm and remove it. Narrow mechanical maintenance routine intended to run on a schedule. | ||
| --- | ||
|
|
||
| # /dead-code-remover - Remove dead code, probe suspected dead code | ||
|
|
||
| Two lanes each run: (1) delete code that is provably unreachable, (2) plant | ||
| probes on code that looks dead but cannot be proven dead statically, and | ||
| harvest probes planted by earlier runs. | ||
|
|
||
| ## Lane 1: provably dead - delete now | ||
|
|
||
| Static signals, by ecosystem: | ||
|
|
||
| ```bash | ||
| bunx knip # JS/TS: unused files, exports, deps | ||
| cargo machete # Rust: unused deps | ||
| ``` | ||
|
|
||
| Plus: exports with zero imports (`rg` the symbol), branches behind | ||
| always-false flags, code behind removed feature flags, unreferenced assets. | ||
|
|
||
| Provable means: no dynamic dispatch, no reflection, no string-keyed lookup, | ||
| not a public API of a published package, not referenced from config, | ||
| templates, or CI. If any of those apply, it goes to Lane 2. | ||
|
|
||
| Delete it, then verify: build, typecheck, full test suite. One theme per PR | ||
| (e.g. "remove unused exports in packages/x"), max ~400 deleted lines. | ||
|
|
||
| ## Lane 2: suspected dead - probe, then harvest | ||
|
|
||
| For code that looks dead but is only provably-unused at runtime: | ||
|
|
||
| 1. Plant a probe at the entry point with a greppable marker: | ||
|
|
||
| ```ts | ||
| // DEADCODE-PROBE 2026-08-23 remove-after 2026-08-30 | ||
| console.warn("[deadcode-probe] <symbol> reached"); | ||
|
Comment on lines
+39
to
+40
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win Make the probe example non-operational and date-driven. The harvest command at Lines 48-50 searches for the exact token used at Line 39. It will report this tracked Proposed documentation fix-// DEADCODE-PROBE 2026-08-23 remove-after 2026-08-30
+// DEADCODE-PROBE-EXAMPLE <created-date> remove-after <created-date-plus-7-days>
console.warn("[deadcode-probe] <symbol> reached");
...
-rg -n "DEADCODE-PROBE" --no-heading
+rg -n "DEADCODE-PROBE" --no-heading --glob '!**/SKILL.md'Also applies to: 48-50 🤖 Prompt for AI Agents |
||
| ``` | ||
|
|
||
| Use the codebase's existing logger if one exists. Probes ship in their own | ||
| PR labeled `agent:probe`. | ||
|
|
||
| 2. On every run, harvest expired probes: | ||
|
|
||
| ```bash | ||
| rg -n "DEADCODE-PROBE" --no-heading | ||
| ``` | ||
|
|
||
| For each probe past its `remove-after` date, check the log store (or Sentry | ||
| breadcrumbs, or grep production logs if accessible) for the probe message. | ||
|
|
||
| - Never fired: delete the probe and the code it guards, in a normal Lane 1 PR. | ||
|
Comment on lines
+52
to
+55
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift Require complete log coverage before deleting code. The routine treats 🤖 Prompt for AI Agents |
||
| - Fired: delete the probe only, and record the symbol under "Confirmed alive" | ||
| below so no future run re-probes it. | ||
|
|
||
| ## Hard rules | ||
|
|
||
| - Never delete: public API of published packages, migration code, error | ||
| handlers for rare-but-real paths, platform-conditional code for platforms | ||
| still supported. | ||
| - Deleting a file also means deleting its tests, mocks, stories, and exports. | ||
| Leftover references fail the verify step. | ||
| - Probe windows are 7 days minimum. Do not remove a probe early. | ||
|
|
||
| ## PR conventions | ||
|
|
||
| - Branch: `chore/dead-code-<slug>` | ||
| - Commit: `chore: remove dead <thing>` / `chore: probe suspected dead <thing>` | ||
| - Labels: `refactor` + `agent:mechanical` (removals), `agent:probe` (probes) | ||
| - PR body: evidence per deletion (tool output or zero-reference proof; for | ||
| harvested probes, the probe date range checked and where logs were checked). | ||
|
|
||
| ## Tuning | ||
|
|
||
| This file is the routine. When a PR is rejected or a deletion gets reverted, | ||
| add the case below and tighten the rules. | ||
|
|
||
| Confirmed alive (never re-probe): | ||
|
|
||
| - (none yet) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| --- | ||
| name: dup-unifier | ||
| allowed-tools: Read, Bash, Edit, Write, Grep, Glob | ||
| description: Scan the codebase for similar-yet-slightly-divergent abstractions and put up small PRs that unify them. Narrow mechanical maintenance routine intended to run on a schedule. | ||
| --- | ||
|
|
||
| # /dup-unifier - Unify divergent duplicate abstractions | ||
|
|
||
| Find pairs or clusters of code that started as the same idea and drifted apart | ||
| (copy-pasted helpers, parallel components, re-implemented utilities), then | ||
| unify each cluster in its own small PR. | ||
|
|
||
| ## Scan | ||
|
|
||
| Run in order, cheapest first: | ||
|
|
||
| ```bash | ||
| bunx jscpd --min-tokens 50 --reporters json --output .tmp/jscpd . | ||
| ``` | ||
|
|
||
| - `jscpd` catches literal near-duplicates | ||
| - `ast-grep` catches structural duplicates that differ in identifiers: | ||
| scan for repeated shapes (same function skeleton, same hook pattern, | ||
| same error-handling wrapper) across files | ||
| - Grep for naming smells: `*Util`, `*Helper`, `format*`, `parse*`, `is*`, | ||
| `get*` defined in more than one module with near-identical bodies | ||
|
|
||
| Rank candidates by: (uses x divergence risk) descending. Skip vendored code, | ||
| generated files, tests that intentionally duplicate fixtures, and anything in | ||
| `.gitignore`d paths. | ||
|
|
||
| ## Unify | ||
|
|
||
| One cluster per PR. For the top candidate: | ||
|
|
||
| 1. Pick the canonical location (most imported, or the shared package if one | ||
| exists). Do not invent a new `utils/` dumping ground for a single pair. | ||
| 2. Merge the variants: the union of behavior only if every difference is | ||
| intentional; otherwise prefer the newest/most-tested variant and note the | ||
| dropped behavior in the PR body. | ||
|
Comment on lines
+38
to
+40
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Do not drop divergent behavior during unification. Lines 38-40 allow the routine to prefer the newest or most-tested variant and record dropped behavior. That can change observable behavior. It also contradicts Lines 46-47, which require behavior-preserving changes and require stopping when behavior would change. Replace this fallback with “stop and open an issue” until every difference is proven intentional or explicitly handled. Proposed rule change-3. Merge the variants: the union of behavior only if every difference is
- intentional; otherwise prefer the newest/most-tested variant and note the
- dropped behavior in the PR body.
+3. Merge the variants only when every difference is intentional and the result
+ preserves observable behavior. If a difference is not resolved, stop and
+ open an issue instead of dropping that behavior.🤖 Prompt for AI Agents |
||
| 3. Point all call sites at the canonical version. Delete the copies. | ||
| 4. Verify: typecheck, lint, and the test suites of every touched package. | ||
|
|
||
| ## Hard rules | ||
|
|
||
| - Behavior-preserving only. If unification would change observable behavior, | ||
| stop and open an issue instead of a PR. | ||
| - Max ~300 changed lines per PR. Bigger clusters get split across days. | ||
| - Never unify two things that merely look alike but serve different domains | ||
| (false-positive duplication). When in doubt, skip and record why below. | ||
| - No new abstraction layers. Unifying two functions must not produce a | ||
| factory, base class, or config object. | ||
|
|
||
| ## PR conventions | ||
|
|
||
| - Branch: `chore/dup-unify-<slug>` | ||
| - Commit: `refactor: unify duplicated <thing> into <location>` | ||
| - Label: `refactor` + `agent:mechanical` | ||
| - PR body: the cluster (file:line for each copy), the chosen canonical | ||
| location and why, and any dropped divergence. | ||
|
|
||
| ## Tuning | ||
|
|
||
| This file is the routine. When a PR from this routine is rejected, add the | ||
| reason to the list below and adjust the rules so it does not recur. | ||
|
|
||
| Known false positives (do not attempt again): | ||
|
|
||
| - (none yet) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Cover all supported deep-import forms.
The command at Line 16 matches only imports that contain
from "..."orfrom '...'. It misses side-effect imports such asimport "foo/internal/x", CommonJSrequire("foo/internal/x"), and dynamicimport("foo/internal/x"). Those callers can bypass the public surface and remain undetected. Add AST-based matching or explicit patterns for the import forms used by the repository.🤖 Prompt for AI Agents