T-6D5U-add-astro-docs-site

Status: closed/done · Impact: high · Complexity: large

Goal

Stand up a published documentation surface for the sdlc plugin — an Astro Starlight site sourced from the plugin’s own artifacts (skills, schemas, scripts) plus a small hand-written architecture / roadmap / changelog set. Pair it with a project-local /dev-update-docs skill that does both mechanical regen (deterministic Node script walks the plugin source and writes the reference pages) and semantic accuracy verification (the LLM cross-checks the hand-written pages against the live codebase and corrects drift, flagging what it can’t fix). Together they validate the architecture pattern the README espouses — deterministic tools + LLM judgment — in a domain (docs) where the LLM piece is genuinely needed.

Today

Plugin lives under plugin/: plugin/.claude-plugin/, plugin/skills/<19 skill dirs>/ (backlog-triage, entities-audit, entities-migrate, epic-new, import-planning, milestone-new, milestones-from-file, orchestrate, pr-check, project-cleanup, review-todos, setup, task-close-out, task-define, task-ensure-ready, task-new, task-review, task-work, update-skill-doc), plugin/entities/{backlog,epic,milestone,task}/schema.json, plugin/scripts/*.py (11 scripts including new_task.py, new_milestone.py, new_epic.py, new_backlog.py, setup_planning.py, audit_entities.py, migrate_entities.py, find_todos.py, lint_skill_prose.py, project_cleanup.py, scan_planning_candidates.py), plugin/validators/validate_frontmatter.py, docs/planning/{tasks,epics}/, README.md.
README is the only published reference. Accurate but limited; written as a project-intro, not as a reference site.
No project-local skills exist; .claude/skills/ does not exist in this repo.
The plugin is loaded via Claude Code’s plugin marketplace mechanism (machine-specific; not in scope for this task — the restructure that made this work is already done).

Proposed

Repo layout adds (plugin already lives under plugin/):

.
├── .claude/
│   └── skills/
│       └── dev-update-docs/SKILL.md       (NEW — project-local; not part of distributed plugin)
├── plugin/                                 (existing — unchanged)
├── site/                                   (NEW — Astro Starlight app)
│   ├── astro.config.mjs
│   ├── package.json
│   ├── src/
│   │   └── content/
│   │       ├── config.ts                   (Starlight docs collection definition)
│   │       └── docs/
│   │           ├── index.md                (landing page; hand-written)
│   │           ├── architecture/           (hand-written — expands the README philosophy)
│   │           │   ├── overview.md
│   │           │   ├── deterministic-first.md
│   │           │   ├── harness-agnostic.md
│   │           │   └── data-model.md
│   │           ├── reference/              (AUTO-GENERATED — never hand-edited)
│   │           │   ├── skills/<skill>.md   (one per plugin/skills/<skill>/SKILL.md)
│   │           │   ├── entities/<type>.md  (one per plugin/entities/<type>/schema.json)
│   │           │   └── scripts/<name>.md   (one per plugin/scripts/*.py)
│   │           ├── roadmap.md              (hand-written)
│   │           └── changelog.md            (hand-written initially)
│   └── scripts/
│       └── regen.mjs                       (the deterministic generator)
├── docs/                                   (existing — stays at root)
├── README.md                               (updated: doc-site pointer)
└── ...

The /dev-update-docs project-local skill lives at .claude/skills/dev-update-docs/SKILL.md and on invocation:

Runs node site/scripts/regen.mjs — deterministic regen of reference/* pages from plugin/skills/*/SKILL.md, plugin/entities/*/schema.json, plugin/scripts/*.py.
Walks the hand-written pages (index.md, architecture/, roadmap.md, changelog.md) and semantically verifies them against the live plugin: do they cite skill names that still exist? Reference scripts/entities that still exist? Match the current version in the manifest? Use the LLM to detect drift; use Edit to fix what’s fixable; flag the rest for the user.
Runs npm --prefix site build to confirm the site still compiles.
Reports: regen summary (files added/updated/removed), semantic-drift findings (fixed vs. flagged), build status.

Approach

Init the Astro Starlight site. From repo root:
```
npm create astro@latest site -- --template starlight --typescript strict --no-git --skip-houston --install
```
Verify npm --prefix site dev serves the default Starlight content at the localhost port it announces. Commit site/ baseline.
Configure the docs collection. Edit site/astro.config.mjs: set title: 'sdlc', description, sidebar groups (Architecture, Reference, Roadmap, Changelog), social.github placeholder. Remove or replace Starlight’s example content under site/src/content/docs/ — keep index.md (replace body), drop the rest.
Hand-written content. Write index.md (landing pitch), the four architecture/*.md pages (expand the README’s philosophy section — not duplicate it verbatim; the README stays the TL;DR, the site is the long form), roadmap.md (current direction; lift from the README’s roadmap block), changelog.md (start with the current state: plugin layout under plugin/, the entity-schema migration, the orchestrator skill).
Regen generator (site/scripts/regen.mjs). Node script, zero new deps beyond what Astro brings. Walks ../plugin/skills/*/SKILL.md, ../plugin/entities/*/schema.json, ../plugin/scripts/*.py. For each, parses YAML frontmatter / JSON / module docstring and writes a matching .md under site/src/content/docs/reference/{skills,entities,scripts}/. Each generated page starts with . Idempotent: running twice produces no git diff. If a previously-generated page corresponds to a now-missing source file, the script deletes it (and logs the deletion explicitly — removals are loud, not silent). Skip non-skill entries under plugin/skills/ (README.md, CLAUDE.md).
Project-local update-docs skill at .claude/skills/dev-update-docs/SKILL.md. Frontmatter: no name: field (project-local skills get bare names from the dir). allowed-tools: [Bash, Read, Edit, Glob, Grep, AskUserQuestion]. Body structures the four-phase flow (regen → semantic verify → build → report) as numbered steps. Contract: this skill is the only thing that touches site/src/content/docs/reference/*; humans edit only the hand-written pages and regen.mjs itself.
End-to-end smoke test. Invoke the skill from repo root. Confirm: reference pages regen with correct content; semantic-verify pass produces zero findings against the (currently-coherent) hand-written content; build succeeds; report is readable. Then deliberately break something — rename a skill dir in plugin/skills/ — re-invoke, confirm the skill flags the now-stale references in the hand-written pages.
Update root README. Add a doc-site pointer with npm --prefix site dev quickstart. Note the project-local skill alongside the plugin’s own skills.

Files to touch

Created (new):

site/ — Astro Starlight scaffold from npm create astro (many files; treat as one logical add)
site/src/content/docs/index.md — landing
site/src/content/docs/architecture/{overview,deterministic-first,harness-agnostic,data-model}.md — hand-written (4 files)
site/src/content/docs/roadmap.md — hand-written
site/src/content/docs/changelog.md — hand-written
site/scripts/regen.mjs — deterministic generator
.claude/skills/dev-update-docs/SKILL.md — project-local skill
.gitignore additions for site/node_modules/, site/dist/, site/.astro/

Modified:

README.md — doc-site pointer added

Acceptance criteria

AC-1: npm --prefix site install && npm --prefix site build succeeds on a fresh clone (no committed node_modules or dist).
AC-2: site/src/content/docs/architecture/ contains the four planned pages, all hand-written, none carrying the AUTO-GENERATED marker.
AC-3: site/src/content/docs/reference/skills/ contains one page per skill dir under plugin/skills/ (excluding README.md and CLAUDE.md); reference/entities/ contains one page per plugin/entities/<type>/schema.json; reference/scripts/ contains one page per plugin/scripts/*.py. All generated by regen.mjs.
AC-4: Each auto-generated page starts with .
AC-5: Running node site/scripts/regen.mjs twice in succession produces no git diff on the second run (idempotent).
AC-6: .claude/skills/dev-update-docs/SKILL.md exists; invoking the resulting slash command runs regen → semantic-verify → build → report end-to-end in this repo. Failure modes (broken cross-reference in a hand-written page, missing entity schema, build error) surface to the user with file/line context.
AC-7: Root README.md describes the doc site and tells the reader how to preview locally with one command.
AC-8: npm --prefix site dev starts and serves the site; the rendered sidebar shows Architecture / Reference / Roadmap / Changelog; the Reference section contains Skills, Entities, and Scripts subsections with page names matching the source artifacts.

Out of scope

Deployment to GitHub Pages, Vercel, Netlify, or a custom domain. The site builds locally; publishing is a follow-on task.
Custom Starlight theme / branding / fonts. Defaults are fine for v1.
Search index tuning beyond Starlight defaults.
Multi-version docs (v0.1.x vs v0.2.x etc.).
i18n / translations.
A CI workflow (lint / build / deploy on push). Manual npm run build is sufficient for v1.
Automating changelog generation from git history. v1 changelog is hand-maintained.
A prose-style linter for hand-written pages. The update-docs skill catches factual drift; stylistic policing is a different concern.
The plugin restructure (root → plugin/) and the schema-layout migration (schemas/ → plugin/entities/<type>/schema.json) — both already done out-of-band.

Dependencies

none

Discovery context

This task validates two things at once: (1) the monorepo restructure path the README hinted at — peer projects coexisting under one root, with the plugin as one tenant — and (2) the deterministic-tooling-plus-LLM-orchestration pattern in a non-trivial domain. The update-docs skill is a textbook case for the pattern: mechanical regen is unambiguously a script’s job, but verifying that a hand-written sentence like “the plugin currently ships 5 skills” is still true requires reading the current source — LLM-shaped work. If this skill feels natural to invoke, it’s a good signal the pattern generalizes; if it feels awkward, that’s signal too. Either way, a working public docs surface unblocks eventually publishing the plugin to a wider marketplace audience.

Post-mortem

Captured by /sdlc:task-work on 2026-05-20. PR: pending.

Acceptance criteria coverage

AC-1: auto — npm --prefix site install && npm --prefix site run build succeeded; verified the build runs end-to-end against the regenerated reference + hand-written pages.
AC-2: auto — file listing confirms four architecture/*.md pages exist and none carry the AUTO-GENERATED marker (those live only under reference/).
AC-3: auto — regen.mjs run produced exactly 19 skill pages, 4 entity pages, 11 script pages, matching the source artifact counts under plugin/.
AC-4: auto-with-caveat — every generated page begins with the AUTO-GENERATED marker as the first body line immediately after the YAML frontmatter. Strict “starts with at byte 0” reading is impossible because Astro/Starlight requires frontmatter at the literal top of the file; the marker placement (first thing inside the body, with a comment in regen.mjs documenting the constraint) preserves the AC’s intent. Flagging here for reviewer awareness.
AC-5: auto — running node site/scripts/regen.mjs twice produced no git status changes on the second run; verified.
AC-6: agent-manual (partial) — the SKILL.md exists at the spec’d path. The deterministic phase 1 (regen) and phase 3 (build) were exercised end-to-end during implementation. The phase 2 semantic-verify is LLM-shaped and runs in the slash-command harness; a full end-to-end invocation of /dev-update-docs by the user is the natural first real exercise of phase 2. Deliberate-break smoke test was performed by renaming plugin/skills/setup/ → plugin/skills/setup-TEMP/ and re-running regen: the script correctly deleted the stale reference page and created the new one (and restored cleanly when reverted).
AC-7: auto — README now has the ## Documentation site section with npm --prefix site dev quickstart and a pointer to the /dev-update-docs skill.
AC-8: agent-manual — Astro build output lists Architecture, Reference (Skills/Entities/Scripts subsections), Roadmap, and Changelog pages all generated. A live visual check in a browser at http://localhost:4321 is deferred-user — the build’s page-list output is the programmatic proxy; the actual sidebar render is the human’s call.

What worked

The regen.mjs design — one walker per artifact type, write-if-changed, sweep-delete-orphans — fell out cleanly with no dep beyond node:fs. The idempotence + loud-deletion ACs were satisfied by the same pattern.
Astro/Starlight npm create baseline + a single config edit was enough to get the sidebar wired. Starlight 0.39’s autogenerate migration was a 10-minute fix once the build error pointed at it.
The npm vs pnpm lockfile mismatch was caught early (the scaffolder defaulted to pnpm; the task spec called for npm). Wiping pnpm-lock and reinstalling with npm gave a clean package-lock.json without further fuss.

Friction and automation gaps

Sandbox denial on node/npm/npx/pnpm/yarn blocked the first pickup attempt mid-Step 4 — the worktree initialization step does not currently surface “this task will need these tool families; check your permission allowlist first.” The unblock cycle (block-commit, user-permission-grant, unblock-commit) created two paired commits in the feat branch’s history that net to no change. A pre-flight check in /sdlc:task-work Step 3 or 4 — grep the task body for tool families like npm, cargo, uv, then probe command -v for each in the worktree, and surface missing permissions to the user before any implementation work — would catch this class up front. → T-Z8VC-task-work-preflight-permissions-probe
The task’s Approach step 1 specifies --install on npm create astro, which currently defaults the scaffolder to pnpm. The downstream task spec then calls for npm --prefix site build, so the lockfile has to be swapped post-scaffold. Either the task spec should specify --package-manager npm (if such a flag exists), or the /dev-update-docs skill / a follow-up task should document the swap as an expected step. As-is, a future implementer following the spec verbatim hits the same wrinkle.
AC-4 (“each auto-generated page starts with <!-- AUTO-GENERATED ...”) conflicts with Astro/Starlight’s hard requirement that YAML frontmatter sit at byte 0 of the file. The implementer has to make a judgment call and document it. The task spec should either rephrase the AC to “is unambiguously marked as auto-generated near the top” or explicitly call out the Astro frontmatter constraint and the marker-after-frontmatter placement. Either rephrasing avoids the next implementer reaching the same fork.
Starlight 0.39’s removal of {label, autogenerate} shorthand at the same nesting level forced a config rewrite mid-build. The error message was clear, but the cost of catching it post-config-write rather than at-config-time is real. A linter or schema for astro.config.mjs’s starlight integration would catch this; in the absence of that, the task spec could cite the current Starlight major version and the autogenerate-as-nested-items shape so the implementer writes it correctly the first time.
Commit messages with multi-line bodies got rejected by the sandbox when authored via heredoc patterns. Single-line messages worked. The conventions doc at plugin/conventions/commit-messages.md describes the heredoc + -F pattern as canonical, but the harness may need a permission allowlist refresh for tmpf=$(mktemp) && cat > ... shapes. Worth investigating — single-line conventional-commit messages lose the “why” context. → T-7UIC-investigate-sandbox-multiline-commit-denial
The /dev-update-docs skill’s semantic-verify phase (phase 2) has not been exercised against a deliberately-stale hand-written page in this run. The deterministic regen smoke test was done (rename skill dir → regen → confirm deletion); the LLM-shaped drift check on index.md etc. waits for the user’s first real invocation. Acceptable for v1; a follow-up task could harden that loop with a deterministic seed-and-check fixture. → T-RXKE-eval-harness-for-doc-authoring-skills

Spawned follow-up tasks

T-Z8VC-task-work-preflight-permissions-probe — created. Probe the sandbox permission allowlist for tool-family signals in the task body before creating the worktree.
T-7UIC-investigate-sandbox-multiline-commit-denial — created. Resolve why the canonical heredoc commit-message pattern hit sandbox denials during this run.
T-RXKE-eval-harness-for-doc-authoring-skills — linked existing. Already targets the LLM-shaped drift-check eval loop that /dev-update-docs would benefit from.

← Back to Tasks