# Superpowers Sage: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-abilities

- Skill: `hekivo/superpowers-sage-architecture-discovery` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add hekivo/superpowers-sage-architecture-discovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hekivo/superpowers-sage-architecture-discovery/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-architecture-discovery

---


# 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`.

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