# Droost

> Droost is an open-source framework for building and managing Drupal with AI. Its tools connect an agent to a running site, its code index explains the project, and its spec-driven workflow takes changes through plan → code → test → complete. Use the pieces you need in your existing workflow. GPL-2.0-or-later.

This installation and operation snapshot covers Droost module 2.x, Workflow
and Engine 1.x, CMS and Theme 1.x, and UI Kit 2.x. Reviewed 27 October 2026.
Check [requirements](https://droost.org/docs/requirements.md) and [releases](https://droost.org/docs/releases.md) against
the project's Composer lock before installing.

The HTML articles, Markdown exports, full export and search index use the same
published documentation. No JavaScript or account is needed to read them.

- [Agent installation playbook](https://droost.org/agents.md): detailed setup, the DDEV wrapper, prerequisites, readiness checks and operator choices.
- [Complete documentation](https://droost.org/llms-full.txt): this snapshot, every article, the project directory and installation playbook in one text file.
- [Searchable documentation index](https://droost.org/docs-search.json): a JSON array with each article's title, description, section (`kind`), aliases, full searchable `text`, HTML `url`, absolute `markdown_url` and upstream `source_url`. Download and search locally; it is not a query API. Relative HTML URLs resolve against this site.
- [Project directory](https://droost.org/projects): official repositories and package listings.
- [Demo sites and source](https://droost.org/demos): working examples and public development records.

## The pieces and how they fit

- **Droost / Droost Framework** is the umbrella for the ecosystem. The [Drupal.org framework project](https://www.drupal.org/project/droost_framework) is its directory, not another runtime package to install.
- **Droost module (`drupal/droost`)** exposes the running site's content and structure through Drupal's Tool API. Coding agents use `drush droost:tool`; MCP clients use optional `droost_mcp`, MCP Server and its Tool API bridge. `droost_canvas` adds Canvas tools, `droost_build` adds site-building tools, and `droost_dev` adds developer inspection. It works without Workflow. [Module guide](https://droost.org/docs/module.md).
- **Droost Workflow (`droost/workflow`)** supplies the `droost` CLI in a separate Composer project at `tools/droost/`. Its Brain indexes code, symbols and documentation without booting Drupal; its Workflow checks each phase of a spec-driven change and records the evidence. Commands, tickets, design intake, custom gates, house rules, hooks and walls all belong here. It works without the Drupal module. [Workflow guide](https://droost.org/docs/how-it-works.md).
- **Droost Engine (`droost/engine`)** is the framework-independent library beneath Workflow: the harness, wiki and code-search foundations. Workflow installs it as a dependency; a normal site does not need a separate Engine installation. [Engine source](https://github.com/Ignibyte/droost-engine).
- **Droost CMS (`drupal/droost_cms`)** is an optional Drupal recipe. We recommend it on a fresh Drupal CMS project: it applies the CMS starter, enables Droost content tools and Canvas integration, selects Droost Theme, and adds a component display example using UI Patterns. Workflow is installed separately. Existing sites do not need the recipe and can integrate the packages individually. [CMS guide](https://droost.org/docs/droost-cms.md).
- **Droost Theme (`drupal/droost_theme`)** is the stock Tailwind CSS v4 / daisyUI theme an AI can build on, with design tokens and reusable Single Directory Components (SDCs). It is optional. Customize through a subtheme and compile any new Tailwind utilities for production. [Theme guide](https://droost.org/docs/droost-theme.md).
- **Droost UI Kit (`drupal/droost_ui_kit`)**, formerly **Droost UI Patterns (`droost_ui_patterns`)**, adds development tools for mapping entity fields into SDC props and slots on Manage Display. It uses the separate **UI Patterns 2** project for runtime rendering. Canvas handles freeform pages; UI Patterns handles structured entity displays. The old Droost UI Patterns project is retired; UI Patterns itself is not. [UI Kit guide](https://droost.org/docs/droost-ui-kit.md).

Together: Workflow understands the files and coordinates the work; the module
inspects or changes the running Drupal site; Theme, Canvas and UI Patterns
render the result. CMS supplies an optional starting configuration, and UI Kit
helps compose entity displays.

## Installation snapshot

Work in the project root. Use DDEV when `.ddev/` exists and `ddev` is
available; otherwise use local PHP and Composer, with `vendor/bin/drush` if
installed. Workflow needs PHP 8.3+ and `pdo_sqlite` where it runs. Droost
module 2.x needs Drupal 11.3+ and Tool API 1.0 beta12+.

These commands use local Composer and the project's Drush. On DDEV, use
`ddev composer`, `ddev drush`, and `ddev droost` in place of
`tools/droost/vendor/bin/droost`. Install the
[DDEV wrapper](https://droost.org/docs/commands.md#on-ddev-ddev-droost) from the playbook first;
`ExecRaw: true` preserves quoted arguments.
Run recipe shell scripts inside the container with `ddev exec` on DDEV.

### 1. Choose the site layer

For an existing site, add the module if you want live-site tools:

```bash
composer require 'drupal/tool:^1.0@beta' 'drupal/droost:^2.0'
vendor/bin/drush en droost -y
```

Only on a development copy, enable additional tools if needed:

```bash
vendor/bin/drush en droost_build droost_dev -y
```

For a **fresh Drupal CMS project**, we recommend the optional CMS recipe.
Create it with `composer create-project drupal/cms my-site`, then work
inside `my-site` using its selected runner:

```bash
composer require 'drupal/tool:^1.0@beta' 'drupal/droost_cms:^1.0'
vendor/bin/drush site:install minimal -y
vendor/bin/drush recipe ../recipes/droost_cms
recipes/droost_cms/scripts/assert-recipe-applied.sh .
```

Alternatively select Droost CMS in the Drupal CMS installer. Apply the recipe
once, before the CMS starter has already been applied. Do not run fresh-site
installation commands on an existing site. See the [CMS guide](https://droost.org/docs/droost-cms.md)
for its agent layer. Theme and UI Kit have separate installation guides below.

### 2. Install Workflow separately

Create its tools project if it does not already exist. Set `platform.php` to
the PHP version the site actually runs; `8.3.0` below is an example.

```bash
mkdir -p tools/droost
composer init -d tools/droost -n --name=local/droost-tools
composer config -d tools/droost platform.php 8.3.0
composer require -d tools/droost 'droost/workflow:^1.0'
tools/droost/vendor/bin/droost init
tools/droost/vendor/bin/droost code:index
tools/droost/vendor/bin/droost doctor
tools/droost/vendor/bin/droost brief
```

Ignore `tools/droost/vendor/` in Git. Install any chosen Droost modules before
`init` so it discovers their skills. Review the generated `AGENTS.md`,
`CLAUDE.md`, `.claude/` skills/hooks and `droost/droost.yml`; restart the agent
session to load them. The Brain index describes files, not current database
content. Refresh it with `code:index` after significant changes.

### 3. Check readiness

- Resolve issues from `doctor`; use `brief`, `code:wiki` and `code:tree` to confirm the agent sees the intended project.
- With the module installed, list tools using `vendor/bin/drush droost:tool`, then inspect a tool's input schema with `vendor/bin/drush droost:tool droost_entities help`. [Inspection examples](https://droost.org/docs/inspect-site.md).
- Configure the tools required by the chosen gates: PHPCS with Drupal standards, PHPStan, PHPUnit and, for browser checks, Playwright with a browser and a reachable site. A missing tool is not a passing check. [Setup details](https://droost.org/docs/setup-by-hand.md).
- Have the operator choose effort and completion policy. Explicit settings in `droost/droost.yml` override preset defaults. Existing sites may need a reviewed baseline for pre-existing findings. [Settings](https://droost.org/docs/settings.md), [existing sites](https://droost.org/docs/existing-site.md).
- On a CMS install, add its agent layer using `recipes/droost_cms/scripts/install-layer.sh .`, merge the supplied example settings and rerun `init`, as described in the CMS guide. Applying the recipe alone does not complete this step.

## How a change operates

1. **Plan:** open a run with `droost workflow:run` (the full binary path above, or `ddev droost workflow:run`). Read `code:wiki` and `code:tree`, inspect relevant code and write a spec with testable requirements. The plan must cite real files; claiming to have read them is not evidence.
2. **Code:** implement the declared change. Coding standards, static analysis, house rules and configured review gates check it.
3. **Test:** run the applicable PHP/browser checks and design parity checks. Link requirements to evidence; record anything needing manual verification honestly.
4. **Complete:** update the project wiki, run completion checks and read `workflow:report`. `workflow:status` shows the current phase. The default lead is autonomous; human-led settings hold completion for the operator.

`workflow:run` also checks and advances the current phase; follow its result
rather than skipping steps. In Claude Code the optional plugin provides
`/droost:workflow:start`, `/droost:workflow:continue` and
`/droost:workflow:status`. Other agents follow the generated instructions
and CLI. [First run](https://droost.org/docs/first-run.md), [all commands](https://droost.org/docs/commands.md).

**Make Workflow yours:** add custom gates, house rules and lifecycle hooks
in `droost/`. Walls can refuse agent tool calls through the Claude Code guard.
Only Claude Code has this guard; other agents still run workflow gates.
Soft enforcement warns about phase violations; hard enforcement blocks them.
[Extension guide](https://droost.org/docs/hooking-in.md), [hooks and walls](https://droost.org/docs/hooks-and-walls.md).

## Operating boundaries

- Keep `droost_build` and `droost_dev` off production sites. Content tools and authenticated MCP can run in production with deliberate permissions and configuration. Enabling the base module alone does not expose MCP. [MCP setup](https://droost.org/docs/module-mcp.md).
- Module write gates and Workflow quality gates are different controls. Ordinary module CLI write categories default on unless explicitly disabled; PHP evaluation and raw SQL writes default off. Web writes require explicit gates in `settings.droost.php` and Drupal account permissions. Build/developer tools refuse web calls. [Module gates](https://droost.org/docs/module-gates.md), [Workflow gates](https://droost.org/docs/gates.md).
- Operator actions include arming module write gates and Workflow effort changes, bypasses, waivers, writing baselines, switching the lead to autonomous, moving tickets, and answering or abandoning design intake. Follow the documented operator flow; present the exact command when a decision is needed. [Command reference](https://droost.org/docs/commands.md).
- Failed or unavailable checks are not passes. Read the gate outcomes and evidence in the report. Run records and wiki notes explain what happened; review them for credentials, personal data and other private material before publishing.
- Droost 1.x and 2.0 alphas need the documented uninstall/reinstall migration. [Upgrade guide](https://droost.org/docs/upgrading.md).

## Examples and source

- [Hockey demo](https://hockey.droost.org) and [public repository](https://github.com/Ignibyte/droost_hockey).
- [Wild Bill demo](https://wildbill.droost.org) and [public repository](https://github.com/Ignibyte/droost_wildbill).
- The demo repositories include reviewed source and historical observability records showing how the work progressed. Databases, credentials and uploads are excluded. The public demos have email, form submissions and public login disabled.
- [Build from a design](https://droost.org/docs/site-from-a-design.md): design intake, approval, implementation and parity checks, including importing an existing design.
- [Workflow source](https://github.com/Ignibyte/droost-workflow), [Engine source](https://github.com/Ignibyte/droost-engine), and the [complete project directory](https://droost.org/projects).

## Documentation table of contents

Every article follows, grouped in reading order. Links fetch Markdown directly,
including the documentation home at `/docs/index.md`. Links between articles
in the exports also stay in Markdown. Use the full export for all context,
or search the JSON index and retrieve only the relevant pages.

## Start here

- [Droost documentation](https://droost.org/docs/index.md): Understand the projects, choose the tools you need, and start working with your Drupal site.
- [Choose your setup](https://droost.org/docs/getting-started.md): Start with the part of Droost that matches your project. You can add the other tools as you need them.
- [Inspect your Drupal site](https://droost.org/docs/inspect-site.md): List the available tools, read a tool’s help, and inspect an entity type before making changes.
- [FAQ](https://droost.org/docs/faq.md): Short answers to the questions people ask first: what Droost is, which part to install, which agents it works with, production, cost, privacy and upgrading.

## Droost module

- [Droost module](https://droost.org/docs/module.md): Droost, the Drupal module: an agent asks the live site about itself and changes it through checked, gated writes. What it is, what to enable where, and how to install it.
- [Tools and permissions](https://droost.org/docs/module-tools.md): All 54 Droost tools in three permission groups: content tools for any site, build tools for development, developer tools for local only.
- [Write gates](https://droost.org/docs/module-gates.md): Control write categories with settings-based gates. Learn the CLI defaults, explicit web permissions and operator commands.
- [Over MCP, for editors](https://droost.org/docs/module-mcp.md): droost_mcp offers the content tools to Claude Desktop, claude.ai and other MCP clients, each call held to the connected account's own Drupal access.
- [Extending the module](https://droost.org/docs/module-extending.md): A Droost tool is a Tool API plugin. Write one in any module, and every route into Droost reaches it: drush, Drupal AI and MCP.
- [Upgrading from 1.x or a 2.0 alpha](https://droost.org/docs/upgrading.md): Droost 1.x is deprecated and unsupported. There is no upgrade path from 1.x or the 2.0 alphas to 2.0: uninstall first, then install fresh.

## Droost Workflow

- [Droost Workflow](https://droost.org/docs/how-it-works.md): 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.
- [Commands](https://droost.org/docs/commands.md): Every droost command and what it does: knowing the code, the run, what the agent records, the intake, tickets, your own commands, setup, and ddev droost on DDEV.
- [Set up with an AI agent](https://droost.org/docs/setup-with-ai.md): Tell your agent to read one file and follow it. It installs droost, checks your tools and explains the levels. Then you do the three things that are yours.
- [Set up by hand](https://droost.org/docs/setup-by-hand.md): Install droost yourself: its own folder, init, the map of your code, the level, and the tools the checks use.
- [On an existing site](https://droost.org/docs/existing-site.md): Adding droost to a site that already has code, a team and its own habits: start with a baseline of the old problems, so new runs are judged only on what they add.
- [The Claude Code plugin](https://droost.org/docs/claude-plugin.md): Install droost's plugin in Claude Code to watch each run beside your chat: the steps, the spec, the checks and the review, live.
- [Your first run](https://droost.org/docs/first-run.md): Ask for one small change and watch it go through plan, code, test and complete. What you will see, what you answer, and how to read the report.
- [Build a site from a design](https://droost.org/docs/site-from-a-design.md): Hand the agent a design (a zip, a folder of HTML, a prototype) and it plans the whole site with you first: questions, a roadmap of small tickets, your approval, then one run per ticket.
- [Make it yours](https://droost.org/docs/hooking-in.md): Add your own checks to the workflow: a gate at a step, or a house rule about how your team builds. Each is a file or one line in droost.yml.
- [Hooks and walls](https://droost.org/docs/hooks-and-walls.md): Hooks tell your code when a run starts, moves on or finishes. Walls are asked before the agent uses a tool, and can refuse it. Plus scripts only a person may run, and tabs of your own in the run panel.

## Build a site

- [Droost CMS](https://droost.org/docs/droost-cms.md): A Drupal recipe that sets up a fresh Drupal CMS site for an AI agent to build: droost's content tools, Droost Theme, UI Patterns beside Canvas, and a worked example.
- [Droost Theme](https://droost.org/docs/droost-theme.md): A base theme with design tokens, Tailwind CSS v4, daisyUI and reusable Drupal components.
- [Droost UI Kit](https://droost.org/docs/droost-ui-kit.md): Build Manage Display from Single Directory Components on UI Patterns 2, through droost's site-building tools.

## Reference

- [Settings](https://droost.org/docs/settings.md): droost/droost.yml, the one settings file: the level, who drives and who finishes a run, the gates, and the retries.
- [Gates](https://droost.org/docs/gates.md): Every built-in gate, which phase runs it, what each result word means, the seeker, retries, waivers and the baseline for old code.
- [Parity](https://droost.org/docs/parity.md): Hold the site to the design it copies: capture the design's pages once, and the parity gate compares each built page with them, text, type, colour and place.
- [Tickets](https://droost.org/docs/tickets.md): Bind a run to a ticket: markdown files in your repository, or your own tracker through a bridge of yours.
- [Troubleshooting](https://droost.org/docs/troubleshooting.md): The problems people hit most, and what to do about each.
- [Releases](https://droost.org/docs/releases.md): The current release of every Droost project, how to require it, and where each project's release notes live.
- [Requirements](https://droost.org/docs/requirements.md): What each Droost project needs: Drupal and PHP versions, Tool API, and the tools the workflow's checks run.