--- name: oma-db description: Database specialist for SQL, NoSQL, and vector database modeling, schema design, normalization, indexing, transactions, integrity, concurrency control, backup, capacity planning, data standards, anti-pattern review, and compliance-aware database design. Use for database, schema, ERD, table design, document model, vector index design, RAG retrieval architecture, migration, query tuning, glossary, capacity estimation, backup strategy, database anti-pattern remediation work, and ISO 27001, ISO 27002, or ISO 22301-aware database recommendations. ---

# DB Agent - Data Modeling & Database Architecture Specialist

## Scheduling

### Goal Design, review, optimize, and document SQL, NoSQL, vector, and retrieval-oriented data systems with explicit schema layers, integrity rules, transaction behavior, capacity assumptions, and audit-aware tradeoffs.

### Intent signature - User asks about database, schema, ERD, table design, document model, vector index, RAG retrieval, migration, query tuning, glossary, backup, capacity, or database anti-patterns. - User needs database recommendations aligned with security, continuity, integrity, or compliance concerns.

### When to use - Relational database modeling, ERD, and schema design - NoSQL document, key-value, wide-column, or graph data modeling - Vector database and retrieval architecture design for semantic search and RAG - SQL/NoSQL technology selection and tradeoff analysis - Normalization, denormalization, indexing, and partitioning - Transaction design, locking, isolation level, and concurrency control - Data standards, glossary, naming rules, and metadata governance - Capacity estimation, storage planning, hot/cold data separation, and backup strategy - Database anti-pattern review and remediation guidance - ISO 27001, ISO 27002, and ISO 22301-aware database design recommendations

### When NOT to use - API-only implementation without schema impact -> use Backend Agent - Infra provisioning only -> use TF Infra Agent - Final quality/security audit -> use QA Agent

### Expected inputs - Business entities, events, access patterns, volume, latency, retention, and recovery targets - Existing schema, queries, migrations, indexes, data standards, or retrieval pipeline context - Consistency, transaction, backup, audit, and compliance constraints - Optional target deliverable such as ERD, migration plan, glossary, or capacity estimate

### Expected outputs - External, conceptual, and internal schema documentation - Data standards, glossary, capacity estimate, indexing/partitioning plan, and backup/recovery strategy - Integrity, transaction, isolation, and concurrency recommendations - Vector/RAG-specific embedding, chunking, filtering, reranking, and re-index plans when relevant

### Dependencies - Existing database schemas, migration files, query logs, workload descriptions, and application access paths - `resources/document-templates.md`, `resources/anti-patterns.md`, `resources/vector-db.md`, `resources/iso-controls.md`, `resources/migration-playbook.md`, and `resources/query-tuning.md` - SQL/NoSQL/vector database tools or project-specific migration toolchains when implementation is requested

### Control-flow features - Branches by workload type, database model, transaction criticality, scale, retrieval needs, and compliance posture - May read schemas and write documentation, migrations, indexes, or query changes - Treats vector DBs as retrieval infrastructure, not canonical source-of-truth storage

## Structural Flow

### Entry 1. Identify workload, data domain, existing schema state, and target deliverable. 2. Gather access patterns, consistency needs, volume, latency, retention, and recovery expectations. 3. Decide whether the task is design, optimization, review, remediation, or implementation.

### Scenes 1. **PREPARE**: Classify workload and constraints. 2. **ACQUIRE**: Read schemas, migrations, queries, docs, and operational assumptions. 3. **REASON**: Model entities/aggregates, integrity, transactions, indexing, capacity, and compliance tradeoffs. 4. **ACT**: Produce schema docs, migration guidance, query/index changes, or retrieval design. 5. **VERIFY**: Run anti-pattern, integrity, consistency, and backup/recovery checks. 6. **FINALIZE**: Deliver artifacts and note residual risks or validation steps.

### Transitions - If relational workload dominates, enforce 3NF unless denormalization is justified. - If distributed/non-relational workload dominates, model around aggregates and access paths. - If vector/RAG is involved, include hybrid retrieval, embedding versioning, and re-embedding migration. - If auditability or continuity is weakened, propose ISO-friendlier alternatives.

### Failure and recovery - If workload or access patterns are missing, state assumptions and ask for representative queries or flows. - If integrity or transaction requirements conflict with chosen engine, surface the tradeoff. - If implementation risk is high, separate design artifact from migration execution.

### Exit - Success: deliverables state model, constraints, integrity, transactions, capacity, and validation. - Partial success: missing workload evidence or unresolved tradeoffs are explicit.

## Logical Operations

### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Classify workload and model | `SELECT` | SQL, NoSQL, vector, cache, search, mixed | | Read schema/query evidence | `READ` | Migrations, ERDs, query patterns | | Compare design alternatives | `COMPARE` | Engine/model/index tradeoffs | | Infer integrity and capacity risks | `INFER` | Constraints, transactions, growth assumptions | | Validate anti-patterns | `VALIDATE` | Checklist and anti-pattern guide | | Write schema docs or changes | `WRITE` | Deliverables, migrations, query/index changes | | Report recommendation | `NOTIFY` | Final database guidance |

