Changelog

Flow 1.0Pull request reviewsPlus
Permalink

Flow 1.0 and the new AdonisJS Plus

Flow reviews your pull requests, installs from one command, and drops the spec-driven workflow. Plus has a new account area, registry sign-in and price.

Plus leaves early access today, and Flow 1.0 comes with it. Over the last few months, early access members told us what made Flow useful: the knowledge base, the skills and the lint rules. Flow 1.0 keeps those, drops the spec-driven workflow and the dashboard, and adds reviews of your pull requests for problems specific to AdonisJS. Plus moves to a new app with a new account area to go with it. Thank you to each member who stayed with us through the changes.

Your tokens and .npmrc keep working, and your price stays the same while your subscription renews. Upgrading takes a few minutes. The steps are at the end of this post.

Pull request reviews

Flow reviews each pull request for problems specific to AdonisJS, with nine lenses from the team behind the framework. The review runs in your GitHub Actions on your own Claude Code or Codex, and a critical or major finding fails the check. Each push is reviewed again.

Flow reviews do not replace CodeRabbit or other general reviewers. They look only for AdonisJS problems, so you can run both. Plus sells no credits. The review uses your own subscription or API key.

The nine lenses look for:

  • review-access-control: an action that reads or changes another user's record, or acts on a record without an authorization check.
  • review-response-exposure: a private value sent to the client, an error that tells too much, or a private page that a cache or the browser history keeps.
  • review-response-design: a response that breaks the rules of the flow-response-design skill.
  • review-cruddy-controllers: a controller or route that breaks the rules of the flow-cruddy-controllers skill.
  • review-migration-safety: a migration that can lose data, fail on a table with rows, or lock a large table.
  • review-input-validation: input from a request, a webhook or a job that reaches the code without a validator.
  • review-query-cost: an N+1 query, a read of every row of a growing table, or a connection held while the code waits.
  • review-code-placement: server code that breaks the rules of the flow-code-placement skill.
  • review-tests: a changed behaviour with no test that proves it.

To turn on reviews, install the GitHub App from your account. See Code reviews.

Local reviews

Review your branch on your computer before you open a pull request. The command starts a session of your coding agent, with the same lenses as a review on GitHub. It works with Claude Code, Codex, Cursor and OpenCode, and needs no GitHub App.

npx @adonisplus/flow review

See Local reviews.

Apply a feature pack

Apply a feature pack with one command. It starts your coding agent with the flow-apply skill and the pack you name.

npx @adonisplus/flow apply --pack=passkeys

See Feature packs.

One install command

Flow is a command of its own now, npx @adonisplus/flow install, and works without the Ace commands. It writes a flow.lock, so each computer installs the same agents and docs. See Installation and setup.

Workflow skills

Flow no longer ships workflow skills. Use the workflow skills you like, for example Matt Pocock's skills or pstack, next to the Flow skills. A guide for using them with Flow is coming.

New skills

Six new skills give your agent the decisions of an AdonisJS app. Your agent finds and uses them on its own. You never invoke them.

  • flow-access-control scopes each read and write to its user, tenant or organisation, and checks access to each record.
  • flow-code-placement decides where a helper, a service or shared code goes.
  • flow-pattern-object-design turns a value and its loose functions into one class.
  • flow-response-design decides the props of a page, the transformer that makes them, and the relations to preload.
  • flow-schema-design settles soft deletes, money, enums, polymorphic relations and changes to tables that have rows.
  • flow-validation-layers decides whether a check goes in the validator, a guard or a database constraint.

See Skills.

New lint rules

Four new lint rules keep functions, private controller methods and types in their place.

  • no-top-level-functions reports functions declared at the top level of a file. Behaviour lives in classes.
  • exported-functions-are-factories reports exported functions, unless they are create… or make… factories that return a class instance.
  • no-private-controller-methods reports private and protected methods on controllers.
  • types-live-in-types-directory reports types and interfaces declared outside types/.

See Lint rules.

The new Plus app

plus.adonisjs.com has a new website and a new account area.

  • Onboarding tracks your setup, step by step.
  • GitHub App turns on pull request reviews.
  • Feedback takes your feature requests. Accepted requests go into the build queue.
  • Invites send the GitHub invite to the account you sign in with.
  • Billing opens your Polar portal.

Registry sign-in

Sign in to the registry from your browser, with no token to create. npm, pnpm and Bun use:

npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web

Yarn uses:

yarn npm login --scope adonisplus --web-login

CI and deployments still need a token. See CI and deployment.

Docs

New and updated pages: Code reviews, Coding agents, Customizing, Updating Flow, Monorepos and Troubleshooting.

Upgrade with your agent

Paste this prompt into your coding agent, in the root of your project. It upgrades Flow, and asks before it deletes or commits anything.

Upgrade AdonisJS Plus Flow in this project from 0.5 to 1.0. If a step fails, work out what is wrong and fix it.

