Workspace

Problem

Most personal engineering sites are built once and left static — a resume rendered as HTML, updated rarely, with no real process behind the pages beyond “add a project, ship it.” I wanted something that behaved like an actual engineering product: planned before it was built, with every architectural decision recorded and justified, not just implemented and forgotten.

Approach

Workspace follows a strict documentation-first workflow: vision and roadmap first, then Architectural Decision Records for anything foundational (rendering stack, theming model, navigation architecture), then per-surface specifications derived from those decisions, and only then implementation. Nothing gets built before it’s been decided and written down — and every decision that changes later gets a new, superseding record rather than a silently edited one. As of this writing, that’s 5 accepted ADRs and 10 specifications governing a site with three primary surfaces.

The site itself is Astro-based with Svelte islands for the handful of things that need real interactivity (a command palette, a theme switcher, search), content modeled as typed Markdown/MDX collections validated by Zod schemas, and a build-time content linter enforcing structural rules schemas can’t express — mandatory narrative sections, singleton content caps, architecture-diagram requirements. Development was AI-assisted throughout, but every non-trivial architectural choice was proposed, reviewed, and only then written into a decision record before any code followed it.

Tradeoffs

Documentation-first has a real cost: every new surface or feature (a command palette, a color scheme system, pagination) started with a planning session before a line of code was written, which is slower than just building. The payoff came on the second and third pass — retrofitting a color-scheme system onto tokens that were designed for exactly that swap, or adding search without touching either surface’s content model, cost far less than it would have on a codebase built ad hoc.

The other tradeoff is scope discipline: several ideas (a fourth base palette, an OS-window aesthetic, a public activity feed) were deliberately rejected or reversed once built, specifically because the site’s own guiding principle is that the development-environment metaphor is an accent, never the backbone. Saying no to those ideas, in writing, mattered as much as saying yes to the ones that shipped.

Architecture

The Application Shell owns navigation and layout for three primary surfaces, each built on the same content foundation and sharing a common infrastructure layer beneath them.

Outcome

A statically-built, content-driven site with three primary surfaces, build-time search and GitHub data fetching, a working theme system, and a documentation trail — vision, roadmap, decisions, and specs — that explains every structural choice on its own, without needing this write-up to make sense of it. The repository is public as a template: the same structure, stripped of personal content, that anyone can clone and fill in with their own identity.