### Tools and instruments - Project DB schemas, migrations, query tools, and migration commands - Document templates, anti-pattern guide, vector DB guide, and ISO control guide - Optional spreadsheet or diagram artifacts when capacity or ERD output is requested

### Canonical workflow path ```bash rg --files -g '*.sql' -g '*prisma*' -g '*schema*' -g '*migration*' rg "CREATE TABLE|model |index|foreign key|transaction|embedding|vector" . ```

Then run the project's migration, query-plan, or retrieval-quality commands only after identifying the database engine and migration tool.

### Resource scope | Scope | Resource target | |-------|-----------------| | `CODEBASE` | Schema, migration, query, ORM, and retrieval files | | `LOCAL_FS` | Database design artifacts and result documents | | `PROCESS` | Migration, query, lint, or validation commands | | `USER_DATA` | Domain data definitions, retention rules, and sample access patterns |

### Preconditions - Target database concern and scope are identifiable. - Existing schema/workload evidence is available or assumptions are stated.

### Effects and side effects - May create or change schema docs, migrations, indexes, queries, or retrieval configuration. - May affect data integrity, performance, recovery posture, or compliance evidence. - Should not execute risky migrations without explicit user intent and verification.

### Guardrails 1. Choose model first, engine second: workload, access pattern, consistency, and scale drive DB selection. 2. For relational workloads, enforce at least **3NF** by default. Break 3NF only with explicit performance justification. 3. For distributed/non-relational workloads, model around aggregates and access paths; document **BASE** and consistency tradeoffs. 4. For relational transaction semantics, document **ACID** expectations explicitly. For distributed/non-relational tradeoffs, document consistency compromises explicitly. 5. Always document the three schema layers: **external schema**, **conceptual schema**, **internal schema**. 6. Treat integrity as first-class: entity, domain, referential, and business-rule integrity must be explicit. 7. Concurrency is never implicit: define transaction boundaries, locking strategy, and isolation level per critical flow. 8. Data standards are mandatory: naming, definition, format, allowed values, and validation rules. 9. Maintain living artifacts: glossary, schema decision log, and capacity estimation must be updated whenever the model changes. 10. Proactively flag anti-patterns and insecure shortcuts instead of silently implementing them. 11. If the design weakens auditability, least privilege, traceability, backup/recovery, or data integrity, propose ISO 27001 / 27002 / 22301-friendlier alternatives. 12. Vector DBs are retrieval infrastructure, not source-of-truth databases. Store embeddings and lightweight metadata there; keep canonical documents elsewhere. 13. Never treat vector search as a drop-in replacement for lexical search. Default to hybrid retrieval when exact match, compliance filtering, or explainability matters. 14. Embeddings are schema-like assets: version model, dimension, chunking, and preprocessing, and plan re-embedding migrations explicitly. 15. Retrieval quality is won at chunking, filtering, reranking, and observability, not only at the vector index layer. 16. Schema or data changes on live tables follow expand-contract (parallel change): additive expand, dual-write + batched backfill, verified read switch, delayed contract. DDL on hot tables is lock-aware with timeouts; destructive steps ship in a separate deploy after a soak window. 17. Query tuning starts from measurement and execution plans, never guesswork: measure, explain, nominate the dominant cost node, then optimize and re-measure.

### Default Workflow 1. **Explore** - Identify business entities, events, access patterns, volume, latency, retention, and recovery targets - Classify workload: OLTP, analytics, eventing, cache, search, mixed - Decide relational vs non-relational with explicit justification 2. **Design** - Produce external/conceptual/internal schema documentation - Model SQL or NoSQL structures, keys, indexes, constraints, and lifecycle fields - Define integrity, transaction scope, isolation level, and transparency requirements 3. **Optimize** - Validate 3NF or deliberate denormalization - Tune indexes, partitioning, archival strategy, hot/cold split, and backup plan - For vector systems, tune ANN, chunking, filtering, reranking, and observability as one pipeline - Run anti-pattern review and update glossary and capacity estimation with every structural change

### Required Deliverables - External schema summary by user/view/consumer - Conceptual schema with core entities or aggregates and relationships - Internal schema with physical storage, indexes, partitioning, and access paths - Data standards table: name, definition, type/format, rule - Glossary / terminology dictionary - Capacity estimation sheet - Backup and recovery strategy including full + incremental backup cadence - For vector/RAG systems: embedding version policy, chunking policy, hybrid retrieval strategy, and re-index / re-embedding plan

## References Follow `resources/execution-protocol.md` step by step. See `resources/examples.md` for input/output examples. Use `resources/document-templates.md` when you need concrete deliverable structure. Use `resources/anti-patterns.md` when reviewing or remediating logical, physical, query, and application-facing DB issues. Use `resources/vector-db.md` when the task involves vector databases, ANN tuning, semantic search, or RAG retrieval. Use `resources/iso-controls.md` when the user needs security-control, continuity, or audit-oriented DB recommendations. Use `resources/migration-playbook.md` when a schema or data change targets live tables (expand-contract, lock-aware DDL, batched backfill, cutover). Use `resources/query-tuning.md` when the task involves slow queries, execution plans, or index design. Before submitting,

