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

package/skills/oma-architecture/resources/stakeholder-synthesis.md

@@ -0,0 +1,80 @@
+# Stakeholder Synthesis Protocol
+
+Consult stakeholder agents only when the decision is cross-cutting enough to justify the cost.
+
+## Consultation Thresholds
+
+### Solo Analysis
+
+Use when:
+- single module or local subsystem
+- no major cross-domain effects
+- decision can be made from direct code/context analysis
+
+### Targeted Consultation
+
+Consult 1-3 agents when:
+- the decision affects multiple layers
+- tradeoffs are real but bounded
+- specific specialist input is needed
+
+Typical pairings (agent ids, not skill names — see the mapping table in `.agents/workflows/orchestrate.md`):
+- `pm`: business constraints, scope, product priorities
+- `backend`: service/API/domain concerns
+- `db`: data ownership, schema, consistency
+- `tf-infra`: deployment and operational architecture
+- `qa`: risk, performance, security, testability
+- `frontend` / `mobile`: client integration and complexity costs
+
+### Full Stakeholder Sweep
+
+Use when:
+- architecture is system-wide
+- multiple teams/domains are materially affected
+- the decision will constrain future roadmap work
+
+## Dispatch Mechanics
+
+Consultation is a real subagent call, not an imagined persona.
+
+1. Resolve dispatch per the project's Per-Agent Dispatch rules (`target_vendor_for_agent` in `.agents/oma-config.yaml`):
+   - same vendor as the current runtime → the runtime's native subagent path (e.g., Claude Code Agent tool)
+   - different vendor, or no native subagent support → `oma agent spawn <agent>` for that agent only
+2. Give each consulted agent a bounded charter:
+   - the decision in one sentence
+   - constraints that are already fixed (not up for debate)
+   - the specific question for that specialty
+   - expected output: position plus top risk, 10 lines or fewer
+3. One round only by default; a second round requires a named unresolved conflict.
+4. Cost bound: targeted consultation is 1-3 agents. A full sweep must state its cross-cutting justification in the artifact.
+
+## Synthesis Rules
+
+1. Capture perspectives as inputs, not votes
+2. Separate:
+   - agreements
+   - conflicts
+   - assumptions
+3. Name the real tradeoff behind disagreements
+4. Make an explicit recommendation even if perspectives differ
+5. If user decision is required, present framed options rather than an unstructured summary
+
+## Output Section
+
+Include a section like:
+
+```md
+## Stakeholder Perspectives
+- PM: ...
+- Backend: ...
+- DB: ...
+
+## Agreements
+- ...
+
+## Tensions
+- ...
+
+## Recommendation
+- ...
+```

