192 lines
13 KiB
Markdown
192 lines
13 KiB
Markdown
# Implementation Plan: Website Reset and AstroDeck Rebuild
|
|
|
|
**Branch**: `223-astrodeck-website-rebuild` | **Date**: 2026-04-22 | **Spec**: [spec.md](spec.md)
|
|
**Input**: Feature specification from `/specs/223-astrodeck-website-rebuild/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.
|
|
|
|
## Summary
|
|
|
|
This plan turns Spec 223 into a documentation-first rebuild workflow for `apps/website`. The primary requirement is to discard the current website implementation as the forward substrate while preserving the validity of continuing website specs and the history of legacy implementation tasks.
|
|
|
|
The technical approach is:
|
|
1. Confirm the current website is a standalone Astro 6 static app with file-based routes, content collections, and Playwright smoke coverage.
|
|
2. Treat AstroDeck as an external template source that must be inventoried before any rebuild mapping or custom work starts.
|
|
3. Model the rebuild with file-based planning artifacts only: current-site inventory, AstroDeck source intake, AstroDeck primitive inventory, website-spec classification, per-spec mapping or supersession-closure records, superseded legacy-task treatment, material-drift follow-up, and an exception register with review outcomes plus embedded approved exception records.
|
|
4. Hand off follow-up task planning as an inventory-first slice, a conditional Spec 213 disposition-or-mapping slice, and per-spec mapping slices for the continuing website specs, with each per-spec mapping artifact owning its embedded replacement task list and explicit spec-update follow-up when mapping reveals material page inventory, CTA logic, navigation, or trust messaging drift.
|
|
|
|
## Phases & Checkpoints
|
|
|
|
### Phase 0 - Research & Scope Lock
|
|
|
|
- Done when the current `apps/website` substrate, AstroDeck availability, route drift, and planning-artifact contract are documented in [research.md](research.md).
|
|
- Done when no Technical Context field remains unresolved.
|
|
|
|
### Phase 1 - Design Artifacts
|
|
|
|
- Done when [data-model.md](data-model.md), [contracts/rebuild-planning-artifacts.yaml](contracts/rebuild-planning-artifacts.yaml), and [quickstart.md](quickstart.md) define the inventory, classification, mapping, superseded-task, and exception workflow.
|
|
- Done when the Constitution Check is re-run post-design and still passes without introducing runtime or platform obligations.
|
|
|
|
### Phase 2 - Task Planning Handoff
|
|
|
|
- Done when `/speckit.tasks` can generate a task set that starts with AstroDeck inventory, keeps a conditional dedicated path for Spec 213, and then splits into per-spec mapping slices for Specs 214, 215, 217, and 218.
|
|
- Done when legacy-task superseded handling and exception boundaries are explicit enough that task generation cannot silently fall back to greenfield rebuild work.
|
|
|
|
## Final Follow-up Execution Order
|
|
|
|
1. Bind the mounted AstroDeck snapshot to the aliases in `astrodeck-source-intake.md` and `astrodeck-primitive-inventory.md`.
|
|
2. Execute the conditional foundation slice in `mappings/spec-213-website-foundation-v0.md`.
|
|
3. Execute the shared visual-adaptation slice in `mappings/spec-214-website-visual-foundation.md`.
|
|
4. Execute the canonical IA and route-mapping slice in `mappings/spec-215-website-core-pages.md`.
|
|
5. Execute the homepage section-composition slice in `mappings/spec-217-homepage-structure.md`.
|
|
6. Execute the homepage hero-refinement slice in `mappings/spec-218-homepage-hero.md`.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: TypeScript 5.9, Astro 6, Node.js 20+
|
|
**Primary Dependencies**: Astro, astro-icon, Tailwind CSS v4, Playwright 1.59
|
|
**Storage**: File-based route files, Astro content collections under `src/content`, public assets, and planning documents under `specs/223-astrodeck-website-rebuild`; no database
|
|
**Testing**: Static build plus Playwright smoke tests in `apps/website/tests/smoke` for follow-up implementation slices; this planning slice itself is documentation-only
|
|
**Validation Lanes**: N/A for this planning slice; fast-feedback for follow-up website implementation (`corepack pnpm build:website`, `cd apps/website && corepack pnpm exec playwright test`)
|
|
**Target Platform**: Static public website served from the Astro app in `apps/website`
|
|
**Project Type**: Monorepo web application with a standalone Astro website app
|
|
**Performance Goals**: No new runtime goal in this planning-only slice; follow-up rebuild work must preserve static-site buildability and smoke-testable route rendering across the current public route family
|
|
**Constraints**: Strictly local to `apps/website`; AstroDeck-first inventory and mapping; legacy tasks remain visible as superseded history; no default greenfield work; no platform or Filament coupling
|
|
**Scale/Scope**: Current website scope covers 12 public route files, 5 governing website specs (213, 214, 215, 217, 218), component families under `src/components/{primitives,sections,content,layout}`, and file-based content collections for articles, changelog, and resources
|
|
|
|
## UI / Surface Guardrail Plan
|
|
|
|
- **Guardrail scope**: no operator-facing surface change
|
|
- **Native vs custom classification summary**: N/A
|
|
- **Shared-family relevance**: none
|
|
- **State layers in scope**: none
|
|
- **Handling modes by drift class or surface**: report-only
|
|
- **Repository-signal treatment**: review-mandatory for follow-up inventory and mapping artifacts; no runtime hard-stop in this slice
|
|
- **Special surface test profiles**: N/A
|
|
- **Required tests or manual smoke**: N/A for this planning slice; follow-up implementation slices must use browser smoke plus static build proof
|
|
- **Exception path and spread control**: one named exception boundary only, for non-AstroDeck primitives that fail the mapping search and meet the documented exception rule
|
|
- **Active feature PR close-out entry**: N/A
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- [X] **Inventory-first / snapshots / Graph contract / deterministic capabilities / run observability / automation**: N/A. This slice introduces no runtime inventory model, no Graph calls, no queued work, and no `OperationRun`.
|
|
- [X] **Scope / ownership / workspace and tenant isolation / RBAC / operator-surface rules**: N/A. The work is repository-local to `apps/website` and does not touch `/admin`, `/system`, tenant scope, or platform permissions.
|
|
- [X] **Proportionality / no premature abstraction / few layers**: Pass. All outputs remain file-based design artifacts; no runtime registries, DTO layers, or persisted models are introduced.
|
|
- [X] **LEAN-001**: Pass. The discarded website implementation is replaced rather than preserved through compatibility shims or legacy aliases.
|
|
- [X] **TEST-GOV-001**: Pass. This slice is explicitly docs-only, states `N/A` for runtime proof, and pushes build/browser proof to follow-up implementation specs.
|
|
- [X] **UI-FIL / BADGE / UX-001 / action-surface / naming / opsurface rules**: N/A. No Filament or operator-facing UI changes are planned in this slice.
|
|
|
|
## Test Governance Check
|
|
|
|
- **Test purpose / classification by changed surface**: N/A
|
|
- **Affected validation lanes**: N/A
|
|
- **Why this lane mix is the narrowest sufficient proof**: This slice only produces planning artifacts and does not change runtime behavior.
|
|
- **Narrowest proving command(s)**: N/A
|
|
- **Fixture / helper / factory / seed / context cost risks**: none
|
|
- **Expensive defaults or shared helper growth introduced?**: no
|
|
- **Heavy-family additions, promotions, or visibility changes**: none
|
|
- **Surface-class relief / special coverage rule**: N/A
|
|
- **Closing validation and reviewer handoff**: Reviewers should inspect the generated planning artifacts for completeness, continuity with Spec 223, and explicit follow-up validation ownership.
|
|
- **Budget / baseline / trend follow-up**: none
|
|
- **Review-stop questions**: lane fit, hidden runtime claims, accidental platform coupling
|
|
- **Escalation path**: none
|
|
- **Active feature PR close-out entry**: N/A
|
|
- **Why no dedicated follow-up spec is needed**: This slice already exists to define the reset and planning contract; follow-up implementation proof belongs in the subsequent mapping specs and task plans.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation & Planning Artifacts (this feature)
|
|
|
|
```text
|
|
specs/223-astrodeck-website-rebuild/
|
|
├── current-website-inventory.md
|
|
├── astrodeck-source-intake.md
|
|
├── astrodeck-primitive-inventory.md
|
|
├── governing-website-spec-classification.md
|
|
├── legacy-task-disposition.md
|
|
├── exception-register.md
|
|
├── material-drift-follow-up.md
|
|
├── mappings/
|
|
│ ├── spec-213-website-foundation-v0.md
|
|
│ ├── spec-214-website-visual-foundation.md
|
|
│ ├── spec-215-website-core-pages.md
|
|
│ ├── spec-217-homepage-structure.md
|
|
│ └── spec-218-homepage-hero.md
|
|
├── plan.md
|
|
├── research.md
|
|
├── data-model.md
|
|
├── quickstart.md
|
|
├── contracts/
|
|
│ └── rebuild-planning-artifacts.yaml
|
|
└── tasks.md
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
apps/website/
|
|
├── astro.config.mjs
|
|
├── package.json
|
|
├── playwright.config.ts
|
|
├── src/
|
|
│ ├── content.config.ts
|
|
│ ├── components/
|
|
│ │ ├── content/
|
|
│ │ ├── layout/
|
|
│ │ ├── primitives/
|
|
│ │ └── sections/
|
|
│ ├── content/
|
|
│ │ ├── articles/
|
|
│ │ ├── changelog/
|
|
│ │ ├── pages/
|
|
│ │ └── resources/
|
|
│ ├── layouts/
|
|
│ ├── lib/
|
|
│ ├── pages/
|
|
│ │ ├── index.astro
|
|
│ │ ├── product.astro
|
|
│ │ ├── trust.astro
|
|
│ │ ├── changelog.astro
|
|
│ │ ├── contact.astro
|
|
│ │ ├── privacy.astro
|
|
│ │ ├── imprint.astro
|
|
│ │ ├── terms.astro
|
|
│ │ ├── solutions.astro
|
|
│ │ ├── integrations.astro
|
|
│ │ ├── legal.astro
|
|
│ │ └── security-trust.astro
|
|
│ └── styles/
|
|
└── tests/
|
|
└── smoke/
|
|
├── home-product.spec.ts
|
|
├── solutions-trust-integrations.spec.ts
|
|
├── changelog-core-ia.spec.ts
|
|
├── contact-legal.spec.ts
|
|
└── visual-foundation-guardrails.spec.ts
|
|
```
|
|
|
|
**Structure Decision**: Use the existing monorepo structure as-is. This plan is centered on `apps/website` and the planning artifacts under `specs/223-astrodeck-website-rebuild`, with only bounded traceability updates to the referenced 213/214/215/217/218 spec or task files when legacy-task supersession or material-drift follow-up requires them. No new runtime packages, shared libraries, or platform directories are introduced. The per-spec mapping or disposition files are also the forward-looking rebuild-plan artifacts: they embed the replacement task list or explicit supersession closure instead of spawning separate per-spec `tasks.md` files in this slice.
|
|
|
|
## Complexity Tracking
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| none | N/A | N/A |
|
|
|
|
## Proportionality Review
|
|
|
|
- **Current operator problem**: Website contributors and reviewers need one explicit rebuild contract so they can discard the current implementation without losing continuing website truth or legacy task history.
|
|
- **Existing structure is insufficient because**: The current website specs define public-surface intent, but they do not specify how a full substrate change should preserve those decisions, reconcile current routes, and prevent silent greenfield rebuilding.
|
|
- **Narrowest correct implementation**: File-based artifacts only: research, data model, contracts, quickstart, inventories, classifications, mapping sheets, superseded-task handling, material-drift follow-up, and exception boundaries.
|
|
- **Ownership cost created**: Ongoing maintenance of a planning vocabulary for current-site inventory, AstroDeck primitive inventory, spec classification, mapping records, legacy-task disposition, and bounded exceptions.
|
|
- **Alternative intentionally rejected**: A code-first template import or a single monolithic rebuild task list was rejected because both would hide the strategy shift and collapse inventory, classification, and mapping into one opaque step.
|
|
- **Release truth**: Current-release truth for the public website rebuild; not future platform preparation.
|
|
|
|
## Post-Design Constitution Check
|
|
|
|
- [X] Post-design gate still passes: artifacts remain file-based and local to `apps/website`.
|
|
- [X] No runtime, platform, RBAC, Filament, or operator-surface obligations were introduced during design.
|
|
- [X] Follow-up implementation responsibility is explicit: inventory first, mapping second, tasks third, build/browser proof in later slices.
|