TenantAtlas/specs/223-astrodeck-website-rebuild/quickstart.md

Quickstart: Website Reset and AstroDeck Rebuild

This quickstart describes how to execute Spec 223 after planning is approved.

Prerequisites

• Work on branch 223-astrodeck-website-rebuild or a follow-up branch derived from it.
• Keep the existing apps/website codebase available for comparison until legacy-task disposition and current-site inventory are complete.
• Obtain the AstroDeck source snapshot that will act as the new substrate. It does not need to be committed yet, but it must be available for inventory and mapping.

Step 1: Capture the current website inventory

Inspect the current website surface before replacing anything.

• Record every current route under apps/website/src/pages.
• Record current component families under apps/website/src/components.
• Record content-backed sources from apps/website/src/content and apps/website/src/content.config.ts.
• Record current smoke coverage under apps/website/tests/smoke so follow-up rebuild work preserves intentional route and guardrail coverage.

Step 2: Capture the AstroDeck inventory

Create a reviewable inventory of the imported AstroDeck source.

• List AstroDeck pages.
• List AstroDeck sections.
• List AstroDeck components.
• Flag demo-only copy, media, and CTA behavior that will require adaptation or removal.

Step 3: Classify the governing website specs

Classify the current website spec set before touching implementation tasks.

• Evaluate Specs 213, 214, 215, 217, and 218.
• Mark each as continuing, partially valid, or superseded.
• Record why the classification was chosen.
• Record the scopeSummary for each classified spec.
• Record the followUpPlan path for each classified spec so the owning per-spec mapping artifact or explicit supersession-closure artifact is visible immediately.
• If Spec 213 remains continuing or partially valid, assign it its own dedicated rebuild-plan artifact instead of folding it into the 214-218 slices.

Step 4: Mark legacy implementation tasks as superseded

Do not reopen or reset legacy tasks.

• Preserve the old task history.
• Mark implementation tasks tied to the discarded website with the canonical historical marker superseded by AstroDeck rebuild.
• Point each superseded task to the new follow-up plan or task list, or record the explicit statement no replacement work required.

Step 5: Build per-spec AstroDeck mappings

For each continuing or partially valid website spec:

• Identify candidate AstroDeck pages, sections, and components.
• Decide keep, adapt, remove, or exception for each relevant primitive.
• Capture required adaptation to routes, content slots, styling, CTA logic, and trust/legal behavior.
• Record acceptance mapping back to the governing spec.
• Author the replacement task list inside the same per-spec mapping or disposition artifact so forward delivery ownership is explicit before implementation begins.
• Name each replacement task by the relevant AstroDeck page, section, component, or mapping activity rather than using generic build verbs.
• Give Spec 213 its own mapping or explicit supersession-closure artifact depending on the classification outcome.

Step 6: Record exceptions only when the primitive search fails

Custom work is the exception path.

• Search AstroDeck first.
• Treat a primitive as adequate only when keep or bounded adaptation can satisfy the requirement without introducing a net-new IA contract or unsupported interaction model.
• Record every missing-candidate review in the exception register as either approved exception or no exception required.
• If no adequate primitive exists, capture the documented exception record in exception-register.md with the failed adequacy rationale and named approver.
• Bound the exception to one page, section, or component slice.

Step 7: Record material drift as explicit spec work

AstroDeck adoption must not silently change website truth.

• Log any material page inventory, CTA logic, navigation, or trust messaging drift.
• Update the affected existing website spec or create a named follow-up website spec.
• Link the drift record to the mapping artifact that exposed it.

Step 8: Record cross-spec execution order for the follow-up tasks

After the per-spec artifacts already contain their embedded replacement task lists or supersession closures, record the cross-spec execution order in this sequence:

1. AstroDeck intake binding and primitive verification using astrodeck-source-intake.md and astrodeck-primitive-inventory.md
2. Conditional Spec 213 disposition-or-mapping slice in mappings/spec-213-website-foundation-v0.md
3. Spec 214 visual-adaptation slice in mappings/spec-214-website-visual-foundation.md
4. Spec 215 IA and route-mapping slice in mappings/spec-215-website-core-pages.md
5. Spec 217 homepage section-composition slice in mappings/spec-217-homepage-structure.md
6. Spec 218 homepage hero-refinement slice in mappings/spec-218-homepage-hero.md

Each per-spec mapping or disposition artifact should already contain its replacement task list or explicit supersession closure before this cross-spec execution order is recorded.

Step 9: Begin implementation only after the planning artifacts are complete

Implementation should start only when:

• every current website surface has a disposition
• every continuing or partially valid website spec has a mapping artifact
• legacy tasks are marked superseded
• every material drift item points to an updated or follow-up website spec
• any custom primitive has an approved exception record

Validation

This planning slice does not require runtime validation. Follow-up implementation slices should use:

• corepack pnpm build:website
• cd apps/website && corepack pnpm exec playwright test

Expected Outputs

• A current-site inventory for apps/website
• An AstroDeck source-intake record
• An AstroDeck primitive inventory
• A classification of Specs 213, 214, 215, 217, and 218
• Superseded legacy-task records
• Per-spec AstroDeck mappings and embedded replacement task lists or explicit supersession closures, including the conditional Spec 213 artifact
• Material-drift follow-up records tied to updated or follow-up website specs
• An exception register with approved-exception and no-exception outcomes
• Exception records only where AstroDeck cannot satisfy an active requirement