From superpowers-sage
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.
npx claudepluginhub codigodoleo/superpowers-sage --plugin superpowers-sageThis skill uses the workspace's default tool permissions.
Implement Sage components by reading from plan directories, consulting design assets, and verifying after each component.
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.
Use when an approved implementation plan exists and is ready to be executed. Initializes shared state, dispatches parallel developer agents, performs integration review, and runs full verification (lint, tsc, format, build).
Automates design system construction from repository analysis: extracts patterns, builds OKLCH token hierarchies, implements accessible components with tests, verifies via multi-reviewer panels.
Share bugs, ideas, or general feedback.
Implement Sage components by reading from plan directories, consulting design assets, and verifying after each component.
Announce at start: "I'm using the building skill to implement from the plan."
$ARGUMENTS
If a plan path is provided, read the plan. Otherwise, check for active plan in docs/plans/.
plan.md frontmatter for strategy, components, design-toolarchitecture.md for architectural decisionscontent-model.md for data modeling decisionscomponents/ for sub-plansassets/ for design reference imagesIf no plan exists, suggest running /architecture-discovery then /plan-generator first.
Based on content model:
config/poet.phplando theme-composer require <package>lando flush after PHP changesDesign system gate (runs once, before the component loop):
Check that the visual foundation exists:
resources/css/design-tokens.css — must exist and contain real tokens (not placeholder)/kitchensink — must be accessible and visually validated (Playwright screenshot taken)If either is missing or unvalidated → invoke /sage-design-system and pause until the kitchensink screenshot confirms all tokens and UI atoms render correctly. Do NOT implement any block without a validated design system.
For each component in order:
CRITICAL: subagents do NOT inherit MCP tools from the calling session. Dispatching
design-extractor without first persisting design data to disk produces fabricated specs
with VERIFY placeholders and estimated values.
Inversion pattern — always pre-fetch in THIS thread before dispatching:
With the MCP tool available in this session, capture reference data to disk:
| Tool | Commands | Output |
|---|---|---|
| Pencil | batch_get(resolveVariables:true, readDepth:4) + get_screenshot | assets/section-<name>.nodes.json + section-<name>-ref.png |
| Figma | get_design_context + get_screenshot (with nodeId) | assets/section-<name>.nodes.json + section-<name>-ref.png |
| Paper | get_node_info + get_computed_styles + get_screenshot + get_jsx | assets/section-<name>.nodes.json + section-<name>.styles.json + section-<name>-ref.png + section-<name>.reference.jsx |
| Stitch | get_screen | assets/section-<name>-ref.png |
Confirm all expected files exist on disk (ls docs/plans/<plan>/assets/).
NOW dispatch the design-extractor agent:
assets/section-<name>-spec.mdThe subagent reads the pre-captured files as source of truth — the MCP call was already made here. The subagent's only job is to structure the data into the spec file.
Verify the output is not fabricated: open the spec file and check for VERIFY markers
or suspiciously round numbers. If found, the extraction failed — re-dispatch with clearer
path references.
Fallback (no design-extractor agent available — Cursor IDE / single-agent mode):
If the subagent system is unavailable:
assets/section-<name>-spec.md and assets/section-<name>-ref.png from diskget_design_context + get_metadata (node geometry)get_computed_styles + get_node_infobatch_get(resolveVariables: true) + batch_get(readDepth: 4)get_screendesign-extractor: deferred in the plan.md frontmatterassets/section-{name}.png or assets/section-{name}.md from disk/designing to capture itcontent-model.md for this component's classification/modeling for this componentAuto-discover which reference skills are relevant:
@sage-lando references/acf-composer.md@sage-lando references/blade-templates.md@acorn-livewire@acorn-routes@sage-lando references/frontend-stack.mdIsolation approach depends on the dev environment:
| Environment | Isolation | Why |
|---|---|---|
| Lando (default for Sage) | Branch + atomic commit per component | Lando mounts /app to a fixed path in .lando.yml. Worktrees live at sibling paths and require re-mounting the container for each worktree — high friction, Lando container already knows only one path. |
| docker-compose / vanilla | Worktree per component | Container mount is flexible; worktrees at .worktrees/<component>/ are cheap and safe. |
| Bare-metal / local PHP | Worktree per component | No container constraints. |
Explicit user override (--no-worktree or plan frontmatter isolation: branch-only) | Honor the override |
Detection rule: if .lando.yml exists at repo root → use branch-commit strategy unless the user explicitly opts into worktrees.
# Start on the feature branch recorded in plan.md
FEATURE_BRANCH=$(grep '^branch:' docs/plans/<active-plan>/plan.md | awk '{print $2}')
git checkout "$FEATURE_BRANCH"
# Implement this component's files in place. Commit atomically when done.
# ... edit code ...
git add -A
git commit -m "feat({slug}): implement component per sub-plan"
Each component becomes one (or a few) well-scoped commit(s) on the feature branch. Roll back individually by reverting the commit. Lando keeps working without reconfiguration.
FEATURE_BRANCH=$(grep '^branch:' docs/plans/<active-plan>/plan.md | awk '{print $2}')
COMPONENT_BRANCH="${FEATURE_BRANCH}-<component-name>"
git worktree add .worktrees/<component-name> -b $COMPONENT_BRANCH $FEATURE_BRANCH
Example: feature branch feat/onepage-blocks-2026-03-23, component hero:
git worktree add .worktrees/hero -b feat/onepage-blocks-2026-03-23-hero feat/onepage-blocks-2026-03-23
Implement inside the worktree. The worktree mirrors the full repo root. Theme files are at .worktrees/<component>/content/themes/<theme>/.
ZERO ARBITRARY TAILWIND VALUES.
Every colour, font, spacing value must be a token declared in @theme.
{{-- ✅ Correct — use token names --}}
<section class="bg-bg text-text py-24">
{{-- ❌ Forbidden — arbitrary values are a Critical issue --}}
<section class="bg-[#131313] text-[#e5e2e1] py-[96px]">
For ACF blocks: After running lando acorn acf:block {Name} --localize, invoke /block-scaffolding for this block before proceeding. The custom element contract (tag-selector CSS scoped to block-{slug}, JS class extending BaseCustomElement, selective CSS+JS enqueue, $spacing/$supports/$styles, block README) is that skill's responsibility — do not implement manually.
After implementing:
lando flush — clears Acorn/Blade/OPcache (required after PHP changes)
lando theme-build — compiles Tailwind + JS
Pre-capture live screenshot in THIS thread (Playwright MCP lives here, not in the subagent):
Verification Inputs blockdocs/plans/<plan>/assets/section-<name>-live.pngThen dispatch visual-verifier agent with:
url: read from spec Verification Inputs blockselector: read from spec Verification Inputs blockspec: docs/plans/<plan>/assets/section-<name>-spec.mdref: docs/plans/<plan>/assets/section-<name>-ref.pnglive: docs/plans/<plan>/assets/section-<name>-live.pngThe subagent reads both images via the Read tool and compares visually. If the subagent somehow has Playwright MCP it can also re-capture, but the pre-captured image is the fallback when it doesn't.
On MATCH:
Branch-commit strategy (Lando): already on the feature branch — nothing to merge. Proceed.
Worktree strategy:
git checkout <feature-branch>
git merge <component-branch>
git worktree remove .worktrees/<component-name>
git branch -d <component-branch>
On DRIFT or FAIL_ARBITRARY_VALUES: fix in place → re-run lando theme-build → re-dispatch visual-verifier → commit/merge on MATCH
After commit/merge: git push to sync the feature branch with the remote
When components are independent (no shared CPTs or services):
dispatching-parallel-agents or subagent-driven-development base skillsAfter all components:
lando flush to clear all cacheslando theme-build for production buildresources/views/components/*.blade.php or the @theme block in resources/css/app.css was touched this session, append an entry to docs/design-system-changelog.md (see section 5 below).git add -A && git commit -m "feat(blocks): <feature-name> — all components verified" && git push — required before declaring the build phase complete/reviewing for convention auditfinishing-a-development-branch for merge/PRWhen building touches design-system-level files (atoms, tokens, base typography, layout components), append an entry to docs/design-system-changelog.md. Create the file if absent with this structure:
# Design System Changelog
Chronological record of changes to the shared visual contract. Automatically appended by /building on completion.
## YYYY-MM-DD — <PR title or commit short summary>
### Atoms
- `<x-component>` **added prop `tone`** — default, backward-compatible
- `<x-button>` **added variant `secondary-dark`** — text-link on dark bg
### Tokens
- `--text-h2-compact: 44px` (new)
- `--container-narrow: 360px` (new)
### Modifier classes
- `h2.hero`, `h2.compact` (new, unlayered, override type selector)
### Breaking changes
- _(none)_
Detection rule: if git diff --name-only <session-start>..HEAD includes:
resources/views/components/**/*.blade.php → inspect for new props, removed props, variant additionsresources/css/app.css (@theme block) → inspect for new/changed/removed tokensresources/css/blocks/**/*.css → skip (block-scoped, not shared contract)Generate the entry by diffing the files; don't ask the user to hand-write it.
When finishing-a-development-branch completes (PR merged), append to docs/milestones.md:
# Milestones
## YYYY-MM-DD — v<version> (PR #<number>)
- **Scope:** <1-line PR title>
- **Components delivered:** <list>
- **Architectural patterns validated:** <list>
- **Decisions recorded in:** <spec path>
- **Known follow-ups:** <list or "none">
This survives context compaction and gives future sessions a fast recap of what shipped. Do NOT rely on memory files alone — milestones are commit history with meaning.
lando flush and lando theme-build@theme tokens; arbitrary [#hex] classes are a Critical issue caught by visual-verifierBefore generating code that references CPTs, fields, routes, or Livewire components:
discover-abilities
execute-ability posts/list-types
execute-ability acf/field-groups
Never invent slugs or field names — always query first when the stack is available.
See sageing/references/mcp-query-patterns.md.