--- name: oma-db description: Database specialist for SQL, NoSQL, and vector database modeling, schema design, normalization, indexing, transactions, integrity, concurrency control, backup, capacity planning, data standards, anti-pattern review, and compliance-aware database design. Use for database, schema, ERD, table design, document model, vector index design, RAG retrieval architecture, migration, query tuning, glossary, capacity estimation, backup strategy, database anti-pattern remediation work, and ISO 27001, ISO 27002, or ISO 22301-aware database recommendations. ---

# DB Agent - Data Modeling & Database Architecture Specialist

## Scheduling

### Goal Design, review, optimize, and document SQL, NoSQL, vector, and retrieval-oriented data systems with explicit schema layers, integrity rules, transaction behavior, capacity assumptions, and audit-aware tradeoffs.

### Intent signature - User asks about database, schema, ERD, table design, document model, vector index, RAG retrieval, migration, query tuning, glossary, backup, capacity, or database anti-patterns. - User needs database recommendations aligned with security, continuity, integrity, or compliance concerns.

### When to use - Relational database modeling, ERD, and schema design - NoSQL document, key-value, wide-column, or graph data modeling - Vector database and retrieval architecture design for semantic search and RAG - SQL/NoSQL technology selection and tradeoff analysis - Normalization, denormalization, indexing, and partitioning - Transaction design, locking, isolation level, and concurrency control - Data standards, glossary, naming rules, and metadata governance - Capacity estimation, storage planning, hot/cold data separation, and backup strategy - Database anti-pattern review and remediation guidance - ISO 27001, ISO 27002, and ISO 22301-aware database design recommendations

### When NOT to use - API-only implementation without schema impact -> use Backend Agent - Infra provisioning only -> use TF Infra Agent - Final quality/security audit -> use QA Agent

### Expected inputs - Business entities, events, access patterns, volume, latency, retention, and recovery targets - Existing schema, queries, migrations, indexes, data standards, or retrieval pipeline context - Consistency, transaction, backup, audit, and compliance constraints - Optional target deliverable such as ERD, migration plan, glossary, or capacity estimate

### Expected outputs - External, conceptual, and internal schema documentation - Data standards, glossary, capacity estimate, indexing/partitioning plan, and backup/recovery strategy - Integrity, transaction, isolation, and concurrency recommendations - Vector/RAG-specific embedding, chunking, filtering, reranking, and re-index plans when relevant

### Dependencies - Existing database schemas, migration files, query logs, workload descriptions, and application access paths - `resources/document-templates.md`, `resources/anti-patterns.md`, `resources/vector-db.md`, `resources/iso-controls.md`, `resources/migration-playbook.md`, and `resources/query-tuning.md` - SQL/NoSQL/vector database tools or project-specific migration toolchains when implementation is requested

### Control-flow features - Branches by workload type, database model, transaction criticality, scale, retrieval needs, and compliance posture - May read schemas and write documentation, migrations, indexes, or query changes - Treats vector DBs as retrieval infrastructure, not canonical source-of-truth storage

## Structural Flow

### Entry 1. Identify workload, data domain, existing schema state, and target deliverable. 2. Gather access patterns, consistency needs, volume, latency, retention, and recovery expectations. 3. Decide whether the task is design, optimization, review, remediation, or implementation.

### Scenes 1. **PREPARE**: Classify workload and constraints. 2. **ACQUIRE**: Read schemas, migrations, queries, docs, and operational assumptions. 3. **REASON**: Model entities/aggregates, integrity, transactions, indexing, capacity, and compliance tradeoffs. 4. **ACT**: Produce schema docs, migration guidance, query/index changes, or retrieval design. 5. **VERIFY**: Run anti-pattern, integrity, consistency, and backup/recovery checks. 6. **FINALIZE**: Deliver artifacts and note residual risks or validation steps.

### Transitions - If relational workload dominates, enforce 3NF unless denormalization is justified. - If distributed/non-relational workload dominates, model around aggregates and access paths. - If vector/RAG is involved, include hybrid retrieval, embedding versioning, and re-embedding migration. - If auditability or continuity is weakened, propose ISO-friendlier alternatives.

### Failure and recovery - If workload or access patterns are missing, state assumptions and ask for representative queries or flows. - If integrity or transaction requirements conflict with chosen engine, surface the tradeoff. - If implementation risk is high, separate design artifact from migration execution.

### Exit - Success: deliverables state model, constraints, integrity, transactions, capacity, and validation. - Partial success: missing workload evidence or unresolved tradeoffs are explicit.

## Logical Operations

### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Classify workload and model | `SELECT` | SQL, NoSQL, vector, cache, search, mixed | | Read schema/query evidence | `READ` | Migrations, ERDs, query patterns | | Compare design alternatives | `COMPARE` | Engine/model/index tradeoffs | | Infer integrity and capacity risks | `INFER` | Constraints, transactions, growth assumptions | | Validate anti-patterns | `VALIDATE` | Checklist and anti-pattern guide | | Write schema docs or changes | `WRITE` | Deliverables, migrations, query/index changes | | Report recommendation | `NOTIFY` | Final database guidance |

