Installation

This guide covers installing Flow into an AdonisJS application. You will learn how to:

• Add the Flow package to your project
• Run the harness installer and answer its prompts
• Understand what the installer writes to disk
• Update or remove the harness

Overview

Flow ships as an AdonisJS package. Installing it takes two steps: add the package, then run the harness installer. The package registers an ace command, flow:install, and that command does the real work of copying harness docs and skills into your project and registering them with your coding agent.

The installer is interactive. It asks which agent you use, how your application renders responses, and which packages and skills to set up, then writes only what those answers call for.

Prerequisites

Before installing Flow, make sure that:

• Your project is an AdonisJS v7 application running on Node.js 24 or later.
• At least one supported AdonisJS package is listed in your package.json. The installer scans for these to decide which harness docs apply, and stops if it finds none.
• You have a coding agent set up in the project. Flow supports Claude Code, Cursor, OpenAI Codex CLI, GitHub Copilot, and OpenCode.

Adding the package

@adonisplus/flow is published to the AdonisJS Plus registry. If you have not configured the registry for this project yet, follow the packages installation guide first.

Add the package with node ace add:

node ace add @adonisplus/flow

The add command installs the package and runs Flow's configure hook, which registers the flow:install and flow:uninstall commands in your adonisrc.ts. No harness files are written yet. That happens in the next step.

Running the installer

With the package configured, run the harness installer:

node ace flow:install

The installer asks four questions. Each answer narrows what gets written to your project.

Coding agents

Select one or more agents to install for. Flow pre-selects any agent it detects in the project, such as a .claude directory or an AGENTS.md file, so the default is usually correct. You can install for several agents in a single run, and each one gets its skills written to its own location.

Rendering stack

Choose how your application renders responses: Inertia with React, Inertia with Vue, a JSON API, hypermedia with Edge templates, or generic if no specific rendering layer applies. Flow auto-detects the most likely option from your dependencies.

The stack matters because several harness docs and skills ship in per-stack variants. A controller example for a JSON API differs from one that returns an Inertia page, and the installer copies only the variant that fits your answer.

Packages

Select which AdonisJS packages to install harness docs for. The list is limited to supported packages that the installer found in your package.json, because a doc for a package you do not use is just noise in the agent's context.

Skills

Select which skills to install: the spec-driven workflow skills and the engineering skills. Installing every skill is a reasonable default.

Non-interactive install

Every prompt has a matching flag, so you can script the install or run it in CI. Passing a flag skips the prompt it covers.

node ace flow:install --agent=claude --stack=api --package="*" --skill="*"

The value * means "all" for the --package and --skill flags. Passing --skill="" installs no skills.

What the installer writes

When the installer finishes, your project has the following additions.

The harness docs directory

The harness docs are copied into .flow/docs/, one Markdown file per topic. This directory is the knowledge base your agent reads from. See the Knowledge base guide for what it contains.

Skills

The selected skills are written into your agent's skills directory. The exact location depends on the agent, so the per-agent guides cover it: see Claude Code, Cursor, OpenAI Codex CLI, GitHub Copilot, or OpenCode.

A managed block in your agent's context file

Flow upserts a managed block into your agent's primary context file, such as CLAUDE.md or AGENTS.md. The block records where the harness docs live and what stack the project uses.

<!-- FLOW-DOCS-INDEX-START -->
[AdonisJS Harness Docs Index]|root: ./.flow/docs|STOP. What you remember about
AdonisJS may be wrong for this project. Read the relevant harness doc first and
treat it as the primary working reference for framework and app tasks.|topics:{
routing.md: HTTP routing|controllers.md: Controllers|...}
<!-- FLOW-DOCS-INDEX-END -->
<!-- FLOW-PROJECT-FACTS-START -->
[Project Facts]|stack: api|packageManager: npm|appRoot: ./|node: >=24.0.0
<!-- FLOW-PROJECT-FACTS-END -->

The docs index tells the agent where the harness docs live and instructs it to read the relevant doc before relying on memory. The topics list lets the agent map a task ("add a validator") to the doc that covers it. The project facts record the stack and toolchain so the agent does not have to re-derive them.

The block is wrapped in comment markers. When you re-run the installer, Flow replaces the content between those markers and leaves the rest of the file untouched.

Updated ignore files

Flow appends entries to .gitignore and .prettierignore for the .flow/docs/ directory and the installed skill directories. The harness is a derived artifact, much like node_modules: you regenerate it by re-running the installer. Keeping it out of version control means each developer installs the harness for the agent they personally use, and a Flow upgrade does not produce a large, noisy diff.

Updating the harness

To pull in a newer version of Flow, update the package and re-run the installer:

node ace flow:install

The managed block in your context file is replaced in place, the harness docs are rewritten, and the skills are reinstalled. Your answers are remembered as the prompt defaults, so a re-run is fast.

Removing Flow

To remove the harness, run the uninstaller:

node ace flow:uninstall

It asks which agents to remove from, then deletes the installed skills, strips the managed section from the context file, and removes the .flow/docs/ directory. It does not touch any plans the workflow skills wrote to .flow/changes/, so your in-progress and archived work is preserved.

Next steps

• Open the guide for your agent: Claude Code, Cursor, OpenAI Codex CLI, GitHub Copilot, or OpenCode.
• Read Spec-driven development to start using the workflow.