insolvia-new-package

How to add a new package, app, or backend service to the Insolvia monorepo. Use this when scaffolding a new buildable unit — "add a package", "create a new app", "scaffold a service", "new shared libr

SKILL.md

GitHub

Adding a new package / app / service

TypeScript package or app (npm workspace member)

  1. Create it under packages/<name>/ (shared library) or apps/<name>/ (runnable app), with its own package.json and a tsconfig.json that extends the root tsconfig.base.json.
  2. Add it to the root package.json workspaces list by exact path — the list is deliberately explicit and must never become packages/* or apps/*. apps/insolvia_marketing must stay OUT: it consumes @insolvia-ai/design-system by published version, and a member symlink would build it against local source, so a broken package would pass CI and only break after publishing. See the comment block in the root package.json — it owns this reasoning.
  3. Give it a README.md (human: what it is + how to run it via its scripts/) and a CLAUDE.md (agent rules/conventions for that area). Every area has both — see any existing package for the shape. Add a one-line eslint.config.js re-exporting the root eslint.base.js (there is deliberately no discoverable eslint.config.js at the repo root — see that file for why).
  4. If it deploys, add <name>-pr.yml + <name>-<env>.yml workflows (follow the existing <area>-pr.yml / <area>-<env>.yml shape and the PR-gate design in docs/reference/architecture.md) and an infra/envs/* entry. If it ships a container image, its ECR repository comes first, in another repository: add insolvia-shared-<component> to insolvia-services' infra/envs/shared and let that repo's release apply it before the PR here that deploys it — the env root's data "aws_ecr_repository" lookup hard-fails until the repository exists, and nothing orders the two repos' pipelines for you. If the deploy role needs a new grant for it, that is a ci-trust PR there too (the insolvia-deploy-role-permissions skill).
  5. Document it in the map in the root README.md.

Python service (the exception — not a workspace member)

Lives under services/<name>/, is not an npm workspace member (no package.json in the root workspaces list). Use the layered src/ layout every service here shares (see services/api or services/mcp) (core/api/adapters/entrypoints) with a per-service pyproject.toml (pytest) plus the shared root ruff.toml, and its own tests/test_architecture.py enforcing the dependency direction. Steps 3–5 above still apply.

The design system is in another repository

If the new thing is a shared component or a design token, this skill is the wrong door — and so is this repository. @insolvia-ai/design-system and @insolvia-ai/tokens live in insolvia-ai/design-system and reach this repo only as published versions (ADR 0010). Add the component there, publish, then use the insolvia-design-system-bump skill to take the version.

Do not create a local package to hold shared UI as a way around that. The app had a source-level channel to the design system once, through a workspace symlink, and removing it is the whole point of ADR 0010.