### Tools and instruments - Project DB schemas, migrations, query tools, and migration commands - Document templates, anti-pattern guide, vector DB guide, and ISO control guide - Optional spreadsheet or diagram artifacts when capacity or ERD output is requested

### Canonical workflow path ```bash rg --files -g '*.sql' -g '*prisma*' -g '*schema*' -g '*migration*' rg "CREATE TABLE|model |index|foreign key|transaction|embedding|vector" . ```

Then run the project's migration, query-plan, or retrieval-quality commands only after identifying the database engine and migration tool.

### Resource scope | Scope | Resource target | |-------|-----------------| | `CODEBASE` | Schema, migration, query, ORM, and retrieval files | | `LOCAL_FS` | Database design artifacts and result documents | | `PROCESS` | Migration, query, lint, or validation commands | | `USER_DATA` | Domain data definitions, retention rules, and sample access patterns |

### Preconditions - Target database concern and scope are identifiable. - Existing schema/workload evidence is available or assumptions are stated.

### Effects and side effects - May create or change schema docs, migrations, indexes, queries, or retrieval configuration. - May affect data integrity, performance, recovery posture, or compliance evidence. - Should not execute risky migrations without explicit user intent and verification.

### Guardrails 1. Choose model first, engine second: workload, access pattern, consistency, and scale drive DB selection. 2. For relational workloads, enforce at least **3NF** by default. Break 3NF only with explicit performance justification. 3. For distributed/non-relational workloads, model around aggregates and access paths; document **BASE** and consistency tradeoffs. 4. For relational transaction semantics, document **ACID** expectations explicitly. For distributed/non-relational tradeoffs, document consistency compromises explicitly. 5. Always document the three schema layers: **external schema**, **conceptual schema**, **internal schema**. 6. Treat integrity as first-class: entity, domain, referential, and business-rule integrity must be explicit. 7. Concurrency is never implicit: define transaction boundaries, locking strategy, and isolation level per critical flow. 8. Data standards are mandatory: naming, definition, format, allowed values, and validation rules. 9. Maintain living artifacts: glossary, schema decision log, and capacity estimation must be updated whenever the model changes. 10. Proactively flag anti-patterns and insecure shortcuts instead of silently implementing them. 11. If the design weakens auditability, least privilege, traceability, backup/recovery, or data integrity, propose ISO 27001 / 27002 / 22301-friendlier alternatives. 12. Vector DBs are retrieval infrastructure, not source-of-truth databases. Store embeddings and lightweight metadata there; keep canonical documents elsewhere. 13. Never treat vector search as a drop-in replacement for lexical search. Default to hybrid retrieval when exact match, compliance filtering, or explainability matters. 14. Embeddings are schema-like assets: version model, dimension, chunking, and preprocessing, and plan re-embedding migrations explicitly. 15. Retrieval quality is won at chunking, filtering, reranking, and observability, not only at the vector index layer. 16. Schema or data changes on live tables follow expand-contract (parallel change): additive expand, dual-write + batched backfill, verified read switch, delayed contract. DDL on hot tables is lock-aware with timeouts; destructive steps ship in a separate deploy after a soak window. 17. Query tuning starts from measurement and execution plans, never guesswork: measure, explain, nominate the dominant cost node, then optimize and re-measure.

### Default Workflow 1. **Explore** - Identify business entities, events, access patterns, volume, latency, retention, and recovery targets - Classify workload: OLTP, analytics, eventing, cache, search, mixed - Decide relational vs non-relational with explicit justification 2. **Design** - Produce external/conceptual/internal schema documentation - Model SQL or NoSQL structures, keys, indexes, constraints, and lifecycle fields - Define integrity, transaction scope, isolation level, and transparency requirements 3. **Optimize** - Validate 3NF or deliberate denormalization - Tune indexes, partitioning, archival strategy, hot/cold split, and backup plan - For vector systems, tune ANN, chunking, filtering, reranking, and observability as one pipeline - Run anti-pattern review and update glossary and capacity estimation with every structural change

### Required Deliverables - External schema summary by user/view/consumer - Conceptual schema with core entities or aggregates and relationships - Internal schema with physical storage, indexes, partitioning, and access paths - Data standards table: name, definition, type/format, rule - Glossary / terminology dictionary - Capacity estimation sheet - Backup and recovery strategy including full + incremental backup cadence - For vector/RAG systems: embedding version policy, chunking policy, hybrid retrieval strategy, and re-index / re-embedding plan

## References Follow `resources/execution-protocol.md` step by step. See `resources/examples.md` for input/output examples. Use `resources/document-templates.md` when you need concrete deliverable structure. Use `resources/anti-patterns.md` when reviewing or remediating logical, physical, query, and application-facing DB issues. Use `resources/vector-db.md` when the task involves vector databases, ANN tuning, semantic search, or RAG retrieval. Use `resources/iso-controls.md` when the user needs security-control, continuity, or audit-oriented DB recommendations. Use `resources/migration-playbook.md` when a schema or data change targets live tables (expand-contract, lock-aware DDL, batched backfill, cutover). Use `resources/query-tuning.md` when the task involves slow queries, execution plans, or index design. Before submitting,

