Refactor AGENTS.md for clarity and structure; update package.json to include AGENTS.md in formatting script

AGENTS.md

@@ -1,48 +1,54 @@
+# General
 
-# Rules
+- The `README.md` contains the full spec of the application. Read it end-to-end to understand the full context. It should be kept up to date whenever the code is ready for a PR
+- You must follow the instructions in the `AGENTS.md` file while working on your task and regularly review if you are still aligned with these instructions and the spec.
+- Do not stop until every acceptance criterion is implemented, verified locally and prepared for review.
+- **Co-locate docs**: every code file must have a matching `*.md` sidecar next to it, that explains the component in detail. The goal of the sidecar is to make purpose, API, invariants, examples and test strategy of the component obvious to agents and humans.
 
-## General
 - This is a minimal local first web app (static HTML + modular JS). Prefer tailwind over custom CSS.
-- Entrypoint: `index.html` (+ static pages in `pages/`)
+- Entrypoint: `index.html` (+ static pages in `pages/` if any needed)
 - The code is composed of small, focused modules in `src/` (`components/`, `utils/`, ..) with colocated tests
 - Run `npm test` and `npm outdated` at the start and end of each significant task and weekly at minimum; keep dependencies healthy. Prefer bumping to the `Wanted` version unless blocked by incompatibilities (document any exceptions). Also run `npm audit` to catch security issues even when versions are current
-- `README.md` typically contains big picture dev. spec and context. It should be kept up to date whenever the code is ready for a PR
 - Only change code directly related to the current task; keep diffs small!
 - Preserve existing comments & docs; add concise, long-lived comments where useful and avoid narrating changes via comments
 - When external documentation could be consulted, do so to validate your plan makes sense. If you lack a browsing/online search tool, ask the user to run an online search for you (e.g., "Please search for \"x\" and paste back the findings")
 
 ## Dependencies & no-build approach to use
+
 This project follows a no-build, static workflow:
+
 - Use native ES modules and `<script type="importmap">` to map bare specifiers when needed.
 - Then load your entry/module scripts with `<script type="module">` and import using the mapped specifiers.
 - Prefer CDN URLs from unpkg.com for third-party modules compatible with ESM.
 - Do not add bundlers/build chains unless explicitly requested/approved.
 
-## Test layout
-- Unit specs: `*.test.js`
-- Property-based specs: `*.property.test.js`
-- Property-based tests are important, don't omit them for important components
-- Keep tests deterministic and fast; avoid E2E unless asked
-
-## Use TDD if possible
-1. Prefer the simplest fix first when working on multiple issues
-2. Add a failing test first and run `npm test` to verify it's failing
-3. Make minimal, focused changes
-4. Re-run `npm test` after each fix and document real output
-5. Iterate until green
-
-## Feature development process to use
+## When communicating with the developer
 
-Follow this lightweight spec-first flow before coding:
+Do requirements gathering before implementation
 
-1) Requirements gathering
 - Ask one question at a time and iterate until requirements are clear
 - Build questions on previous responses
 - Provide numbered response options for the user to select from
 
-2) Specification development to play through before implementation
-- Smaller changes: clearly state what changes, how it integrates, testing strategy and key edge cases
-- Major features: capture functional requirements, architecture choices/integration points, data handling (I/O, validation), error handling and edge cases, testing strategy (unit + property-based + integration), and any UI & performance considerations
+# Validating Assumptions via Tests
 
-3) Document all components
-- Compile concise specification md files next to new components if any were added. This way similar to the test files also each component will have a specification file. 
+- Never submit code whose hypothesis is not captured by a test.
+- Reduce risks from assumptions (no matter how sure you are) by **proving these assumptions with tests**.
+  Do not throw away the produced tests after you did the validation, because they often serve as useful documentation of a behavior. Make sure their comments explain their purpose.
+- **TDD by default.** Interfaces emerge from tests.
+
+## TDD Loop
+
+1. **State a hypothesis** (behavior/API).
+2. **Write a failing test** for it.
+3. **Run tests** and **observe the failure** is for the expected reason.
+4. **Implement the minimum** to pass (green).
+5. **Refactor** with tests still green.
+6. **Update the sidecar** with any changed assumptions, invariants, or examples.
+
+## Test layout
+
+- Unit specs: `*.test.js`
+- Property-based specs: `*.property.test.js`
+- Property-based tests are important, don't omit them for any components
+- Keep tests deterministic and fast; avoid E2E unless asked

package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "test": "npm run test:core && npm run test:e2e:index",
     "test:core": "npm run format && npm run lint && npm run check:all && npm run test:unit",
-    "format": "prettier --write --ignore-unknown --no-error-on-unmatched-pattern \"src\" \"pages\" \"config\" \"docs\" index.html README.md package.json",
+    "format": "prettier --write --ignore-unknown --no-error-on-unmatched-pattern \"src\" \"pages\" \"config\" \"docs\" index.html README.md AGENTS.md package.json",
     "test:unit": "jest --coverage --config config/jest.config.js",
     "lint": "eslint . --config config/eslint.config.js",
     "test:watch": "jest --watch --config config/jest.config.js",