1. Find the package manager from the lockfile, and the AdonisJS app, the folder with adonisrc.ts.
2. In adonisrc.ts, remove `() => import('@adonisplus/flow/commands')` from `commands` and `() => import('@adonisplus/flow/flow_dashboard_provider')` from `providers`.
3. Upgrade @adonisplus/flow to the latest version, as a dev dependency of the app.
4. In the folder of the app, run `npx @adonisplus/flow install --yes --agent <you>`. In a monorepo, add `--workspace`. It removes the Flow 0.5 skills and agent files, and updates the Flow block of CLAUDE.md or AGENTS.md.
5. If the project is a monorepo and Flow 0.5 is installed at the workspace root, remove its files there: .flow/, the flow-* folders of .claude/skills, .agents/skills, .cursor/skills and .opencode/skills, and the Flow block of CLAUDE.md and AGENTS.md.
6. Ask me before you delete .flow/changes, .flow/states, .flow/boards, .flow/archive and .junie/. Flow 1.0 does not use them.
7. Run the linter, and tell me about errors from the new Flow lint rules. Do not fix them unless I ask.
8. Tell me what changed, then ask me: "Flow has been upgraded. Should I add and commit these changes?" The changes include flow.lock and .flow/review.yml.

Upgrade by hand

  1. Remove the old entries from adonisrc.ts

    Section titled "Remove the old entries from adonisrc.ts"

    Flow 1.0 has no Ace commands and no dashboard. Remove these two lines, or node ace fails.

    adonisrc.ts
    commands: [
      () => import('@adonisplus/flow/commands'), 
    ],
    providers: [
      () => import('@adonisplus/flow/flow_dashboard_provider'), 
    ],
  2. Upgrade @adonisplus/flow, then run the installer in the folder of your app. It replaces the files of Flow 0.5.

    npm i -D @adonisplus/flow@latest
    npx @adonisplus/flow install
  3. Flow 1.0 does not use .flow/changes, .flow/states, .flow/boards, .flow/archive or .junie/. Delete them. In a monorepo, also remove the Flow 0.5 files at the workspace root, because Flow now lives in the folder of your app. See Monorepos.

  4. Commit flow.lock and .flow/review.yml, with the other changes of the installer.

Breaking changes

The spec-driven workflow skills (brief, blueprint, assert, build, sync, archive) and the dashboard at /__dashboard are removed. Junie and the generic stack are no longer supported. In a monorepo, Flow installs in the folder of your app, not at the root.

Feature packFlow 0.5.0Persona 0.4.0
Permalink

Passkeys feature pack, Flow updates and validation rules

A feature pack for passkeys, a design tests skill and lint rules in Flow, and validation rules for passwords and emails in Persona.

Passkeys feature pack

Passkeys are now available as a Feature pack. Your users can sign in with their fingerprint, face, or screen lock instead of a password.

Like every pack, it works with all the officially supported stacks: React, Vue, Hypermedia, and API. Flow applies it for you with /flow.apply passkeys.

Video: the passkeys demo in the new starter kit

Design tests skill

Flow now ships a design tests skill. It helps your agent decide what is worth testing and what each test should check, so your suite stays lean and catches the bugs that matter.

Ask your agent to /flow-design-tests the tests of a feature to review them, or to plan the tests of a new feature.

Lint rules for your test suite

Flow also ships a set of ESLint rules that keep your test suite consistent, whether a test was written by you or by your agent. They are opt-in. Install the ESLint integration, then pass the Flow rules to your config.

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

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

The first three rules keep spec files to tests, helper modules to runtime code, and mutable state inside the test that uses it. See Lint rules.

Optional workflow skills

The spec-driven workflow is now optional. You can install Flow for its harness docs and skills alone.

Validation rules for passwords and emails

Persona ships three new validation rules. passwordPolicy() enforces the length, strength and character rules you choose. uncompromised() rejects a password that appeared in a known data leak. nonDisposable() rejects an email address from a throwaway provider.

The feature packs use the new rules, and your agent can build a password strength meter with them. To get them, upgrade to @adonisplus/persona@0.4.0 and run node ace configure @adonisplus/persona. See Validation rules.

Upgrade

To pick up everything, update @adonisplus/flow and re-run node ace flow:install.

Feature packFlow
Permalink

Feature packs, Inertia 5 and the whole framework in Flow

Kit components become feature packs that Flow applies for you. Flow also supports Inertia 5, covers all of AdonisJS, and works in monorepos.

Feature packs

Kit components are now feature packs, from auth and social login to two-factor and the rest. The bigger change is that Flow applies a pack into your app for you.

Each pack has an apply command for your agent, for example /flow.apply auth in Claude Code. Flow checks the dependencies, adds the pack to your existing code, styles the screens with your design system, runs the tests, and shows you the result with screenshots.