package/skills/oma-backend/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: oma-backend
+description: Implement server APIs, authentication, and application data access.
+  Schema modeling and query tuning use oma-db.
+---
+
+# Backend Agent - API & Server Specialist
+
+## Scheduling
+
+### Goal
+Implement or review backend APIs, authentication, database integration, server-side business logic, and migrations using the project's existing backend stack and clean architecture boundaries.
+
+### Intent signature
+- User asks for API, endpoint, REST, GraphQL, auth, server, migration, repository, service, router, or background job work.
+- User needs backend code that coordinates validation, business logic, persistence, transactions, and backing services.
+
+### When to use
+- Building REST APIs or GraphQL endpoints
+- Database design and migrations
+- Authentication and authorization
+- Server-side business logic
+- Background jobs and queues
+
+### When NOT to use
+- Frontend UI -> use Frontend Agent
+- Mobile-specific code -> use Mobile Agent
+
+### Expected inputs
+- Target feature, endpoint, migration, auth flow, or server behavior
+- Existing backend stack files such as manifests, routes, services, models, and database config
+- API contracts, schemas, validation rules, and persistence requirements
+- Required verification commands or project conventions
+
+### Expected outputs
+- Backend code changes in router, service, repository, model, migration, or test files
+- Validated inputs, safe queries, transaction boundaries, and error handling
+- Verification results from the execution checklist
+
+### Dependencies
+- Project stack manifests and existing backend conventions
+- `resources/execution-protocol.md`, `resources/checklist.md`, and `resources/orm-reference.md`
+<!-- oma-docs:ignore-start -->
+- Optional `stack/stack.yaml`, `stack/tech-stack.md`, snippets, and API templates
+<!-- oma-docs:ignore-end -->
+- Database, queue, cache, mail, auth, or external API resources configured through environment or secret managers
+
+### Control-flow features
+- Branches by detected stack, ORM/query pattern, auth requirement, migration impact, and transaction scope
+- Reads and writes codebase files
+- May touch local database migrations or generated code
+- Must not hardcode secrets or share unsafe ORM lifecycle objects across concurrent work
+
+## Structural Flow
+
+### Entry
+1. Detect the backend stack from project files first.
+2. Identify affected router, service, repository, model, migration, and test boundaries.
+3. Load stack-specific references only when needed.
+
+### Scenes
+1. **PREPARE**: Determine stack, architecture boundaries, and acceptance criteria.
+2. **ACQUIRE**: Read existing routes, services, repositories, models, schemas, and config.
+3. **ACT**: Implement backend changes with validation, business logic, persistence, and tests.
+4. **VERIFY**: Run relevant lint, type, test, migration, and checklist commands.
+5. **FINALIZE**: Report changed behavior, verification, and unresolved risks.
+
+### Transitions
+- If stack files exist, follow them before generic guidance.
+- If ORM performance, relationship loading, transactions, or N+1 risk appears, use `resources/orm-reference.md`.
+- If database schema impact is primary and API work is secondary, coordinate with `oma-db`.
+- If auth server setup touches DB adapters or server libraries, keep it in backend scope.
+
+### Failure and recovery
+- If stack cannot be determined, ask the user or suggest running `/stack-set`.
+- If verification fails, fix root cause before handoff.
+- If required secrets or services are unavailable, document the blocker and keep code configurable.
+
+### Exit
+- Success: backend change is implemented, tested, and aligned with local architecture.
+- Partial success: blocker, missing dependency, or verification gap is explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Detect stack and conventions | `READ` | Manifests, stack files, existing code |
+| Select implementation boundary | `SELECT` | Router/service/repository pattern |
+| Validate inputs and schemas | `VALIDATE` | Stack validation library |
+| Implement business logic | `WRITE` | Service layer code |
+| Implement persistence | `WRITE` | Repository/model/migration code |
+| Call external/backing services | `CALL_TOOL` | DB, queue, cache, auth, or API clients |
+| Run verification | `CALL_TOOL` | Tests, typecheck, lint, migrations |
+| Report result | `NOTIFY` | Final summary |
+
+### Tools and instruments
+- Project language/framework toolchain
+- ORM or database client
+- Test, lint, typecheck, and migration commands
+- Stack-specific templates and snippets when present
+
+### 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.
+
+
+<!-- oma-docs:ignore-start -->
+Then run the project's discovered verification commands, usually lint/typecheck/tests and migrations when schema changes are involved. Prefer `stack/stack.yaml` `verify:` commands when present.
+<!-- oma-docs:ignore-end -->
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `CODEBASE` | Backend source, tests, schemas, migrations |
+| `LOCAL_FS` | Stack references and generated artifacts |
+| `PROCESS` | Test, lint, typecheck, migration commands |
+| `CREDENTIALS` | Environment-managed DB URLs, API keys, secrets |
+| `NETWORK` | External APIs or backing services when required |
+
+### Preconditions
+- Target behavior and affected backend boundary are identifiable.
+- Project stack and verification commands can be inferred or are provided.
+- Required credentials remain outside source code.
+
+### Effects and side effects
+- Mutates backend source files, tests, and possibly migrations.
+- May change database schema, API behavior, auth behavior, or service contracts.
+- May require generated clients or migration artifacts.
+
+### 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. **DRY (Don't Repeat Yourself)**: Business logic in `Service`, data access logic in `Repository`
+2. **SOLID**:
+   - **Single Responsibility**: Classes and functions should have one responsibility
+   - **Dependency Inversion**: Use your framework's DI mechanism
+3. **KISS**: Keep it simple and clear
+
+### Architecture Pattern
+
+```
+Router (HTTP) → Service (Business Logic) → Repository (Data Access) → Models
+```
+
+### Repository Layer
+- Encapsulate DB CRUD and query logic
+- No business logic, return ORM entities
+
+### Service Layer
+- Business logic, Repository composition, external API calls
+- Business decisions only here
+
+### Router Layer
+- Receive HTTP requests, input validation, call Service, return response
+- No business logic, inject Service via DI
+
+### Core Rules
+
+1. **Clean architecture**: router → service → repository → models
+2. **No business logic in route handlers**
+3. **All inputs validated** with your stack's validation library
+4. **Parameterized queries only** (never string interpolation)
+5. **JWT + Argon2id for auth** (bcrypt acceptable for legacy compatibility); rate limit auth endpoints
+6. **Async where supported**; type annotations on all signatures
+7. **Custom exceptions** via centralized error module (not raw HTTP exceptions)
+8. **Explicit ORM loading strategy**: do not rely on default relation loading when query shape matters
+9. **Explicit transaction boundaries**: group one business operation into one request/service-scoped unit of work
+10. **Safe ORM lifecycle**: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it
+11. **Validate required configuration**: DB URLs, API keys, secrets, and feature flags come from environment variables or secret managers. Missing credentials fail clearly in default and production modes. Deterministic fixtures require an explicitly selected test/demo mode; label simulated results and never treat simulated payment, authentication, mail, or other effects as completed real operations.
+12. **Stateless services**: no in-memory session or user state between requests; use external stores (DB, Redis, cache) for shared state
+13. **Backing services as resources**: DB, queue, cache, mail are swappable attached resources connected via config; Repository layer must not assume a specific instance
+
+### Stack Detection
+
+1. **Project files first**: Read existing code, package manifests (pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml, etc.) to determine the tech stack
+2. **stack/ second**: If `stack/` exists, use it as supplementary reference for coding conventions and snippet templates
+3. **Neither exists**: Ask the user or suggest running `/stack-set`
+
+### Stack-Specific Reference
+
+<!-- oma-docs:ignore-start -->
+- **Stack manifest (SSOT)**: `stack/stack.yaml`: structured declaration (`language`, `framework`, `orm`) and `verify:` contract consumed by `oma verify agent backend`. Schema: `variants/stack.schema.json`.
+- Tech stack narrative: `stack/tech-stack.md`: human-readable reference only; `stack.yaml` wins on conflict.
+- Code snippets (copy-paste ready): `stack/snippets.md`
+- API template: `stack/api-template.*`
+<!-- oma-docs:ignore-end -->
+
+## References
+- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)
+
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Checklist (run before handoff): `resources/checklist.md`
+- ORM reference: `resources/orm-reference.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 — propagators/baggage, span conventions, log correlation, PII redaction

package/skills/oma-backend/resources/checklist.md

@@ -0,0 +1,45 @@
+# Backend Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## API Design
+- [ ] RESTful conventions followed (proper HTTP methods, status codes)
+- [ ] OpenAPI documentation complete (all endpoints documented)
+- [ ] Request/response schemas defined with validation library
+- [ ] Pagination for list endpoints returning > 20 items
+- [ ] Consistent error response format
+
+## Database
+- [ ] Migrations created and tested
+- [ ] Indexes on foreign keys and frequently queried columns
+- [ ] No N+1 queries; relation loading strategy chosen explicitly for the ORM in use
+- [ ] No over-fetching; selected only required fields/columns/attributes
+- [ ] Transactions used for multi-step operations with explicit unit-of-work boundaries
+- [ ] ORM session/client/entity-manager lifecycle matches the framework's concurrency model
+- [ ] Query risks reviewed: missing indexes, full scans, repeated identical queries, join row multiplication
+
+## Security
+- [ ] JWT authentication on protected endpoints
+- [ ] Password hashing with Argon2id (bcrypt cost 10-12 acceptable for legacy compatibility)
+- [ ] Rate limiting on auth endpoints
+- [ ] Input validation enforced (no raw user input in queries)
+- [ ] SQL injection protected (ORM or parameterized queries)
+- [ ] No secrets in code or logs
+
+## Testing
+- [ ] Unit tests for service layer logic
+- [ ] Integration tests for all endpoints (happy + error paths)
+- [ ] Auth scenarios tested (missing token, expired, wrong role)
+- [ ] Project coverage target met; if no target exists, document changed behavior coverage and any justified exclusions
+
+## Code Quality
+- [ ] Clean architecture layers: router -> service -> repository
+- [ ] No business logic in route handlers
+- [ ] Async/await used consistently
+- [ ] Type annotations on all function signatures
+
+## Cloud Readiness
+- [ ] No hardcoded config values (DB URLs, API keys, ports); all from env vars
+- [ ] No in-process state between requests (sessions, caches, counters)
+- [ ] Logs written to stdout/stderr, not file; structured format (JSON) preferred
+- [ ] Graceful shutdown handled for background jobs and open connections

package/skills/oma-backend/resources/error-playbook.md

@@ -0,0 +1,97 @@
+# Backend Agent - Error Recovery Playbook
+
+When you encounter a failure, find the matching scenario and follow the recovery steps.
+Use the relevant recovery steps. If required information or authority is missing, pause the dependent action and continue independent work.
+
+---
+
+## Import / Module Not Found
+
+**Symptoms**: Module/package not found errors
+
+1. Check the import path: typo? wrong package name?
+2. Verify the dependency exists in your package manifest
+3. If missing: note it in your result as "requires install the missing dependency"; do NOT install yourself
+4. If it's a local module: check the directory structure with `get_symbols_overview`
+5. If the path changed: use `search_for_pattern("class ClassName")` to find the new location
+
+---
+
+## Test Failure
+
+**Symptoms**: test runner returns FAILED, assertion errors
+
+1. Read the full error output: which test, which assertion, expected vs actual
+2. `find_symbol("test_function_name")` to read the test code
+3. Determine: is the test wrong or is the implementation wrong?
+   - Test expects old behavior → update test
+   - Implementation has a bug → fix implementation
+4. Run the specific failing test with verbose output
+5. After the fix, run affected regression tests; run a broader suite only when impact or project requirements justify it
+6. **After 3 failures**: Try a different approach. Record current attempt in progress and implement alternative
+
+---
+
+## Database Migration Error
+
+**Symptoms**: Migration command fails, `IntegrityError`, duplicate column
+
+1. Read the error; is it a conflict with existing migration?
+2. Check current DB state: Check current migration state
+3. Inspect applied steps and partial changes first. In production or shared environments, prefer a reviewed forward fix. Roll back only in disposable development databases or with a tested, data-safe down migration; do not rewrite an already-applied migration.
+4. If schema mismatch: compare model with actual DB schema
+5. **NEVER do this**: Force-mark migrations as applied (risk of data loss)
+
+---
+
+## Authentication / JWT Error
+
+**Symptoms**: 401/403 responses, `InvalidTokenError`, `ExpiredSignatureError`
+
+1. Check: is the secret key consistent between encode and decode?
+2. Check: is the algorithm specified (`HS256` vs `RS256`)?
+3. Check: is the token being sent in the correct header format? (`Bearer {token}`)
+4. Check: is token expiry set correctly? (access: 15min, refresh: 7day)
+5. Test with a manually created token to isolate the issue
+
+---
+
+## N+1 Query / Slow Response
+
+**Symptoms**: API response > 500ms, many similar SQL queries in logs
+
+1. Enable SQL logging on the database connection
+2. Count queries for a single request
+3. If N+1: add eager loading strategy appropriate for your ORM to the query
+4. If slow single query: check indexes with `EXPLAIN ANALYZE`
+5. If still slow: consider caching with Redis
+
+---
+
+## Rate Limit / Quota Error (LLM runtime)
+
+**Symptoms**: `429`, `RESOURCE_EXHAUSTED`, `rate limit exceeded` (any vendor runtime — Gemini, Claude, Codex, etc.)
+
+1. Identify the source. An expected rate-limit response from the application under review is a test result, not an agent-provider quota failure.
+2. For provider quota exhaustion, stop affected provider calls and record the unavailable checks; continue independent authorized work when possible.
+3. Preserve injected session/task/run IDs and the claim path. Save progress/results under the configured memory base using the task/run-scoped names in `../../_shared/runtime/memory-protocol.md`.
+4. Use a valid claim status (`partial`, `blocked`, or `failed`) with the actual cause and unresolved work per `../../_shared/runtime/result-contract.md`; do not invent a `quota_exceeded` status.
+
+---
+
+## Workflow State Unavailable
+
+Follow `../../_shared/runtime/memory-protocol.md`; state storage is independent of the code-intelligence provider.
+
+1. Use the injected progress/result paths and session/task identity.
+2. If a file operation fails, retry once when the failure may be transient.
+3. Preserve work and report the failed path and error to the coordinator. Do not silently redirect artifacts to `/tmp` or mark a missing result as completed.
+4. For read-only tasks, return the result through the runtime's response channel as required by the dispatch contract.
+
+---
+
+## General Principles
+
+- **After 3 failures**: If same approach fails 3 times, must try a different method
+- **Blocked**: If no progress after 5 turns, save current state and record `Status: blocked` in result
+- **Out of scope**: If you find issues in another agent's domain, only record in result; do not modify directly

package/skills/oma-backend/resources/execution-protocol.md

@@ -0,0 +1,39 @@
+# Backend Agent - Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Analyze
+- Read the task requirements carefully
+- Identify which endpoints, models, and services are needed
+- Inspect existing structure and relevant symbols via `../../_shared/core/code-intelligence.md`; if the configured provider is unavailable, use native search only for paths outside this project or ignored paths
+- If the task is ORM-heavy, load `resources/orm-reference.md` before deciding on loading strategy, transaction scope, or client/session lifecycle
+- List assumptions; ask if unclear
+
+## Step 2: Plan
+- Decide on file structure: models, schemas, routes, services
+- Define API contracts (method, path, request/response types)
+- Plan database schema changes (tables, columns, indexes, migrations)
+- Plan relation loading strategy, transaction boundary, and ORM lifecycle constraints explicitly
+- Identify security requirements (auth, validation, rate limiting)
+
+## Step 3: Implement
+- **Honor the task's `test_approach`** (see `../../_shared/core/test-approach.md`): for `tdd` tasks, write and run the focused test first (record the RED failure), make the minimal change (GREEN), then continue; for `tdd` the test comes before item 3 below
+- Typical affected files (choose an order from actual dependencies):
+  1. Database models + migrations
+  2. Validation schemas (request/response)
+  3. Service layer (business logic)
+  4. API routes (thin, delegate to services)
+  5. Tests (unit + integration)
+- Use `stack/api-template.*` as reference
+- Follow clean architecture: router -> service -> repository -> models
+
+## Step 4: Verify
+- Check applicable items in `resources/checklist.md`
+- Use `../../_shared/core/common-checklist.md` only for cross-domain verification
+- Ensure affected tests and required project checks pass
+- For `tdd` tasks, append the `TDD_EVIDENCE` block (test command, RED, GREEN) to the result file per `../../_shared/core/test-approach.md`
+- Confirm OpenAPI docs are complete
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.

package/skills/oma-backend/resources/orm-reference.md

@@ -0,0 +1,61 @@
+# Backend Agent - ORM Reference
+
+Use this guide when the task involves ORM query design, relation loading, transaction scoping, or session/client lifecycle decisions.
+
+## ORM Rules
+
+### 1. Relation loading must be chosen per use case
+
+Backend Agent should therefore:
+- choose loading strategy per endpoint or service method
+- compare join-based eager loading, batched/select-in loading, and separate follow-up queries
+- choose SQLAlchemy's `joinedload`, `selectinload`, `lazyload`, or `raiseload` explicitly for the access pattern
+- use Sequelize `include` for join-based eager loading or `separate: true` for `hasMany` when separate loading fits the query
+- treat accidental lazy loads in loops as a performance bug
+
+### 2. Transaction boundaries must follow business operations
+
+Backend Agent should therefore:
+- open one explicit transaction for one business operation; in Sequelize, use a managed transaction callback for that unit of work
+- keep read-modify-write flows inside the same transaction boundary
+- avoid per-statement auto-commit designs
+- never hold a database transaction open across user think time
+
+### 3. ORM lifecycle objects are not generic shared singletons
+
+Backend Agent should therefore:
+- reuse factory/client objects only when the ORM recommends reuse
+- keep transaction-scoped mutable objects request-scoped or task-scoped
+- never share stateful unit-of-work objects across concurrent tasks unless the vendor explicitly permits it
+
+Operational reading:
+- Prisma: reuse one `PrismaClient` in long-running apps; do not create a new client per query; do not disconnect after every request
+- SQLAlchemy: `Session` and `AsyncSession` are mutable, transaction-scoped, and the documented model is session-per-thread / async-session-per-task
+- Hibernate: prefer session-per-request over session-per-operation
+
+### 4. Field projection is mandatory unless full entity hydration is required
+
+Backend Agent should therefore:
+- fetch only required columns, attributes, or nested fields using Prisma nested `select`, TypeORM `select`, or Sequelize `attributes`
+- prefer projections, DTO shaping, or raw results when domain objects are not needed; use TypeORM `getRawMany()` or Sequelize `{ raw: true }` when entity hydration is unnecessary
+- treat over-fetching as a query design flaw, not a minor optimization item
+
+### 5. Mapping defaults must never be trusted blindly
+
+Lazy and eager defaults are convenience features, not query plans. Multiple vendors warn that both directions can fail differently:
+- lazy defaults can explode into N+1
+- eager defaults can create oversized joins, duplicate parent rows, or unnecessary payloads
+
+Backend Agent should therefore:
+- inspect relation defaults before changing repository or endpoint behavior
+- override defaults at query time when access shape differs from mapping defaults
+- prefer repository-level query shaping over relying on entity metadata alone
+
+### 6. Query review must include access-path and row-shape checks
+
+Backend Agent should therefore review:
+- missing indexes on filters, joins, and foreign keys
+- full table scans
+- repeated identical queries that should be cached or batched
+- row multiplication from `hasMany` / collection eager joins
+- memory cost of hydrating full entities when raw results or projections are enough