Multi-stack support — React/React Native now (Stage 1), any detected stack via L2 research (Stage 2)

[artyhoo]

Summary

The framework's promise is "generate enforcement rules from principles, not copy-pasted presets" (README "Methodology"), but it currently ships one preset — preset-next-15-canonical — and install.sh only accepts ts-server / react-next. This issue tracks making the one-button install configure the full enforcement perimeter (rules-as-tests + mutation + arch boundaries + hooks/CI + docs/skills/agents) for more stacks, in two stages:

• Stage 1 (curated bridge): add react (SPA) and react-native (Expo/RN) presets by hand. Cheap relative to Stage 2, not zero — includes de-Next-ifying shared templates (eslint.config.react.mjs currently pulls @next/eslint-plugin-next).
• Stage 2 (general): realize the deferred L2 LLM-driven research path so an arbitrary detected stack is researched → synthesized → self-validated → installed, removing the per-stack hand-authoring bottleneck — without weakening "documents lie; tests don't".

Why it's Next-only today (grounded)

• The engine is already stack-agnostic: synthesizer/synthesize.ts is a pure ResearchPlan → SynthesisPlan function, recipes filtered by an appliesTo: string[] framework key. The detector already generalizes (packages/core/detector/ emits stack + version + missing[] for any project; does not assume Next).
• The content is Next-only: synthesizer/recipes/ has 5 files, all next-* / nextjs-*; only preset package is packages/preset-next-15-canonical/. Its 3 ESLint rules are Next-specific (RSC server/client boundary + server actions).
• The research layer (L2) was pivoted to deterministic-curated in Phase 5 — no live LLM/HTTP at runtime (retros/phase-5.md:14-19). LLM-driven research is the documented future superset, deferred to a v2 trigger (retros/phase-5.md:81,151); the v2 contract (Anthropic web_search + allowed_domains) is already stubbed as a static allowlist (:19,73).
• Stack-agnostic core already applies to any TS project: no-direct-time-randomness, no-unsafe-zod-parse, require-otel-span (packages/core/eslint-rules/).

So "more stacks" is blocked on rule content, not the pipeline.

Stage 1 — curated react and react-native presets

Presets

• packages/preset-react-spa/ — React 19 SPA on Vite (no SSR / server actions).
• packages/preset-react-native/ — Expo / React Native.

Mirror the preset-next-15-canonical layout: eslint-rules/, templates/ (eslint config, test-runner config, ARCHITECTURE.*.md, CI workflow), RULES.*.md, audit-self/.

Installer wiring

• Accept react / react-native in the arg parser (install.sh:81) and stack guard (:189).
• Add menu options 3) react / 4) react-native (install.sh:177-190).
• Extend auto-detect: react-native/expo in deps → react-native; react-dom present and next absent → react; else existing fallback.

Rules — REUSE first (per build-first-reuse-default.md)

• React SPA: ADOPT eslint-plugin-react, eslint-plugin-react-hooks (exhaustive-deps), eslint-plugin-jsx-a11y (already in the dev-dep list). BUILD only gap rules, candidates: no-business-logic-in-component (via dependency-cruiser layer boundary), require-error-boundary.
• React Native: BUILD where no upstream analog fits — no-web-only-globals (flag document/window/localStorage/DOM in RN), require-stylesheet-create, prefer-flashlist-over-flatlist. Each ships a paired valid/invalid test (principle 02).
• REFERENCE existing ecosystem skills instead of re-deriving RN best practices: react-native-best-practices, building-native-ui, vercel-react-native-skills, treemap-rn.
• Prior-art SSOT is empty for these plugins — no eslint-plugin-react/react-native entries in prior-art-evaluations.md today. The BUILD candidates above are hypotheses pending a per-preset R-phase (DeepWiki/WebSearch ≥3 phrasings + SSOT consult), not approved builds. Stage 1 adds the ADOPT/BUILD verdict entries as an explicit deliverable (each rule is a capability commit).

These two presets also serve as the proving cases for Stage 2's generate path.

Stage 2 — any detected stack (L2 LLM research path / v2)

L2 Research Agent — LLM path (Planner, read-only)