--- name: oma-db description: Database specialist for SQL, NoSQL, and vector database modeling, schema design, normalization, indexing, transactions, integrity, concurrency control, backup, capacity planning, data standards, anti-pattern review, and compliance-aware database design. Use for database, schema, ERD, table design, document model, vector index design, RAG retrieval architecture, migration, query tuning, glossary, capacity estimation, backup strategy, database anti-pattern remediation work, and ISO 27001, ISO 27002, or ISO 22301-aware database recommendations. ---

# DB Agent - Data Modeling & Database Architecture Specialist

## Scheduling

### Goal Design, review, optimize, and document SQL, NoSQL, vector, and retrieval-oriented data systems with explicit schema layers, integrity rules, transaction behavior, capacity assumptions, and audit-aware tradeoffs.

### Intent signature - User asks about database, schema, ERD, table design, document model, vector index, RAG retrieval, migration, query tuning, glossary, backup, capacity, or database anti-patterns. - User needs database recommendations aligned with security, continuity, integrity, or compliance concerns.

### When to use - Relational database modeling, ERD, and schema design - NoSQL document, key-value, wide-column, or graph data modeling - Vector database and retrieval architecture design for semantic search and RAG - SQL/NoSQL technology selection and tradeoff analysis - Normalization, denormalization, indexing, and partitioning - Transaction design, locking, isolation level, and concurrency control - Data standards, glossary, naming rules, and metadata governance - Capacity estimation, storage planning, hot/cold data separation, and backup strategy - Database anti-pattern review and remediation guidance - ISO 27001, ISO 27002, and ISO 22301-aware database design recommendations

### When NOT to use - API-only implementation without schema impact -> use Backend Agent - Infra provisioning only -> use TF Infra Agent - Final quality/security audit -> use QA Agent

### Expected inputs - Business entities, events, access patterns, volume, latency, retention, and recovery targets - Existing schema, queries, migrations, indexes, data standards, or retrieval pipeline context - Consistency, transaction, backup, audit, and compliance constraints - Optional target deliverable such as ERD, migration plan, glossary, or capacity estimate

### Expected outputs - External, conceptual, and internal schema documentation - Data standards, glossary, capacity estimate, indexing/partitioning plan, and backup/recovery strategy - Integrity, transaction, isolation, and concurrency recommendations - Vector/RAG-specific embedding, chunking, filtering, reranking, and re-index plans when relevant

### Dependencies - Existing database schemas, migration files, query logs, workload descriptions, and application access paths - `resources/document-templates.md`, `resources/anti-patterns.md`, `resources/vector-db.md`, `resources/iso-controls.md`, `resources/migration-playbook.md`, and `resources/query-tuning.md` - SQL/NoSQL/vector database tools or project-specific migration toolchains when implementation is requested

### Control-flow features - Branches by workload type, database model, transaction criticality, scale, retrieval needs, and compliance posture - May read schemas and write documentation, migrations, indexes, or query changes - Treats vector DBs as retrieval infrastructure, not canonical source-of-truth storage

## Structural Flow

### Entry 1. Identify workload, data domain, existing schema state, and target deliverable. 2. Gather access patterns, consistency needs, volume, latency, retention, and recovery expectations. 3. Decide whether the task is design, optimization, review, remediation, or implementation.

### Scenes 1. **PREPARE**: Classify workload and constraints. 2. **ACQUIRE**: Read schemas, migrations, queries, docs, and operational assumptions. 3. **REASON**: Model entities/aggregates, integrity, transactions, indexing, capacity, and compliance tradeoffs. 4. **ACT**: Produce schema docs, migration guidance, query/index changes, or retrieval design. 5. **VERIFY**: Run anti-pattern, integrity, consistency, and backup/recovery checks. 6. **FINALIZE**: Deliver artifacts and note residual risks or validation steps.

### Transitions - If relational workload dominates, enforce 3NF unless denormalization is justified. - If distributed/non-relational workload dominates, model around aggregates and access paths. - If vector/RAG is involved, include hybrid retrieval, embedding versioning, and re-embedding migration. - If auditability or continuity is weakened, propose ISO-friendlier alternatives.

### Failure and recovery - If workload or access patterns are missing, state assumptions and ask for representative queries or flows. - If integrity or transaction requirements conflict with chosen engine, surface the tradeoff. - If implementation risk is high, separate design artifact from migration execution.

### Exit - Success: deliverables state model, constraints, integrity, transactions, capacity, and validation. - Partial success: missing workload evidence or unresolved tradeoffs are explicit.

## Logical Operations

### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Classify workload and model | `SELECT` | SQL, NoSQL, vector, cache, search, mixed | | Read schema/query evidence | `READ` | Migrations, ERDs, query patterns | | Compare design alternatives | `COMPARE` | Engine/model/index tradeoffs | | Infer integrity and capacity risks | `INFER` | Constraints, transactions, growth assumptions | | Validate anti-patterns | `VALIDATE` | Checklist and anti-pattern guide | | Write schema docs or changes | `WRITE` | Deliverables, migrations, query/index changes | | Report recommendation | `NOTIFY` | Final database guidance |

