From 38ef8dd6c11806c31bb12c3a86796a9711753340 Mon Sep 17 00:00:00 2001 From: DavidQ Date: Mon, 22 Jun 2026 11:37:32 -0400 Subject: [PATCH 1/2] Add canonical repository structure instructions --- docs_build/dev/ProjectInstructions/README.txt | 3 + .../canonical-repository-structure.md | 78 +++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 project-instructions/addendums/canonical-repository-structure.md diff --git a/docs_build/dev/ProjectInstructions/README.txt b/docs_build/dev/ProjectInstructions/README.txt index 77de19c20..214ab9acb 100644 --- a/docs_build/dev/ProjectInstructions/README.txt +++ b/docs_build/dev/ProjectInstructions/README.txt @@ -40,3 +40,6 @@ READ THIS FIRST 9. Follow OWNER governance decisions. 10. When guidance conflicts, newest OWNER-approved guidance wins. 11. Batch Governance Mode is the default for governance, documentation, and administrative work. + +Addendum index: +- Canonical Repository Structure: project-instructions/addendums/canonical-repository-structure.md diff --git a/project-instructions/addendums/canonical-repository-structure.md b/project-instructions/addendums/canonical-repository-structure.md new file mode 100644 index 000000000..8adff9135 --- /dev/null +++ b/project-instructions/addendums/canonical-repository-structure.md @@ -0,0 +1,78 @@ +# Canonical Repository Structure + +## Purpose + +Prevent technical debt by requiring all new and modified code to follow one repository structure. + +## Canonical Structure + +Tools: +- toolbox/{tool-name}/index.html + +Tool assets: +- assets/toolbox/{tool-name}/js/index.js +- assets/toolbox/{tool-name}/css/index.css + +Themes: +- assets/theme-v1/ +- assets/theme-v2/ + +Shared JavaScript: +- assets/js/shared/ + +Engine: +- src/engine/{feature-name}/ + +API: +- api/{feature-name}/ + +Server: +- server/{feature-name}/ + +Tests: +- tests/toolbox/{tool-name}/ +- tests/engine/{feature-name}/ +- tests/api/{feature-name}/ +- tests/server/{feature-name}/ +- tests/js/shared/ +- tests/regression/ + +## Rules + +- Theme first. Use theme styles whenever possible. +- Tool CSS is allowed only when a requirement cannot be satisfied by the active theme. +- Every tool must be independently testable. +- Regression tests do not replace tool-level tests. +- Shared functionality belongs in assets/js/shared/. +- New development must follow the canonical structure. +- No new scattered JavaScript folders. +- No new scattered CSS folders. +- No new scattered test folders. + +## Legacy Migration + +When a tool is modified: + +1. Review JS location. +2. Review CSS location. +3. Review test location. +4. Move touched files into the canonical structure. +5. Update imports. +6. Update tests. +7. Remove legacy references. + +Legacy files may only be deleted when no active references remain. + +## Folder Ownership + +A folder may contain only assets related to that feature. + +Example: + +assets/toolbox/text-to-speech/ + +may not contain files used exclusively by another tool. + +Shared functionality must be moved to: + +assets/js/shared/ From 18f04a6b18304f9f0e73d4657a4bc30a6d2df639 Mon Sep 17 00:00:00 2001 From: DavidQ Date: Mon, 22 Jun 2026 11:44:12 -0400 Subject: [PATCH 2/2] Add platform development standards instructions --- docs_build/dev/ProjectInstructions/README.txt | 1 + .../platform-development-standards.md | 143 ++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 project-instructions/addendums/platform-development-standards.md diff --git a/docs_build/dev/ProjectInstructions/README.txt b/docs_build/dev/ProjectInstructions/README.txt index 214ab9acb..03d5d8290 100644 --- a/docs_build/dev/ProjectInstructions/README.txt +++ b/docs_build/dev/ProjectInstructions/README.txt @@ -43,3 +43,4 @@ READ THIS FIRST Addendum index: - Canonical Repository Structure: project-instructions/addendums/canonical-repository-structure.md +- Platform Development Standards: project-instructions/addendums/platform-development-standards.md diff --git a/project-instructions/addendums/platform-development-standards.md b/project-instructions/addendums/platform-development-standards.md new file mode 100644 index 000000000..a98ddfd7f --- /dev/null +++ b/project-instructions/addendums/platform-development-standards.md @@ -0,0 +1,143 @@ +# Platform Development Standards + +## Purpose + +Establish repository-wide standards for database usage, entity lifecycle management, creator tool design, and shared component reuse. + +--- + +# PostgreSQL Platform Standard + +## Rules + +- SQLite is deprecated. +- PostgreSQL is the canonical database platform. +- New development must not introduce SQLite. +- New tools must target PostgreSQL. +- New tests must target PostgreSQL. +- New migrations must target PostgreSQL. + +## Legacy + +Existing SQLite references should be removed when touched by active development. + +## Exception + +Owner approval is required for any non-PostgreSQL database implementation. + +--- + +# Referenced Entity Protection + +## Purpose + +Prevent accidental data loss and broken references. + +## Rules + +Entities referenced by another record may not be directly deleted. + +Allowed actions: + +- Archive +- Deprecate +- Replace + +Direct deletion is prohibited while references exist. + +## Examples + +- Messages +- TTS Profiles +- Emotion Profiles +- Characters +- Objects +- Assets +- Worlds +- Tags + +## Exception + +Owner approval required for destructive removal. + +--- + +# Table First Tool Standard + +## Purpose + +Provide a consistent creator experience across all tools. + +## Preferred + +- Table driven interfaces +- Inline editing +- Add row at bottom +- Expandable child rows +- Save and Cancel on the active row + +## Avoid + +- Large data-entry forms +- Separate edit pages +- Wizard-style CRUD workflows + +## Exception + +Forms may be used when table interaction is not practical. + +--- + +# Shared Component Governance + +## Purpose + +Reduce duplicate code across tools. + +## Shared JavaScript Location + +```text +assets/js/shared/ +``` + +## Examples + +- API helpers +- Table helpers +- Status helpers +- Dialog helpers +- Validation helpers + +## Rules + +Functionality used by multiple tools should be moved into shared components. + +Tool-specific functionality remains within the tool folder. + +Shared functionality must not be stored inside an unrelated tool folder. + +## Testing + +Shared functionality must include tests under: + +```text +tests/js/shared/ +``` + +Tool-specific functionality remains tested within its corresponding tool test location. + +--- + +# Governance Enforcement + +## Rules + +New development must follow these standards. + +When modifying existing functionality: + +1. Review compliance with these standards. +2. Correct violations when practical within the scope of the work. +3. Avoid introducing new technical debt. + +Repository-wide standards must exist in Project Instructions and not solely within chat discussions.