From 12b72196b6139a789683c4c1d44b36cc9353cd98 Mon Sep 17 00:00:00 2001
From: CsUtil <45512166+cs-util@users.noreply.github.com>
Date: Fri, 24 Oct 2025 15:24:01 +0000
Subject: [PATCH 1/3] Refactor AGENTS.md for clarity and structure; update
 package.json to include AGENTS.md in formatting script

---
 AGENTS.md    | 55 +++++++++++++++++++++++++++++-----------------------
 package.json |  2 +-
 2 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 09003d0..d0d32f7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,9 +1,12 @@
+# General
 
-# Rules
+- The readme.md contains the full spec of the application. Read it end-to-end to understand the full context.
+- You must follow the instructions in the agent.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 that explains it in detail.
 
-## 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
@@ -12,37 +15,41 @@
 - 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
+# Relying on tests as your central tool for all development
 
-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 (repeat)
+
+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 important components
+- Keep tests deterministic and fast; avoid E2E unless asked
diff --git a/package.json b/package.json
index 6ae58f5..7eedf72 100644
--- a/package.json
+++ b/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",

From 232d26e719fe1da57f29e5b19e68fdcbb745e730 Mon Sep 17 00:00:00 2001
From: CsUtil <45512166+cs-util@users.noreply.github.com>
Date: Sat, 25 Oct 2025 10:55:48 +0000
Subject: [PATCH 2/3] Enhance AGENTS.md documentation for clarity and detail;
 refine co-location and testing sections

---
 AGENTS.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d0d32f7..573c2ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,7 +3,7 @@
 - The readme.md contains the full spec of the application. Read it end-to-end to understand the full context.
 - You must follow the instructions in the agent.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 that explains it in detail.
+- **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.
 
 - This is a minimal local first web app (static HTML + modular JS). Prefer tailwind over custom CSS.
 - Entrypoint: `index.html` (+ static pages in `pages/` if any needed)
@@ -31,14 +31,14 @@ Do requirements gathering before implementation
 - Build questions on previous responses
 - Provide numbered response options for the user to select from
 
-# Relying on tests as your central tool for all development
+# Validating Assumptions via Tests
 
 - 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 (repeat)
+## TDD Loop
 
 1. **State a hypothesis** (behavior/API).
 2. **Write a failing test** for it.
@@ -51,5 +51,5 @@ Do requirements gathering before implementation
 
 - Unit specs: `*.test.js`
 - Property-based specs: `*.property.test.js`
-- Property-based tests are important, don't omit them for important components
+- Property-based tests are important, don't omit them for any components
 - Keep tests deterministic and fast; avoid E2E unless asked

From 1cba3d99f4f0986551e8d850a3bf560f71b86bd1 Mon Sep 17 00:00:00 2001
From: CsUtil <45512166+cs-util@users.noreply.github.com>
Date: Sat, 25 Oct 2025 10:57:52 +0000
Subject: [PATCH 3/3] Update AGENTS.md for consistency and clarity in README
 references

---
 AGENTS.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 573c2ba..1e13a22 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
 # General
 
-- The readme.md contains the full spec of the application. Read it end-to-end to understand the full context.
-- You must follow the instructions in the agent.md file while working on your task and regularly review if you are still aligned with these instructions and the spec.
+- 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.
 
@@ -9,7 +9,6 @@
 - 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")