# Flow with Matt Pocock's skills

This recipe is for you if you use [Matt Pocock's skills](https://github.com/mattpocock/skills) and want to use Flow in the same app.

## How they differ

Matt's skills are about how you work. You talk through a change with your agent, turn it into a spec and tickets, and build each ticket. They work with any framework.

Flow is about AdonisJS. It gives your agent accurate docs for the framework and its packages, and design skills that settle each choice the AdonisJS way. The team behind AdonisJS maintains both.

## The skills you will use

You will use Matt's skills for the steps of your work:

- `/grill-with-docs` asks you questions about a change until you and your agent agree on it.
- `/to-spec` turns the conversation into a spec.
- `/to-tickets` breaks the spec into tickets.
- `/implement` builds one ticket and then reviews it. `/implement-spec` builds all the tickets of a spec.

## Point Matt's skills at Flow

::agent-prompt
Paste this prompt into your coding agent, in the root of your project. It adds one ADR, and asks before it commits anything.

```
Add an ADR to this project that tells Matt Pocock's skills to use Flow.

1. Find the folder where this project keeps its ADRs. If the project has no ADRs yet, use docs/adr/ and create it.
   Give the new ADR the next free number in that folder, and the name adonisjs-work-follows-the-flow-harness. For example, when the last ADR is 0003, write 0004-adonisjs-work-follows-the-flow-harness.md.

2. Write this text in the ADR, unchanged:

# AdonisJS work follows the Flow harness

This app uses Flow. The harness docs in `.flow/docs/` (indexed in `CLAUDE.md` or `AGENTS.md`) are the primary source for the AdonisJS facts of this app, and the `flow-*` skills settle the AdonisJS design choices. We chose Flow over general defaults because generic advice, such as "extract duplicated code", "test at any module seam" or "add an adapter", conflicts with how AdonisJS settles these choices.

## Consequences

Each skill below must use the Flow part of its row before it works on the app.

| Flow part | Its job | Skills that must use it |
| --- | --- | --- |
| Harness docs in `.flow/docs/` | Facts and APIs of the framework and its packages | `research`, `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `prototype`, `diagnosing-bugs`, `tdd`, `implement`, `implement-spec`, `wayfinder`, `teach`, `wizard`, `improve-codebase-architecture` |
| `flow-schema-design` | Migrations and models | `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `implement`, `tdd` |
| `flow-cruddy-controllers` | Routes and controllers | `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `implement`, `tdd` |
| `flow-response-design` | Pages, page props and transformers | `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `prototype`, `implement`, `tdd` |
| `flow-validation-layers` | Validators and checks on incoming data | `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `implement`, `tdd` |
| `flow-access-control` | The scope of each read and write | `grill-me`, `grill-with-docs`, `to-spec`, `to-tickets`, `diagnosing-bugs`, `implement`, `tdd` |
| `flow-design-tests` | Which tests to write, through which surface | `tdd` (its seams are the surfaces of this skill), `to-spec` (Testing Decisions), `to-tickets`, `diagnosing-bugs` (the regression test), `implement` |
| `flow-code-placement` and `flow-pattern-object-design` | Where code goes, and when an abstraction is allowed | `codebase-design`, `improve-codebase-architecture`, `to-tickets` (prefactoring), `implement`, `tdd` |
| `flow-apply` | Feature packs, such as auth, passkeys and two-factor | `to-spec`, `to-tickets`, `implement` |

In a grilling session, a decision that a Flow skill settles is not a question for the user. State the answer of the Flow skill instead.

3. Show me the ADR. Then ask me: "Should I commit the ADR?"

In a monorepo:
- The AdonisJS app is the folder with adonisrc.ts. In a monorepo, this folder is below the repository root, for example apps/backend/. If more than one folder has adonisrc.ts, ask me which apps the ADR covers.
- Step 1: keep the ADR at the repository root, with the other ADRs and Matt's skills. Do not put it in the folder of the app.
- Step 2: change the first sentence to name the app, for example "The AdonisJS app in `apps/backend/` uses Flow." Write each Flow path from the repository root, for example `apps/backend/.flow/docs/` and `apps/backend/CLAUDE.md`. Add this sentence after the first paragraph: "The `flow-*` skills are in `apps/backend/.claude/skills/` or `apps/backend/.agents/skills/`."
```
::

Most of Matt's skills read the ADRs of your project when they design and build a change, for example `/grill-with-docs`, `/to-spec`, `/to-tickets` and `/implement`. The ADR tells them to read the Flow docs and use the Flow skills first. In `/grill-with-docs`, your agent then gives you the answer of a Flow skill and does not ask you the question.

## Reviewing your work

`/implement` ends with Matt's `code-review` skill. It checks that the implementation sticks to the spec.

The Flow review is separate. Use it to review a diff or a pull request after you build. Run `npx @adonisplus/flow review` on your branch, or let it review each pull request on GitHub. See [Local reviews](/docs/flow/reviews/local-reviews) and [GitHub setup](/docs/flow/reviews/setup).
