| name | monorepo-import |
| description | Plan and execute conservative imports of sibling monitoring services or alerting stacks into this monorepo. Use when moving an external repo/service into `monitoring-monorepo`, reorganizing alerting/service roots, or wiring package, CI, Terraform, deploy, docs, and post-merge verification around an imported subsystem. |
| title | Monorepo Import Skill |
| status | active |
| owner | eng |
| canonical | true |
| last_verified | "2026-05-26T00:00:00.000Z" |
Monorepo Import
Use this for importing or reorganizing a deployable monitoring subsystem inside
this repo. Examples: the Aegis import into top-level aegis/, and the external
mento-protocol/alerts stack landing under alerts/{infra,rules}.
Principle
Preserve runtime behavior first. Do not bundle a redesign, channel migration,
provider swap, or deprecation into the first import unless the user explicitly
widens scope.
Phase 1: Map Before Moving
Inspect both the source system and this repo before proposing a layout:
- source deployable units, package manager, lockfile, CI workflows, Terraform
roots/backends, secrets, scheduled jobs, scripts, docs, and live endpoints
- existing repo roots and ownership boundaries:
aegis/, alerts/,
terraform/, metrics-bridge/, indexer-envio/, ui-dashboard/,
shared-config/
- existing root scripts, package filters, CI path filters, dependency-cruiser
boundaries, AGENTS files, README/docs/runbooks
- current deploy owners: App Engine, Cloud Functions, Terraform, Vercel, Envio,
Grafana, QuickNode, Sentry, Slack/Discord
Do not treat a directory name as authority. For example, terraform/alerts is
the Grafana v3 rule plane, not a generic bucket for every alert-related system.
Phase 2: Choose The Smallest Layout
Default placement rules:
- If the repo already has peer top-level packages, prefer a peer top-level root
for a service package (
aegis/, not services/aegis/).
- For alerting, prefer one discoverable top-level
alerts/ namespace while
preserving deployable subroots underneath it.
- Keep deploy-unit clarity over visual symmetry. Terraform, CI, and operators
must be able to tell what applies independently.
- Leave Aegis-owned Grafana/Terraform under
aegis/ unless the task explicitly
includes moving that ownership boundary.
Good import plan shape:
- target tree
- what is copied unchanged
- what gets repo integration glue
- what deliberately stays out of scope
- verification per deploy unit
- rollback or handoff path
Phase 3: Wire Integration Surfaces
For each imported subsystem, audit and update the relevant surfaces:
pnpm-workspace.yaml, package.json root scripts, package names, lockfiles- package-local
AGENTS.md and README/runbooks
.github/workflows/** and required-status-safe path/filter behavior.dependency-cruiser.cjs, knip config, ESLint, TypeScript, test config- Terraform script entrypoints and backend prefixes/state expectations
- deploy scripts and post-merge deploy workflows
- docs that point at the old standalone repo or old command names
When adding new commands/scripts/workflows, grep canonical docs for stale
patterns and update them in the same PR.
Phase 4: Verify In Layers
Run the narrow local checks for the imported subsystem first, then the repo's
agent gate:
- package build/typecheck/test/lint for imported TypeScript packages
forge test for imported Foundry helpers/contracts- Terraform fmt/init/validate/plan for touched Terraform roots; never apply
without explicit user approval
- workflow syntax and path/filter review for new CI/deploy workflows
pnpm agent:quality-gate --run before opening or updating the PR
If registry/network access is unavailable, do not pretend lockfile or install
work is verified. Surface the blocked command and rerun with network access when
that command is required.
Phase 5: Ship And Confirm Runtime
After merge, verify the real deploy path for any imported deployable:
- GitHub Actions workflow result for the new deploy workflow
- live health/metrics endpoint where applicable
- Terraform state/output when Terraform owns the runtime
- alert delivery or webhook behavior when alerting plumbing changed
Use live deployment state as truth during post-merge verification. Local branch
staleness or a transient git ref lock is not a reason to ignore a successful
workflow plus live endpoint check.
Scope Guards
Stop and ask before:
- changing production alert routing semantics
- migrating Slack/Discord/Sentry channels beyond what the import requires
- applying Terraform
- deleting or archiving the source repo
- changing runtime projects/accounts/backends instead of preserving them
Prefer a follow-up issue/PR for redesigns discovered during the import.
