v1.39.0 ·
A page for each task
The problem
The website teaches (tutorials) and lists facts (CLI, phases, templates, glossary). It has no page for "I want to do X — give me the steps." A user who already knows AIDLC and wants to, say, run two pieces of work at once has to find the answer inside a deep-dive chapter written to teach, not to be followed.
This serves a user of the product. It adds no lifecycle gate. The one new test extends an
existing guard (packages/website/src/test/tutorial-drift.test.ts) instead of adding a new
mechanism.
How it could be solved
Three decisions, each about keeping the pages honest.
The first was where the pages should live. The user chose a section on the website over a page set in the repository or a command that prints them. The files sit in the content package, next to the tutorials, so they ship with every install and the website reads them the same way it reads everything else.
The second was how strict a page's shape should be. Every page has exactly three headings, in the same order, and nothing else at that level. A page with a heading missing, out of order, or one too many fails the website build rather than shipping. Holding the shape exact also keeps each page to a single title, which screen readers rely on.
The third was how to stop the pages going stale. The tutorials already had a test that checks every command they show against the tool's own list of commands and options. The new pages were added to that test instead of getting one of their own, so there is one check to maintain, not two. Before trusting it, a page was broken on purpose with a misspelt command and option; the test failed and named the page, the line and the missing part.
How AIDLC solves it
The website has a new How-to section at /how-to/. Each page is one task: what you will do,
the exact steps, and one thing to run that shows it worked. It sits in the main menu between
Tutorials and Blog, and site search finds every page.
Six pages ship: add AIDLC to a project you already have, run two pieces of work at the same time, change a requirement after its phase is finished, send your roadmap to GitHub Issues and a Project board, see what a piece of work cost, and keep AIDLC up to date.
Every page was followed step by step against the real command line before it was written down, and three of them changed because the commands did not behave the way the first draft said. A page that names a command or option the tool no longer has now fails the website's tests, so the pages cannot quietly go out of date when the tool changes.
The pages live in the content package under howto/, next to the tutorials, so they ship
with every install.