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>
This commit is contained in:
Marcos Paulo
2026-09-05 01:18:27 +00:00
parent aa85c1d0b7
commit aae4d42229
79 changed files with 3805 additions and 0 deletions
+38
View File
@@ -0,0 +1,38 @@
# Task 17 — hands-on passthrough
**Agent**: `astro-architect` · **Model**: MiniMax-M3
**Depends on**: 01 · **Parallel with**: 12, 13, 14
**Worktree**: `.agents/scripts/worktree.sh start 17 hands-on`
## Goal
`hands-on/starter/` and `hands-on/rules/` ship **byte-identical** from
`public/`, unprocessed.
## Why this is a task and not a footnote
These are **lab fixtures**. The workshop exercise is that an attendee points an
agent at dependency-free HTML/CSS/JS and watches it work. Componentizing them,
minifying them, or letting a bundler touch them destroys the lesson — and the
prompts in `app.js` reference these files by path and content.
The risk is an agent "helpfully" improving them. This task exists to say
explicitly: do not.
## Steps
1. Move both directories to `public/hands-on/`.
2. Confirm Astro copies `public/` verbatim with no processing.
3. Confirm URLs `/ai-for-dummies/hands-on/starter/` and `.../rules/` resolve.
4. Confirm every lint/format config **ignores** them (the templates already do).
## Done when
- [ ] `diff -r` between the original directories and `dist/hands-on/` is empty
- [ ] Both URLs serve; both labs work standalone
- [ ] The `hands-on/starter/` reference in the full guide still resolves
- [ ] `verify.mjs`'s `starterHtml` / `starterJs` assertions still pass
## Do not
Do not reformat, lint, componentize, or "modernise" a single line.