doompi-author-extension

# Author a DoomPi extension Build the smallest extension that owns one clear capability and follows the host lifecycle already used by nearby DoomPi packages. ## Choose the environment - Inside the DoomPi monorepo, read `AGENTS.md` and `templates/doom-extension/scaffold.yaml` before writing. Use the canonical `scaffold-doom-extension` definition when it fits, then keep only the folders the capability needs. - Outside the monorepo, create the equivalent public ESM package manually and depend on published DoomPi foundation packages. Never publish `workspace:*` ranges. Choose the package tier from the capability, not convenience: - `packages/core/*` for runtime foundations that must always be present. - `packages/default/*` for normal distribution features selected by default configuration. - `packages/minor/*` for optional modes. - `packages/clients/*` for standalone client-facing processes. - `layers/<layer>/*` for selectable layer extensions. ## Workflow 1. Inspect a nearby package with the same host surfaces and reuse its structure. 2. Put logic in `services/<serviceName>/index.ts`, service ports in `type.ts`, mutable state in `models`, request handlers in `controllers`, and tools in `tools`. Keep reusable types, schemas, and constant data in their named folders. Do not create `adapters`, `container`, `commands`, or `providers` roots. 3. Author each contribution at `src/extensions/<scope>/(backend|frontend)/<surface>/<name>[.<target>].<ext>`. Export one declaration or factory through the typed `define*` helper for that surface. Do not hand-write `pi.ts`, `server.ts`, or `web.ts`; `doompiExtension()` generates them beneath ignored `generated/` and builds the published host artifacts. 4. Return typed contributions from a named declaration or per-mount factory. Factories may be async. Use optional `onStart`, `onStop`, and `onDispose` hooks for lifecycle work; helpers own Cordis initialization, registration, readiness, and cleanup. 5. Put provider plugins in services and include them in the `services` contribution array. Consume required providers inside an owning injection with the corresponding `require...` accessor. The helper handles optional providers for native contributions such as resources and minor modes. 6. Keep package exports explicit and flat under `src/exports`, with only reusable APIs. If the extension contributes Help, publish `src/prompts/<skill-name>/SKILL.md`, link it from `llms.txt`, and declare its descriptor in `resources` with the exact package name and `import.meta.url`. 7. For frontend contributions, add a root `tsconfig.web.json`, keep routed `(frontend)` files out of the Node project, and typecheck both projects. 8. Run the repository checks or equivalent standalone package checks before publishing. Read [references/extension-contract.md](references/extension-contract.md) for the concrete package, lifecycle, and verification contract.