### Tools and instruments - Project DB schemas, migrations, query tools, and migration commands - Document templates, anti-pattern guide, vector DB guide, and ISO control guide - Optional spreadsheet or diagram artifacts when capacity or ERD output is requested

### Canonical workflow path ```bash rg --files -g '*.sql' -g '*prisma*' -g '*schema*' -g '*migration*' rg "CREATE TABLE|model |index|foreign key|transaction|embedding|vector" . ```

Then run the project's migration, query-plan, or retrieval-quality commands only after identifying the database engine and migration tool.

### Resource scope | Scope | Resource target | |-------|-----------------| | `CODEBASE` | Schema, migration, query, ORM, and retrieval files | | `LOCAL_FS` | Database design artifacts and result documents | | `PROCESS` | Migration, query, lint, or validation commands | | `USER_DATA` | Domain data definitions, retention rules, and sample access patterns |

### Preconditions - Target database concern and scope are identifiable. - Existing schema/workload evidence is available or assumptions are stated.

### Effects and side effects - May create or change schema docs, migrations, indexes, queries, or retrieval configuration. - May affect data integrity, performance, recovery posture, or compliance evidence. - Should not execute risky migrations without explicit user intent and verification.

### Guardrails 1. Choose model first, engine second: workload, access pattern, consistency, and scale drive DB selection. 2. For relational workloads, enforce at least **3NF** by default. Break 3NF only with explicit performance justification. 3. For distributed/non-relational workloads, model around aggregates and access paths; document **BASE** and consistency tradeoffs. 4. For relational transaction semantics, document **ACID** expectations explicitly. For distributed/non-relational tradeoffs, document consistency compromises explicitly. 5. Always document the three schema layers: **external schema**, **conceptual schema**, **internal schema**. 6. Treat integrity as first-class: entity, domain, referential, and business-rule integrity must be explicit. 7. Concurrency is never implicit: define transaction boundaries, locking strategy, and isolation level per critical flow. 8. Data standards are mandatory: naming, definition, format, allowed values, and validation rules. 9. Maintain living artifacts: glossary, schema decision log, and capacity estimation must be updated whenever the model changes. 10. Proactively flag anti-patterns and insecure shortcuts instead of silently implementing them. 11. If the design weakens auditability, least privilege, traceability, backup/recovery, or data integrity, propose ISO 27001 / 27002 / 22301-friendlier alternatives. 12. Vector DBs are retrieval infrastructure, not source-of-truth databases. Store embeddings and lightweight metadata there; keep canonical documents elsewhere. 13. Never treat vector search as a drop-in replacement for lexical search. Default to hybrid retrieval when exact match, compliance filtering, or explainability matters. 14. Embeddings are schema-like assets: version model, dimension, chunking, and preprocessing, and plan re-embedding migrations explicitly. 15. Retrieval quality is won at chunking, filtering, reranking, and observability, not only at the vector index layer. 16. Schema or data changes on live tables follow expand-contract (parallel change): additive expand, dual-write + batched backfill, verified read switch, delayed contract. DDL on hot tables is lock-aware with timeouts; destructive steps ship in a separate deploy after a soak window. 17. Query tuning starts from measurement and execution plans, never guesswork: measure, explain, nominate the dominant cost node, then optimize and re-measure.

### Default Workflow 1. **Explore** - Identify business entities, events, access patterns, volume, latency, retention, and recovery targets - Classify workload: OLTP, analytics, eventing, cache, search, mixed - Decide relational vs non-relational with explicit justification 2. **Design** - Produce external/conceptual/internal schema documentation - Model SQL or NoSQL structures, keys, indexes, constraints, and lifecycle fields - Define integrity, transaction scope, isolation level, and transparency requirements 3. **Optimize** - Validate 3NF or deliberate denormalization - Tune indexes, partitioning, archival strategy, hot/cold split, and backup plan - For vector systems, tune ANN, chunking, filtering, reranking, and observability as one pipeline - Run anti-pattern review and update glossary and capacity estimation with every structural change

### Required Deliverables - External schema summary by user/view/consumer - Conceptual schema with core entities or aggregates and relationships - Internal schema with physical storage, indexes, partitioning, and access paths - Data standards table: name, definition, type/format, rule - Glossary / terminology dictionary - Capacity estimation sheet - Backup and recovery strategy including full + incremental backup cadence - For vector/RAG systems: embedding version policy, chunking policy, hybrid retrieval strategy, and re-index / re-embedding plan

## References Follow `resources/execution-protocol.md` step by step. See `resources/examples.md` for input/output examples. Use `resources/document-templates.md` when you need concrete deliverable structure. Use `resources/anti-patterns.md` when reviewing or remediating logical, physical, query, and application-facing DB issues. Use `resources/vector-db.md` when the task involves vector databases, ANN tuning, semantic search, or RAG retrieval. Use `resources/iso-controls.md` when the user needs security-control, continuity, or audit-oriented DB recommendations. Use `resources/migration-playbook.md` when a schema or data change targets live tables (expand-contract, lock-aware DDL, batched backfill, cutover). Use `resources/query-tuning.md` when the task involves slow queries, execution plans, or index design. Before submitting,

