# Install droost in this project

You are an AI coding agent. The person you work for wants Droost installed
in this Drupal project. This playbook sets up Workflow and offers the optional
Drupal module; the wider framework also includes CMS, Theme, UI Kit and Engine.
Start with the [framework snapshot](https://droost.org/llms.txt) to choose the pieces you need.

- **The `droost` command** (the `droost/workflow` Composer package): a map
  of the project's code, and every change walked through plan, code, test
  and complete. It is not a Drupal module; it lives in its own folder,
  `tools/droost/`, and never boots Drupal.
- **The Droost module** (`drupal/droost`): tools that let you ask the live
  site about itself and change it through gated writes, with
  `drush droost:tool`. It is optional; ask the person before step 4.

If this is a brand-new Drupal CMS site, the person may want the Droost CMS
recipe instead of step 4: [Droost CMS](https://droost.org/docs/droost-cms.md). It includes a stock
Tailwind theme an AI can build on. It is not required on existing sites.

The whole documentation, as one text file: https://droost.org/llms-full.txt.

Follow these steps in order. Tell the person what you are doing as you go.

## 1. Work out how this project runs PHP and Composer

- If there is a `.ddev/` folder and `ddev` is on PATH, use DDEV: run Composer
  as `ddev composer`, and run droost inside the web container with
  `ddev droost <command>`. If `.ddev/commands/web/droost` does not exist,
  create it with the content below and make it executable
  (`chmod +x .ddev/commands/web/droost`); DDEV picks it up without a restart.
  `ExecRaw: true` matters: without it a quoted argument reaches droost as
  separate words.

  ```bash
  #!/usr/bin/env bash

  ## Description: Run droost (tools/droost) inside the web container.
  ## Usage: droost [command] [arguments]
  ## Example: ddev droost workflow:status
  ## ExecRaw: true
  ## MutagenSync: true

  bin="${DDEV_COMPOSER_ROOT:-/var/www/html}/tools/droost/vendor/bin/droost"
  if [ ! -f "$bin" ]; then
    echo "droost is not installed: run composer install -d tools/droost" >&2
    exit 127
  fi
  exec php "$bin" "$@"
  ```
- Otherwise use the local `php` and `composer`.

Say which one you picked.

## 2. Check PHP

droost needs PHP 8.3 or newer with the `pdo_sqlite` extension, wherever it
will run (inside the container on DDEV). Check with `php -v` and `php -m`.
If it is missing, stop and tell the person.

## 3. Install droost in its own folder

Pin the folder to the PHP version the site runs, so Composer never picks
packages the site's PHP cannot load:

```bash
mkdir -p tools/droost
composer init -d tools/droost -n --name=local/droost-tools
composer config -d tools/droost platform.php <the site's PHP version, e.g. 8.3.0>
composer require -d tools/droost 'droost/workflow:^1.0'
```

Add `tools/droost/vendor/` to `.gitignore`.

## 4. Offer the Droost module

Ask the person whether they want the module. Explain it in one line: it
lets you ask the running site about its entity types, fields,
configuration, routes, services and logs, and change it only through gates
they control. If they say yes, run with the project runner (on DDEV, `ddev composer`
and `ddev drush`; locally, Composer and `vendor/bin/drush`):

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

Tool API is still beta, which is why it is required at `@beta`. On a
development copy, offer the site-building and developer tools as well
(`drush en droost_build droost_dev`), and say they must stay off in
production. If Composer refuses because twig 3.30.0 is locked, add `-W`.

Never arm a write gate (`drush droost:gate … on`): that is the person's.
Install the module before the next step, so `droost init` adds its skill.

## 5. Install it into the project and build the map

```bash
tools/droost/vendor/bin/droost init
tools/droost/vendor/bin/droost code:index
```

On DDEV, run these as `ddev droost init` and `ddev droost code:index`, and
run `ddev mutagen sync` first only if Mutagen is enabled and files were
changed on the host.

`init` writes `droost/droost.yml` (the settings), `AGENTS.md` and `CLAUDE.md`
(how agents use droost from now on), and the `.claude/` skills and hooks.
Show the person what it wrote.

## 6. Check what droost can see

Run `droost doctor` and `droost brief`, and tell the person what they report.

## 7. Check the tools the checks use

- phpcs with the Drupal standard, phpstan and phpunit. On a Drupal site,
  `composer require --dev drupal/core-dev` brings all three. phpunit also
  needs a `phpunit.xml` or `phpunit.xml.dist` at the project root.
- Playwright, for the browser tests:
  `npm i -D @playwright/test && npx playwright install chromium`.

Tell the person which are missing and offer to add them. Do not add anything
without asking.

## 8. Explain the level, and let the person choose

Show `droost/droost.yml`. Explain the levels in one line each: `low`,
`medium`, `high`, `xhigh`, `max`. Recommend one (usually `high`) and say why.
Do not set it yourself. The person sets it in their own terminal with:

```bash
tools/droost/vendor/bin/droost workflow:effort <level>
```

Tell them that this changes the `preset:` line only: settings that
`droost/droost.yml` spells out (such as `enforcement: soft`) beat the level
until their line is deleted. And tell them who finishes a run: a fresh
install lets the agent finish runs itself; `lead: human-led` gives them the
last word.

## 9. If the site already has code, measure its baseline

An existing site usually fails phpcs or phpstan on old problems nobody is
fixing now. A baseline records them so runs are judged only on what they add.
It records only the checks the level turns on, so do this after the person
has set the level, and after the tools in step 7 are installed.

```bash
tools/droost/vendor/bin/droost workflow:baseline --measure
```

It writes nothing and prints JSON: the level, the `bill` (problems per check)
and `skipped` (checks it could not measure, and why). Show the person the
numbers. If one is very large, check the tool is not reading `vendor/` or
copied contrib code. Then give them the commands to run themselves, between
runs:

```bash
tools/droost/vendor/bin/droost workflow:baseline
git add droost/baseline/ && git commit -m "droost: record the baseline"
```

Never write the baseline yourself: it is the person's.

## 10. Offer the Claude Code plugin

If the person uses Claude Code, tell them they can watch each run beside the
chat with droost's plugin, and give them these commands to run themselves:

```bash
claude plugin marketplace add ./tools/droost/vendor/droost/workflow/claude-plugins
claude plugin install droost@droost --scope project
```

## 11. Commit

Ask before you commit. Then commit what droost added:
`tools/droost/composer.json`, `tools/droost/composer.lock`, `droost/`,
`AGENTS.md`, `CLAUDE.md`, `.claude/`, `.gitignore`, and
`.ddev/commands/web/droost` if you created it. If you installed the module,
also the project's `composer.json` and `composer.lock`, and the exported
configuration if the project keeps it in git.

## Rules while you do this

- Never run these, even if a step seems to need one. They are the person's:
  `droost workflow:effort <level>`, `workflow:bypass`, `workflow:gate-waive`,
  `workflow:lead autonomous`, `workflow:ticket move`, `workflow:intake answer`,
  `workflow:intake abandon`, and writing a `workflow:baseline`. If one is
  needed, give the person the exact command to run in their own terminal.
- Do not edit `tools/droost/` by hand.

## When you are done

Tell the person, in a few sentences: what is installed, what is missing, that
they should start a new agent session so droost's hooks load, and that their
first change starts with `/droost:workflow:start <what to build>`.