Architecture discovery

Skill hekivo/superpowers-sage/skills/architecture-discovery

Architecture discovery for Sage/Acorn projects — map existing codebase, discover post types, routes, ACF field groups, Livewire components, Service Providers, identify architectural gaps, architecture decision records, ADR, component boundary map, data flow diagram, risk register, implementation sequencing, discovery session, understanding unknown codebases, use before architecting or building new features, output contract, discover-abilitiesFrom its SKILL.md

Install

npx -y skills add hekivo/superpowers-sage --skill architecture-discovery

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, as published. Nobody here has run it

Architecture Discovery

Design-first architecture workflow for WordPress + Sage + Acorn + Lando projects.

Announce at start: "I'm using architecture-discovery to produce an approved architecture spec before any implementation plan."

Input

$ARGUMENTS

HARD GATES

Never write implementation code in this skill.
Never invoke superpowers-sage:building before architecture approval and plan generation.
Never skip section-by-section approval.

Procedure (summary)

Full step-by-step procedures for each phase are in references/discovery-procedures.md.

Branch & scope — ensure feature branch exists, normalize scope in one sentence.
Explore context — read config/poet.php, existing blocks, providers, active plans.
Clarifying questions — gather requirements one at a time (UX, editor, integrations, constraints).
Identify components — list with responsibility, inputs/outputs, dependencies, risks.
Parallel probes — dispatch content-modeler, design-extractor (PANORAMIC), sage-reviewer in parallel; synthesize.
Propose approaches — 2-3 options with trade-offs; ask user to choose. Apply AD-2 preset if porting legacy schemas.
Decision graph — classify tasks as parallel/sequential/gated.
Section: Overview — present + ask approval.
Section: Components & data flow — present + ask approval.
Section: Quality strategy — present + ask approval.
Write spec — docs/superpowers/specs/YYYY-MM-DD-<topic>-architecture.md. Commit.
Spec review loop — dispatch sage-reviewer up to 3 times; escalate on persistent failure.
User approval gate — revise until approved.
Handoff — prepare handoff payload; invoke superpowers-sage:plan-generator.

For detailed procedure steps and the AD-2 preset block, read skills/architecture-discovery/references/discovery-procedures.md.

Output Contract

Full output artifact specifications are in references/output-contract.md.

Required outputs:

Approved architecture spec at docs/superpowers/specs/YYYY-MM-DD-<topic>-architecture.md
Review feedback resolved or explicitly waived
Complete handoff payload for superpowers-sage:plan-generator

For spec template and handoff payload format, read skills/architecture-discovery/references/output-contract.md.

Verification

Before completion, confirm all items:

Spec file exists at docs/superpowers/specs/YYYY-MM-DD-<topic>-architecture.md
Spec has user approval recorded in conversation
At least one reviewer loop executed (or explicit user waiver)
Handoff payload is complete and unambiguous

Failure modes

No design reference available: proceed text-first, mark visual assumptions explicitly.
Scope too broad: decompose into sub-projects and complete first sub-scope only.
Repeated reviewer failures: escalate after 3 attempts.
Missing content model signal: re-run superpowers-sage:content-modeler before finalizing spec.