oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-brainstorm/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: oma-brainstorm
+description: Explore goals, constraints, and alternative approaches before
+  choosing a design. Use when the user requests ideation or design exploration.
+---
+
+# Brainstorm - Design-First Ideation
+
+## Scheduling
+
+### Goal
+Explore user intent, constraints, and alternative approaches before planning or implementation, then preserve an approved design for downstream planning.
+
+### Intent signature
+- User says they have an idea, want to brainstorm, compare approaches, explore concepts, or design before planning.
+- Request is ambiguous enough that implementation or task planning would be premature.
+
+### When to use
+- Exploring a new feature idea before planning
+- Understanding user intent and constraints before committing to an approach
+- Comparing multiple design approaches with trade-offs
+- When the user says "I have an idea" or "let's design something"
+- Before invoking `/plan` for complex or ambiguous requests
+
+### When NOT to use
+- Requirements are already clear and well-defined -> use `oma-pm` directly
+- Implementing actual code -> delegate to specialized agents
+- Performing code reviews -> use `oma-qa`
+- Debugging existing issues -> use `oma-debug`
+
+### Expected inputs
+- Early idea, ambiguous goal, product concept, design question, or set of constraints
+- Existing project context when the idea must fit a codebase or product direction
+- User preferences and approval gates
+
+### Expected outputs
+- Clarified intent and constraints
+- Viable approaches as prose briefs (scenario, mechanism, residual risk), with comparison and recommendation when alternatives aid the decision
+- Section-by-section approved design document
+- Blind-review issue list (Tier 1 resolved, Tier 2/3 resolved or explicitly deferred)
+- Saved design artifact before handoff to planning
+
+### Dependencies
+- Shared context loading, reasoning templates, clarification protocol, quality principles, and skill routing
+- Optional `resources/triz-lite.md` for contradiction-shaped approach seeding
+- Per-agent reviewer dispatch (e.g. `qa-reviewer`, `architecture-reviewer`) for the high-stakes blind-review escalation path
+- Downstream PM workflow for task decomposition after design approval
+
+### Control-flow features
+- Branches by ambiguity, user answers, approach comparison, and approval gates
+- Optional TRIZ-lite branch when a technical/UX contradiction blocks distinct approaches
+- Asks one question at a time
+- Blind review round before save; may dispatch fresh-context reviewer subagents for high-stakes designs (the only subagent-spawning path in this skill)
+- Stops before implementation or task planning
+
+## Structural Flow
+
+### Entry
+1. Confirm that the request is exploratory rather than ready for implementation.
+2. Load enough project context to understand constraints.
+3. Start with intent and constraints, not solutions.
+
+### Scenes
+1. **PREPARE**: Explore context and frame the design question.
+2. **ACQUIRE**: Ask clarifying questions one at a time.
+3. **REASON**: Compare viable approaches with tradeoffs when alternatives aid the decision; explain binding constraints when only one remains.
+4. **VERIFY**: Reuse existing design authority and resolve only material open choices, then run a blind review round (independent lenses critique without seeing each other's feedback) before saving.
+5. **FINALIZE**: Save design and transition to planning when appropriate.
+
+### Transitions
+- If requirements become clear and implementation-ready, transition to PM planning.
+- If user rejects an approach, revise before moving to detailed design.
+- If implementation pressure appears early, defer it until design approval.
+- If approaches collapse into knob-turning on one axis, load `resources/triz-lite.md` and reseed, then re-present prose briefs.
+
+### Failure and recovery
+- If the user cannot answer a question, propose assumptions and ask for confirmation.
+- If scope expands, split the design into smaller sections.
+- If alternatives collapse into one option, identify the real constraint causing that; use TRIZ-lite only when that constraint is a technical/UX contradiction.
+
+### Exit
+- Success: approved design exists and is ready for planning.
+- Partial success: open questions and assumptions are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Read context and idea | `READ` | User prompt and project context |
+| Ask targeted questions | `REQUEST` | Clarification phase |
+| Compare approaches | `COMPARE` | Tradeoff matrix |
+| Infer recommendation | `INFER` | Recommended option |
+| Record option selection | `CALL_TOOL` | Actual approach, comparison evidence, and design/option revision; matching `instanceId` and verifier `--instance` in an active OMA workflow |
+| Resolve design authority | `VALIDATE` | Existing instruction, delegated choice, or explicit answer for an unresolved material design choice |
+| Run blind review | `VALIDATE` | Independent lens critiques, tiered issue list, Tier 1 resolution |
+| Write design artifact | `WRITE` | `docs/decisions/` and a linked coordination summary |
+| Transition to plan | `NOTIFY` | Handoff summary |
+
+### Tools and instruments
+- Context loading, reasoning templates, clarification protocol
+- Optional TRIZ-lite resource for contradiction seeding
+- Project memory for coordination summaries and `docs/decisions/` for retained approach proposals
+
+### Canonical workflow path
+```text
+1. Ask one clarifying question at a time.
+2. (Optional) If technical/UX contradiction or same-axis approaches only → resources/triz-lite.md.
+3. Present viable alternatives as prose briefs and compare them when useful; do not invent extra options to meet a count; reuse an existing selection or delegated choice and resolve only an open material choice. In an active OMA workflow, record the actual approach, rationale, evidence, and design/option revision with `brainstorm.option-selection`; verify the matching --instance (workflow Step 3 owns the commands).
+4. Design section by section within existing authorization, then blind review: independent lenses suited to the uncertainty and stakes critique the design; resolve Tier 1 issues (fresh-context reviewer subagents for high-stakes designs).
+5. Save the approved approach to `docs/decisions/{NNN}-{name}.md` and update `docs/decisions/index.md` before handing off to planning. Keep this directory versioned. Read `docs/plans/designs/` and `docs/design-docs/` only as legacy fallback until migration; `design` names UI work.
+```
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `MEMORY` | User intent, assumptions, decisions |
+| `CODEBASE` | Existing project context when relevant |
+| `LOCAL_FS` | Approved design artifacts; optional TRIZ-lite appendix in design doc |
+
+### Preconditions
+- The user is still exploring or the request is ambiguous.
+- The agent can ask clarifying questions before implementation.
+
+### Effects and side effects
+- Produces design decisions and persisted design docs.
+- Influences downstream planning but does not implement code.
+
+### Guardrails
+1. **No implementation or planning before design approval** - brainstorm produces a design document, not code or task plans
+2. **One question at a time** - ask clarification and approval questions through the available asynchronous question tool first, following `../_shared/core/clarification-protocol.md`; fall back to a permitted question tool or plain text. Continue independent work while waiting, and never infer approval from silence or a preselected option.
+3. **Compare viable approaches** - offer two or three when they aid the decision, and explain constraints when fewer remain. Recommend according to the actual goal, effort, reversibility, and risk. Do not favor a larger structural change solely because of its label.
+4. **Explain viable approaches in prose** - state scenario, mechanism, residual risk, and effort. Use a comparison matrix when it helps the decision, then give the recommendation; a single constrained option needs its rationale, not invented alternatives
+5. **Section-by-section design** - present the design incrementally; reuse existing decisions and delegated authority, asking only for unresolved material choices under the shared execution policy
+6. **Blind review before save** - mandatory unless the design is trivially small (1-2 files, low stakes); lenses critique independently; use fresh-context reviewer subagents for architecturally significant, hard-to-reverse, or security-/compliance-sensitive designs
+7. **YAGNI** - do not over-engineer; design only what is needed for the stated goal
+8. **TRIZ-lite is optional** - only for technical/UX contradictions or same-axis collapse; max 3–5 principles from the curated set; no fake scores, full TRIZ/ARIZ, or classical matrices; seeds feed Step 3 briefs and do not replace user approval
+9. **Save the selected approach, then transition** - persist it in `docs/decisions/` before handing off to `/plan`. Run-specific critique and `result-*.md` reports belong in `.agents/results/`; leave the destination in the source report when promoting a document into `docs/`
+
+### Execution Phases
+Follow the brainstorm workflow step by step:
+1. **Phase 1 - Context**: Explore the existing codebase and understand the project landscape
+2. **Phase 2 - Questions**: Ask clarifying questions one at a time to understand intent and constraints
+3. **Phase 3 - Approaches**: Optionally seed with TRIZ-lite for a real contradiction; compare viable approaches in prose and recommend according to the stated constraints, effort, reversibility, and risk
+4. **Phase 4 - Design**: Present the detailed design section by section, preserving existing authorization and resolving only open material choices
+5. **Phase 5 - Blind Review**: Use independent reviewer lenses proportionate to the design uncertainty and stakes, consolidate into Tier 1/2/3 issues, resolve Tier 1 before save; escalate to fresh-context reviewer subagents for high-stakes designs. Skip only for trivially small designs (1-2 files, low stakes)
+6. **Phase 6 - Documentation**: Save the approved approach to `docs/decisions/{NNN}-{name}.md`, update its index, and record a linked coordination summary in project memory
+7. **Phase 7 - Transition**: Hand off to `/plan` for task decomposition
+
+### Common Pitfalls
+- **Jumping to solutions**: Asking "how" before fully understanding "what" and "why"
+- **Too many questions at once**: Overwhelming the user with a wall of questions
+- **Single approach bias**: Skipping viable alternatives without explaining binding constraints
+- **Matrix-only options**: Dumping a trade-off table without scenario/mechanism prose so the user cannot choose
+- **Same-axis "alternatives"**: Three intensities of the same knob (interval/TTL/debounce) presented as distinct approaches
+- **TRIZ on everything**: Loading triz-lite without a real contradiction, adding ceremony without better options
+- **Over-engineering**: Designing for hypothetical future requirements instead of stated needs
+- **Inventing design authority**: Treating an agent recommendation as approval of a user-owned unresolved choice, or asking again for a choice already authorized
+- **Skipping blind review**: Saving a non-trivial design without the independent critique round, or letting the design's author-context leak into escalated reviewer prompts
+
+## References
+- TRIZ-lite (optional Step 3 seeding): `resources/triz-lite.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Clarification protocol: `../_shared/core/clarification-protocol.md`
+- Quality principles: `../_shared/core/quality-principles.md`
+- Skill-to-agent mapping: `../_shared/core/skill-routing.md`

package/skills/oma-brainstorm/resources/triz-lite.md

@@ -0,0 +1,117 @@
+# TRIZ-lite (Optional Approach Seeding)
+
+Lightweight inventive seeding for **technical / UX contradictions** only.
+Not full TRIZ, ARIZ, the classical contradiction matrix, or scored pseudo-formulas.
+
+Default: **off**. Load only when Step 3 triggers apply.
+
+---
+
+## When to load
+
+Load this file and run T1–T4 when **any** of the following is true:
+
+- Improving A clearly worsens B (performance vs cost, freshness vs load, security vs UX, etc.)
+- Draft approaches collapse into the same axis (only “turn the knob”: interval, TTL, debounce, log level)
+- User explicitly asks for TRIZ, inventive framing, or contradiction-focused options
+
+## When NOT to load
+
+- Ambiguous product intent without a technical/UX contradiction → stay on normal clarification
+- Trivial / 1–2 file changes
+- Pure organizational or political conflict (do not force a technical contradiction)
+- Two or three **mechanistically different** approaches already exist
+
+---
+
+## Protocol
+
+### T0 — Trigger check
+
+If none of the “when to load” conditions hold → **skip** this file; use normal Step 3 generation.
+
+### T1 — Technical contradiction
+
+```markdown
+### Technical contradiction
+- Improve: {desired gain}
+- Degrades: {what gets worse}
+- Current compromise: {today’s middle-ground}
+- Why compromise is insufficient: {one sentence}
+```
+
+Optional physical contradiction (“must be X and not X at once”) only if it is real — do not invent one.
+
+### T2 — Ideal Final Result (IFR)
+
+```markdown
+### Ideal Final Result
+{One sentence: the system delivers the improve-side outcome with little extra machinery and without the usual compromise}
+```
+
+IFR is a **direction**, not a Step 4 implementation spec.
+
+### T3 — Principle seeds (pick 3–5)
+
+Use only this curated software/UX-oriented set. Do **not** dump all 40 classical principles.
+
+| # | Principle | Seed questions (software / UX) |
+|---|-----------|--------------------------------|
+| 1 | Segmentation | Split modules, stages, shards, progressive rollout? |
+| 2 | Taking out | Remove work from the hot path? CQRS / side channel? |
+| 3 | Local quality | Different policy per region, widget, tier, or failure mode? |
+| 5 | Merging | Batch, colocate, single pipeline? |
+| 10 | Preliminary action | Precompute, warm cache, migrate ahead, budget limits up front? |
+| 11 | Beforehand cushioning | Retry, fallback, feature flag, keep last-good UI? |
+| 13 | The other way around | Push↔pull, sync↔async, server↔edge, invert control? |
+| 15 | Dynamics | Adaptive TTL, dynamic fidelity, policy engine? |
+| 19 | Periodic action | Batch window, lease renew, coalesce, snapshot ticks? |
+| 24 | Intermediary | Queue, BFF, adapter, outbox, event bus, draft/commit layer? |
+| 25 | Self-service | Self-heal, client revalidation, automation? |
+| 28 | Replace mechanical coupling | Indirect signals: events, observations, data-driven policy? |
+
+Rules:
+
+1. Choose principles that **connect to the T1 contradiction** — no random lists.
+2. For each chosen principle, write **one concrete seed sentence** (not only the principle name).
+3. Produce at least four seeds (a principle may contribute more than one seed), then compress to **2–3 approaches**.
+
+### T4 — Compress into normal Step 3 approaches
+
+Map seeds into the standard approach briefs (see workflow Step 3 presentation rules).
+
+- Keep **tactical** vs **structural** labels.
+- Default recommendation remains **structural** (engineering-first).
+- Pure knob-turning (only interval/TTL/debounce/log-level) is not a full approach unless the problem is throwaway scope; prefer absorbing it into a structural option or marking non-recommended.
+- Optional one-line appendix for the design doc:
+
+```markdown
+## Appendix: TRIZ-lite
+- Contradiction: improve X / degrades Y
+- IFR: ...
+- Principles used: {ids}
+- Discarded seeds: {one line each}
+```
+
+Keep the appendix ≤15 lines.
+
+---
+
+## Anti-patterns
+
+- Running TRIZ-lite on every brainstorm
+- Listing all 12 principles without seeds
+- Inventing continuous “TRIZ scores”
+- Replacing ATAM / ADR / full architecture review with this file
+- Expanding seeds into a full Step 4 design before the user picks an approach
+- Using principle names as the only user-visible explanation (always prose-brief the approach)
+
+---
+
+## Minimal example
+
+**Contradiction:** fresher metrics vs DB load/cost  
+**IFR:** readers see near-real-time metrics without per-user DB polling  
+**Seeds:** taking out (read path leaves DB), preliminary (pre-aggregate), periodic (shared worker snapshot), intermediary (read model)  
+**Approaches:** (A) event → aggregator → read model; (B) shared poller + short cache + invalidation; (C) tighter poll only — non-recommended tactical  
+**Recommend:** A

package/skills/oma-coordination/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: oma-coordination
+description: Coordinate assigned specialist tasks and handoffs manually. Use
+  when supervising a multi-agent project step by step.
+---
+
+# Multi-Agent Workflow Guide
+
+## Scheduling
+
+### Goal
+Guide manual multi-agent coordination for complex work that spans PM, frontend, backend, mobile, and QA responsibilities.
+
+### Intent signature
+- User wants step-by-step coordination, manual agent spawning, or multi-domain work planning without full automation.
+- Task spans multiple specialist agents and requires contract alignment.
+
+### When to use
+
+- Complex feature spanning multiple domains (full-stack, mobile)
+- Coordination needed between frontend, backend, mobile, and QA
+- User wants step-by-step guidance for multi-agent coordination
+
+### When NOT to use
+
+- Simple single-domain task -> use the specific agent directly
+- User wants automated execution -> use orchestrator
+- Quick bug fixes or minor changes
+
+### Expected inputs
+- Complex feature or project goal
+- Required domains and priority tiers
+- Workspace/session constraints and API/data contract needs
+
+### Expected outputs
+- Manual coordination sequence
+- PM task decomposition, agent spawn order, monitoring guidance, and QA review step
+- API/data contract alignment checkpoints
+
+### Dependencies
+- PM, frontend, backend, mobile, QA, and orchestrator skills
+- CLI `oma agent spawn` and progress/result memory conventions
+
+### Control-flow features
+- Branches by task complexity, priority tiers, dependency ordering, and whether automation is desired
+- Spawns independent same-priority tasks in parallel when appropriate
+- Monitors progress files and contract alignment
+
+## Structural Flow
+
+### Entry
+1. Confirm the task is complex enough for multi-agent coordination.
+2. Reuse a current plan and handoff state; use PM when task decomposition or contract changes are needed.
+3. Identify priority tiers and shared contracts.
+4. Apply the shared collaboration policy before assigning parallel work or coordinating ownership handoffs and result collection.
+
+### Scenes
+1. **PREPARE**: Define session, domains, and task decomposition needs.
+2. **ACT**: Spawn agents by priority with separate workspaces.
+3. **VERIFY**: Monitor progress and API/data contract alignment.
+4. **FINALIZE**: Run QA review and coordinate remediation.
+
+### Transitions
+- If task is simple, route to one specialist.
+- If user wants automated execution, use orchestrator.
+- If QA reports a blocking defect or required verification gap, route the affected work to the responsible agent within the existing recovery budget.
+
+### Failure and recovery
+- If contracts diverge, pause downstream frontend/mobile work until backend/API contract is reconciled.
+- If agent workspaces conflict, split ownership boundaries.
+- If progress stalls, inspect progress files and reissue focused instructions.
+
+### Exit
+- Success: specialist outputs are coordinated and QA-reviewed.
+- Partial success: blocked agents, contract conflicts, or QA failures are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Read request and domains | `READ` | User prompt and project context |
+| Select agent plan | `SELECT` | PM decomposition and priority tiers |
+| Spawn agents | `CALL_TOOL` | `oma agent spawn` |
+| Monitor progress | `READ` | injected task/run-scoped progress, claims, and receipts |
+| Validate contracts | `VALIDATE` | API/data model alignment |
+| Notify coordination status | `NOTIFY` | Final coordination summary |
+
+### Tools and instruments
+- `oma agent spawn`, PM/frontend/backend/mobile/QA agents
+- Memory/progress/result files
+- Configured code intelligence, with native fallback per `../_shared/core/code-intelligence.md`
+
+### Canonical command path
+```bash
+# If planning is required, dispatch the declared PM task first; otherwise reuse the current plan.
+oma agent spawn pm <pm-prompt-file> <session-id> --task-id <plan.pm_task.id> -w ./pm
+oma agent spawn backend <backend-prompt-file> <session-id> --task-id <plan.backend_task.id> -w ./backend &
+oma agent spawn frontend <frontend-prompt-file> <session-id> --task-id <plan.frontend_task.id> -w ./frontend &
+wait
+```
+
+When native runtime dispatch is available (per-agent target vendor equals the current runtime vendor), prefer the runtime's native subagent path and use `oma agent spawn` as the cross-vendor fallback — same resolution rule as oma-orchestration.
+
+Useful `agent spawn` options: `--vendor <vendor>` (CLI vendor override), `--isolation worktree` (git worktree per spawn, prevents file conflicts), `--read-only` (non-destructive tools only, e.g. for review/QA passes).
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Progress/result files and workspaces |
+| `PROCESS` | Agent spawn commands |
+| `MEMORY` | Session state and task board |
+| `CODEBASE` | Shared contracts and implementation areas |
+
+### Preconditions
+- Task requires multiple domains.
+- A current plan identifies task ownership, acceptance checks, dependencies, and priority tiers.
+
+### Effects and side effects
+- Spawns or guides multiple agents.
+- Coordinates workspace ownership and QA feedback.
+
+### Guardrails
+
+1. Reuse a valid plan; call PM only when decomposition or contract changes are required
+2. Spawn independent tasks in parallel (same priority tier)
+3. Reuse or update contracts for changed API boundaries before dependent frontend/mobile work
+4. QA review is always the final step
+5. Assign separate workspaces to avoid file conflicts (or use `--isolation worktree` for a git worktree per spawn)
+6. Follow `../_shared/core/code-intelligence.md`: discover configured tools, do not auto-install or track, and use native search only for paths outside this project or ignored paths when unavailable or timed out
+7. Resume from the current handoff state and execute applicable steps in dependency order; record why a branch is not applicable
+
+### Workflow
+
+#### Step 1: Plan with PM Agent
+
+Reuse an existing valid plan. Otherwise, PM analyzes requirements and creates the task breakdown, acceptance checks, contracts, and priorities. Preserve injected session/task/run IDs; do not regenerate a plan already frozen by dispatch.
+
+#### Step 2: Spawn Agents by Priority
+
+Resolve the dispatch path per agent, then spawn:
+
+1. Resolve the per-agent target vendor from oma-config.yaml (`agents:` override, else `model_preset`)
+2. If the target vendor equals the current runtime vendor and a native subagent path exists, use native dispatch
+3. Otherwise use `oma agent spawn` for that agent
+4. Spawn all same-priority tasks in parallel using background processes
+
+```bash
+# Example: spawn backend and frontend in parallel
+oma agent spawn backend backend-prompt.md session-id --task-id plan.backend_task.id -w ./backend &
+oma agent spawn frontend frontend-prompt.md session-id --task-id plan.frontend_task.id -w ./frontend &
+wait
+```
+
+#### Step 3: Monitor & Coordinate
+
+- Apply `../_shared/core/execution-policy.md` for the execution deadline, resource ownership, and cancellation. Prefer host completion notifications; otherwise use one coordinator with bounded polling backoff. Cancellation or deadline exhaustion stops new dispatch, review, and recovery; use bounded termination checks and report survivors or unsupported cancellation in the handoff.
+- Read injected run artifacts and receipts. Human-readable progress/results use `{memoryConfig.basePath}/progress-{agentId}-{taskId}-{runId}-{sessionId}.md` and the corresponding `result-` name; see `../_shared/runtime/memory-protocol.md`. Keep the structured claim path unchanged.
+- Verify API contracts align between agents
+- Ensure shared data models are consistent
+
+#### Step 4: QA Review
+
+Review the coordinated deliverables with QA. Resolve blocking defects and required verification gaps through the responsible agents; rerun affected checks before finalizing.
+
+### Automated Alternative
+
+For fully automated execution without manual spawning, use the **orchestrator** skill instead.
+
+## References
+- Parallel worker collaboration: `../_shared/core/collaboration-policy.md` (before assigning parallel work or coordinating peer issues, ownership handoffs, and result collection)

package/skills/oma-db/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: oma-db
+description: Design schemas and migrations, tune queries, or plan vector
+  retrieval and database operations. Application API implementation uses
+  oma-backend.
+---
+
+# 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
+- Application ownership recommendations, alternatives, transition priorities, and technical retention evidence when DB business logic is affected
+- 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
+Use the configured code-intelligence provider to locate files and inspect symbols
+or content. For Serena, use `find_file`, `search_for_pattern`,
+`get_symbols_overview`, and `find_symbol`. Native search is limited to the
+provider exclusions and non-code paths permitted by the project's search policy.
+
+
+Then run the project's migration, query-plan, or retrieval-quality commands only after identifying the database engine and migration tool.
+For affected triggers, stored procedures, functions, views, DB jobs, or ORM hooks,
+apply `resources/anti-patterns.md` §5 application ownership review. Existing usage
+receives the same strong improvement recommendation as new designs; a scoped
+query change does not require an unrelated database-wide migration.
+
+### 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
+Apply framework, library, architecture, and data-model defaults only when the target project has no established choice. Scoped edits do not authorize a stack migration or unrelated infrastructure.
+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. For full schema design, document external, conceptual and internal schema views. For a scoped index/query/model change, update only the affected existing views.
+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. Apply existing data standards; add relevant naming, definition, format and validation rules for newly modeled data.
+9. Update affected existing glossary, decision and capacity artifacts when the change alters their assumptions. A query-only task does not require new modeling documents.
+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.
+18. Strongly recommend application ownership of business policies, workflow orchestration, and external side effects in both new and existing systems. Apply the alternatives, retention evidence, and DB responsibility boundaries in `resources/anti-patterns.md` §5. Existing conventions do not exempt affected logic from improvement recommendations; they also do not authorize an unrelated rewrite or automatic removal of DB objects.
+
+### 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 the relevant anti-pattern review and update artifacts whose definitions or capacity assumptions changed
+
+### Deliverables by Scope
+For full modeling/design requests, use the following as applicable. Scoped tuning
+or migration work needs the relevant artifact delta, SQL/plan evidence and
+verification outcome; omit unaffected documents.
+- 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
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Self-check (run before handoff): `resources/checklist.md`
+- Examples: `resources/examples.md`
+- Deliverable templates: `resources/document-templates.md`
+- Anti-pattern review guide: `resources/anti-patterns.md` (schema/query review or affected business logic in DB objects and ORM hooks)
+- Live migration playbook: `resources/migration-playbook.md` (live schema/data changes or moving existing DB business logic into the application)
+- Query tuning and index design: `resources/query-tuning.md`
+- Vector DB and RAG guide: `resources/vector-db.md`
+- ISO control guide: `resources/iso-controls.md`
+- Error recovery: `resources/error-playbook.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Clarification: `../_shared/core/clarification-protocol.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)
+- Observability handoff: `../oma-observability/SKILL.md` §Integrations — DB span conventions (N+1, lock-wait, pool), cardinality budgets