aurelienbobenrieth/agentlint/rule-advisor

agentlint rule advisor

First choose the right enforcement mechanism:

• Use a linter, type, schema, test, or codemod for a mechanical invariant with one correct result.
• Use architecture or dependency tooling for a mechanically provable boundary.
• Use runtime tests or monitoring for runtime behavior.
• Use agentlint when a deterministic trigger can identify evidence whose correct outcome still needs contextual judgment.

Start from one concrete recurring correction or required review. Before authoring, inspect existing checks, rules, tests, and durable repository documentation. Establish the invariant, trigger, important permitted cases, scope, authority, and source. Ask only questions that can change that contract.

Compose one effective defineRule:

• standard.id names durable intent; increment revision only when its meaning changes.
• detector.id names reusable detection technology; increment version when evidence equivalence or detection semantics change.
• binding.id names this repository use; choose agent or human authority and keep material options explicit.
• Choose state for current source or repository structure. Choose change when before/after evidence is essential.
• Prefer parsed patterns or tree-sitter queries for local syntax, createOnce for stateful analysis, and a normalized change detector for operations.
• Provide positive permitted examples in guidance. Do not teach agents a catalogue of tempting wrong answers.
• Add focused mustReport activation fixtures and mustStaySilent boundary fixtures. They are proof samples, not an exhaustive taxonomy.
• Identify the material justification. State fingerprints cover the containing file. Declare other supporting files in binding.dependencies and include them in fixtures. Test that changing supporting evidence invalidates the decision.
• Imperative state detectors default to repository scans. Use scan: "file" only when files are independent. Keep plain data for after() because syntax nodes expire after their file visitor.
• Emit concrete local messages. For change findings, choose stable key, material JSON evidence, and optional non-authoritative lineageKey deliberately.

Keep the complete rule in the repository config or an imported rule package:

const rule = defineRule({
  lifecycle: "state",
  standard: {
    id: "domain/standard",
    revision: 1,
    title: "Name the desired property",
    guidance: {
      standard: "State the desired property assertively.",
      checks: ["State the short judgment criterion."],
      examples: [{ code: "showThePermittedPath()" }],
    },
  },
  detector: {
    id: "stack/trigger",
    version: 1,
    match: { pattern: "$OBJ.operation($$$ARGS)", message: "$OBJ requires review." },
    fixtures: {
      mustReport: ["api.operation({})"],
      mustStaySilent: ["api.otherOperation({})"],
    },
  },
  binding: {
    id: "domain/standard",
    authority: "agent",
    include: ["src/**/*.ts"],
  },
});

Validate and calibrate:

<agentlint-cmd> rules test --rule domain/standard
<agentlint-cmd> rules scan --rule domain/standard --review
<agentlint-cmd> explain domain/standard

Review every current candidate. Refine detector, binding, guidance, and fixtures until the activation surface is useful. If the concern cannot be expressed usefully, remove the rule rather than leaving warning-only or candidate state behind.

For an existing plugin, init --preset <package>#<export> scaffolds explicitly chosen presets without installing them or overwriting a config. Calibrate a small starting set before enforcing it.

Export calibration reports from the review UI. Compare successive reports with rules calibration earlier.json later.json --format json: exact evidence is counted once, later labels replace earlier ones, and material policy versions stay separate. Applicability excludes unsure labels. Repeated invalidations count observed identities within explicit lineages, not every historical code edit. Reports never create acceptances.