# Droost Workflow > How the droost command works and why it helps: the brain that understands your code, the workflow that builds to your terms, the guard, and the ways to extend it. 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](https://droost.org/docs/module.md). 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](https://droost.org/docs/commands.md) 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](https://droost.org/docs/settings.md)). 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](https://droost.org/docs/settings.md) 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](https://droost.org/docs/hooking-in.md) shows how.