From 5ffc9183f1bc63d63764f3b37ffc231306639861 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Wed, 12 Aug 2026 20:57:00 -0400 Subject: [PATCH] Add repo memory layer and plans Co-Authored-By: Claude Fable 5 --- .agents/MEMORY.md | 33 +++++++++++++++++++++++++++++++++ .agents/memory/architecture.md | 5 +++++ .agents/memory/conventions.md | 5 +++++ .agents/memory/decisions.jsonl | 1 + .agents/memory/lessons.md | 22 ++++++++++++++++++++++ .agents/plans/README.md | 8 ++++++++ .agents/plans/active/.gitkeep | 0 .agents/plans/archive/.gitkeep | 0 .agents/proposals/README.md | 7 +++++++ .gitignore | 2 ++ AGENTS.md | 12 +++++++++++- 11 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 .agents/MEMORY.md create mode 100644 .agents/memory/architecture.md create mode 100644 .agents/memory/conventions.md create mode 100644 .agents/memory/decisions.jsonl create mode 100644 .agents/memory/lessons.md create mode 100644 .agents/plans/README.md create mode 100644 .agents/plans/active/.gitkeep create mode 100644 .agents/plans/archive/.gitkeep create mode 100644 .agents/proposals/README.md create mode 100644 .gitignore diff --git a/.agents/MEMORY.md b/.agents/MEMORY.md new file mode 100644 index 0000000..e64f65f --- /dev/null +++ b/.agents/MEMORY.md @@ -0,0 +1,33 @@ +# Repo Memory + +Curated, reviewed knowledge for coding agents working in this repository. +Memory is an accelerator, not a second source of truth. + +## Precedence (highest first) + +1. Source code and tests +2. Executable configuration +3. Accepted design records / docs +4. `AGENTS.md` +5. This memory + +If memory conflicts with anything above it, the memory is stale — propose a fix. + +## Topics + +- `memory/architecture.md` — durable architectural decisions and constraints +- `memory/conventions.md` — validated conventions not obvious from the code +- `memory/lessons.md` — hard-won lessons and recurring landmines +- `memory/decisions.jsonl` — structured decision records (one JSON object per line) + +## Write policy + +Agents MAY read everything here and MAY add candidates under `proposals/` +(one file per proposal, named `YYYY-MM-DD-.md`, with evidence links). +Agents MUST NOT edit `memory/` directly; trusted memory changes only through +reviewed commits that promote a proposal. + +## Prohibited content + +Credentials or secrets, personal data, raw transcripts or tool logs, session +TODOs, high-frequency agent state, unverified external claims. diff --git a/.agents/memory/architecture.md b/.agents/memory/architecture.md new file mode 100644 index 0000000..72d22ff --- /dev/null +++ b/.agents/memory/architecture.md @@ -0,0 +1,5 @@ +# Architecture + +Durable architectural decisions and constraints for Artstr Studio. + +No entries yet. diff --git a/.agents/memory/conventions.md b/.agents/memory/conventions.md new file mode 100644 index 0000000..ae5d83f --- /dev/null +++ b/.agents/memory/conventions.md @@ -0,0 +1,5 @@ +# Conventions + +Validated conventions not obvious from the code. + +No entries yet. diff --git a/.agents/memory/decisions.jsonl b/.agents/memory/decisions.jsonl new file mode 100644 index 0000000..a0592a2 --- /dev/null +++ b/.agents/memory/decisions.jsonl @@ -0,0 +1 @@ +{"kind":"lesson","subject":"codebase/single-file-editing","summary":"The entire app lives in src/index.html (~42k lines, no build, no npm), so edits must be surgical and tightly scoped; the only automated suite is node --test \"tests/premium/*.test.mjs\" (quoted glob form required), covering src/premium2-helpers.mjs — everything else is validated manually in a browser.","status":"active","evidence":[{"type":"repository","ref":"src/index.html"},{"type":"test","ref":"tests/premium"},{"type":"repository","ref":"AGENTS.md"}],"created":"2026-08-12","supersedes":[]} diff --git a/.agents/memory/lessons.md b/.agents/memory/lessons.md new file mode 100644 index 0000000..0299c77 --- /dev/null +++ b/.agents/memory/lessons.md @@ -0,0 +1,22 @@ +# Lessons + +Hard-won lessons and recurring landmines. + +## The whole app is one ~42k-line file — edit surgically, test what you can + +Nearly every change lands in `src/index.html` (~42k lines): logic, styles, +and inline encoders all live there by design, with no build step and no +package.json. Tight scoping matters — locate the exact function or block and +keep the diff minimal, because a sloppy edit in a file this size is hard to +review and easy to break silently. The only automated coverage is +`node --test "tests/premium/*.test.mjs"` (Node 22; the quoted glob form is +required so the pattern reaches node's test runner intact), which covers +`src/premium2-helpers.mjs` and the premium/NWC flows. Everything else is +validated manually by opening `src/index.html` in a browser and exercising +the affected feature. + +Authoritative source: +- src/index.html +- tests/premium/ (fixtures in tests/fixtures/) +- src/premium2-helpers.mjs +- AGENTS.md ("Build / test / validate", "Change policy") diff --git a/.agents/plans/README.md b/.agents/plans/README.md new file mode 100644 index 0000000..36bcc9a --- /dev/null +++ b/.agents/plans/README.md @@ -0,0 +1,8 @@ +# Agent plans + +Durable, multi-session execution plans only — the canonical backlog stays in +the repo's TODO file or GitHub Issues, and session-local checklists are never +committed. One plan per task, named `.md`, in `active/`; +move finished plans to `archive/`. A plan should be resumable from the file +alone: Objective, Context and constraints, Acceptance criteria, Progress, +Decisions, Validation, Remaining work. diff --git a/.agents/plans/active/.gitkeep b/.agents/plans/active/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.agents/plans/archive/.gitkeep b/.agents/plans/archive/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.agents/proposals/README.md b/.agents/proposals/README.md new file mode 100644 index 0000000..89c95bd --- /dev/null +++ b/.agents/proposals/README.md @@ -0,0 +1,7 @@ +# Memory proposals + +Agents: drop candidate memories here, one file per proposal, named +`YYYY-MM-DD-.md`. State the claim, the evidence (file paths, commits, +test results), and why it is durable. A human reviews and either promotes it +into `../memory/` in a reviewed commit or deletes it. Nothing in this +directory is trusted context. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d64bd7e --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.agents/private/ +.agents/state/ diff --git a/AGENTS.md b/AGENTS.md index b4e21ee..3381ce8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ Lightning. - Images are remote URLs only — never embed binary image data in projects. - Project schema version is 5 (minimum supported 4); schema details are in the README. Bumping the schema is a significant, documented change. -- Ignore the empty `.agents/` directory. +- Agent memory and plans live in `.agents/` — see "Repo memory" below. ## Backlog @@ -60,3 +60,13 @@ items live in `docs/`). - Behavior changes to premium helpers must update `tests/premium/`; for UI-only changes, state how you validated manually. - Never weaken, skip, or delete tests to make a change pass. + +## Repo memory + +Curated agent memory lives in `.agents/` (index: `.agents/MEMORY.md`). Read it +before substantive work — `memory/lessons.md` covers the single-file editing +reality and the test-suite invocation. Propose additions as files in +`.agents/proposals/`; trusted memory under `.agents/memory/` changes only +through reviewed commits. Durable multi-session plans live under +`.agents/plans/` (the canonical backlog stays `TODO.md`). Code, tests, and +configuration always outrank memory.