Skip to content

v1.8.0 ·

A site that runs the lifecycle, and a doctor for the repo

The problem

The AIDLC website was a Vite + React SPA with a generic indigo-on-Tailwind look, living in the monorepo as the aidlc-web package. It documented the framework but did not sell it — nothing about it communicated that AIDLC is a serious product. The ambition had changed: this needed to be a killer website, and in the near future the site — and possibly AIDLC itself — may become its own product. A docs-shaped afterthought could not carry that. The site had to be rebuilt as a product-grade experience with a distinctive visual identity, on infrastructure the owner controls: an AWS account of his own, via Amplify, at aidlc.rodrigoasensio.com.

The same release carried a second, unrelated piece of work. aidlc update had accumulated an installer seam that quietly did repo hygiene as a side effect — writing nested .gitignore files, clearing expired ephemera, untracking cost files that should never have been committed. That work was real and necessary, but it was invisible, bundled into a command whose name promised something else, and impossible to run on its own or preview before it acted.

How it could be solved

Option A — Incremental retheme of the existing Vite SPA

Keep the existing web package, swap the token layer, restyle the components.

  • ✅ Smallest effort; no framework migration.
  • ❌ Rejected: keeps the SPA architecture, so there is no static-generation or SEO story; keeps the docs-site information architecture; and cannot deliver the product-experience ambition.

Option B — New Next.js package in the monorepo, rethought from scratch ✅ CHOSEN

A new packages/website on Next.js and Tailwind, with a cyber-terminal theme and an information architecture designed fresh — every existing feature has to re-earn its place. Static-first, deployed on Amplify.

  • ✅ Meets the ambition; keeps the content package on a workspace dependency, so docs read from the real source of truth; extracting the site to its own repo later stays cheap.
  • ❌ Larger build, and a feature-regression window until the new site reaches the old one's useful surface.

Option C — Standalone repo from day one

  • ✅ Cleanest "own product" story.
  • ❌ Deferred: every content change would need an npm publish round-trip, and there would be two repositories to maintain before the product hypothesis is even validated. Worth revisiting at the product pivot.

On the repo-hygiene half: a new command rather than more hidden behavior

For the aidlc doctor side of this release the question was narrower — whether hygiene work should keep living inside aidlc update or become something you can name and run. It became its own command, with a two-tier model: safe checks apply themselves, while anything that touches the git index is gated behind a confirmation, --yes, or a --dry-run preview. The deciding argument was that a repair you cannot preview is a repair you cannot trust, and update gave no way to ask what it was about to do.

How AIDLC solves it

nextjs-website-revamp

A real product site for AIDLC at aidlc.rodrigoasensio.com — replacing the old Vite SPA with a Next.js 16 static export on AWS Amplify, and then retiring the old one entirely.

The site explains the framework by running it. The home page hero is a lifecycle simulator: it steps a canned full-feature run and a bugfix run through themed terminal frames, showing the state YAML and gate results at each phase. It works without JavaScript — the server-rendered markup is frame zero with the controls disabled — so the thing that demonstrates the product is not gated behind a bundle.

The documentation derives itself from the source of truth rather than restating it. Docs pages load the @rasensio/aidlc-content package directly at build time, so templates, skills, and guidance layers are read from the shipped content rather than transcribed. Phases are derived from template phase lists and skill metadata. The CLI reference is generated by walking the built CLI's recursive --help across all 16 top-level commands, including dynamically registered subcommands — so a command that exists but is undocumented becomes a build failure rather than a stale page.

The drift check became a real gate. Rewritten to verify reference freshness by regenerating and comparing, plus the version literal, the Node engine floor across the site and both READMEs, and contract tokens in page prose. It caught a real error during implementation: the page claimed Node 18 when engines said 22.13.

Search, metadata, and analytics. A prebuild step emits a 69-record search index that gzips to 2.8 KB against a 100 KB budget, lazy-loaded on first focus with a proper combobox keyboard pattern. Per-page metadata, a sitemap, robots, a themed 404. Google Analytics is env-gated — with no measurement ID the build emits zero GA bytes, verified against real output rather than assumed.

The theme is ported verbatim, not reinvented — a token layer carried over from rodrigoasensio-v2 with an explicit pre-paint script so a stored light preference wins over OS dark, and scanline, grid, cursor-blink, and gradient effects that all respect prefers-reduced-motion.

Deployed as a fully static export on Amplify behind a custom domain with CSP, nosniff, and Referrer-Policy headers. Lighthouse on mobile emulation against the deployed URL: 97 performance, 96 accessibility, 100 best practices, 100 SEO on both the home page and the CLI reference.

The cutover deleted 11 MB of the old site — the retired web package, its Vercel config, and the Vercel project link — repointed every canonical reference, and left the full suite green at 1486 tests with the drift check passing in a tree where the old package no longer exists.

update-spring-clean

aidlc doctor — a command that checks and repairs repo hygiene, and says what it is about to do before it does it.

The work it does was not new; it was hidden. aidlc update had accumulated an installer seam that quietly wrote nested .gitignore files, cleared expired ephemera, and untracked cost files that should never have been committed — real maintenance, bundled into a command whose name promised something else, with no way to preview it or run it alone.

Doctor replaces that seam with a registry of migrations, each one a check-and-apply pair that is safe to run repeatedly because it tests state rather than assuming it. Ten shipped in v1: gitignore coverage for the cost and knowledge directories, nested gitignore installation, the merge=union gitattributes for state logs, shipped-action installation, pruning of stale registry entries, session stashes, and cost locks, and untracking committed cost ephemera.

The design decision that matters is two tiers. Safe migrations apply themselves — writing an ignore file harms nothing. Anything that touches the git index waits for a confirmation, --yes, or a --dry-run preview, and in a non-interactive session it declines to act and prints the exact command instead of guessing. A repair you cannot preview is a repair you cannot trust.

aidlc update now runs the doctor pass instead of carrying its own installer, so the behavior users already relied on is preserved while becoming inspectable. The two commands differ in one deliberate way: doctor exits non-zero when confirm-tier work is still pending, so CI can fail on an unhealthy repo, while update never fails for hygiene reasons.

Self-hosted on this repository at release time, it wrote two missing .gitignore files and correctly reported 16 committed cost files pending untrack — declining to act, since the session was non-interactive, and naming the command to finish the job.

Shipped as v1.8.0 in both packages, which move in lockstep: the CLI carried the doctor module and command, the update integration, and read-half refactors across sessions, recorder, registry, claim-store, gitattributes, and shipped-actions; the content package had no changes this cycle and rode along per release policy.