Implement the live path behind the existing L2 interface (packages/core/research/): given {stack, version, missing[]} from the detector, produce a versioned ResearchPlan (research-plan.schema.json) via Anthropic web_search constrained to allowed_domains. Planner is read-only — never writes files (keeps the L2/L3 prompt-injection firewall: untrusted fetched docs can't reach disk).

L3 Synthesizer — generalize beyond curated recipes

When no curated recipe matches a researched pattern, emit a candidate rule from the research plan as a structured, validated SynthesisPlan (never free-form LLM code). Curated recipes stay the deterministic fast-path/cache for known stacks (Next stays byte-stable).

L4 Self-validation gate — BUILD, then mandatory (tenet-preserving)

Every generated rule — curated or LLM-derived — must pass the principle gate before install: paired negative test (02), non-tautological (04), AST-over-grep where applicable (03), manifest-SSOT (05). A rule that can't fail against a synthetic violation fixture is dropped, not shipped. Determinism moves from "how the rule was authored" to "the rule provably fails when violated". Note: the L4 install-gate does not exist yet — retros/phase-5.md deferred the L4 Validator to "Phase 7+". Building it is an explicit Stage 2 deliverable, not a pre-existing mechanism this stage merely invokes.

Installer wiring — generic stack

• Detector result → curated preset if one exists, else the generate-and-validate flow.
• Generation is an explicit, consumer-side, opt-in step (--generate / AIF_RESEARCH=llm) run install-time on the consumer's own Claude subscription — never in CI, so no-paid-llm-in-ci.md is intact. The framework itself never bills: any cost is the consumer's own, incurred only on explicit opt-in.
• Cache the generated ResearchPlan + SynthesisPlan into .ai-factory/ so re-installs / --refresh are deterministic and reviewable (snapshot the artifact, not the generation).

Sequencing commitment (hybrid decision — added 2026-06-19)

Stage 1 is a bridge, not a terminus. To prevent it from stranding 3 hand-maintained presets (the "stale presets" failure README §Methodology warns of):

• On Stage 1 close (both presets merged) → the merging session writes docs/meta-factory/research-patches/<date>-phase-5-v2-trigger-fired.md (fires the deferred Phase-5 v2 trigger this issue already names) AND opens the Stage 2 tracking umbrella. Stage 2 is the mandatory immediately-following umbrella, not "someday".
• Until that patch lands, every hand-authored preset beyond Next is tracked debt against README §Methodology, not silent drift.

Design rationale: docs/superpowers/specs/2026-06-19-multi-stack-hybrid-design.md (hybrid A-now + B-committed, with full A-vs-B trade-off analysis).

Acceptance criteria

Stage 1:

• ./install.sh react --dry-run and ./install.sh react-native --dry-run complete with ✅ Dry-run complete, no ❌ Unknown stack.
• Fresh Vite-React and Expo repos install cleanly; lint / test / arch:check / test:mutation all run; at least one custom rule per stack catches its target antipattern.

Stage 2:

• ./install.sh --generate on a stack with no curated preset (e.g. SvelteKit, Vue SPA, Fastify-only) installs a stack-appropriate set; every generated rule has a passing/failing paired test; rules failing the L4 gate are reported and excluded.
• Next.js path stays byte-identical; re-install from cache is deterministic.

Both: make self-audit stays green (recursive self-application unbroken); auto-detect picks the right stack from package.json.

Conventions to honor (repo discipline)

• Each new preset/rule is a capability commit → prior-art consult (docs/meta-factory/prior-art-evaluations.md) + DeepWiki/WebSearch ≥3 phrasings + Prior-art: trailer (CLAUDE.md "Build-vs-reuse invariant"). Default per build-first-reuse-default.md: ADOPT upstream lint plugins; BUILD only genuine gaps + the research→synthesize→validate pipeline.
• New shipped docs (RULES.*.md, ARCHITECTURE.*.md) carry Authoritative for: headers and join SHIPPED_DOCS in install.sh (principle 09). New rules ship paired negative tests (principle 02), AST-over-grep where applicable (principle 03).
• Stage 2 must preserve the L2 (read-only Planner) / L3 (validated-output-only) prompt-injection split; LLM fetch constrained to allowed_domains. no-paid-llm-in-ci.md unchanged (research is install-time, not CI). Document Stage 2 as the firing of the deferred Phase-5 v2 trigger in a research-patch.

Risks / open questions

• LLM non-determinism → mitigated by L4 gate + caching the generated artifact; open: how to snapshot-test a path whose first run is variable (test the validator on fixtures, not raw generator output).
• Research quality for niche stacks → low-confidence stacks install only stack-agnostic core + flag "generated, review before trusting"; never claim full coverage.

---

_{Code claims in this issue verified against staging on 2026-06-19: install.sh:81 accepts only ts-server|react-next (guard :189-190, menu :179-184); synthesizer/recipes/ = 5 files, all next-*/nextjs-*; single packages/preset-next-15-canonical; 3 agnostic core rules in packages/core/eslint-rules/; L2 scaffolding present (packages/core/research/ incl. research-plan.schema.json, allowlist.ts, validate-plan.ts).}

[artyhoo]

Stage 1 progress — react-spa R-phase complete (2026-06-20)

Design resolved to hybrid (Stage 1 curated now + Stage 2 generate-path committed) — see docs/superpowers/specs/2026-06-19-multi-stack-hybrid-design.md.

react-spa rule prior-art R-phase done (docs/meta-factory/research-patches/2026-06-20-react-spa-rules-rphase.md, SSOT #136-141):

Candidate	Verdict	Note (corrects issue premise where flagged)
eslint-plugin-react / react-hooks v6 / jsx-a11y	ADOPT	own-stack backfill (already in next-15; SSOT had no rows)
React Compiler lint	ADOPT (folds into react-hooks v6)	eslint-plugin-react-compiler deprecated/merged into v6
no-business-logic-in-component	ADAPT, not BUILD	mostly REUSE of eslint-plugin-boundaries/dependency-cruiser; inline residue YAGNI until proven
require-error-boundary	T16 SPLIT	BUILD presence-rule (genuine gap) + ADOPT/REFERENCE eslint-react/error-boundaries usage-rule

Primary-React-plugin fork resolved → eslint-plugin-react (consistency with next-15 per dual-implementation-discipline; @eslint-react → WATCHLIST #141).

Caveat: DeepWiki MCP was down → WebSearch-grounded; B/C negative-existence claims are provisional-strong — DeepWiki re-probe required before B/C capability commits.

Next: react-native R-phase → I-phase per preset (writing-plans) → install.sh wiring → Stage 1 close fires the Phase-5 v2 trigger (opens Stage 2).

[artyhoo]

Stage 1 progress — react-native R-phase complete (2026-06-20)

react-native rule prior-art R-phase done (docs/meta-factory/research-patches/2026-06-20-react-native-rules-rphase.md, SSOT #142–#148) — PR #650 (supersedes #649; rebased after #648 merged). 26/26 CI green.

All three issue BUILD hypotheses → zero clean BUILDs (BFR-default outcome, mirrors react-spa):

Candidate (issue verdict)	R-phase verdict	Note
no-web-only-globals (BUILD)	ADAPT	REUSE no-restricted-globals + eslint-config-expo globals (window:false); BUILD-residue YAGNI
require-stylesheet-create (BUILD)	ADOPT	eslint-plugin-react-native/no-inline-styles
prefer-flashlist-over-flatlist (BUILD)	REJECT	no upstream rule; perf-opinion not correctness; 3-way landscape (FlatList/FlashList/LegendList); no-restricted-imports opt-in if wanted

ADOPT layer: eslint-config-expo (Expo baseline) · @react-native/eslint-config + @callstack/eslint-config (bare-RN) · eslint-plugin-react-native (RN style rules, WATCHLIST low-maint) · eslint-plugin-react-native-a11y (T16: RN a11y ≠ jsx-a11y — supersedes react-spa #138 for RN).

DeepWiki was UP (vs the react-spa sibling) → negative-existence claims source-repo-verified; discharges react-spa §5 open-item-1 in part.

Open fork for I-phase (DECISION-NEEDED, maintainer): preset scope = Expo-only / bare-RN / both? (selects A1 eslint-config-expo vs A2 baseline; researcher lean = Expo-first). Verdicts hold regardless.

Next: both Stage 1 R-phases done (react-spa #648 ✅ + react-native #650) → I-phase per preset (writing-plans) → install.sh wiring → Stage 1 close fires the Phase-5 v2 trigger (opens Stage 2).