Files

T

Marcos Paulo aae4d42229 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

2.4 KiB

Raw Blame History

Task 20 — Cutover and cleanup

Agent: astro-architect, with a human watching · Model: MiniMax-M3 assisting Depends on: all · Worktree: .agents/scripts/worktree.sh start 20 cutover

This task touches production publishing. Do not run it unattended.

Goal

The Astro build is what the world sees, the old files are gone, and the docs describe reality.

Steps

Full verification on the built site: all 10 routes, all 6 query params, both languages, vote widget against the live API, screenshots at four widths.
Delete the superseded files — only after their replacements are proven: app.js, styles.css, responsive.css, chapters.css, landing.css, rules/app.js, rules/styles.css, skills/app.js, skills/styles.css, skills-review/*.js, skills-review/*.css, and the ten old index.html files. git rm, one commit, reviewable. Keep: hands-on/** (now under public/), submitted-skills/**, skill-reviews/**, docs/**, vote-service/**.
Publish via the mechanism chosen in task 01.

Verify on the real host with a cache-buster:

for r in "" full-guide summary models agents skills rules skills-review \
         hands-on/starter hands-on/rules; do
  curl -sS -o /dev/null -w "%{http_code} $r\n" \
    "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/$r/?v=$(git rev-parse --short HEAD)"
done

All ten must be 200. A stale cached 200 looks identical to success — the ?v= is what distinguishes them.

Update the docs: README.md, docs/operations-guide.md (build + publish path, and it must stop claiming pages is "the exact published source" if that is no longer true), GATES.md, and AGENTS.md (stack is no longer "migration in progress").
Fast-forward pages per the procedure in docs/operations-guide.md.

Rollback

pages still holds the working vanilla site until you overwrite it. If cutover fails, reset pages to its previous commit — the old site returns immediately. Note the SHA before you start:

git rev-parse origin/pages   # write it down

Done when

Ten routes 200 on the real host with a fresh cache-buster
Vote widget works end-to-end from the published origin (CORS is origin-sensitive — ALLOWED_ORIGIN must still match)
Old files deleted; npm run gate green
Docs match reality
Previous pages SHA recorded for rollback

2.4 KiB Raw Blame History