AGENTS.md — Harness Packages

These package-specific rules supplement the repo-wide conventions.

Plugin export shape: service packages default-export their service class; function plugins named-export name / inject / Config / apply and have no default export. Mixing the forms makes the Loader discard the function plugin's namespace (postmortem).
Optional services use ctx.get(name). Reserve ctx.<name> for declared injections; the property proxy is topology-sensitive, while strict ctx.get reads the global service store (postmortem).
Product-visible plugins require a non-unit REAL-composition test. Hand-built ctx.plugin(...) suites are insufficient. Boot test-only cordis.yml through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. Policy.
Typed same-process service and plugin calls are contracts, not serialization boundaries. Prefer readonly borrowed values; materialize or defensively validate only at parser/config, queued, model/tool JSON, durable/file, worker, process, or wire boundaries.
Represent one asynchronous operation with one lifecycle controller or transaction. Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.

Naming notes:

src/types.ts contains only types — no runtime code.
Tests live at package level under tests/, not src/__tests__/.
A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. doc-sync gates what it can; apply dsh-prose-standard for complete, concise prose and verify accuracy against code.
Package READMEs document model/token effects using the canonical Model Experience format.
Package READMEs put durable consumer gaps and non-obvious maintainer constraints under ## Known Limitations and Deferred Work; ordinary cleanup stays in its TODO or RFC. Packages with none use a justified allowlist entry (rationale).