Marcos Paulo
aae4d42229
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>
60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# 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.
|