homepage/AGENTS.md

AGENTS.md

Rules for any agent working in this repository.

Always

1. Read .agents/PLAN.md first — project goals, architecture, and the LOCKED DECISIONS (Architectural Anchors) are binding.
2. Follow the phased protocol in .agents/phases/:
   • todo/NN_name/ — pending phases (00_phase.md overview + NN_task.md task files; task sort order = execution order).
   • complete/ — finished phases (read-only history).
   • New work is captured as a phase directory via the phase-authoring skill; code changes flow through the phased-execution skill (each task runs in a fresh subprocess behind the validation gate).
3. Test before you ship:
   • ./build.sh — rebuild dist/ (tests run against dist/, the deployed artifact — never test src/ directly).
   • npm test — the Playwright E2E suite (pinned @playwright/test 1.62.0; do not bump without re-checking the cached browser revision).
   • For any nginx/Dockerfile change: ./scripts/check-headers.sh (Phase 03+).

Never

• Modify .agents/PLAN.md except via an explicit user-approved change to the LOCKED DECISIONS (record the approval in the PLAN's review history).
• Modify anything in .agents/phases/complete/.
• Edit files in .agents/phases/todo/ without asking the user first (phase rewrites are a phase-authoring action).
• Add runtime dependencies, CDNs, or a JS build toolchain (LOCKED: vanilla HTML/CSS/JS, flat src/*.js, build.sh hashing).
• Add real network I/O to the fake terminal (LOCKED: simulated output only — see Phase 02 and PLAN §2.5).
• Add Strict-Transport-Security inside the nginx container — TLS/HSTS are the Caddy edge's job (the container serves plain HTTP on 8080).

Conventions

• Static site: edits in src/ → ./build.sh → dist/ (hash-cached names). New root-level assets are picked up automatically by build.sh; nested directories are not (keep JS files flat in src/).
• Terminal modules: terminal-commands.js (canned data), terminal-achievements.js, terminal-vim.js, terminal.js (core) — load order is fixed in index.html (all defer); keep dependencies pointing only at earlier files.
• Commits: small, imperative subject; one logical change per commit.
• dist/, node_modules/, test-results/, playwright-report/ are build/test artifacts — never edit them by hand.