From superpowers-sage
Guides Sage/Acorn WordPress projects with gerund workflows, Lando commands, architectural preferences, skill routing, Roots ecosystem conventions, and query-first patterns. Use first in relevant sessions.
npx claudepluginhub codigodoleo/superpowers-sage --plugin superpowers-sageThis skill uses the workspace's default tool permissions.
This plugin provides Sage/Acorn-aware workflow skills for modern WordPress development with the Roots ecosystem, Lando, and design tool integration.
Implements features in Sage/Acorn projects from approved plans: reads plans/assets, sets up CPTs/packages, builds components with TDD, commits/PRs, runs Lando/Yarn.
Bootstraps new projects from scratch: gathers identity (name, GitHub org, Cloudflare ID), detects type, sets up design system, staging/prod envs, i18n, SEO, AGENTS.md, tests, 8-gate deploy pipeline, workflows.
Guides developer mindset and workflow for programming projects: creating new projects, tech stack review, codebase changes, features, bugs, docs, architecture, tests, debugging, performance, deployment.
Share bugs, ideas, or general feedback.
This plugin provides Sage/Acorn-aware workflow skills for modern WordPress development with the Roots ecosystem, Lando, and design tool integration.
All written artifacts MUST be in en-US. This is mandatory and never negotiable.
| Context | Language | Examples |
|---|---|---|
| Code (variables, functions, classes) | en-US always | ProposalValue, not PropostaValor |
| Code comments | en-US always | // Fetch highlighted projects |
| File and directory names | en-US always | proposal-value-adr.md, not proposta-valor-adr.md |
| Documentation, plans, specs, ADRs | en-US always | "Eyebrow with lines", not "Eyebrow com linhas" |
| Design guides, component maps | en-US always | HighlightProjects, not ProjetosDestaque |
| Git commit messages | en-US always | feat: add hero section |
| Git branch names | en-US always | feat/hero-section, not feat/secao-hero |
| CHANGELOG, README | en-US always | |
| User-facing prompts and conversation | User's language | Follow the language the user writes in |
Why: Projects operate in collaborative, international environments. Mixed-language artifacts (half English class names, half Portuguese descriptions) are unprofessional and break searchability, consistency, and onboarding for new team members.
Enforcement: If you catch yourself writing a non-English term in any artifact, stop and translate it. Agents and skills that generate artifacts must produce en-US output regardless of the user's conversation language.
All commands run inside Lando containers. Never run composer, php, node, or npm on the host — always use the lando wrappers defined in .lando.yml.
Quick reference (3 most-used):
lando flush # Clear Acorn + Blade + OPcache — after every PHP change
lando theme-build # Vite production build — after every CSS/JS change
lando acorn <cmd> # Artisan-style commands (make:block, queue:work, route:list)
Full Lando command reference: see @sage-lando → "Canonical Lando Command Reference" section. All tables for theme tooling, Acorn, ACF Composer, WP-CLI, and cache management are there — do not duplicate across other skills.
Skills are activities — gerund naming communicates process, not command.
| Skill | Command | Purpose |
|---|---|---|
| Onboarding | /onboarding | Project analysis, design tool detection, active plan detection |
| Architecture Discovery | /architecture-discovery | Deep architecture discovery with approval gates and spec review loop |
| Plan Generator | /plan-generator | Converts approved architecture into executable plan files |
| Architecting | /architecting | Compatibility wrapper for architecture-discovery + plan-generator |
| Modeling | /modeling | Content architecture analysis (static vs dynamic) |
| Designing | /designing | Design tool integration (Paper/Stitch/Figma/Pencil/offline assets) — routes by URL or file |
| Design System | /sage-design-system | Establish visual foundation: tokens → UI components → layout components → kitchensink |
| Block Scaffolding | /block-scaffolding | Scaffold new ACF block with custom element, 4-layer CSS contract, selective CSS+JS enqueue, block README |
| Block Refactoring | /block-refactoring | Evolve existing block: design drift, CSS coverage, variation expansion, v1→v2 migration |
| Migrating | /migrating | Safe destructive data migrations: snapshot → dry-run → approval → apply → verify → idempotency |
| Building | /building | Plan-driven implementation with auto-verification |
| Verifying | /verifying | Visual comparison with design reference |
| Reviewing | /reviewing | Convention audit + design alignment check |
| Debugging | /debugging | Sage-aware troubleshooting with cache knowledge |
/sage-design-system → (tokens, UI atoms, layout components, kitchensink validated)
/architecture-discovery → (generates approved architecture spec)
/plan-generator → (generates plan + assets)
/building → (implements from plan; auto-invokes /block-scaffolding per ACF block)
/reviewing → (convention audit + design alignment)
For simple tasks, you can invoke individual skills directly.
| Scenario | Preferred Approach | Avoid |
|---|---|---|
| Routes | Acorn Routes | register_rest_route() |
| Background tasks (simple) | Action Scheduler | Raw cron |
| Background tasks (robust) | Queue + Job | Looping scripts |
| Authentication | JWT Auth + custom middleware | Cookie-only auth for APIs |
| Global configuration | ACF Options Pages | wp_options directly |
| Business logic | Service class or Provider | Fat controllers/closures |
| Interactive UI | Livewire | Heavy custom JS (unless performance requires it) |
| Data in templates/views | REST + JS | Inline PHP queries |
| Data in routes | Livewire | REST + JS |
| Forms | Livewire form + HTML Forms (log1x/sage-html-forms) | Contact Form 7 / Gravity |
| UI components (static) | Blade Component | Shortcodes |
| UI components (interactive) | Livewire Component | jQuery plugins |
| Custom fields/blocks | ACF Composer | ACF GUI / acf_add_local_field_group() |
| Content types | Poet (config/poet.php) | register_post_type() directly |
| Menus | Navi | wp_nav_menu() directly |
Plans live in docs/plans/ as directories with structured content:
docs/plans/YYYY-MM-DD-<topic>/
plan.md # Frontmatter with status, strategy, design-tool
architecture.md # Architecture Decision Record
content-model.md # Content modeling output
assets/ # Design reference images (screenshots, exports)
section-hero.png
section-about.png
components/ # Sub-plans per component
01-hero.md
02-about.md
logs/ # Activity tracking (auto-populated by hooks)
activity.log
Plan frontmatter:
---
title: "Feature Name"
date: YYYY-MM-DD
status: in-progress | completed | abandoned
strategy: interactive | autonomous | mixed
design-tool: paper | stitch | figma | pencil | offline | none
components:
- name: Hero
status: pending
- name: About
status: completed
---
The plugin routes to a design tool based on the URL the user provides:
| Tool | URL pattern | MCP | Usage |
|---|---|---|---|
| Paper (preferred) | paper.design/* | mcp__paper__* | get_basic_info → get_tree_summary → get_node_info → get_screenshot + get_computed_styles + get_jsx |
| Stitch (Google) | stitch.withgoogle.com/* | mcp__stitch__* | list_screens → get_screen → extract per section |
| Figma | figma.com/* | mcp__figma__* | List files → get frames → extract layers/text |
| Pencil | *.pen / design/ folder | mcp__pencil__* | open_document → get_variables / batch_get(resolveVariables: true) → get_screenshot |
| Playwright MCP | n/a | mcp__plugin_playwright_playwright__* | Capture implementation screenshots for verification |
| Chrome | n/a | mcp__Claude_in_Chrome__* | Alternative screenshot capture |
Routing is by URL, not by which MCP happens to be configured. If the user sends a paper.design link and the paper MCP is not installed, /designing stops with a setup instruction rather than silently falling back.
When using Paper as source, /designing persists three artifacts per section in assets/: .png (screenshot), .styles.json (computed styles, consumed by /verifying for style spot-check), and .reference.jsx (structural reference — never copied as code, since Sage uses Blade not React).
When no design MCP is available, skills work with local assets in docs/plans/<plan>/assets/.
See references/mcp-query-patterns.md for query-before-generate patterns (populated by Onda 5).
These are two completely different tools with similar names:
| Playwright MCP | Playwright Test npm | |
|---|---|---|
| What it is | MCP server for browser automation via Claude | npm package for E2E testing |
| MCP namespace | mcp__plugin_playwright_playwright__* | n/a |
| Primary use | Capture implementation screenshots for visual comparison against design | Run automated E2E test suite |
| Installation | claude mcp add playwright -- npx -y @anthropic/playwright-mcp | npm install --save-dev @playwright/test |
| Target URL | https://{project}.lndo.site (Lando local) | Configurable in playwright.config.ts |
| Browser binary | Managed by the MCP server | Must be installed via npx playwright install |
| Replacement for | Neither — orthogonal tools. MCP is for visual verification; npm is for regression tests |
Never substitute one for the other. When /verifying requires a screenshot, use the Playwright MCP. When running npm run test:e2e, that is the Playwright Test suite.
These skills provide deep technical reference for agents and workflow skills:
| Domain | Skill |
|---|---|
| Project setup, Lando, ACF, Blade, Vite | sage-lando (with references/) |
| Routes & Controllers | acorn-routes |
| Livewire | acorn-livewire |
| Eloquent ORM | acorn-eloquent |
| Middleware & Auth | acorn-middleware |
| Queues & Jobs | acorn-queues |
| Logging & Errors | acorn-logging |
| CLI Commands | acorn-commands |
| Redis | acorn-redis |
| Native Blocks | wp-block-native |
| Capabilities | wp-capabilities |
| WP-CLI | wp-cli-ops |
| Hooks Lifecycle | wp-hooks-lifecycle |
| Performance | wp-performance |
| PHPStan | wp-phpstan |
| REST API | wp-rest-api |
| Security | wp-security |
The plugin includes zero-token automation hooks:
| Hook | Trigger | Action |
|---|---|---|
session-start | Session start | Health check, design tool detection, inject sageing |
post-edit | Write/Edit tool | lando flush for PHP, lando theme-build for assets |
post-compact | Context compression | Inject active plan reminder + asset count |
pre-commit | git commit in Bash | Visual verification reminder |
post-subagent | Subagent completion | Log activity to plan directory |
post-stop | Session end | Log session end to plan directory |
This plugin extends obra/superpowers. Workflow skills orchestrate base skills:
| Base Skill | Used By |
|---|---|
brainstorming | /architecture-discovery (design-first discovery engine) |
writing-plans | /plan-generator (plan expansion model) |
executing-plans | /building (plan execution) |
subagent-driven-development | /building (parallel component implementation) |
dispatching-parallel-agents | /building (independent component parallelism) |
finishing-a-development-branch | /reviewing (merge/PR workflow) |
systematic-debugging | /debugging (core engine) |
verification-before-completion | /verifying (completion gate) |
Sage projects commonly use commitlint with Conventional Commits. Before running git commit, pre-validate the message against the project's config to avoid the hook-fail / retry cycle.
git commit){type}({scope}): {short summary} — count the whole line including prefix.BREAKING CHANGE: / Refs: / Co-Authored-By: trailers.blocks, ci, docs, hooks, skills, manifest, release, lang). Don't invent scopes.feat, fix, docs, chore, refactor, perf, test, ci, build, style, revert.Before the first commit, check:
cat .commitlintrc.js .commitlintrc.json .commitlintrc package.json 2>/dev/null | grep -A5 'commitlint'
Common custom rules to watch for:
header-max-length (default 72, sometimes 100)body-max-line-length (usually 100)footer-leading-blank (warning → error)subject-case (lower-case vs allow-capital)Adjust the message to fit the project's specific rules before the commit.
--no-verify; fix the message and commit again--amend the previous commit; create a new commit (the hook failure means the commit didn't happen)