superpowers-sage:sage-lando

Roots Sage + Acorn + Lando

When to use

• Setting up or modifying a Lando-based WordPress development environment
• Creating ACF blocks, field groups, partials, or options pages
• Building Blade components, view composers, or layouts
• Configuring Vite, Tailwind v4, or frontend assets
• Registering custom post types, taxonomies, or service providers
• Running Acorn or ACF Composer generators
• Troubleshooting Sage/Acorn/Lando issues

Inputs required

• The project root path (contains .lando.yml and root composer.json)
• The theme directory path (contains theme composer.json and app/ directory)
• The specific domain: blocks, fields, components, providers, frontend, or environment setup
• For generators: the name (and optional subdirectory) for the class being created

Procedure

0) Triage

Determine the task domain:

1. Environment setup / Lando — read references/lando-setup.md, then go to step 1
2. ACF blocks, fields, partials, options — read references/acf-composer.md, then go to step 2
3. Blade templates, components, composers — read references/blade-templates.md, then go to step 3
4. Frontend (Vite, Tailwind, CSS/JS) — read references/frontend-stack.md, then go to step 4
5. Service providers, services, bindings — read references/service-providers.md, then go to step 5
6. CPTs, taxonomies, navigation — read references/routing-and-cpts.md, then go to step 6
7. Testing — read references/testing.md, then go to step 7
8. Debugging — read references/troubleshooting.md, then go to step 8
9. WordPress plugin installation via Composer — read references/wordpress-composer.md, then go to step 9

1) Understand the project structure

Confirm the project follows this layout:

project-root/
├── .lando.yml                    # Lando config — recipe: wordpress
├── .env                          # WP_HOME, DB credentials
├── composer.json                 # Root: roots/wordpress, WP core + plugins
├── wp/                           # WordPress core (managed by Composer)
├── content/
│   ├── plugins/                  # WordPress plugins
│   └── themes/
│       └── {theme}/
│           ├── composer.json     # Theme: roots/acorn, log1x/* packages
│           ├── package.json      # Theme: vite, tailwind, etc.
│           ├── vite.config.js
│           ├── app/
│           │   ├── Providers/
│           │   │   └── ThemeServiceProvider.php
│           │   ├── Services/       # Business logic classes
│           │   ├── View/
│           │   │   ├── Composers/  # View composers (auto-discovered)
│           │   │   └── Components/ # Blade components
│           │   ├── Blocks/         # ACF Gutenberg blocks
│           │   ├── Fields/         # ACF field groups
│           │   │   └── Partials/   # Reusable field partials
│           │   ├── Options/        # ACF options pages
│           │   ├── Console/
│           │   │   └── Commands/   # Custom Acorn CLI commands
│           │   ├── setup.php       # Theme support, nav menus, sidebars
│           │   ├── actions.php     # Global add_action calls
│           │   ├── filters.php     # Global add_filter calls
│           │   └── helpers.php     # Global helper functions
│           ├── config/
│           │   └── poet.php        # CPTs, taxonomies, block categories
│           ├── stubs/              # Custom generator stubs (auto-detected)
│           └── resources/
│               ├── views/          # Blade templates (.blade.php)
│               │   ├── layouts/    # Layout templates (app.blade.php)
│               │   ├── partials/   # Shared partials
│               │   ├── sections/   # Page sections
│               │   ├── components/ # Component views
│               │   └── blocks/     # ACF block views
│               ├── css/
│               ├── js/
│               └── fonts/