Skip to main content
Status: Accepted Date: 2026-05-25 Participants: Jeremy Bloom (project owner) Supersedes: ADR-016, ADR-017 Related: ADR-008, ADR-010, ADR-013, constitution §1

​
Context

Two related pieces of forward-looking scaffolding were added on 2026-04-22 (PR #137/#138 follow-ups) and never activated:
  1. Workspace-packages overlay (ADR-016). Empty packages/core-*, packages/platform, and packages/shared stubs — package.json files only, with an encoreos.sourceDirectory pointer back to src/. No source was moved. A metadata-layer audit (scripts/audit/audit-package-boundaries.ts, npm audit:package-boundaries, CI gate in build.yml) enforced the declared dependency graph, and scripts/dev/generate-core-package-jsons.mjs regenerated the stubs.
  2. Microfrontends overlay (ADR-017). A root microfrontends.json routing map plus empty packages/encoreos-app / packages/encoreos-public placeholders, a validation script (scripts/audit/validate-microfrontends-config.ts, npm audit:microfrontends), a runbook, and an activation checklist. The scaffolding commit was explicitly titled “Vercel Microfrontends scaffolding (inert until activation).”

​
Evidence both overlays are inert (gathered 2026-05-25)

  • Zero @encoreos/* imports anywhere in src/, tests/, or tools/. The app resolves everything through the @/ path alias (tsconfig.app.json, vite.config.ts). The workspace package names are never consumed.
  • Turborepo tasks are all root-scoped (//#…); no workspace package is a build target.
  • vercel.json contains no microfrontends/app/public configuration. The @vercel/microfrontends dependency is not installed. The vite plugin is “intentionally absent” (comment-only).
  • ADR-017 status was Proposed (“becomes Accepted on Phase 3 activation”); the activation checklist never ran.
The overlays therefore add cognitive load — confusing packages/ tree, near-identical boilerplate, two extra audit gates, a routing file, a runbook — while having no runtime or build effect today.

​
Decision

Remove both overlays and return to the single-app monolith of record:
  • Delete packages/core-*, packages/platform, packages/shared, packages/encoreos-app, packages/encoreos-public, and the orphaned packages/encore-spec (which had only a stray node_modules/). Keep packages/docs (the real Docusaurus site).
  • Delete microfrontends.json and its validator (scripts/audit/validate-microfrontends-config.ts, npm audit:microfrontends).
  • Delete scripts/audit/audit-package-boundaries.ts, scripts/dev/generate-core-package-jsons.mjs, the npm scripts audit:package-boundaries / packages:regenerate-cores, and the audit:package-boundaries step in .github/workflows/build.yml.
  • Prune the removed members from the root package.json workspaces array.
  • Remove the now-orphaned docs (WORKSPACE_PACKAGES.md, MICROFRONTENDS_RUNBOOK.md, MICROFRONTENDS_ACTIVATION_CHECKLIST.md) and their docs.json nav entries; clean the microfrontends activation comments from vite.config.ts.
Architecture boundaries remain enforced by the import-scan layer (check-architecture), which was always the primary gate; only the redundant package-metadata layer is retired.

​
Consequences

Positive
  • packages/ shrinks to the one real package (docs); the confusing empty-stub tree is gone.
  • Two CI/audit gates and their scripts retire; the dependency graph is enforced by the import-scan that already runs.
  • No more “why are these packages empty?” onboarding friction.
Negative / accepted
  • The metadata-layer boundary check (a second enforcement layer over import-scan) is gone. Acceptable: it never caught anything import-scan didn’t, and nothing imported the packages.
  • A future modular/microfrontends migration starts clean rather than from this scaffolding. Git history (this ADR + ADR-016/017 + the original commits) preserves the prior design for revival.

​
References

  • Supersedes ADR-016, ADR-017
  • Cleanup design: docs/superpowers/specs/2026-05-25-scripts-packages-cleanup-design.md
  • Cleanup plan: docs/archive/superpowers-plans-2026-05/2026-05-25-scripts-packages-cleanup.md