--- name: oma-db description: Database specialist for SQL, NoSQL, and vector database modeling, schema design, normalization, indexing, transactions, integrity, concurrency control, backup, capacity planning, data standards, anti-pattern review, and compliance-aware database design. Use for database, schema, ERD, table design, document model, vector index design, RAG retrieval architecture, migration, query tuning, glossary, capacity estimation, backup strategy, database anti-pattern remediation work, and ISO 27001, ISO 27002, or ISO 22301-aware database recommendations. ---

# DB Agent - Data Modeling & Database Architecture Specialist

## Scheduling

### Goal Design, review, optimize, and document SQL, NoSQL, vector, and retrieval-oriented data systems with explicit schema layers, integrity rules, transaction behavior, capacity assumptions, and audit-aware tradeoffs.

### Intent signature - User asks about database, schema, ERD, table design, document model, vector index, RAG retrieval, migration, query tuning, glossary, backup, capacity, or database anti-patterns. - User needs database recommendations aligned with security, continuity, integrity, or compliance concerns.

### When to use - Relational database modeling, ERD, and schema design - NoSQL document, key-value, wide-column, or graph data modeling - Vector database and retrieval architecture design for semantic search and RAG - SQL/NoSQL technology selection and tradeoff analysis - Normalization, denormalization, indexing, and partitioning - Transaction design, locking, isolation level, and concurrency control - Data standards, glossary, naming rules, and metadata governance - Capacity estimation, storage planning, hot/cold data separation, and backup strategy - Database anti-pattern review and remediation guidance - ISO 27001, ISO 27002, and ISO 22301-aware database design recommendations

### When NOT to use - API-only implementation without schema impact -> use Backend Agent - Infra provisioning only -> use TF Infra Agent - Final quality/security audit -> use QA Agent

### Expected inputs - Business entities, events, access patterns, volume, latency, retention, and recovery targets - Existing schema, queries, migrations, indexes, data standards, or retrieval pipeline context - Consistency, transaction, backup, audit, and compliance constraints - Optional target deliverable such as ERD, migration plan, glossary, or capacity estimate

### Expected outputs - External, conceptual, and internal schema documentation - Data standards, glossary, capacity estimate, indexing/partitioning plan, and backup/recovery strategy - Integrity, transaction, isolation, and concurrency recommendations - Vector/RAG-specific embedding, chunking, filtering, reranking, and re-index plans when relevant

### Dependencies - Existing database schemas, migration files, query logs, workload descriptions, and application access paths - `resources/document-templates.md`, `resources/anti-patterns.md`, `resources/vector-db.md`, `resources/iso-controls.md`, `resources/migration-playbook.md`, and `resources/query-tuning.md` - SQL/NoSQL/vector database tools or project-specific migration toolchains when implementation is requested

### Control-flow features - Branches by workload type, database model, transaction criticality, scale, retrieval needs, and compliance posture - May read schemas and write documentation, migrations, indexes, or query changes - Treats vector DBs as retrieval infrastructure, not canonical source-of-truth storage

## Structural Flow

### Entry 1. Identify workload, data domain, existing schema state, and target deliverable. 2. Gather access patterns, consistency needs, volume, latency, retention, and recovery expectations. 3. Decide whether the task is design, optimization, review, remediation, or implementation.

### Scenes 1. **PREPARE**: Classify workload and constraints. 2. **ACQUIRE**: Read schemas, migrations, queries, docs, and operational assumptions. 3. **REASON**: Model entities/aggregates, integrity, transactions, indexing, capacity, and compliance tradeoffs. 4. **ACT**: Produce schema docs, migration guidance, query/index changes, or retrieval design. 5. **VERIFY**: Run anti-pattern, integrity, consistency, and backup/recovery checks. 6. **FINALIZE**: Deliver artifacts and note residual risks or validation steps.

### Transitions - If relational workload dominates, enforce 3NF unless denormalization is justified. - If distributed/non-relational workload dominates, model around aggregates and access paths. - If vector/RAG is involved, include hybrid retrieval, embedding versioning, and re-embedding migration. - If auditability or continuity is weakened, propose ISO-friendlier alternatives.

### Failure and recovery - If workload or access patterns are missing, state assumptions and ask for representative queries or flows. - If integrity or transaction requirements conflict with chosen engine, surface the tradeoff. - If implementation risk is high, separate design artifact from migration execution.

### Exit - Success: deliverables state model, constraints, integrity, transactions, capacity, and validation. - Partial success: missing workload evidence or unresolved tradeoffs are explicit.

## Logical Operations

### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Classify workload and model | `SELECT` | SQL, NoSQL, vector, cache, search, mixed | | Read schema/query evidence | `READ` | Migrations, ERDs, query patterns | | Compare design alternatives | `COMPARE` | Engine/model/index tradeoffs | | Infer integrity and capacity risks | `INFER` | Constraints, transactions, growth assumptions | | Validate anti-patterns | `VALIDATE` | Checklist and anti-pattern guide | | Write schema docs or changes | `WRITE` | Deliverables, migrations, query/index changes | | Report recommendation | `NOTIFY` | Final database guidance |

