db-core Code Generation

Use this skill when you need to generate or update any db-core layer in a module:

DB beans
Document beans
DAOs
DB/document converters
Procedures that call DAOs

This skill is designed to keep generation and scaffolding deterministic, schema-driven, and safe across module variants.

What this skill guarantees

Schema-first decisions: generation inputs and converter context fields are inferred from discovered schema/model files, not script aliases alone.
Capability-aware planning: generation resolves from module capabilities (or
```
generate
```
script), with DAO
```
--schemas
```
validation in both
```
--plan auto
```
and
```
--plan chain
```
.
Predictable converter scaffolds: defaults to
```
generated/beans/*
```
imports, enforces
```
convertFrom
```
/
```
convertTo
```
mapping rules, and preserves stable context parameter order.
Safe optional wrappers: validates and uses
```
src/beans/*
```
and
```
src/dao/*
```
only when those wrappers actually exist.
Procedure-safe boundaries: procedure APIs stay DB-oriented while DAO APIs stay document-oriented, with convention-aware scaffolding defaults.
Default audit ownership:
```
created_at
```
/
```
updated_at
```
ownership stays in DAO unless explicitly overridden.
Preflight pause/resume: pause only when
```
node_modules
```
is missing; ask the user to run
```
npm run install-snapshot
```
(override script name via
```
--install-script
```
), then resume after user confirmation.
Self-contained execution: command usage, contracts, and post-change checks are defined in this skill without requiring external definition docs.
Module-local context only: inference, examples, conventions, and edits are restricted to the selected
```
--module
```
root.

NEVER do these (anti-patterns)

NEVER manually edit generated artifacts under
```
generated/beans/*
```
or
```
generated/dao/*
```
.
1. Why: generators overwrite these files, so manual edits drift and are lost on regeneration.
2. Correct action: change schema/model inputs and rerun generation.
NEVER patch generated TypeScript to fix field/type/model mismatches.
1. Why: generated output is derivative; schema/datamodel files are the source of truth.
2. Correct action: update the schema/datamodel inputs first, then regenerate.
NEVER write or modify code outside the target
```
db-core
```
scope during this workflow.
1. Why: cross-scope edits create hidden coupling and unnecessary blast radius.
2. Exception: update code outside
```
db-core
```
  only when the user explicitly asks for it.
NEVER use sibling/other
```
db-core
```
modules for context inference, convention inference, or copy patterns.
1. Why: this introduces cross-module coupling and wrong conventions.
2. Correct action: infer only from files under the selected module root.

Inputs

Collect these before making changes:

```
module selector
```
: exact module path or module hint.

scope

generation-only

converter-only

generation-and-converter

procedure-methods

, or

full-procedure

```
target entities
```
: DB bean + document + DAO + converter names.
```
persistence contract
```
: whether module uses direct
```
generated/dao
```
or optional
```
src/dao
```
wrappers.
```
schema locations
```
: discover from generation scripts when not explicitly provided.

Module boundary protocol (mandatory)

Treat the selected
```
--module
```
directory as the only allowed context root for module files.
Read/inspect only paths that are descendants of that module root when inferring schemas, conventions, converters, procedures, and DAO usage.
Reject any inferred/discovered path that resolves outside module root; do not use it for decisions.
Do not sample procedures/converters from other modules for style inference.
If required files are missing inside module root, report and stop or continue with explicit warning; do not substitute from another module.

Reference loading protocol (mandatory)

Before any implementation, select

scope

and load only the required references.

generation-only

MANDATORY - read entire
```
references/generation-checklist.md
```
.

Do NOT load

references/converter-cookbook.md

references/procedure-cookbook.md

converter-only

MANDATORY - read entire
```
references/converter-cookbook.md
```
.
OPTIONAL - read
```
references/generation-checklist.md
```
only if regeneration is also requested.
Do NOT load
```
references/procedure-cookbook.md
```
.

generation-and-converter

MANDATORY - read entire

references/generation-checklist.md

and

references/converter-cookbook.md

Do NOT load
```
references/procedure-cookbook.md
```
unless procedure scaffolding is explicitly requested.

```
procedure-methods
```
or
```
full-procedure
```
:
1. MANDATORY - read entire
```
references/procedure-cookbook.md
```
  .
2. OPTIONAL - read
```
references/generation-checklist.md
```
  only when generation is in scope.
3. Do NOT load
```
references/converter-cookbook.md
```
  unless converter changes are explicitly requested.
Always report which references were loaded and why before running commands.

Discovery-first workflow (required)

Before creating/updating converters or procedures, do all of the following:

Apply
```
Reference loading protocol (mandatory)
```
and declare loaded files.

Parse module generation scripts and resolve schema/model paths:

document generator (for example

json-to-schemas --datamodel ... --out ...

)

DB generator (for example

jsonschema-to-typescript-objects --input ... --beans-path ...

)

DAO generator (for example

pdm-to-daos --datamodel ... --schemas ... --out ...

)

Resolve all script-relative paths against module root, verify they exist, and verify each resolved path stays within module root.
Read discovered schemas/models to capture per-entity:
1. required document keys (PK/SK/index keys)
2. ```
@entity
```
  discriminator/default
3. field requiredness and types
Infer converter context fields from schema requirements:
1. include required document keys not sourced from DB bean fields
2. prioritize partition/sort keys, then required index keys
3. keep parameter names consistent with existing module converter/procedure patterns
If multiple context-field candidates are plausible:
1. rank candidates with brief reasoning
2. choose the best candidate and proceed
3. surface the decision in output
Missing discovered model/schema files should fail inference (or be surfaced as warnings when non-blocking).

Script commands

Run from repository root.

Generation

