# Cabloy Backend Scaffold

> Cabloy Backend Scaffold is an Agent Skill for development published in the cabloy/cabloy repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

This skill should be used when the user needs the Vona backend scaffold/extend path in this Cabloy repo, especially to choose the right `npm run vona` generator or CRUD command and the required backend follow-up after generation. Trigger most strongly on backend requests involving modules, beans, controllers, services, models, entities, DTOs, CRUD, meta.version, field indexes, validation, or backend tests. Do not use it for frontend-first Zova work, stale generated consumer diagnosis, workflow-routing questions, or master-detail / nested-detail aggregation workflows that belong in `cabloy-master-detail`.

- Skill name: `cabloy-backend-scaffold`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/cabloy/cabloy/blob/HEAD/.claude/skills/cabloy-backend-scaffold/SKILL.md
- Repository: cabloy/cabloy (967 GitHub stars when collected)

## SKILL.md

# Cabloy Backend Scaffold

Use this skill when the user wants to add or extend a Vona backend feature thread.

## Goals

1. detect whether the active repository is Cabloy Basic or Cabloy Start
2. stay backend-first unless the request clearly becomes a larger fullstack workflow
3. prefer Vona CLI generation and CRUD tools over manual scaffolding
4. always perform a backend follow-up review so migration, field indexes, DTO/OpenAPI contracts, and tests are not forgotten
5. add a frontend-contract reminder only when the backend change likely affects OpenAPI consumers or generated SDK flows
6. finish with verification guidance that matches the scope of the change

## Step 1: Detect repo and task scope

Check the repository root for these marker files:

- `__CABLOY_BASIC__`
- `__CABLOY_START__`

Interpretation:

- `__CABLOY_BASIC__` present → this is Cabloy Basic
- `__CABLOY_START__` present → this is Cabloy Start
- neither present → inspect nearby scripts and ask before making edition-specific assumptions

Then classify the request:

- **backend-only** if the task is about Vona modules, beans, models, entities, DTOs, CRUD, migration, tests, or backend contracts
- **fullstack** only if the task clearly requires frontend SDK regeneration, frontend page/component work, or a broader cross-stack contract loop

Default to backend-first. Only escalate mentally to a broader fullstack workflow when the backend change obviously crosses the contract boundary.

If the user is still deciding a new business-domain boundary or suite/module naming, use the root `cabloy-domain-planning` skill before scaffolding.

If the task is really a broad cross-stack workflow, consider whether the root `cabloy-workflow` skill is the better primary router.

If the request is not ordinary standalone backend scaffolding but a parent-owned detail aggregation workflow, such as master-detail, nested-detail, aggregate-only detail, standalone-capable detail, or `:tools:masterDetail`, prefer the dedicated `cabloy-master-detail` skill first.

## Step 2: Start from Vona CLI and repo entrypoints

Inspect these surfaces before proposing implementation:

- the repository or workspace `package.json` that owns the scripts
- `npm run vona`
- Vona command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
- `cabloy-docs/backend/` for the relevant backend thread

For deeper reference material, read:

- `references/backend-thread-map.md`
- `references/follow-up-checklist.md`

## Step 3: Choose the correct scaffolding path

### Path A: create one backend bean or module piece

Use `create:*` when the user needs one structural piece such as:

- module
- bean
- controller
- service
- model
- entity
- dto
- test

Typical examples:

- `npm run vona :create:module ...`
- `npm run vona :create:bean controller ...`
- `npm run vona :create:bean dto ...`
- `npm run vona :create:test ...`

### Path B: create a full CRUD thread

Use `tools:*` when the user needs a whole backend thread rather than one isolated file.

Typical example:

- `npm run vona :tools:crud ...`

Choose this path when the user asks for a CRUD feature, an admin-style backend resource thread, or a connected set of controller/service/model/entity/dto/test files.

### Path C: initialize supporting module resources

Use `init:*` when the task is really about module support files rather than business logic itself.

Typical areas include:

- config
- locale
- constant
- asset
- types

## Step 4: Inspect the generated backend thread

After generation, inspect what the CLI created and keep it as the baseline.

Typical backend thread pieces include:

- controller
- service
- model
- entity
- dto
- migration/meta files
- locale files
- tests

Do not throw away the generated structure and rewrite it from scratch unless the generator clearly does not match the task.

## Step 5: Apply backend follow-up logic deliberately

Backend scaffolding is rarely complete after file generation alone. Treat this follow-up review as mandatory.

Check which of these concerns apply:

### Contract and validation

Check whether the feature needs:

- request validation
- DTO design
- OpenAPI metadata
- inferred DTO generation

### Persistence and schema lifecycle

Check whether the feature needs:

- migration/version updates
- `meta.version`
- field indexes
- relation definitions
- datasource or cache considerations

### Verification

Check whether the feature needs:

- unit tests
- `db:reset` or migration verification
- controller action testing
- broader `test` / `tsc` / `build` checks

### Optional frontend-contract reminder

Stay backend-first, but if the backend change likely affects frontend contract consumers, add a reminder such as:

- OpenAPI output may have changed
- frontend SDK or schema-driven layers may need regeneration
- the active edition and frontend flavor may matter for the regeneration path

Do not turn the skill into a full frontend workflow. Only surface the reminder when the contract boundary is clearly involved.

## Step 6: Use docs to avoid missing layers

Use the docs to decide what the generated backend thread still needs.

Especially relevant pages include:

- `cabloy-docs/backend/controller-guide.md`
- `cabloy-docs/backend/service-guide.md`
- `cabloy-docs/backend/model-guide.md`
- `cabloy-docs/backend/entity-guide.md`
- `cabloy-docs/backend/dto-guide.md`
- `cabloy-docs/backend/crud-workflow.md`
- `cabloy-docs/backend/migration-and-changes.md`
- `cabloy-docs/backend/field-indexes.md`
- `cabloy-docs/backend/unit-testing.md`
- `cabloy-docs/backend/validation-guide.md`
- `cabloy-docs/backend/openapi-guide.md`
- `cabloy-docs/backend/dto-infer-generation.md`

## Step 7: Verification guidance

Always end with a verification path that matches the scope of the backend change.

Typical shared checks include:

- `npm run test`
- `npm run tsc`
- `npm run build`

Narrower checks may include:

- module test updates
- route/controller action verification
- migration reset flow
- CRUD workflow test coverage

## Response pattern

When helpful, structure the response around these points:

1. detected edition
2. backend-first or clearly fullstack-sensitive classification
3. recommended Vona CLI path
4. required backend follow-up layers to check
5. optional frontend-contract reminder if applicable
6. verification steps

Keep the response practical. The value of this skill is turning Cabloy backend requests into the right generation + refinement + verification workflow, not writing more prose than necessary.

---

Source: https://www.openparable.com/skill/development/cabloy-backend-scaffold (OpenParable). Cite the canonical URL above.
