docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site to Astro. Nothing here implements the refactor; these are briefs, rules and templates that the task agents read. - .agents/ holds context, rules, checklists, skills, specialist agents, component/page/config templates and gate scripts. It is vendor-neutral so MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at AGENTS.md. - .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on the shared git-common-dir so parallel worktrees serialise, and guards the assertion count in scripts/verify.mjs against a coverage drop. - plans/astro-refactor/ carries the phase graph, per-task briefs and the model-routing recommendation. These files must be tracked before fanning out: a worktree only checks out tracked files, so an untracked plan is invisible to every agent working in one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 01:18:27 +00:00
parent aa85c1d0b7
commit aae4d42229
79 changed files with 3805 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Task 01 — Astro scaffold, gates, and the publishing decision
+
+**Agent**: `astro-architect` · **Model**: Codex · **Depends on**: nothing
+**Blocks**: everything · **Worktree**: `.agents/scripts/worktree.sh start 01 scaffold`
+
+## Goal
+
+A working Astro project that builds, serves one page correctly from the real
+host under `/ai-for-dummies/`, and has all three gate tiers live.
+
+## Scope
+
+`astro.config.mjs`, `package.json`, `tsconfig.json`, `src/layouts/BaseLayout.astro`,
+`.husky/`, `.lintstagedrc.json`, lint configs, `.gitea/workflows/verify.yml`,
+`docs/operations-guide.md`.
+
+Copy the configs from `.agents/templates/config/` — they are written for this
+project (correct ignores for `hands-on/`, `submitted-skills/`, `vote-service/`).
+
+## Steps
+
+1. `npm create astro@latest` into the worktree — minimal template, TypeScript
+   strict, **no UI framework, no CSS framework**.
+2. Set `base: '/ai-for-dummies'`. Every internal link goes through
+   `import.meta.env.BASE_URL` from here on.
+3. `src/layouts/BaseLayout.astro`: `<html lang>`, viewport meta, title,
+   description, global styles slot. Nothing clever.
+4. Merge `.agents/templates/config/package.scripts.json` into `package.json`.
+   **`"prepare": "husky"` is what makes hooks exist** — without it every hook is
+   inert.
+5. `npm install husky lint-staged prettier eslint stylelint …`, then `npx husky init`.
+6. Copy the three hooks and the lint configs into place. Verify with
+   `.agents/scripts/verify-hooks.sh`.
+7. Migrate **one** page (`summary/` — smallest, zero JS) as a smoke test.
+8. Copy `hands-on/` into `public/` (task 17 does this properly; a stub is fine here).
+9. **Make the publishing decision** per `.agents/context/publishing.md`. Recommended:
+   Gitea Actions builds `dist/` and pushes `pages`. Copy
+   `.agents/templates/config/gitea-ci.yaml` to `.gitea/workflows/verify.yml`.
+10. Rewrite the publishing section of `docs/operations-guide.md` to match.
+
+## Done when
+
+- [ ] `npm run build` succeeds; `npm run gate` passes
+- [ ] `.agents/scripts/verify-hooks.sh` reports hooks live
+- [ ] A bad commit message is rejected; a raw hex in a `.astro` file is rejected
+- [ ] `/ai-for-dummies/summary/` serves correctly **from the real host**, not just preview
+- [ ] `docs/operations-guide.md` describes the actual publishing path
+
+## Do not
+
+- Do not migrate more than one page. That is tasks 12–16.
+- Do not add a UI framework, CSS framework, or any runtime dependency.
+- Do not touch `hands-on/` contents, `submitted-skills/`, or `vote-service/`.
+
+## Watch for
+
+The base path is the #1 production-only failure in this migration. `npm run
+preview` will lie to you. Deploy the smoke-test page and curl it with a
+`?v=<sha>` cache-buster.