bash

python .agents/skills/db-core-codegen/scripts/run_dbcore_codegen.py \
  --module <module_root> \
  --plan auto

--plan auto

Uses
```
generate
```
script if available.
Otherwise resolves chain by capability (DB, document, DAO, optional tx DAO).

--plan chain

Always resolves chain by capability.
Requires DB + document + DAO capabilities.
Includes tx DAO only when available or explicitly requested.

Install preflight:

Before running generation scripts, checks

generated/beans/db

generated/beans/document

, and

generated/dao

Also checks whether
```
node_modules
```
exists.
If
```
node_modules
```
is missing, do not run install commands automatically; pause and ask the user to run
```
npm run install-snapshot
```
.
Missing/empty generated outputs are surfaced in preflight metadata, but generation still proceeds when
```
node_modules
```
exists.
Override install script name with
```
--install-script <script-name>
```
.

Pause/resume protocol:

On preflight failure, stop generation and report the exact command and module root to the user.
Do not execute install/setup commands on behalf of the user.
After user confirms completion, rerun the same generation command to resume.

Converter scaffolding

Flat converter layout:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir . \
  --db-type Account \
  --document-type Account \
  --entity-id com.example.document.account \
  --with-list

Nested converter layout:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir events/event-subscription \
  --db-type EventSubscription \
  --document-type EventSubscription \
  --entity-id com.example.document.event_subscription \
  --context-field user_id:userId

--context-field

is omitted, context fields are inferred from discovered schema/model metadata.

Procedure scaffolding

CRUD method scaffolding with convention-aware defaults:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_procedure.py \
  --module <module_root> \
  --db-type Link \
  --document-type Link \
  --methods get,post,update

Common overrides:

```
--timestamp-strategy procedure|dao
```
to override timestamp ownership (default:
```
dao
```
).
```
--post-generate-id always|never
```
to force UUID generation behavior.

--beans-import-style index|entity

and

--dao-import-style index|entity

--dao-class <EntityDaoClass>

and

--dao-method-*

when DAO naming differs.

Contracts

Generation contract

Validate selected DAO/tx DAO scripts have correct
```
--schemas
```
usage.
Run install preflight checks before generation; pause for manual user action only when
```
node_modules
```
is missing.

Validate generated outputs:

```
generated/beans/db
```
```
generated/beans/document
```
```
generated/dao
```

Validate wrappers only if wrapper files exist.
Validate package export/type contracts when present.

Converter contract

```
convertFrom(document)
```
maps
```
Document -> DB
```
.
```
convertTo(db, ...context)
```
maps
```
DB -> Document
```
.
```
convertTo
```
must set
```
@entity
```
.
Context keys must come from schema-first inference and be explicit typed parameters.
Context parameter order should be stable:
1. partition key context
2. sort key context not available on DB bean
3. required index context
Failures must throw
```
ConverterException
```
.

Procedure contract

Procedure boundary accepts/returns DB objects.
DAO boundary accepts/returns document objects.
Procedures should use DAOs via module capability:
1. ```
generated/dao
```
  by default.
2. ```
src/dao
```
  wrappers only when that capability exists in the module.
DAO selection must be explicit from method intent:
1. Use
```
TableDao
```
  for query/list/index pagination and non-atomic batch access.
2. Use
```
TransactionDao
```
  only when atomic all-or-nothing behavior or cross-item invariant enforcement is required.
3. If atomicity is not explicitly required, default to
```
TableDao
```
  (or
```
EntityDao
```
  for single-item key CRUD).
Capture and report DAO choice inputs when scaffolding procedure methods:
1. operation type (
```
query/list
```
  ,
```
single-item CRUD
```
  ,
```
multi-item mutation
```
  )
2. atomicity required (
```
true/false
```
  )
3. invariant scope (single item vs cross-item/cross-entity)
Audit timestamps (
```
created_at
```
/
```
updated_at
```
and camel variants) are DAO-managed by default.
1. Use
```
--timestamp-strategy procedure
```
  only when a module intentionally follows that non-default pattern.
2. Surface the chosen strategy in output.

Output checklist

After changes:

Generation plan is explicit and valid for detected module capabilities.
Converter files compile and exports are updated idempotently.
No hard failures due to absent optional wrapper files.
Discovered schema/model paths are reported.
Inferred context fields are reported per entity with brief reasoning.
Dry-run output is available (human +
```
--json
```
modes).

--json

output includes:

```
discovered_schema_paths
```
```
selected_script_paths
```
```
validated_schema_targets
```
```
inferred_context_fields
```
```
context_decisions
```
```
entity_metadata
```

install_preflight

(

script

script_exists

command

executed

manual_action_required

missing_outputs

missing_node_modules

)

Procedure scaffold output (when used) reports:
1. resolved conventions
2. resolved import styles
3. selected mutation strategy

Report

loaded_references

and

reference_selection_reason

Confirm no manual edits to generated files and no out-of-scope (
```
db-core
```
) changes unless explicitly requested by the user.
Report
```
module_root
```
and confirm all module-file context paths used for inference were under that root.

References

Load these only through the

Reference loading protocol (mandatory)

above.

```
references/generation-checklist.md
```
```
references/converter-cookbook.md
```
```
references/procedure-cookbook.md
```

db-core-codegen

NPX Install

Tags

SKILL.md Content

db-core Code Generation

What this skill guarantees

NEVER do these (anti-patterns)

Inputs

Module boundary protocol (mandatory)

Reference loading protocol (mandatory)

Discovery-first workflow (required)

Script commands

Generation

Converter scaffolding

Procedure scaffolding

Contracts

Generation contract

Converter contract

Procedure contract

Output checklist

References