This guide sets up Flow in your AdonisJS app. You will:

  • Sign in to the AdonisJS Plus registry
  • Install Flow and set it up for your coding agents
  • Check that your agent sees the Flow skills

You can let your coding agent do every step with one prompt, or do them by hand. Both end in the same place.

  • An AdonisJS 7 app, on Node.js 24 or later.
  • A coding agent: Claude Code, Cursor, Codex CLI, GitHub Copilot or OpenCode.
  • npm, pnpm, Bun or Yarn. With Yarn, the app must use nodeLinker: node-modules. Plug'n'Play is not supported yet.

Paste this prompt into your coding agent, in the root of your project. It signs you in, installs Flow, and asks before it commits anything.

Set up AdonisJS Plus Flow in this project. If a step fails, work out what is wrong and fix it.

1. Find the package manager from the lockfile. If the project uses Yarn with Plug'n'Play, stop and tell me that Flow does not support Plug'n'Play yet.
   Check whether the project is a monorepo: the AdonisJS app, the folder with adonisrc.ts, is in a folder below the lockfile. If it is, follow "In a monorepo" below.

2. Point the @adonisplus scope at the Plus registry.
   - npm, pnpm or Bun: add `@adonisplus:registry=https://plus.adonisjs.com/registry/` to the project's .npmrc.
   - Yarn: add this to the project's .yarnrc.yml:
     npmScopes:
       adonisplus:
         npmRegistryServer: "https://plus.adonisjs.com/registry"

3. Sign me in to the registry, unless `npm whoami --registry=https://plus.adonisjs.com/registry/` already prints my email.
   - npm, pnpm or Bun: `npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web`
   - Yarn: `printf 'n\n' | yarn npm login --scope adonisplus --web-login`
   The command prints a link. Show it to me, and wait while I approve the sign-in in my browser. Never print or copy the token.

4. Install @adonisplus/flow as a dev dependency.

5. Ask me: "Would you like to configure Flow for coding agents other than <you>?" The others are claude, cursor, codex, copilot and opencode.

6. Run `npx @adonisplus/flow install --yes --agent <you>`, with one more `--agent` for each agent I picked. If it cannot detect the stack, decide it from the code (controllers that only return JSON: api; Edge views: hypermedia) and run it again with `--stack`. Ask me only when the code does not make it clear.

7. Tell me what Flow installed: the agents, the stack, and the number of docs and skills. Then ask me: "Flow has been installed. Should I add and commit these changes?" The changes are .npmrc or .yarnrc.yml, package.json, the lockfile, flow.lock, .flow/review.yml and the ESLint config.

8. Last, tell me to start a new session of my coding agent and type /flow- to see the Flow skills.

In a monorepo:
- If more than one folder has adonisrc.ts, ask me which app to set up.
- Step 2: add the registry line to the file at the workspace root, not in the folder of the app.
- Steps 4 and 6: run the commands in the folder of the app. In step 6, add `--workspace`.
- Step 7: the changes also include CLAUDE.md or AGENTS.md at the workspace root.
- Step 8: tell me to start the new session in the folder of the app.

If the install fails:
- A 404 from registry.npmjs.org means the scope line of step 2 is missing or wrong.
- A 401 from plus.adonisjs.com means you have no token. Sign me in again.
- Only when signing in keeps failing: open https://plus.adonisjs.com/account/tokens in the browser, create a token, and save it without printing it, with `npm config set //plus.adonisjs.com/registry/:_authToken <token>` (Yarn: `yarn config set --home npmScopes.adonisplus.npmAuthToken <token>`).
  1. Flow and the premium packages are published under the @adonisplus scope, on the AdonisJS Plus registry. This line sends that scope to the registry. It holds no token, so commit it.

    npm
    @adonisplus:registry=https://plus.adonisjs.com/registry/
    pnpm
    @adonisplus:registry=https://plus.adonisjs.com/registry/
    yarn
    npmScopes:
      adonisplus:
        npmRegistryServer: "https://plus.adonisjs.com/registry"
    bun
    @adonisplus:registry=https://plus.adonisjs.com/registry/

    The line goes in .npmrc at the root of your project. With Yarn, it goes in .yarnrc.yml. In a monorepo, that is the workspace root, not your app's folder.

  2. The command prints a link. Open it, and approve the sign-in on the page it opens. The token is saved in your user config (~/.npmrc, or ~/.yarnrc.yml with Yarn), never in the project.

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

    The sign-in creates a token named after your package manager and your system, for example "npm on macOS". It is listed in Tokens on your dashboard, where you can revoke it.

  3. Flow is a command line tool, so it is a dev dependency. Run the command in your app's folder, so that in a monorepo Flow goes into your app and not into the workspace root.

    npm
    Terminal
    npm i -D @adonisplus/flow
    pnpm
    Terminal
    pnpm add -D @adonisplus/flow
    yarn
    Terminal
    yarn add -D @adonisplus/flow
    bun
    Terminal
    bun add -d @adonisplus/flow
  4. Run the installer in your app's folder. It asks which coding agents you use, your stack, and the packages to install docs for. It detects each answer, so the defaults are usually right.

    Terminal
    npx @adonisplus/flow install

    Your answers are saved in flow.lock. The next run reads them, and asks only about what is new.

    In a monorepo, add --workspace the first time. It also writes a pointer to your app in the CLAUDE.md or AGENTS.md at the workspace root, so that an agent started there finds your app. Read Monorepos to learn more.

  5. Commit .npmrc (or .yarnrc.yml), package.json, the lockfile, flow.lock, .flow/review.yml and the change to your ESLint config. In a monorepo, also commit the CLAUDE.md or AGENTS.md at the workspace root.

  6. Start a new session of your coding agent in your app's folder and type /flow-. The Flow skills show up in the list. On your dashboard, the Install Flow card shows "Registry token created" and "Flow installed in a project".

The installer writes these files in your app's folder, also in a monorepo.

  • .flow/docsdocs for the packages your app uses
    • .flow/lensesthe lenses of the code review
      • .flow/review.ymlthe settings of the code review, commit it
      • .claude/skillsthe Flow skills, in the folder of each agent
        • CLAUDE.mdFlow's section, or AGENTS.md for the other agents
        • flow.lockyour answers, commit it

        Each run writes the docs, the lenses and the skills again, so do not edit them. In CLAUDE.md and AGENTS.md, only Flow's section is replaced, and the rest of the file stays yours. The installer adds the missing entries to .gitignore and .prettierignore, so the docs and the skills stay out of git. Once .flow/review.yml and your ESLint config exist, the installer leaves them as they are.

        To use your own docs, skills or lenses next to Flow's, read Customizing Flow.

        Once your project points at the registry, Persona and Permissions install like any AdonisJS package.

        Terminal
        node ace add @adonisplus/persona

        Read the docs of Persona and Permissions to set them up.

        The uninstaller removes the skills, the docs and Flow's section of CLAUDE.md and AGENTS.md. It asks which agents to remove Flow from.

        Terminal
        npx @adonisplus/flow uninstall

        CI and deployment

        A token for each place that installs your app without you.

        Pull request reviews

        Turn on the Flow review on your GitHub repositories.