# Superpowers Sage:building > Plan-driven implementation in Sage/Acorn — reads docs/plans/ directory, implements components from approved sub-plans, runs scaffold generators (lando acorn acf:block), commits incrementally, auto-invokes block-scaffolding per ACF block, runs lando flush and lando theme-build after changes; full PR workflow with sage-reviewer gate. Invoke for: "/building", "implement from the plan", "implement from the plan", "build from the plan", "execute the plan", "start building", "code this feature". Skip when: there is no approved plan yet — run /architecture-discovery then /plan-generator first. - Skill: `hekivo/superpowers-sage-building` (Agent Skill) - Install (CLI): `npx skillmds add hekivo/superpowers-sage-building` - Raw SKILL.md: https://api.skillmd.com/api/skills/hekivo/superpowers-sage-building/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: hekivo (https://skillmd.com/u/hekivo) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/hekivo/superpowers-sage-building --- # Building — Plan-Driven Implementation 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." ## Inputs $ARGUMENTS If a plan path is provided, read the plan. Otherwise, check for active plan in `docs/plans/`. ## Procedure ### 0) Load the plan 1. Read `plan.md` frontmatter for strategy, components, design-tool 2. Read `architecture.md` for architectural decisions 3. Read `content-model.md` for data modeling decisions 4. List `components/` for sub-plans 5. List `assets/` for design reference images If no plan exists, suggest running `/architecture-discovery` then `/plan-generator` first. ### 1) Set up prerequisites Based on content model: 1. If CPTs needed → configure `config/poet.php` 2. If new packages needed → `lando theme-composer require ` 3. If Options Pages needed → create ACF Options class 4. Run `lando flush` after PHP changes ### 2) Implement components (per sub-plan) **Design 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) - Route `/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: #### 0) Pre-fetch design reference, THEN dispatch design-extractor **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:** 1. 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-.nodes.json` + `section--ref.png` | | Figma | `get_design_context` + `get_screenshot` (with nodeId) | `assets/section-.nodes.json` + `section--ref.png` | | Paper | `get_node_info` + `get_computed_styles` + `get_screenshot` + `get_jsx` | `assets/section-.nodes.json` + `section-.styles.json` + `section--ref.png` + `section-.reference.jsx` | | Stitch | `get_screen` | `assets/section--ref.png` | 2. Confirm all expected files exist on disk (`ls docs/plans//assets/`). 3. NOW dispatch the `design-extractor` agent: - Mode: SURGICAL - Target: this specific component section only - Pass the pre-captured paths in the prompt - Output: `assets/section--spec.md` The 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: 1. Re-read `assets/section--spec.md` and `assets/section--ref.png` from disk 2. Pull live design reference via the active MCP tool: - Figma: `get_design_context` + `get_metadata` (node geometry) - Paper: `get_computed_styles` + `get_node_info` - Pencil: `batch_get(resolveVariables: true)` + `batch_get(readDepth: 4)` - Stitch: `get_screen` 3. Record `design-extractor: deferred` in the `plan.md` frontmatter 4. Use the values extracted from step 2 as the source of truth #### a) Re-read design reference (ALWAYS) - Read `assets/section-{name}.png` or `assets/section-{name}.md` from disk - **NEVER rely on context memory** — always re-read from disk before each component - If asset missing, invoke `/designing` to capture it #### b) Check content model - Read `content-model.md` for this component's classification - If not classified, invoke `/modeling` for this component #### c) Consult reference skills Auto-discover which reference skills are relevant: - ACF block → read `@sage-lando` references/acf-composer.md - Blade view → read `@sage-lando` references/blade-templates.md - Livewire → read `@acorn-livewire` - Routes → read `@acorn-routes` - Tailwind/CSS → read `@sage-lando` references/frontend-stack.md #### d) Isolation strategy — decide: worktree vs branch-commit Isolation 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//` 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. ##### Branch + atomic commit (Lando path) ```bash # Start on the feature branch recorded in plan.md FEATURE_BRANCH=$(grep '^branch:' docs/plans//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. ##### Worktree (docker-compose / bare-metal path) ```bash FEATURE_BRANCH=$(grep '^branch:' docs/plans//plan.md | awk '{print $2}') COMPONENT_BRANCH="${FEATURE_BRANCH}-" git worktree add .worktrees/ -b $COMPONENT_BRANCH $FEATURE_BRANCH ``` Example: feature branch `feat/onepage-blocks-2026-03-23`, component `hero`: ```bash 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//content/themes//`. **ZERO ARBITRARY TAILWIND VALUES.** Every colour, font, spacing value must be a token declared in `@theme`. ```blade {{-- ✅ Correct — use token names --}}
{{-- ❌ Forbidden — arbitrary values are a Critical issue --}}
``` **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. #### e) Build and verify After implementing: 1. `lando flush` — clears Acorn/Blade/OPcache (required after PHP changes) 2. `lando theme-build` — compiles Tailwind + JS - If exit non-zero: **stop, report build failure. Do NOT proceed to verification.** 3. **Pre-capture live screenshot** in THIS thread (Playwright MCP lives here, not in the subagent): - Navigate to the URL from the spec's `Verification Inputs` block - Take a screenshot with the canonical viewport width - Save to `docs/plans//assets/section--live.png` Then dispatch `visual-verifier` agent with: - `url`: read from spec `Verification Inputs` block - `selector`: read from spec `Verification Inputs` block - `spec`: `docs/plans//assets/section--spec.md` - `ref`: `docs/plans//assets/section--ref.png` - `live`: `docs/plans//assets/section--live.png` The 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. 4. On `MATCH`: **Branch-commit strategy (Lando):** already on the feature branch — nothing to merge. Proceed. **Worktree strategy:** ```bash git checkout git merge git worktree remove .worktrees/ git branch -d ``` 5. On `DRIFT` or `FAIL_ARBITRARY_VALUES`: fix in place → re-run `lando theme-build` → re-dispatch `visual-verifier` → commit/merge on MATCH 6. After commit/merge: `git push` to sync the feature branch with the remote #### f) Strategy gate - **Interactive strategy**: pause for user approval before next component - **Autonomous strategy**: proceed to next component if verification passed - **Mixed strategy**: pause only for complex components ### 3) Parallel delegation When components are independent (no shared CPTs or services): - Use `dispatching-parallel-agents` or `subagent-driven-development` base skills - Each subagent gets: sub-plan path, asset path, content model excerpt - Review subagent output between batches ### 4) Completion After all components: 1. Run `lando flush` to clear all caches 2. Run `lando theme-build` for production build 3. **Design-system changelog check:** if any file under `resources/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). 4. **Commit gate:** `git add -A && git commit -m "feat(blocks): — all components verified" && git push` — required before declaring the build phase complete 5. Suggest `/reviewing` for convention audit 6. Suggest `finishing-a-development-branch` for merge/PR ### 5) Design-system changelog auto-entry When 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: ```markdown # Design System Changelog Chronological record of changes to the shared visual contract. Automatically appended by /building on completion. ## YYYY-MM-DD — ### Atoms - `` **added prop `tone`** — default, backward-compatible - `` **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 ..HEAD` includes: - `resources/views/components/**/*.blade.php` → inspect for new props, removed props, variant additions - `resources/css/app.css` (@theme block) → inspect for new/changed/removed tokens - `resources/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. ### 6) Milestones auto-save (post-merge) When `finishing-a-development-branch` completes (PR merged), append to `docs/milestones.md`: ```markdown # Milestones ## YYYY-MM-DD — v (PR #) - **Scope:** <1-line PR title> - **Components delivered:** - **Architectural patterns validated:** - **Decisions recorded in:** - **Known follow-ups:** ``` 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. ## Key Principles - **Always re-read assets from disk** — context compression will lose design reference - **Verify after each component** — catch drift early, not at the end - **Consult reference skills** — don't guess patterns, read the reference - **Respect the strategy** — autonomous for simple, interactive for complex - **Hooks handle cache** — post-edit hook auto-runs `lando flush` and `lando theme-build` - **Worktree per component** — every component is implemented in an isolated branch+worktree, merged to the feature branch only after visual verification passes - **Zero arbitrary Tailwind values** — all colours, fonts, and spacing must be `@theme` tokens; arbitrary `[#hex]` classes are a Critical issue caught by visual-verifier ## Query First — MCP Integration Before 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`](../sageing/references/mcp-query-patterns.md).