Roots/Radicle Development Setup

Automated setup and configuration for Roots WordPress projects (Sage 11, Bedrock, Trellis) or Radicle projects with Lima VM, Bonsai CLI integration, and deployment workflows.

What This Skill Does

This skill provides a complete setup workflow for modern WordPress development using the Roots stack or Radicle. It handles:

Instructions

When the user says "Do the thing" or "build my bonsai", follow these steps:

Step 1: Gather Project Information

Before proceeding, if not already provided, ask the user for:

Step 2: Detect Project Structure

Examine the project directory to determine the stack:

**Radicle Project** (if you see):

**Open-Source Roots** (if you see):

Step 3: Radicle Project Setup

If using Radicle, follow this sequence:

1. Check if `/trellis` folder exists. If not:

```bash

php .radicle-setup/trellis.php

```

2. Initialize Trellis (use [sitename] when prompted):

```bash

cd trellis && trellis init

```

3. Start and provision VM:

```bash

trellis vm start

```

If provisioning doesn't happen automatically:

```bash

trellis provision development

```

4. Align Lima VM with `/etc/hosts` and SSH Config (see section below)

5. Build assets and install dependencies:

```bash

npm install && npm run build

composer install

```

6. Configure and install Bonsai CLI:

```bash

composer config repositories.bonsai-cli vcs [email protected]:jackalopelabs/bonsai-cli.git

composer require jackalopelabs/bonsai-cli:dev-kanban

```

7. Configure `wp-cli.yml` with aliases (see section below)

8. Initialize Bonsai:

```bash

wp @development acorn optimize:clear

wp @development acorn bonsai:init

./scripts/bonsai.sh acorn bonsai:generate [project_name]

```

Step 4: Open-Source Roots Setup

If project is empty (only `.cursorrules` exists):

1. Install Trellis and Bedrock:

```bash

trellis new [sitename]

```

If command not found:

```bash

brew install roots/tap/trellis-cli

```

2. Move contents to project root:

```bash

mv [sitename]/site [sitename]/trellis . && rmdir [sitename]

```

3. Install Sage 11:

```bash

cd site/web/app/themes

composer create-project roots/sage

```

4. Build theme and install dependencies:

```bash

cd sage

npm install

npm install alpinejs --save

npm run build

```

5. Initialize and start Trellis:

```bash

cd trellis

trellis init

trellis galaxy install

trellis vm start

```

6. Align Lima VM with `/etc/hosts` and SSH Config (see section below)

7. Configure `site/wp-cli.yml` with aliases (see section below)

8. Activate theme:

```bash

wp @development theme activate sage

```

9. Configure and install Bonsai CLI:

```bash

cd site

composer config repositories.bonsai-cli vcs [email protected]:jackalopelabs/bonsai-cli.git

composer require jackalopelabs/bonsai-cli:dev-kanban

```

10. Initialize Bonsai:

```bash

wp @development acorn optimize:clear

wp @development acorn bonsai:init

./web/app/themes/sage/scripts/bonsai.sh acorn bonsai:generate [project_name]

```

Step 5: Configure WP-CLI Aliases

Edit `wp-cli.yml` (or `site/wp-cli.yml` for open-source):

```yaml

@development:

ssh: [sitename-without-tld].test/srv/www/[sitename]/current

@staging:

ssh: web@staging.[sitename]/srv/www/[sitename]/current

@production:

ssh: web@[sitename]/srv/www/[sitename]/current

```

**Note**: For `@development`, remove the TLD from [sitename] and use `.test` (e.g., `chosen.bonsai.so` becomes `chosen.bonsai.test`)

**Example** for `chosen.bonsai.so`:

```yaml

@development:

ssh: chosen.bonsai.test/srv/www/chosen.bonsai.so/current

@staging:

ssh: [email protected]/srv/www/chosen.bonsai.so/current

@production:

ssh: [email protected]/srv/www/chosen.bonsai.so/current

```

Test the connection:

```bash

ssh [sitename]

```

Step 6: Align Lima VM with /etc/hosts and SSH Config

1. **Add sudoers rule** (one-time):

```bash

trellis vm sudoers | sudo tee /etc/sudoers.d/trellis

```

2. **Get Lima VM port**:

```bash

limactl list

```

Note the port number (e.g., 54368)

3. **Update /etc/hosts**:

```bash

sudo trellis vm start

```

Verify:

```bash

cat /etc/hosts | grep [sitename]

```

Should show: `127.0.0.1 [sitename].test`

4. **Update SSH config**:

```bash

nano ~/.ssh/config

```

Add or update (replace PORT with number from step 2):

```

Host [sitename].test

HostName 127.0.0.1

User [username]

Port PORT

IdentityFile ~/.lima/_config/user

IdentityFile ~/.ssh/id_ed25519

StrictHostKeyChecking accept-new

UserKnownHostsFile ~/.ssh/known_hosts

```

5. **Test connection**:

```bash

ssh [sitename].test

```

Step 7: Deployment Configuration (Staging)

When user requests staging deployment setup:

1. **Digital Ocean Setup**:

- Create Ubuntu 22.04 droplet

- Note public IP address

- Add A record in DNS for domain

- Add IP to `/etc/hosts`: `sudo vim /etc/hosts`

- Add IP to SSH config: `vim ~/.ssh/config`

- Test SSH connection to server

2. **Trellis Configuration**:

- Verify `group_vars/staging/wordpress_sites.yml` uses `main` branch (not `master`)

- Set hostname in `hosts/staging.yml` to [sitename]

- Generate vault password:

```bash

openssl rand -base64 32 > .vault_pass

```

- Add to `ansible.cfg`: `vault_password_file = .vault_pass`

- Encrypt vault:

```bash

trellis vault encrypt

```

3. **Deployment**:

- Pause for user to commit to GitHub

- Provision:

```bash

trellis provision staging

```

- Deploy:

```bash

trellis deploy staging

```

Step 8: Troubleshooting Deployment Issues

**If staging deploy fails:**

1. SSH into newest release and run:

```bash

wp core install --url=[sitename] --title=[project_name] --admin_user=admin --admin_password=admin --admin_email=admin@[sitename] --allow-root

```

2. Redeploy:

```bash

trellis deploy staging

```

**If permission error occurs:**

SSH into server and fix permissions:

```bash

cd /srv/www/staging.[sitename]/releases

sudo chown -R web:www-data *

```

**If Acorn fails on first deployment:**

Comment out the "Run Acorn optimize" task in `trellis/deploy-hooks/build-after.yml` for the first deployment, then redeploy:

```bash

trellis deploy staging

```

After successful deployment, uncomment the task for future deployments.

Important Notes

Example Usage

**User**: "Do the thing"

**AI Response**: "I'll set up your Roots/Radicle project. First, I need some information:

**User**: "Project name is chosen, sitename is chosen.bonsai.so"

**AI**: *Proceeds with automated setup following the instructions above*