[theCodeDrift]

Stack (root → tip):

• ➡️ feat(route): legacy ladder and per-linter custom-rule counts #577 (you are here)
  • feat(agent): per-tool create-legacy-rule recipes with --tool #578

First of two PRs for the legacy-linter-recipes OpenSpec change. For a linter the repository already runs, the agent now uses a rule that linter already ships instead of working out each tool's dialect from scratch. It writes a new custom rule there only when the repository's own rules give it something to copy.

The legacy ladder. route (topic v8) takes these in order:

1. A rule the detected linter already ships solves the request. Always checked first, including the tool's catch-all rules.
2. The repository already has 5 or more of its own custom rules for that linter, so a new one can be modeled on them.
3. A Taskless sg or vale rule.
4. A Taskless runtime rule.

route no longer asks the user to choose between a linter rule and a Taskless rule: the order decides. It also renders a paragraph for each linter detect found, saying what that tool always checks first.

detect --json reports customRules for ESLint, Biome, pylint, flake8, and Ruff: a count of the rules the repository wrote itself for that linter, and where they are.

• ESLint counts rule files in house rule directories.
• Biome counts plugins entries.
• pylint counts load-plugins modules that exist in the repository.
• flake8 counts [flake8:local-plugins] entries and published entry points.
• Ruff is always 0.

ESLint's count is "unknown" when the config defines rules inline or imports a plugin from a local file, because counting those would mean running JavaScript. The recipes treat "unknown" as below the threshold.

Recipes. create-legacy-rule v3 looks for a shipped rule first and asks before adding a plugin the repository does not have. During onboarding (v11), the agent only enables rules from packages already installed: it writes no custom rules and adds no dependencies.

Safe to merge on its own. The route paragraphs name only create-legacy-rule here; #578 adds --tool.

Typecheck, lint, and the full test suite pass. The changeset is in this PR, and #578 extends it.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 5m 47s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no reviews, review threads, or top-level comments beyond the trigger itself, so this is the first review of this PR; everything below is assessed fresh and nothing is being skipped as "already addressed."

• Read .prior-review.json
• Fetch PR diff and changed files
• Review OpenSpec docs for intent
• Review detect/custom-rules.ts
• Review detect/scan.ts and schemas/detect.ts
• Review agent markdown changes (route.md, create-legacy-rule.md, onboard.md)
• Review prompts/recipes.ts and commands/agent.ts
• Review tests
• Post inline comments for findings
• Post final summary

Summary

The implementation lines up well with the OpenSpec proposal/design/spec deltas: the customRules count added to detect --json for ESLint/Biome/pylint/flake8/Ruff, the route legacy ladder, the %(LEGACY_LINTERS)s paragraph rendering, and the rewritten create-legacy-rule.md/onboard.md all match what the specs describe, and the new/updated tests (legacy-ladder.test.ts, the detect.test.ts custom-rule-count suite, prompts.test.ts) exercise the scenarios the spec calls out, including the "unknown treated as below threshold" and monorepo/nested-config cases. I traced the ESLint rule-directory counting, the JSONC-lite parser for Biome, the hand-rolled INI parser for pylint/flake8, and the pyproject entry-point counting against the test fixtures and they check out — the --tool flag and per-tool recipes are correctly left out of scope for this PR (confirmed in agent.ts and tasks.md, section 3+ unchecked).

Two inline findings, both [New]:

1. packages/cli/src/detect/custom-rules.ts:117 — readdirSync(path) in countRuleDirectory isn't wrapped in try/catch, unlike the statSync right below it and every other read in this module. An unreadable rule directory (EACCES, etc.) throws through countEslint → detectRepository, which neither detect.ts nor agent.ts catches; the top-level handler in index.ts would print to stderr and set exitCode = 1 without ever writing JSON to stdout under detect --json. This conflicts with the module's own "derived from files on disk without executing anything" framing and the established "unreadable files are skipped" invariant elsewhere in scan.ts.
2. packages/cli/src/detect/custom-rules.ts:75 — minor: the house rule-directory list (eslint-rules, eslint-local-rules, tools/eslint-rules) is duplicated verbatim in scan.ts's detectRuleStyles. Not a bug, just a drift risk worth a shared constant.

Nothing else stood out as incorrect — the ESLint "unknown" vs. counted-threshold logic, the Biome nested-config summation, the pylint pylint.* exclusion, and the flake8 local-plugin + entry-point counting all matched their test expectations and the design doc's stated behavior.

[theCodeDrift]

Re: @github-actions — "Claude finished @theCodeDrift's task in 5m 47s…"
#577 (comment)

Both inline findings are fixed in ed49196: an unreadable ESLint rule directory is now skipped rather than failing detect (with a test), and the house rule-directory list is shared between custom-rules.ts and scan.ts.

— AI Coding Agent