SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Commit

Browse Source
This commit is contained in:
admin
2026-05-27 23:29:53 +01:00
commit fbc70f96e6
10000 changed files with 1102152 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
AGENTS.md Normal file
View File

@@ -0,0 +1,32 @@
# Agent Compliance Checklist
1. read STATUS.md to be aware of all the libraries we have migrated and have yet to migrate. STATUS.md is the dashboard table — `✅` migrated, `–` yet to be migrated, `❌` not yet written. SUMMARY.md holds the longer descriptions per package; consult it when STATUS.md's one-liner isn't enough. When working on a library, make the very best effort not to duplicate code, but use a suitable library if available. If the library has yet to be migrated, you must prioritise migrating the library first.
2. read ./openspec/AGENTS.md before doing any work to learn of all the work done and work pending. we are migrating libraries from within ../suaveplan/ (main branch) into this branch (genesis), make sure you adhere to the guidlines set out.
2a. before authoring ANY OpenSpec change, read `./openspec/AGENTS.md` §0c — it defines the change-folder structure and the mandatory spec-delta format. Spec content goes in `openspec/changes/<id>/specs/<capability>/spec.md` as a requirement/scenario delta; it NEVER goes into `openspec/specs/` until the change archives. Architecture and rationale go in `design.md`, not the spec delta.
2b. **Spec-first inventory — mandatory before any code.** Before writing a single line of implementation, open `openspec/changes/<id>/specs/<capability>/spec.md` and create a numbered checklist of every `### Requirement` and every `#### Scenario`. You may NOT start coding until this checklist exists. As you implement each requirement, check it off. If a requirement feels hard, inconvenient, or "not needed yet," you must either (a) implement it exactly as written, or (b) open a follow-up OpenSpec change that explicitly scopes it out with architectural justification. **Never silently skip a requirement because tests can pass without it.** This is the single most common cause of spec drift.
3. These migrations are meant to take existing libraries and elevate them to feature-rich enterprise libraries that are extensible/modular, tree-shakeable. they are not meant to be trimmed down versions, they must retain full functionality. you may split them into loadable plugin libraries that plug into the modularised main migrated library.
4. Code coverage must be 100% on all code files you work on, with 100% passing. use "bunx turbo lint test typecheck build --filter=@suaveplan/&lt;package_name&gt;"
5. When you have completed a library, flip its row in STATUS.md from `–` to `✅` and replace the suaveplan summary with a one-line description from the package's README.md. Place the longer summary in the corresponding plugin section of SUMMARY.md.
6. **Before declaring any library done, verify it against its OpenSpec spec — the package must match the spec, not the other way round.** Past audits found packages that passed their own tests yet silently drifted from the contract. Check every one of these:
- **Dependencies match the spec allowlist exactly.** If the spec's purity/dependency requirement names an allowed set, `package.json` `dependencies` MUST be a subset of it — no extras. Every declared dependency MUST be imported somewhere in `src/` (no unused deps), and every dependency the spec mandates the package *use* MUST actually be imported, not just declared. Grep to confirm: a dep that appears only in `package.json` is a defect.
- **Every requirement is implemented.** Walk each `### Requirement` in the spec and confirm the named classes, functions, constants, spans, counters, histograms, events, and error codes actually exist in `src/` — `grep` for each. A requirement with zero implementing code is a defect even if all tests pass.
- **Every registered error code is reachable.** Each code in the package's error metadata MUST be thrown from (or carried on a report by) a real call site exercised by a test. A registered-but-never-used code is a defect.
- **Every `**Verified by:**` line resolves.** The spec names exact `file::"test name"` references. Each file MUST exist and contain a test whose name matches *verbatim*. Renaming or consolidating a test without updating the spec breaks traceability — keep them in lockstep.
- **Every `.ts` has its sibling `.md`, every feature module has its subpath export.** Confirm the `package.json` `exports` map and the docs-coverage gate before claiming completion.
Run the full pre-publish gate (`bunx turbo lint typecheck test build --filter=@suaveplan/<pkg>` plus `test:coverage`) — but treat green tests as necessary, not sufficient. The spec is the contract; reconcile the package to it.
7. **Error codes: always go through `@suaveplan/error`'s `defineCodes` — never hand-write a code string literal.** Every package's error codes MUST be declared with `defineCodes("<NAMESPACE>", ["REASON_A", "REASON_B", …] as const)`. The resulting code string value is the namespaced **`NAMESPACE.REASON`** form (e.g. `defineCodes("AUDIO_CORE", ["PLUGIN_NOT_FOUND"])` yields the value `"AUDIO_CORE.PLUGIN_NOT_FOUND"`, **not** `"AUDIO_PLUGIN_NOT_FOUND"`). You MUST adhere to this everywhere:
- **In code:** throw `new XxxError(CODES.REASON, …)` using the exported `defineCodes` constant. Never type the raw `"NAMESPACE.REASON"` string by hand anywhere — not in `src/`, not in tests.
- **In tests:** assert against the exported code constant (`expect(err.code).toBe(CODES.REASON)`), never against a hand-typed string literal. Hand-typed literals silently rot when the namespace changes.
- **In specs:** when an OpenSpec requirement or scenario references a code — whether in prose backticks or a `code === "…"` assertion — it MUST use the exact `defineCodes` output (`NAMESPACE.REASON`). A spec that names `AUDIO_PLUGIN_NOT_FOUND` when the code is really `AUDIO_CORE.PLUGIN_NOT_FOUND` is a defect in the spec.
- **On mismatch:** if you find a spec literal that does not match the actual `defineCodes` output, fix the **spec** to match the convention-correct value — do not bend the code's namespace to match a mistaken literal. (`**Verified by:**` test-name strings are human-readable labels and may keep a shortened form, but they must stay verbatim-identical to the real test name.)