Plans
This section explains, one by one, the plans that ship with NEO: what each one is meant to do, when it runs, what it needs to receive, and what it leaves behind. It's meant so that anyone on the team can understand what the pipeline is going to do before it does it, and can check afterwards that it did what it said.
In short
- What a plan is: an already-written QA workflow (which skills run, in what order, and when it stops) that the
NEOengine runs, with no AI assistant open and nobody in the conversation. - How it differs from a playbook: a playbook is followed by the AI assistant (for example, Claude) together with a person, with pauses for that person to decide; a plan is run by the engine end to end, usually triggered by CI.
- What this section is for: understanding the intent of each plan. The technical format of the YAML file is in Anatomy of a plan.
1. What is a plan?
A plan is a recipe that a machine runs instead of a person. Like a playbook, it chains several skills in a fixed order to handle a complete situation (a new feature, a hotfix, a bug). The difference is who runs it:
- A playbook is run by the AI assistant (Claude, Codex, Copilot) step by step, while a person goes along, answers questions, and approves at the pauses.
- A plan is run by the engine (the
neoprogram), on its own, from start to finish. Nobody answers questions along the way: everything it needs it gets at the start, and the "continue or stop" decisions are already written into the plan.
That's why plans are the piece that lets QA run on its own in a pipeline: an MR is opened with a label, someone pushes to a hotfix/* branch, and the matching plan starts without anyone having to ask the assistant.
So where does the AI come in?
Inside each step. Each skill still uses an AI model to do its job (reading a story, building a test plan, repairing a test). What the AI does not decide is the flow: which step comes next, when one is skipped, or when everything stops. That is decided by the engine's code, always the same way. That's why two runs of the same plan follow the same path.
2. Plan vs. playbook, side by side
| Playbook | Plan | |
|---|---|---|
| Who runs it? | The AI assistant (for example, Claude), talking with a person | The NEO engine (neo run), on its own |
| What is it, physically? | A document with instructions (.md) |
A configuration file (.yaml) |
| How does it start? | A person asks the assistant | A CI rule (Model 4) or a free-text request that the engine classifies (Model 2) |
| Does it have pauses for a person to decide? | Yes, the human checkpoints | No: the stopping conditions are already written into the plan |
| Can it improvise if something doesn't fit? | The assistant can adapt and ask you | No: if a piece of data is missing or something doesn't check out, the plan stops and records it |
| Orchestration model | Model 3 — Human-in-the-loop | Model 4 — Pure declarative, or Model 2 — Adaptive hybrid |
| Best for | Interactive work, cases that need human judgment | CI pipelines that have to react on their own to an event |
In short: if there's a person talking to the assistant, you use a playbook. If there's nobody (a pipeline, a script), what runs is a plan.
Many plans are the automated version of a playbook: they do the same work, but without pauses and with the decisions already made. Each page in this section explains how it resembles its playbook and how it differs. To understand the models in detail, see The 4 orchestration models and Orchestration models in the engine.
3. How do you read a plan's page?
Every page in this section has the same structure:
| Section | What it answers |
|---|---|
| What does this plan do? | Its intent: what problem it solves and what it leaves behind |
| When does it run? | Which event triggers it and with which orchestration model |
| Differences from the playbook | What changes compared with doing the same thing with the assistant |
| Guiding example | The TechStore case, the online store used throughout the manual: what the plan receives, what happens at each step, and how it ends |
| Common problems | What to do when the result isn't what you expected |
| Visual summary | The whole flow in a diagram |
4. Plan index
| Plan | When it runs | Related playbook |
|---|---|---|
| Feature - New End-to-End | An MR is opened with the feature label: a new feature has to be tested from scratch |
Feature - New End-to-End |
| QA Bug Coverage | A bug moves to QA: confirm it reproduces and leave a test that captures it | Bug Fix Cycle (first half) |
| QA Bug Fix Verification | The developer applied the fix for that bug: verify the tests now pass | Bug Fix Cycle (second half) |
| UI Selector Repair | A frontend PR changed selectors: repair the affected tests before deploying | Frontend UI Change PR |
Where the plans live
The plan files live in the plans/ folder of the engine repository, crowdar-engine-mvp. If you want to write your own plan or change one, start with Anatomy of a plan and Composition patterns.