Your agent reads Flow's instructions, but nothing guarantees it follows them every time. When a convention can be checked in the code itself, Flow ships it as an ast-grep rule that ESLint runs. ESLint reports a violation no matter who wrote the code, in your editor, in npm run lint and in CI, so you never have to remind your agent about it.

npx @adonisplus/flow install offers to add the rules to your eslint.config.js. It installs @adonisjs/eslint-ast-grep and adds two lines to the config.

eslint.config.js
import { configApp } from '@adonisjs/eslint-config'
import { astGrep } from '@adonisjs/eslint-ast-grep'

export default configApp(...astGrep('@adonisplus/flow/rules')) 

If you use a different ESLint config, Flow prints these two lines so you can add them yourself.

Each rule is named ast-grep/<rule>. To switch a rule off for one line, use an ESLint comment.

// eslint-disable-next-line ast-grep/no-top-level-functions
function legacyHelper() {}

To switch it off for the whole app, set it to off in your config.

eslint.config.js
export default configApp(...astGrep('@adonisplus/flow/rules'), {
  rules: { 'ast-grep/no-top-level-functions': 'off' },
})

AdonisJS apps keep their behaviour in classes. A class can receive its dependencies through the container with @inject(), and a test can swap them with app.container.swap(). A top-level function imports its dependencies directly. Functions also have no natural home, so they collect in utils and helpers files. This rule keeps one way of writing behaviour, so your agent never has to choose between a function and a class.

Reports functions declared at the top level of a file. Move the code into a method on a class. The flow-code-placement skill helps your agent pick the class.

It checks the TypeScript files of your backend. It skips inertia/, resources/, tests/, bin/, *.config.ts files and .d.ts files.

An exported function is a top-level function that the rest of your app depends on, so the same reasoning applies. The exception is a factory: a function named create… or make… that builds and returns a class instance, such as a helper that sets up a configured client. A factory gives callers a short way to get an instance, while the behaviour stays in the class it returns. Mixins in mixins/ are not checked, because a mixin is a function by design.

Reports exported functions, unless the name starts with create or make and the function returns a class instance. Turn the function into a factory, or move the code into a method on a class.

It checks the TypeScript files of your backend. It skips inertia/, resources/, tests/, bin/, mixins/, *.config.ts files and .d.ts files.

A controller maps an HTTP request to your app: it reads the input, calls your models and services, and returns a response. A private method on a controller holds a step outside that job, usually a query, a calculation or a rule of your domain. Inside the controller, that step can't be used by a command, a job or another controller, and a test can only reach it through an HTTP request. Put it on a model, a service or a pattern object, where any part of your app can use it and test it. A protected method leads to base controllers that actions inherit from, so the rule reports it too.

Reports private and protected methods on controllers. Write the steps inside the action, or move them to the place the flow-code-placement skill suggests.

It checks the files in controllers/.

This rule keeps types and interfaces in the types directory, so your runtime files only contain code that runs. Every type has one place to import from, and a file that needs only a type never imports a service or a controller to get it, which avoids circular imports. AdonisJS packages follow the same convention and keep their types in separate files. Validators and value objects are not checked, because their types come from their own code.

Reports types and interfaces declared outside the types directory. Move the declaration to types/ and import it with import type.

It checks the TypeScript files of your backend. It skips types/, validators/, values/, inertia/, resources/, tests/ and .d.ts files.

A variable that several tests change makes those tests depend on each other. To understand one test, you have to read every test that reads or changes the variable. Declaring the variable inside the test gives each test its own data.

Reports let and var declarations outside a test callback. Declare the variable inside the test, or use const if the value never changes.

It checks the files in tests/.

A test file defines tests and nothing else. When a test needs a helper, the helper comes from tests/helpers/. Test code and helper code stay in separate files, and every helper is in one place where you can find and reuse it.

Reports exports, reusable functions and classes, and named types in test files. Move reusable code to tests/helpers/ and named types to tests/helpers/types.ts. Values and functions defined inside a single test are fine.

It checks the files in tests/, except tests/helpers/ and tests/bootstrap.ts.

Test helpers contain code that runs. Types used by your tests go in tests/helpers/types.ts, which is the same split that types-live-in-types-directory applies to your app.

Reports types and interfaces declared in test helpers. Move them to tests/helpers/types.ts and import them with import type.

It checks the files in tests/helpers/, except tests/helpers/types.ts.

By default, Playwright matches a text locator against any element that contains the text. A locator for "Sign in" also matches "Sign in with a passkey", so a test can click the wrong button and still pass. Setting exact on every text locator makes each one say which match it means.

Reports Playwright text locators that don't set the exact option. Pass { exact: true }, or { exact: false } when you want a partial match. Without it, a "Sign in" locator also matches "Sign in with a passkey".

It checks the files in tests/.