Playbook: Remove a Cabloy Module

This playbook turns Cabloy module deletion into a repeatable AI-friendly workflow.

When to use this playbook

Use this playbook when the goal is to remove an existing module from the Cabloy monorepo.

Typical triggers include:

• delete a demo module
• retire a backend module
• remove a frontend module
• remove a fullstack module that exists in both Vona and Zova
• clean up stale generated runtime or type residues after a module was removed

Step 1: Detect the repo and scope

Before deleting anything:

1. detect whether the active repo is Cabloy Basic or Cabloy Start
2. confirm whether the module is backend-only, frontend-only, or fullstack
3. inspect the root package.json
4. inspect npm run vona and npm run zova

This avoids deleting the wrong surfaces or using the wrong edition-specific assumptions.

Step 2: Inventory the real module surfaces

Inspect the real source and direct dependency surfaces first.

Typical locations include:

• vona/src/module/<module> or suite-based backend module roots
• zova/src/module/<module> or suite-based frontend module roots
• vona/package.json
• zova/package.json
• generated registries and lockfiles
• tests that still target the module

If the user asked for a public scrub, also inspect cabloy-docs/. Otherwise, treat docs cleanup as a separate scope decision.

Step 3: Remove source and direct references first

Start by removing the real source and direct workspace package references.

Typical order:

1. remove backend module source if in scope
2. remove frontend module source if in scope
3. remove direct workspace dependency entries from the relevant package.json files
4. refresh or clean generated registrations only after source removal

Do not start by hand-editing generated caches while the real module source or package references still exist.

Step 4: Regenerate with the repo-owned workflow

After source cleanup, use the existing root scripts to refresh generated outputs.

Representative root commands in Cabloy Basic include:

npm run build:zova:admin
npm run deps:vona
npm run deps:zova
npm run tsc
npm run test

Fullstack default sequence

When the module exists on both the Vona and Zova sides, the usual sequence is:

1. npm run build:zova:admin
2. npm run deps:vona
3. npm run deps:zova
4. npm run tsc

This keeps the Zova Admin JS bundle and rest output aligned before Vona consumes downstream artifacts.

Narrower branches

For backend-only removal, prefer the narrowest meaningful verification first:

• npm run deps:vona
• npm run tsc
• npm run test when runtime/test coupling is likely

For frontend-only removal, use the relevant Zova build/deps path first, then typecheck.

Step 5: Clean generated runtime directories when residues remain stale

If stale module types or runtime entries still remain after the normal cleanup and regeneration flow, treat generated runtime directories as disposable working state.

In particular, the primary recovery targets for this workflow are:

• vona/.vona
• zova/.zova

These are not necessarily the only generated working directories in the repo, but they are the main stale-runtime targets for normal module-removal recovery.

Why this is safe:

• these directories are generated by the Vona and Zova CLI flows
• they are ignored by the repo because they are not source-of-truth files
• they may survive when a service or build process does not stop cleanly

After deleting them, rerun the normal regeneration flow and typecheck again.

Step 6: Verify that the module is really gone

Search for remaining references to:

• the module relative name
• the backend workspace package name
• the frontend workspace package name
• route or resource names if applicable

Then verify with the narrowest meaningful commands first, followed by broader checks when needed.

Typical verification commands:

npm run build:zova:admin
npm run deps:vona
npm run deps:zova
npm run tsc
npm run test

The expected result is:

• no direct workspace dependency entries remain
• no generated registry still points at the removed module
• no stale typecheck failures still reference the module
• no important runtime or test surfaces still import it

Step 7: Treat docs cleanup as an explicit second scope

Removing code/runtime surfaces does not automatically mean public docs should be rewritten.

Make this an explicit scope decision:

• code/runtime removal only
• code/runtime removal plus docs/examples scrub

If docs cleanup is in scope, update cabloy-docs/ as a separate pass after runtime cleanup is stable.

AI rule of thumb

A good Cabloy module-removal workflow is usually:

1. detect edition and scope
2. inventory real module surfaces
3. remove source and direct references
4. regenerate with repo entrypoints
5. clean generated runtime dirs only when stale residues remain
6. verify the module is really gone

Not:

1. delete a few generated files first
2. guess which paths matter
3. leave workspace dependencies or generated registrations stale