Authoring Rules
When you ask your coding agent to write a rule, Taskless doesn’t jump straight to its service. It routes the request local-first: it stays on your machine whenever it reasonably can, and only calls the Taskless service when a rule genuinely needs it.
Routing makes one decision, which recipe authors this rule, and it makes that from evidence rather than from preference.
Start from the evidence, not the destination
Section titled “Start from the evidence, not the destination”The order matters, and getting it backwards is the common failure. Naming a destination first and justifying it afterwards is how a rule about prose ends up in sg, and how a question that spans files ends up in vale.
So the question to answer first is not “which engine?” but “what would you have to look at to decide this?”
Detecting your repository
Section titled “Detecting your repository”Routing starts with a scan:
./.taskless/bin/cli.mjs detect --jsondetect is offline and deterministic. It reads your repository and reports what it finds, with no network call: the linters you already use, how many custom rules you have written for each, the languages present, any existing rule styles, your CI and commit hooks, and which command-line tools such as gh are on the machine. A linter is found the way its ecosystem installs or runs it, not only from a dedicated config file: a dev dependency in package.json or pyproject.toml, a [lints.clippy] table in Cargo.toml, or a CI step that runs it. In a monorepo the evidence carries the sub-package path, so a linter configured in one workspace is reported as such. This is the ground truth for routing rather than a guess about your tooling.
{ "success": true, "linters": [ { "name": "eslint", "evidence": ["eslint.config.js", "dependency eslint (package.json)"], "customRules": { "count": 0, "evidence": [] } } ], "languages": ["JavaScript", "TypeScript"], "ruleStyles": [], "ci": [], "hooks": []}The real output also carries hostTools and an agent section, trimmed here.
Login state is read at the same time, because it changes which destinations exist. It is an input to the decision, not a requirement for making it. Routing itself needs no account.
Matching evidence to a destination
Section titled “Matching evidence to a destination”| The rule is decided by… | Recipe | Login |
|---|---|---|
| a tool the repo already runs, in that tool’s dialect | create-legacy-rule |
no |
| one file’s syntax tree: a call, an import, a JSX attribute, a type annotation | create-sg-rule |
no |
| a document’s words: docs, README files, comments, commit bodies | create-vale-rule |
no |
| more than one file, or something outside the files | create-runtime-rule / create-remote-rule |
yes |
Run the decision rather than making it yourself:
./.taskless/bin/cli.mjs agent routeTwo distinctions catch people out:
Correlating two things inside one file is still sg. A useEffect whose dependency array omits a value used in its body compares two places, but both are in one file, so a single-file engine can decide it.
Consistency across documents is not vale. Vale sees one document at a time. “No page may use this word” is Vale; “these twelve pages must agree on a term” needs evidence outside the file being checked, which makes it a runtime question.
The destinations
Section titled “The destinations”A linter you already run
Section titled “A linter you already run”If your repository already runs a linter that can express the rule, the rule goes there, in a fixed order:
- A rule the linter already ships. The agent checks the tool’s catch-all rules by name first (
no-restricted-syntax,banned-api,noRestrictedImports, and others), and confirms the rule exists in the version you have installed. Enabling one is a config change, not new code. - A custom rule in that linter, only when the repository already has five or more of its own custom rules for that tool to model it on.
detect --jsonreports that count per linter ascustomRules. - Otherwise, a Taskless rule. A repository with no custom rules of its own gets no first one from Taskless.
Either way the rule is written in that tool’s own dialect, matching your existing config. ESLint, typescript-eslint, Biome, Ruff, pylint, and flake8 each have a recipe of their own, which names the tool’s catch-all rules and the traps that make a rule silently not fire.
This path is author-only: your own toolchain runs the rule. taskless check does not execute external linters. You run the rule with your existing lint script, the same way you run every other rule in that tool.
A local ast-grep rule
Section titled “A local ast-grep rule”When the rule is decided by one file’s structure, Taskless authors an sg rule locally, with no login, into .taskless/rules/sg/<id>/, then checks it with validate and verify in a feedback loop until it passes. These files have the same shape the Taskless service writes, so check runs them the same way. Improving one later takes the local path, since the service improves only the rules it issued.
A local Vale rule
Section titled “A local Vale rule”When the rule is decided by a document’s words, Taskless authors a vale rule into .taskless/rules/vale/<id>/, also locally and with no login. Vale rules need both a style file and a .vale.ini scope, and an incomplete one fails silently, so validate is part of the loop rather than an optional extra. See Vale.
The runtime engine, or the Taskless service
Section titled “The runtime engine, or the Taskless service”Some rules aren’t reasonably solvable from a single file. They need to hold two files at once, read git metadata, resolve an alias, or follow a config chain. Those become runtime rules, or are generated by the Taskless service when local authoring can’t express them.
Both require an account. Service generation also consumes a generation, so it’s reserved for what can’t be done locally. If a local attempt is tried first and can’t capture your cases, Taskless tells you before spending one.
Local-first, by design
Section titled “Local-first, by design”The routing decision always leans toward staying on your machine:
- A rule your own linter can express stays in your linter.
- A rule one file can decide is authored locally, whether that’s
sgorvale. - Only rules that genuinely need an account go there, and never without your knowledge.
Three of the four engines need no login at all.
The recipes
Section titled “The recipes”Each destination has a recipe your coding agent can fetch:
./.taskless/bin/cli.mjs agent route./.taskless/bin/cli.mjs agent create-legacy-rule./.taskless/bin/cli.mjs agent create-legacy-rule --tool=eslint./.taskless/bin/cli.mjs agent create-sg-rule./.taskless/bin/cli.mjs agent create-vale-rule./.taskless/bin/cli.mjs agent create-runtime-rule./.taskless/bin/cli.mjs agent create-remote-ruleTo create a rule directly, see the Overview. To run your rules, see Checking rules locally. For what each engine is and where it stores rules, see Engines.