This page is about the droost command: the brain and the workflow. The third part, the module that lets the agent ask the live site about itself, has its own pages.

The command does two things for an AI agent working on your Drupal site:

  1. It understands your site, so the agent works from your real code instead of guessing. That part is the Droost Brain.
  2. It sets the terms of how the agent builds: every change is planned, checked, tested and written down, to a standard you choose. That part is the Droost Workflow.

Droost Brain

How it understands your site

When you run droost code:index, droost reads your project's files and builds an index of them: every installed module and theme and its version, your custom modules and themes, their classes, functions, hooks, services and routes, and the documentation that comes with them. It keeps the index in a file in your project.

From then on, the agent asks droost questions and gets answers from that index. droost never boots Drupal and never calls drush, which means:

  • It is fast. An answer takes milliseconds, not the seconds a drush call takes.
  • It works when the site is broken. A half-finished change that crashes Drupal does not stop the agent from reading the code.
  • It describes the indexed files. Refresh the index after changes; use the Drupal module when you need the live database or runtime state.

What the agent can ask

Command What it gives the agent Why it helps
droost code:wiki your project's own notes, and a page for every installed module and theme: its version, what it needs, what it provides the agent knows what is installed before it adds or calls anything
droost code:tree your custom code: modules, files, classes, hooks, services, routes the agent builds next to your code, not on top of it
droost search:arch a text search over all the documentation it finds how a module is meant to be used
droost code:symbol, code:graph where something is defined, what calls it, what it depends on it can change one thing without breaking another
droost brief the whole project in one answer a quick start for a new session

See all Droost commands for the complete command reference.

It has to look before it plans

droost records every one of these calls itself. The plan step cannot finish until that record shows the agent read the wiki and the code tree, and the plan cites real files it found. An agent that only says it looked has not looked.

It gets smarter as you build

At the end of every change the agent writes down what it built, in your project's wiki (droost/wiki/). The next change starts from those notes, so the brain grows with the site.

Droost Workflow

Every change is one run, and every run takes the same four steps. Each step ends with gates: checks that must pass before the work moves on. If a gate fails, the agent gets the failure, fixes it, and the gate runs again.

text
 plan ──▶ code ──▶ test ──▶ complete ──▶ a report

Plan

The agent looks at the brain, then writes a spec: what it will build and how you will know it works. The "how you will know" part is a list of requirements in EARS form (Easy Approach to Requirements Syntax): short sentences with a fixed shape, so each one can be tested.

text
WHEN an editor publishes an event,
THE events page SHALL list it, soonest first.

Why it helps: you can read the plan before any code exists, and every requirement becomes something a test has to prove.

Code

The agent builds. Then droost checks the change with the tools Drupal core itself is developed with:

  • phpcs checks the Drupal coding standards;
  • phpstan looks for mistakes in the PHP;
  • your house rules check the way your team builds, if you wrote any.

From the medium level up, a second agent, the seeker, also reviews the change for what tools cannot see: dead code, weak tests, drift from the spec.

Why it helps: every change meets the same bar, whoever (or whatever) wrote it.

Test

The agent writes tests and droost runs them:

  • PHPUnit for the PHP;
  • Playwright for the pages, in a real browser, against your running site;
  • parity, if you are rebuilding a design: the pages are compared with it.

Each requirement from the spec is matched to the test that proves it. One no test can prove is marked "manual", never "passed".

Why it helps: "it works" is something you can check, not something the agent says.

Complete

The agent writes down what it built, and droost checks those notes still match the code. At the stricter levels every gate runs once more. Then you get the report.

Why it helps: the next person, or the next agent, knows what was done.

The report

For every gate the report uses one of these words:

Word Means
passed it ran, checked something, and found nothing wrong
labelled it ran but had nothing to check, so it proves nothing
failed it found a problem
reported it found a problem, and your settings say to note it and move on
off it was switched off, and the report says by what
waived you let it through, with a reason
could not run the tool was missing or crashed; never counted as a pass

A check that could not have failed is never written as "passed".

The guard

In Claude Code, droost hooks into every edit, command and tool call the agent makes. This part is the guard. It stops the agent from:

  • editing files in the wrong step (no code during planning);
  • changing the rules while a run is checking against them;
  • running the commands that are yours: changing the level, waiving a gate, letting a run finish on its own.

When the agent needs one of those, it asks you, and gives you the exact command to run in your own terminal.

Your commands, and edits to the rules, are refused at every setting. Edits in the wrong step are refused with enforcement: hard; the file init writes says soft, which warns once instead (Settings).

The guard enforces the configured policy in Claude Code. With soft enforcement it warns about phase violations; hard enforcement blocks them.

Other agents (Codex, Gemini and others) follow the same workflow from the instructions droost writes into AGENTS.md, and the gates still run. Only Claude Code has the guard today.

You set the terms

All of it is set in one file in your repository, droost/droost.yml:

  • the level, from low to max: how much each run must prove;
  • who finishes a run: you (human-led) or the agent (autonomous);
  • which gates run, and how strict each one is.

It is a file, not a setting in the site, so a change to it shows up in code review like any other change. Settings has the details.

Make it yours

The workflow is built to be extended. Your own pieces are files in the droost/ folder:

  • gates: your own checks at a step, such as a security scan;
  • house rules: how your team builds, checked on every change;
  • hooks: told when a run starts, moves on or finishes;
  • walls: asked before the agent uses a tool, and able to say no.

Make it yours shows how.