Packs cover problems that are already solved, where you want the same shape in every app, above all in the parts that touch security. So each pack stays pinned to one version that we maintain. Flow builds what makes your app yours, and packs handle the groundwork every app needs. See Feature packs.

One page for each pack

The docs are rebuilt around packs. A pack is one page now, with every step in order. Before, auth meant a chain of pages, from setup to signup, login and email verification.

The Kit CLI is deprecated with the name. The registry still serves it, so existing installs keep working, but it gets no new work. Flow applies a pack, or you follow its steps yourself.

Inertia 5

Version 5 of @adonisjs/inertia supports Inertia v3, with end-to-end type safety from your routes, validators and transformers into your React or Vue components. Flow detects Inertia 5 and installs dedicated React and Vue docs for it.

The whole framework in the harness

The harness now covers all of AdonisJS and its ecosystem, adding events, Ace commands, cryptography, cache, rate limiting, atomic locks, Redis, Transmit and its client, and scheduled tasks with Adonis Scheduler. Your agent writes more correct code, and reaches for the recommended packages instead of improvising.

Monorepos

Flow works inside a monorepo. See Monorepos.

Flow
Permalink

The Flow dashboard

A read-only view of everything Flow tracks in your project.

The Flow dashboard

Flow now has a dashboard. Start your dev server and open /__dashboard. The dashboard only reads your .flow folder. It never edits a brief, runs a skill or moves your work forward.

It has four views.

Pulse shows what needs you and what just shipped, with the command that moves each change forward.

Board lays out your changes in columns by stage, from briefed and planned to built and synced.

Timeline lists everything that happened across your changes, newest first.

Capabilities gives each area of your app, such as projects or billing, a page with what it does today and each change that shaped it.

Flow
Permalink

Flow is live

The AI harness for AdonisJS, with a knowledge base, a spec-driven workflow and skills.

Flow

Flow is the AI harness for AdonisJS. It grounds your coding agent in how the framework works, holds it to a plan before it writes code, and applies the conventions of your team each time it changes code.

Knowledge base

Before your agent touches your code, it reads the matching doc from Flow's knowledge base. The docs match the major versions of the AdonisJS packages you have installed. Each one settles a single decision, with the recipe, the edge cases and the patterns to avoid. See Knowledge base.

Spec-driven workflow

Before any file changes, the agent writes a plan against your project. You approve it, and only then does the agent write code. Six commands carry the workflow, from brief and blueprint to assert, build, sync and archive.

Skills

Flow ships skills for the calls every AdonisJS app makes, such as the seven conventional controller methods and the shape of a service. You can add skills for the conventions of your team, and the agent applies them each time it writes code. See Skills.

Flow supports Claude Code, Cursor, Codex CLI and GitHub Copilot.

Kit
Permalink

Social auth

Sign up and log in with a social provider, with no automatic account linking.

Social auth component

Users can sign up and log in with a social provider, and link or unlink more providers from their profile page. The OAuth round trip handles a returning user, a new user with a verified email, a new user with an unverified email, who goes through email verification, and an email that already belongs to an account.

The whole flow fits in about 110 lines of controller code, and the code is yours to read and change. See the social auth docs.

Security decisions

No automatic linking. When a provider returns an email that already has an account, the user sees the conflict. The accounts are never merged silently, which blocks a common account takeover.

The OAuth redirect is a POST. A GET can be triggered by a prefetched link or a browser preloader, with no action from the user.

A "Last used" hint. The login page marks the method the user signed in with last time. The cookie holds no personal data and no credentials.

A fix in the framework

Building this component surfaced an open redirect in redirect.back(). It is fixed, and the framework has new redirect APIs for the intended URL after login, and for the previous URL across an OAuth round trip.

Existing installations

The login and signup controllers now set the last login method cookie. If you use two-factor, follow the updated manual installation of the login challenge. Social logins go through the challenge now, and the session key of a pending challenge has a new name.

Kit
Permalink

Kit components for auth and two-factor

The first Kit components, for Edge and React, with browser tests and full docs.

Auth and two-factor components

The first Kit components are ready. Auth covers registration, login, email verification and password reset. Two-factor covers authenticator enrollment with a QR code, backup codes and recovery.

Each component comes for Edge and React, with browser tests and full docs, and a CLI applies it to your AdonisJS app.

Update AdonisJS first

The components use new framework APIs. Update your AdonisJS dependencies before you apply one.

Kit components are now feature packs, and Flow applies them for you.

PersonaPermissions
Permalink

Persona and Permissions are here

The first two premium packages of Plus. Account management for your User model, and type-safe roles and permissions.

Persona

@adonisplus/persona adds account management to your User model. It handles email changes, password resets, verification tokens and two-factor setup. Every app needs this plumbing, and now you write it once. See the Persona docs.

Permissions

@adonisplus/permissions is a type-safe layer for roles and permissions. You scope a permission to a user, a team, a project, or anything else your app has, and check it with Bouncer. See the Permissions docs.