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/

Critical: Two separate composer.json files exist. Root manages WordPress core and plugins; theme manages PHP dependencies (Acorn, ACF Composer, etc.). Always use lando theme-composer for theme packages.

2) Decide what to create using the decision guides

Composer vs Component vs Block

Where to put logic

setup.php vs actions.php vs filters.php vs ServiceProvider

• setup.php — after_setup_theme hook only: add_theme_support(), register_nav_menus(), image sizes, content width. No business logic.
• actions.php — Simple, self-contained add_action() calls that don't need injected services. If a hook needs a service, move it to a provider.
• filters.php — Same as above but for add_filter(). Query modifications, excerpt length, etc.
• ServiceProvider boot() — Any hook that depends on container-bound services, or complex logic that benefits from dependency injection.

3) Use generators — never create files manually

Never create class files or view files manually. Acorn and ACF Composer provide generators that scaffold the correct stub with proper namespace, base class, and paired view.

Acorn generators (make:*)

• lando acorn make:component {Name} — class + view in app/View/Components/ + resources/views/components/
• lando acorn make:composer {Name} — view composer in app/View/Composers/
• lando acorn make:provider {Name} — service provider in app/Providers/
• lando acorn make:command {Name} — console command in app/Console/Commands/

Pass Category/Name for nested directories. Use --inline, --view, --path on make:component.

ACF Composer generators (acf:*)

• lando acorn acf:block {Name} — block class + view (interactive prompts)
• lando acorn acf:field {Name} — field group class
• lando acorn acf:partial {Name} — reusable field partial
• lando acorn acf:options {Name} — options page class
• lando acorn acf:widget {Name} — widget class + view

All accept --force. acf:block --localize for i18n stub. Bootstrap stubs: lando acorn acf:stubs.

For full generator details and custom stubs, see references/acf-composer.md.

4) Run common Lando commands as needed

5) Read reference files before generating code

Read the relevant reference file before generating code in that domain:

Verification

• Generator was used instead of manually creating files
• Class extends the correct base class (e.g., SageServiceProvider, not ServiceProvider)
• Hooks are in boot(), not register()
• Theme packages installed via lando theme-composer, not lando composer
• The relevant reference file was read before generating domain-specific code
• lando acorn view:clear run after Blade template changes if views appear stale
• lando pint run to fix code style

Failure modes

Problem: Extending ServiceProvider directly

• Cause: Using Laravel's base ServiceProvider instead of the Sage-aware one
• Fix: Extend SageServiceProvider in all theme service providers

Problem: Hooks placed in register() instead of boot()

• Cause: Misunderstanding the container lifecycle
• Fix: Move all add_action / add_filter calls to boot(). The container is not ready during register().

Problem: Wrong Composer context

• Cause: Running lando composer require at project root for a theme dependency, or vice versa
• Fix: Root composer.json manages WP core + plugins. Theme composer.json manages Acorn, ACF Composer, etc. Use lando theme-composer for theme packages.

Problem: wp acorn fails inside Lando

• Cause: Missing --path=/app/wp flag
• Fix: Always specify the WordPress path when running wp acorn in Lando

Problem: Using raw ACF API instead of ACF Composer

• Cause: Calling acf_add_local_field_group() directly
• Fix: Use Log1x\AcfComposer\Builder via ACF Composer classes generated with acf:block, acf:field, etc.

Problem: Blade components created in wrong directory

• Cause: Putting component classes in Composers/ or vice versa
• Fix: Components go in View/Components/, composers go in View/Composers/

Problem: Business logic in global PHP files

• Cause: Writing logic directly in actions.php, filters.php, or setup.php
• Fix: Create a Services/ class, bind it in a provider, and call it from hooks in boot()

Problem: Raw register_post_type() or register_taxonomy()

• Cause: Not using the declarative approach
• Fix: Use log1x/poet via config/poet.php. Only use a Service Provider for complex registrations that exceed Poet's capabilities.

Problem: Manually creating component/block/field files

• Cause: Writing class and view files by hand
• Fix: Always use generators (make:component, acf:block, acf:field). They scaffold both class and view with correct namespace and base class.

Problem: Tailwind configured via tailwind.config.js

• Cause: Using Tailwind v3 patterns
• Fix: Tailwind v4 is CSS-first. Configure via @theme directive in CSS files, not a JS config.

Problem: Mixing root and theme Composer dependencies

• Cause: Installing a theme package at root or a root package in the theme
• Fix: Each composer.json is independent. Never cross-install.

Escalation

• Stop and ask if the project structure does not match the expected layout above
• Stop and ask if the generator fails or produces unexpected output
• Stop and ask if unsure whether logic belongs in a Service Provider vs actions.php/filters.php
• Stop and ask if the task requires a pattern not covered by any reference file

Canonical Lando Command Reference

See references/lando-command-reference.md.