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.claude/skills/insolvia-new-package/SKILL.md
GitHubAdding a new package / app / service
TypeScript package or app (npm workspace member)
- Create it under
packages/<name>/(shared library) orapps/<name>/(runnable app), with its ownpackage.jsonand atsconfig.jsonthatextendsthe roottsconfig.base.json. - Add it to the root
package.jsonworkspaceslist by exact path — the list is deliberately explicit and must never becomepackages/*orapps/*.apps/insolvia_marketingmust stay OUT: it consumes@insolvia-ai/design-systemby 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 rootpackage.json— it owns this reasoning. - Give it a
README.md(human: what it is + how to run it via itsscripts/) and aCLAUDE.md(agent rules/conventions for that area). Every area has both — see any existing package for the shape. Add a one-lineeslint.config.jsre-exporting the rooteslint.base.js(there is deliberately no discoverableeslint.config.jsat the repo root — see that file for why). - If it deploys, add
<name>-pr.yml+<name>-<env>.ymlworkflows (follow the existing<area>-pr.yml/<area>-<env>.ymlshape and the PR-gate design indocs/reference/architecture.md) and aninfra/envs/*entry. If it ships a container image, its ECR repository comes first, in another repository: addinsolvia-shared-<component>to insolvia-services'infra/envs/sharedand let that repo's release apply it before the PR here that deploys it — the env root'sdata "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 aci-trustPR there too (theinsolvia-deploy-role-permissionsskill). - 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.