suaveplan/AGENTS.md

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/<package_name>"

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.)