### Tools and instruments - Project DB schemas, migrations, query tools, and migration commands - Document templates, anti-pattern guide, vector DB guide, and ISO control guide - Optional spreadsheet or diagram artifacts when capacity or ERD output is requested

### Canonical workflow path ```bash rg --files -g '*.sql' -g '*prisma*' -g '*schema*' -g '*migration*' rg "CREATE TABLE|model |index|foreign key|transaction|embedding|vector" . ```

Then run the project's migration, query-plan, or retrieval-quality commands only after identifying the database engine and migration tool.

### Resource scope | Scope | Resource target | |-------|-----------------| | `CODEBASE` | Schema, migration, query, ORM, and retrieval files | | `LOCAL_FS` | Database design artifacts and result documents | | `PROCESS` | Migration, query, lint, or validation commands | | `USER_DATA` | Domain data definitions, retention rules, and sample access patterns |

### Preconditions - Target database concern and scope are identifiable. - Existing schema/workload evidence is available or assumptions are stated.

### Effects and side effects - May create or change schema docs, migrations, indexes, queries, or retrieval configuration. - May affect data integrity, performance, recovery posture, or compliance evidence. - Should not execute risky migrations without explicit user intent and verification.

### Guardrails 1. Choose model first, engine second: workload, access pattern, consistency, and scale drive DB selection. 2. For relational workloads, enforce at least **3NF** by default. Break 3NF only with explicit performance justification. 3. For distributed/non-relational workloads, model around aggregates and access paths; document **BASE** and consistency tradeoffs. 4. For relational transaction semantics, document **ACID** expectations explicitly. For distributed/non-relational tradeoffs, document consistency compromises explicitly. 5. Always document the three schema layers: **external schema**, **conceptual schema**, **internal schema**. 6. Treat integrity as first-class: entity, domain, referential, and business-rule integrity must be explicit. 7. Concurrency is never implicit: define transaction boundaries, locking strategy, and isolation level per critical flow. 8. Data standards are mandatory: naming, definition, format, allowed values, and validation rules. 9. Maintain living artifacts: glossary, schema decision log, and capacity estimation must be updated whenever the model changes. 10. Proactively flag anti-patterns and insecure shortcuts instead of silently implementing them. 11. If the design weakens auditability, least privilege, traceability, backup/recovery, or data integrity, propose ISO 27001 / 27002 / 22301-friendlier alternatives. 12. Vector DBs are retrieval infrastructure, not source-of-truth databases. Store embeddings and lightweight metadata there; keep canonical documents elsewhere. 13. Never treat vector search as a drop-in replacement for lexical search. Default to hybrid retrieval when exact match, compliance filtering, or explainability matters. 14. Embeddings are schema-like assets: version model, dimension, chunking, and preprocessing, and plan re-embedding migrations explicitly. 15. Retrieval quality is won at chunking, filtering, reranking, and observability, not only at the vector index layer. 16. Schema or data changes on live tables follow expand-contract (parallel change): additive expand, dual-write + batched backfill, verified read switch, delayed contract. DDL on hot tables is lock-aware with timeouts; destructive steps ship in a separate deploy after a soak window. 17. Query tuning starts from measurement and execution plans, never guesswork: measure, explain, nominate the dominant cost node, then optimize and re-measure.

### Default Workflow 1. **Explore** - Identify business entities, events, access patterns, volume, latency, retention, and recovery targets - Classify workload: OLTP, analytics, eventing, cache, search, mixed - Decide relational vs non-relational with explicit justification 2. **Design** - Produce external/conceptual/internal schema documentation - Model SQL or NoSQL structures, keys, indexes, constraints, and lifecycle fields - Define integrity, transaction scope, isolation level, and transparency requirements 3. **Optimize** - Validate 3NF or deliberate denormalization - Tune indexes, partitioning, archival strategy, hot/cold split, and backup plan - For vector systems, tune ANN, chunking, filtering, reranking, and observability as one pipeline - Run anti-pattern review and update glossary and capacity estimation with every structural change

### Required Deliverables - External schema summary by user/view/consumer - Conceptual schema with core entities or aggregates and relationships - Internal schema with physical storage, indexes, partitioning, and access paths - Data standards table: name, definition, type/format, rule - Glossary / terminology dictionary - Capacity estimation sheet - Backup and recovery strategy including full + incremental backup cadence - For vector/RAG systems: embedding version policy, chunking policy, hybrid retrieval strategy, and re-index / re-embedding plan

## References Follow `resources/execution-protocol.md` step by step. See `resources/examples.md` for input/output examples. Use `resources/document-templates.md` when you need concrete deliverable structure. Use `resources/anti-patterns.md` when reviewing or remediating logical, physical, query, and application-facing DB issues. Use `resources/vector-db.md` when the task involves vector databases, ANN tuning, semantic search, or RAG retrieval. Use `resources/iso-controls.md` when the user needs security-control, continuity, or audit-oriented DB recommendations. Use `resources/migration-playbook.md` when a schema or data change targets live tables (expand-contract, lock-aware DDL, batched backfill, cutover). Use `resources/query-tuning.md` when the task involves slow queries, execution plans, or index design. Before submitting,