119 lines
6.2 KiB
Markdown
119 lines
6.2 KiB
Markdown
# 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
|