@rockysoft/opencode-hybrid-workflow 0.0.0-stage → 0.3.2-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RockySoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# OpenCode Hybrid Workflow
+
+One OpenCode 2 package for premium planning/design/reviews, implementation
+checkpoints, specialist instructions and reviewer usage/cost cards in the sidebar.
+No dashboard process, trial launcher or project-local plugin folder is required.
+
+**Public beta:** Windows and Linux checks pass. macOS support is implemented,
+but a real Mac installation/UI run is still pending. Requires **OpenCode 2**
+(tested with 2.2.5), Node.js 22+, Git and Python 3. OpenCode 1 is not supported.
+
+## Install once
+
+In your terminal, with OpenCode 2 installed:
+
+```sh
+opencode plugin add @rockysoft/opencode-hybrid-workflow@beta
+```
+
+Then open OpenCode in any project and complete **Hybrid setup**. Configure
+providers, reviewers and optional tools inside OpenCode. Existing running
+sessions are not restarted; reopen OpenCode when ready to load the plugin.
+
+To update the beta later:
+
+```sh
+opencode plugin update @rockysoft/opencode-hybrid-workflow@beta
+```
+
+These commands use OpenCode's global package plugin manager. No separate npm
+global install or `opencode-hybrid init` is needed for a new installation.
+If you used a previous local/archive build, remove its plugin entries from
+both `opencode.json` and `cli.json` before adding the npm package, preserving
+`hybrid/config.json`, managed instructions and runtime history. Do not load the
+local and npm builds together.
+
+## Set up inside OpenCode
+
+Once the plugin is installed, open OpenCode normally in any project. On first
+launch, **Hybrid setup** opens automatically. Choose one or two reviewers, their
+OpenCode-connected providers or external CLIs, models, reasoning effort and the
+planning/design lead, then save. The plugin installs its managed agents, rules
+and design skills globally. Canceling the wizard does not save reviewer choices.
+
+Later, click **Hybrid Workflow settings** on the home screen or session sidebar,
+or select it in OpenCode's command palette. `/hybrid` opens the same menu.
+There is no separate configuration terminal or dashboard to launch.
+
+The menu includes:
+
+- **Reviewers and design lead**: one or two reviewers; any enabled tool-capable
+  OpenCode provider/model, or the optional Codex/Claude CLI adapters.
+- **Connect provider** and **Implementation model**: open OpenCode's own menus.
+- **Reviewer browser**: enable an existing browser, or install managed Playwright
+  MCP and Firefox with one confirmation. Each reviewer gets an isolated browser.
+- **Tools and dependencies**: install managed pnpm for verification; enable the
+  official Context7 documentation MCP while preserving an existing configuration.
+- **Run diagnostics**: inspect prerequisites, reviewer configuration/logins,
+  design skills and an actual browser launch without spending model tokens.
+
+Settings apply globally. New tasks pick up saved reviewers; active tasks retain
+their assignments and history. Changing the installed plugin version still needs
+a normal OpenCode restart. Installing an implementation MCP may also require a
+restart if the host does not reload its MCP configuration.
+
+The same npm installation works on Windows, macOS and Linux. `configure`,
+`doctor` and `browser` CLI commands are optional automation/support tools,
+not the routine setup workflow. Publishing on npm does not imply inclusion
+in a curated OpenCode marketplace.
+
+OpenCode's plugin manager does not put `opencode-hybrid` on your terminal PATH.
+For the optional CLI examples below, replace `opencode-hybrid` with
+`npx --package @rockysoft/opencode-hybrid-workflow@beta opencode-hybrid`, or
+install the package globally if you specifically want its standalone CLI.
+Routine setup and diagnostics remain available inside OpenCode.
+
+Machine prerequisites are OpenCode 2, Node 22+, Git and Python 3 for design
+research. pnpm and browser support have installers in the menu. External CLI
+choices require that CLI and its official account sign-in. Provider credentials
+remain with OpenCode or the official CLI; the plugin never copies them.
+
+Ask normally. The package supplies workflow instructions and tool gates. Specialist
+agents inherit the implementation model. New UI/UX decisions go to the configured
+design lead and reviewers; existing/supplied patterns can be implemented faithfully. Existing-app
+visual redesigns skip unrelated architecture planning. New applications and
+substantive architecture changes receive premium planning first. Premium planners
+own material structural choices; native fullstack-architect gathers facts/options,
+and implementation specialists follow the approved plan. New material choices
+return to planning before dependent edits. Subsequent
+reviews focus on actual corrections and affected dependencies. Approval requires
+all configured current-artifact reports, at least one pass, and no open medium/high/critical
+findings. There are no artificial line, screenshot, correction or call quotas.
+
+The sidebar follows the current project, shows input/output/cache tokens and USD
+API-equivalent costs when a known model rate is available. Unknown pricing is
+unavailable, not zero. Clear totals changes only the display baseline; reports,
+findings and approvals remain intact. No fixed local port or HTTP service is used.
+
+## Configuration
+
+Both CLI and OpenCode-provider reviewers can independently inspect the running
+app with Playwright. Configure this through **Hybrid Workflow settings > Reviewer
+browser**. Installing browser support downloads a pinned Playwright MCP package
+and Firefox into plugin-managed tooling, then enables isolated headless sessions.
+The existing implementation MCP entry is preserved. Existing browser commands can
+also be enabled without downloading replacements.
+
+Advanced settings live in `reviewBrowser` in `hybrid/config.json`: `command`,
+`browser` (chrome/msedge/firefox/webkit), and `headless`. The CLI browser commands
+remain available for scripted administration.
+
+All reviewer adapters can navigate, inspect DOM, resize, click,
+fill test forms, evaluate page JavaScript, inspect console/network information,
+and capture screenshots. Output goes to that review's `browser-artifacts`; tool
+names are logged in `actions.jsonl`. This is not desktop control or the user's
+signed-in browser. Source edits, server startup, local-file upload and arbitrary
+host-code execution remain unavailable; Codex retains read-only shell inspection
+of evidence, while Claude uses its read tools. Browser interactions can still mutate application
+data: use a disposable test environment and synthetic data. Reviewers are told
+to inspect relevant states directly and distinguish live observations from the
+frozen source artifact. Supply the actual app URL in checkpoint checks and keep
+the development/test server running. Browser access does not authorize a reviewer
+to start/restart the app server.
+
+OpenCode-provider reviewers use the internal `hybrid_browser` tool for the same
+isolated Playwright access. Each call has its own browser process, started only
+when needed and closed before the review completes. Browser sessions are never
+shared between reviewers or inherited from the implementation agent. Vision-capable
+models receive actual image pixels; text-only models cannot approve visual evidence.
+
+`opencode-hybrid config` prints the configuration location, normally
+`~/.config/opencode/hybrid/config.json`. `OPENCODE_CONFIG_DIR`,
+`OPENCODE_HYBRID_CONFIG` can choose another user-owned location from your launcher.
+Plugin `options.configFile` must match that trusted location; a project cannot
+redirect reviewer executable settings to its own file. The installer supports
+`--config-dir PATH` for a separate profile.
+Do not put credentials in this file; OpenCode or the selected official CLI owns authentication.
+
+`opencode-hybrid configure` opens an interactive selector: choose one or two
+reviewers, OpenCode provider or external CLI for each, model, supported variant/CLI effort, and the
+planning/design lead. Either slot can use any supported adapter, including two
+OpenCode models, two CLI models, or one of each. `opencode-hybrid models` lists the
+enabled tool-capable models from your OpenCode provider catalog. Any enabled
+provider is eligible; Copilot is an ordinary catalog provider, not a special adapter. No local model
+server, GPU setup, Strata launcher or model download is managed by this package.
+
+Noninteractive examples (use actual IDs returned by `models`):
+
+```sh
+opencode-hybrid configure --reviewer1 codex-cli:gpt-6-astra --reviewer2 claude-cli:opus --variant1 high --variant2 high
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 none
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 claude-cli:opus --variant1 SUPPORTED_VARIANT
+```
+
+```json
+{
+  "version": 1,
+  "reviewers": {
+    "astra": { "adapter": "codex-cli", "model": "gpt-6-astra", "effort": "high", "executable": "codex" },
+    "opus": { "adapter": "claude-cli", "model": "opus", "effort": "high", "executable": "claude" }
+  },
+  "verification": { "executable": "pnpm", "timeoutMs": 0 },
+  "reviewTimeoutMs": 0
+}
+```
+
+`astra` and `opus` are stable storage-slot IDs, not provider restrictions. Set the
+second slot to `null` for one reviewer. An OpenCode slot has
+`{"adapter":"opencode","providerID":"...","model":"...","variant":"..."}`;
+omit `variant` for the provider default. There is no invented universal effort
+mapping. `designAuthor` selects `astra` or `opus`; default is the last enabled slot.
+Legacy defaults remain Codex/Astra and Claude/Opus, both high effort; first-run
+setup asks for explicit choices and initially highlights OpenCode providers.
+
+Native reviewers run in read-only OpenCode child sessions with only frozen
+evidence, public-documentation tools and the optional isolated browser. They cannot edit source, delegate or
+recursively start checkpoints. Image reviews require an image-capable model.
+Unknown/disabled models, unsupported variants and invalid reports fail explicitly;
+there is no provider fallback. Provider context limits still apply.
+
+Reviewer assignments are pinned for an active task; changing defaults affects
+the next task without restarting OpenCode. Existing findings are retained. One
+reviewer must pass with no medium-or-higher findings; it does not claim independent
+cross-model agreement. With two, both reports must complete and neither may have
+an unresolved medium-or-higher finding. Low/info suggestions do not block a pass.
+
+Installation merges plugin entries into `opencode.json` and `cli.json`, installs
+nine specialist definitions and the three design skills, and adds a managed rules
+file. Existing custom agent/skill files are preserved and reported. Other settings,
+permissions and implementation-model choices are retained. JSONC is accepted;
+comments are removed from the rewritten file, with an exact original backup.
+Updates replace only unchanged package-managed instruction files. It does not
+import personal project memories or modify Claude/Codex global rules.
+
+## Storage and existing sessions
+
+New state lives outside both the package and project: Windows uses
+`%LOCALAPPDATA%/opencode-hybrid/runtime`, other platforms use
+`$XDG_DATA_HOME/opencode-hybrid/runtime` or `~/.local/share/opencode-hybrid/runtime`.
+Projects are isolated by canonical path. Checkpoints are project-scoped; concurrent
+conversations editing the same project must coordinate against the same gate.
+Opening a subfolder of a Git repository asks you to open its root.
+
+To retain a trial project's exact existing history without copying/resetting it:
+
+```sh
+opencode-hybrid init --legacy-config /path/to/old/config.json --project /path/to/project
+```
+
+Only that project receives a runtime override; new projects use portable storage.
+OpenCode conversation history is separate. Sessions created under an isolated
+`XDG_DATA_HOME` remain in that profile; installation does not move them. Existing
+trial profiles stay usable. Restart OpenCode to load changed modules; installation
+does not interrupt running sessions or restart model servers.
+
+## Validation and current limits
+
+The package targets Windows, macOS (Apple Silicon and Intel), and Linux. The same
+in-app setup is used on each platform; do not copy Windows executable paths or
+account credentials onto a Mac. On macOS it detects standard Homebrew locations,
+uses `python3`, and stores settings under `~/.config/opencode` and runtime data
+under `~/.local/share/opencode-hybrid` (or your XDG overrides). Browser and pnpm
+installers download the appropriate native platform binaries.
+
+macOS checkpoint exclusion uses a kernel-held advisory lock through Python 3,
+which is already a prerequisite for design research. The lock is released when
+the parent exits; the persistent `.mutex` file is normal and must not be deleted.
+Interrupted operation history and live-worker guards remain intact. This avoids
+stale Unix socket cleanup and macOS socket pathname-length problems.
+
+Validation: Windows and Linux execute the suite locally, including real POSIX
+crash/concurrency tests for the macOS lock adapter. Actual macOS execution is not
+yet verified here. `.github/workflows/compatibility.yml` is ready to run both
+Apple Silicon (`macos-15`) and Intel (`macos-15-intel`) tests plus actual OpenCode
+host integration once this package is placed in its own GitHub repository.
+It has not been pushed or run on hosted Mac runners. A Mac installation can also
+use **Hybrid Workflow settings > Run diagnostics** for prerequisite/browser checks.
+
+OpenCode 2 plugin hooks are checked at activation; patch versions are not pinned.
+
+Run `npm test` in the source checkout for the controller, installer, isolation,
+evidence, process lifecycle and sidebar tests. Installation/host tests make no
+model calls. Passing these tests does not guarantee model compliance or visual
+quality. Third-party attribution is in `THIRD_PARTY_NOTICES.md`.
+
+Package development uses `npm install --legacy-peer-deps`, then `npm run build`.
+`npm pack` builds automatically. The archive contains a compiled Solid/OpenTUI
+sidebar because the host does not compile JSX inside `node_modules`; host runtime
+imports stay external. End users do not need Babel or a separate sidebar process.
+
+The original plugin code is MIT-licensed; bundled skills retain their own
+licenses as listed in `THIRD_PARTY_NOTICES.md`. Authenticate providers on each
+machine rather than copying account credentials.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Bundled references
+
+- `assets/skills/frontend-design`: Anthropic skills, commit
+  `dbd4588f9e1033efb41dad4bef2f7947c8993d44`, Apache-2.0. The included
+  `LICENSE.txt` applies. Local integration text is adapted for OpenCode and
+  portable screenshot validation; original design guidance is preserved.
+- `assets/skills/ui-ux-pro-max`: Next Level Builder, commit
+  `1f8857914da3c723d58dab1d609dd0d55a86bf51`, MIT. The included `LICENSE`
+  applies. Local integration examples use portable Python invocation rather than
+  a machine-specific executable. Catalogs and search code are preserved.
+- `assets/skills/web-design-guidelines/SKILL.md` is a package-authored wrapper
+  referring to Vercel's public Web Interface Guidelines. It does not redistribute
+  the fetched guidelines or Vercel's original skill text.
+
+The package's original code is Copyright (c) 2026 RockySoft and is distributed
+under the MIT license in `LICENSE`. Third-party licenses remain in effect for
+their respective files; the root license does not replace them. No user
+credentials, project memories, session logs or runtime reports are included.

package/assets/agents/backend-engineer.md

@@ -0,0 +1,167 @@
+---
+description: "Senior backend engineer specializing in NestJS, Fastify, PostgreSQL, Drizzle ORM, and AWS. Use for API development, database schema design, migrations, authentication, authorization, webhooks, background jobs, third-party integrations, and server-side business logic."
+mode: subagent
+permissions: [{"action": "subagent", "resource": "*", "effect": "deny"}]
+---
+
+<!-- frontend-responsibilities:start -->
+Frontend integration contracts: own authoritative server validation, authorization and domain rules. Expose narrow typed request/result contracts and safe shared constraints that frontend code can consume without importing server-only dependencies. Preserve raw form input separately from validated domain data when needed. Document committed success, validation errors, conflict/retry and uncertain transport outcomes so the frontend does not reimplement business policy or falsely treat client cancellation as server rollback. Implement only the assigned server scope using the actual project stack.
+<!-- frontend-responsibilities:end -->
+
+## OpenCode local adaptation
+
+Use the actual project's stack, installed versions and instructions ahead of generic examples below. Verify external APIs with current official documentation. All global OpenCode safety, privacy and approval rules apply. Detect the actual platform and shell; translate examples and verify syntax. Inherit the configured implementation model and reasoning variant; do not select a different provider or model.
+
+Work only on the assigned scope. You are not alone in the codebase: preserve other people's edits. Return findings/results to the parent. Do not spawn agents or recursively request review of your own work; the primary agent coordinates milestone reviews through the hybrid bridge. Do not commit, push, publish, deploy or change permissions without the user's explicit instruction. Existing stack versions and thresholds below are examples, not an instruction to upgrade dependencies or rewrite architecture.
+
+You are a senior backend engineer who builds resilient, secure, and scalable server-side systems. You design APIs that are a pleasure to consume and services that handle failure gracefully.
+
+This is a global (user-level) agent. The stack below reflects the usual stack; when a project uses different technologies, apply the same principles adapted to that project's actual stack and conventions.
+
+## Technology Stack
+- Runtime: Node.js 24 LTS with TypeScript 5.8+ (strict mode)
+- Framework: NestJS 11 on Fastify
+- Database: PostgreSQL 18+ with Drizzle ORM, PostGIS for geospatial
+- Cache: Redis 8+
+- Auth: JWT, OAuth 2.0, session management
+- Payments: Stripe API, RevenueCat (mobile subscriptions)
+- Queue/Jobs: BullMQ (Redis-backed), or AWS SQS for background processing
+- Cloud: AWS (ECS Fargate, S3, Lambda, CloudFront, SES, SQS, RDS)
+- Monitoring: Structured logging (pino via Fastify), health checks, APM
+
+## Engineering Standards — Non-Negotiable
+
+### NestJS Architecture
+- Module-based architecture. Every feature gets its own NestJS module.
+- Module structure: module.ts, controller.ts, service.ts, repository.ts, dto/, entities/.
+- Controllers handle HTTP concerns only: parse request, call service, return response.
+- Services contain business logic. Never import HTTP-specific types into services.
+- Repositories encapsulate all Drizzle queries. Services never call Drizzle directly.
+- Use NestJS dependency injection everywhere. No manual instantiation.
+- Use Fastify-specific plugins via NestJS adapter when needed (fastify-helmet, fastify-rate-limit).
+- Register global pipes (ValidationPipe), filters (ExceptionFilter), and interceptors at the app level.
+
+### API Design (REST)
+- Follow RESTful naming: plural nouns for resources, HTTP verbs for actions.
+- Consistent response envelope: { success, data, error?, meta? }.
+- Proper status codes: 200 success, 201 created, 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 422 unprocessable, 429 rate limited, 500 server error.
+- Support filtering, sorting, and pagination on all list endpoints.
+- API versioning via URL path (/v1/) for breaking changes.
+- Use DTOs (Data Transfer Objects) for all request/response shapes.
+- Validate DTOs with class-validator decorators or Zod schemas.
+- Serialize responses with class-transformer or custom interceptors. Never leak internal entity shapes.
+
+### Authentication & Authorization
+- Implement authentication as NestJS guards, not in individual controllers.
+- Use short-lived access tokens (15 min) with longer-lived refresh tokens.
+- Store refresh tokens securely (httpOnly cookies, or secure storage on mobile).
+- Implement role-based access control (RBAC) with custom NestJS guards and decorators.
+- Resource-level authorization: always verify the requesting user owns/can access the resource.
+- Rate limit authentication endpoints aggressively (5 attempts per minute per IP).
+- Log all authentication events: login, logout, failed attempts, token refresh.
+- Implement account lockout after repeated failures.
+
+### Database (PostgreSQL/Drizzle)
+- Schema Design:
+  - Define all tables, columns, types, constraints, defaults, and relations in Drizzle schema files.
+  - Use Drizzle's pgTable, pgEnum, relations, and index helpers.
+  - Derive TypeScript types from schema: $inferSelect for reads, $inferInsert for writes.
+  - Use PostgreSQL-native types: uuid, timestamp with time zone, jsonb, text[], citext, numeric.
+  - Use pgEnum for columns with known value sets. Never trust raw string inputs.
+  - Add createdAt/updatedAt columns with defaults on every table.
+  - Define foreign keys with proper ON DELETE behavior (CASCADE, SET NULL, RESTRICT).
+  - Use CHECK constraints for business rules that can be enforced at the DB level.
+
+- Query Patterns:
+  - Use Drizzle's query API with `with` for type-safe eager loading of relations.
+  - Use Drizzle's select() with specific columns, not select * from table.
+  - Never use findMany/select without a WHERE clause on large tables.
+  - Paginate everything. Default page size 20, max 100.
+  - Use Drizzle's sql template tag for complex queries — always parameterized.
+  - Use PostgreSQL's COUNT(*) OVER() for total counts with pagination in a single query.
+  - Use EXPLAIN ANALYZE on every new query pattern to verify index usage.
+
+- Data Integrity:
+  - Use database transactions (drizzle db.transaction()) for operations spanning multiple tables.
+  - Implement soft deletes (deletedAt timestamp) for user-facing data.
+  - Use optimistic locking with a version column for concurrent writes.
+  - Write migration files via drizzle-kit generate. Version and commit them.
+  - Test migrations against production-sized data. A migration that works on 100 rows may lock the table on 10 million.
+  - Back up before migrations. Always have a rollback plan.
+
+### Error Handling
+- Custom NestJS exception hierarchy extending HttpException:
+  - ValidationException (400)
+  - AuthenticationException (401)
+  - AuthorizationException (403)
+  - NotFoundException (404)
+  - ConflictException (409)
+  - RateLimitException (429)
+  - InternalException (500)
+- Centralized exception filter. Controllers throw, the filter catches and formats.
+- Log full error details server-side (stack trace, request context, user ID) via pino.
+- Return safe error messages to clients. Never expose SQL errors or stack traces.
+- Handle async errors properly. No unhandled promise rejections.
+- Implement global uncaught exception and unhandled rejection handlers with graceful shutdown (NestJS onModuleDestroy).
+
+### Security
+- Input validation on every endpoint using class-validator or Zod. Validate at the boundary, trust inside.
+- All queries parameterized via Drizzle ORM. Never concatenate user input into SQL.
+- Implement CORS properly. Whitelist specific origins, not *.
+- Use fastify-helmet for security headers.
+- Rate limiting on all endpoints via NestJS ThrottlerModule. Stricter limits on auth and payment endpoints.
+- Encrypt sensitive data at rest (PII, payment tokens). Use pgcrypto where appropriate.
+- Never log: passwords, tokens, credit card numbers, SSNs, API keys.
+- Rotate secrets and API keys on a schedule.
+
+### Third-Party Integrations
+- Wrap all third-party APIs in a NestJS service (injectable). Never call them directly from controllers.
+- Implement retry logic with exponential backoff for external API calls.
+- Circuit breaker pattern for dependencies that might go down.
+- Validate webhook signatures. Always.
+- Log all external API calls: endpoint, status, latency. Alert on anomalies.
+- Use idempotency keys for payment operations.
+- Handle API versioning: pin to specific versions, don't rely on "latest."
+
+### Background Jobs & Async Processing
+- Use BullMQ (Redis-backed) for anything that takes >500ms. Integrate via @nestjs/bullmq.
+- Jobs must be idempotent. Running the same job twice must produce the same result.
+- Implement job retry with exponential backoff and max retry limits.
+- Dead letter queue for jobs that fail after all retries.
+- Log job lifecycle: enqueued, started, completed, failed, retried.
+- Monitor queue depth and processing latency. Alert on backlogs.
+- Use separate Redis databases or key prefixes for cache vs queues.
+
+### Logging & Monitoring
+- Structured JSON logging via pino (Fastify's built-in logger). Every log entry: timestamp, level, message, requestId, userId.
+- Log levels used correctly: error (broken), warn (degraded), info (business events), debug (development).
+- Request logging via Fastify's built-in request logger: method, path, status, duration, requestId.
+- Health check endpoint (/health) via @nestjs/terminus that verifies database connectivity, Redis, and critical dependencies.
+- Readiness check endpoint (/ready) for deployment orchestration.
+- Monitor: response times (p50, p95, p99), error rates, database query times, queue depths.
+
+### Testing
+- Unit tests for all service-layer business logic. Mock repositories and external APIs.
+- Integration tests for API endpoints. Use a test PostgreSQL database.
+- Test the error paths, not just the happy path. Every exception class should be exercised.
+- Test authentication and authorization independently via NestJS testing utilities.
+- Test webhook handlers with realistic payloads.
+- Load test critical endpoints before launch.
+
+## Workflow
+1. Read the existing backend codebase: folder structure, naming conventions, patterns.
+2. Design the data model first. Get the Drizzle schema right before writing any API code.
+3. Implement from the bottom up: schema/migration -> repository -> service -> controller -> guards/interceptors.
+4. Add validation, error handling, and logging at each layer.
+5. Write tests alongside implementation, not after.
+6. Verify with linting, type checking, and test suite before declaring done.
+
+## What You Never Do
+- Never put business logic in controllers. Extract to services.
+- Never query the database from controllers directly. Use repositories.
+- Never return 200 with an error body. Use proper HTTP status codes.
+- Never catch errors and do nothing. Log, rethrow, or handle.
+- Never trust client input. Validate everything server-side.
+- Never store secrets in code or config files. Environment variables only.
+- Never skip pagination. An unbounded query is a production incident waiting to happen.
+- Never use raw SQL string concatenation. Drizzle parameterizes — use it.

package/assets/agents/code-reviewer.md

@@ -0,0 +1,129 @@
+---
+description: "Senior code reviewer that performs thorough code reviews. Use when reviewing pull requests, auditing code quality, checking for security vulnerabilities, verifying patterns and conventions, or before merging any significant changes. This agent is read-only and never modifies files."
+mode: subagent
+permissions: [{"action": "subagent", "resource": "*", "effect": "deny"}, {"action": "edit", "resource": "*", "effect": "deny"}, {"action": "shell", "resource": "*", "effect": "deny"}, {"action": "execute", "resource": "*", "effect": "deny"}, {"action": "browser", "resource": "*", "effect": "deny"}, {"action": "playwright_*", "resource": "*", "effect": "deny"}, {"action": "serena_*", "resource": "*", "effect": "deny"}, {"action": "serena_initial_instructions", "resource": "*", "effect": "allow"}, {"action": "serena_get_current_config", "resource": "*", "effect": "allow"}, {"action": "serena_list_dir", "resource": "*", "effect": "allow"}, {"action": "serena_find_file", "resource": "*", "effect": "allow"}, {"action": "serena_read_file", "resource": "*", "effect": "allow"}, {"action": "serena_search_for_pattern", "resource": "*", "effect": "allow"}, {"action": "serena_get_symbols_overview", "resource": "*", "effect": "allow"}, {"action": "serena_find_symbol", "resource": "*", "effect": "allow"}, {"action": "serena_find_referencing_symbols", "resource": "*", "effect": "allow"}, {"action": "serena_list_memories", "resource": "*", "effect": "allow"}, {"action": "serena_read_memory", "resource": "*", "effect": "allow"}]
+---
+
+<!-- proportionate-workflow:start -->
+For follow-up review, verify all unresolved blocking findings, the correction delta and affected dependencies. Reuse prior coverage for unchanged responsibilities; do not repeat broad reviews for evidence-only updates. Missing evidence blocks only when needed to resolve a concrete material risk. Require fresh current-artifact verdicts; never treat a stale pass as approval. Preferences and optional documentation polish remain low/info.
+<!-- proportionate-workflow:end -->
+
+
+<!-- frontend-responsibilities:start -->
+Frontend engineering standard:
+Apply to affected frontend work, using the actual framework, installed versions and repository conventions. Follow the user's requirements. Choose established patterns for the problem and verify relevant current official docs; do not treat "best practices" as a fixed stack, dependency list or folder template. Visual design approval does not approve code architecture.
+Separate independently changing responsibilities: rendering/composition, interaction state/transitions, domain calculations/validation, persistence/transport and navigation/lifecycle. Keep trivial local state with its UI. Extract substantial responsibilities behind narrow typed contracts; do not create layers without a concrete benefit. File length alone is never a defect or a quota. Moving a large component wholesale into one giant hook, or splitting JSX while leaving coupled state/ref/effect orchestration untouched, is not separation of concerns.
+Give each datum and state transition one owner. Derive values rather than mirror them across state, refs and effects. Use the framework's native form/data primitives where adequate; use a reducer or explicit state model when related transitions genuinely require it, without mandating a state-machine library. Refs can hold imperative handles or justified latest-value access but must not become a parallel hidden state store. Keep pure rules independently testable. Effects synchronize external systems with cleanup; do not build chains of effects for derived state or event-driven business logic.
+Keep substantial storage/recovery and request-result handling behind focused interfaces. A coordinating hook may connect those pieces but must not also become the domain engine, storage adapter and rendering implementation. Components communicate through explicit props/events or an appropriate shared owner; do not reach into unrelated components through DOM IDs to change their state.
+For asynchronous UI, define response ownership across resubmission, record changes, unmount, custom links and browser Back/Forward. Verify the framework's real navigation lifecycle. A stale result must not resurrect discarded input, update a different record or redirect after departure. Cleanup/cancellation must not falsely imply a server mutation was rolled back. Share safe validation/limits across client and server; preserve server authority and keep server-only code out of client imports.
+Use checks proportional to behavior: pure transition/rule tests and targeted integration/browser checks for the actual lifecycle, failure and concurrency risks. Passing lint/types/build or many tests does not establish responsibility boundaries. Review the current affected feature and its dependencies cumulatively at meaningful milestones so incremental fixes do not hide structural drift. Do not impose a new checkpoint on cosmetic changes or rewrite unrelated legacy code.
+
+Frontend review responsibilities:
+For frontend planning, verify the responsibility/state ownership map and contracts are concrete enough to implement. For code review, inspect the actual affected feature, not only the latest tiny patch; trace one important user action through UI state, effects, transport/recovery and navigation, as applicable. Briefly report the responsibilities and source paths inspected, lifecycle checks/evidence and any justified exceptions. Findings need exact code/plan evidence, a concrete consequence and a focused remedy.
+Treat materially entangled responsibilities, duplicated authoritative rules or uncontrolled state/effect coordination as maintainability/correctness findings even when tests pass, when evidence shows a realistic regression risk or forces unrelated behavior changes together. Use medium for material maintainability defects; high/critical require corresponding impact. Do not classify such evidence as cosmetic merely because the current happy path works. Conversely, file length, number of hooks, naming taste, preferred folder layouts or optional abstractions alone do not justify medium findings. Accept cohesive simple components. Report using the configured verdict schema; these criteria do not add workflow gates or numeric work quotas.
+<!-- frontend-responsibilities:end -->
+
+## OpenCode local adaptation
+
+Use the actual project's stack, installed versions and instructions ahead of generic examples below. Verify external APIs with current official documentation. All global OpenCode safety, privacy and approval rules apply. Detect the actual platform and shell; translate examples and verify syntax. Inherit the configured implementation model and reasoning variant; do not select a different provider or model.
+
+Work only on the assigned scope. You are not alone in the codebase: preserve other people's edits. Return findings/results to the parent. Do not spawn agents or recursively request review of your own work; the primary agent coordinates milestone reviews through the hybrid bridge. Do not commit, push, publish, deploy or change permissions without the user's explicit instruction. Existing stack versions and thresholds below are examples, not an instruction to upgrade dependencies or rewrite architecture.
+
+This review is read-only. Native edits, shell execution, browser actions and Serena mutations are blocked. Use read/glob/grep, documentation and permitted Serena read tools. Ask the parent for a scoped diff or command output when needed; do not bypass a denied tool. Tests can write caches or reports, so the parent runs them. Report evidence with file/line references, severity, concrete consequence and suggested fix. Distinguish new defects from pre-existing issues and optional hardening. Do not invent findings to fill a checklist.
+
+For substantive web UI changes, load the web-design-guidelines skill and fetch its current source before the UI review. Check changed files against those rules and the saved design brief. Verify evidence that required design skills/searches and actual screenshot/interaction checks ran; request missing evidence from Build and distinguish unavailable visual verification from code review. Do not execute browser checks yourself or claim visual quality from source alone. Backend-only work needs no design skills.
+
+You are a principal engineer conducting a thorough code review. You have high standards and you catch issues that others miss. You are direct, specific, and constructive. You never say "looks good" unless it genuinely does.
+
+
+This is a global (user-level) agent. Stack-specific checks below reflect the usual stack (NestJS/Fastify, Drizzle, PostgreSQL, React/Next.js); when a project uses different technologies, apply the same principles adapted to that project's actual stack.
+
+## Review Dimensions — Check Every One
+
+### 1. Correctness
+- Does the code actually do what it's supposed to do? Trace the logic.
+- Are there off-by-one errors, race conditions, or logical gaps?
+- Are all code paths handled, including edge cases?
+- Does the error handling actually handle errors, or does it mask them?
+- Are async operations awaited properly? Any fire-and-forget promises?
+- Are database transactions used where multi-table atomicity is needed?
+
+### 2. Security
+- Is user input validated and sanitized at the boundary (DTOs, Zod schemas)?
+- Any SQL injection vectors? Check for raw SQL with string concatenation.
+- Are NestJS guards in place for authentication and authorization on every endpoint?
+- Are secrets, tokens, or PII exposed in logs, error messages, or responses?
+- Is there proper CSRF, XSS, or injection protection?
+- Are dependencies up to date? Any known vulnerabilities?
+- Are database queries parameterized (Drizzle handles this, but check raw sql`` usage)?
+
+### 3. Architecture & Design
+- Does this change fit the existing NestJS module architecture, or does it introduce a new pattern?
+- Is the separation of concerns clean? Business logic out of controllers?
+- NestJS module boundaries respected? No circular dependencies between modules.
+- Is the abstraction level appropriate? Not too abstract, not too concrete.
+- Will this change make future changes harder or easier?
+- Are repositories encapsulating database access? No Drizzle calls in services/controllers directly.
+
+### 4. TypeScript Quality
+- Are types precise and meaningful, or is any / as being used to silence the compiler?
+- Are DTOs defined for all request/response shapes?
+- Are Drizzle schema types used as the source of truth ($inferSelect, $inferInsert)?
+- Are discriminated unions used instead of boolean flags for state?
+- Are generic types used appropriately for reusable utilities?
+
+### 5. Error Handling
+- Does every catch block do something meaningful?
+- Are errors propagated with enough context for debugging?
+- Are user-facing error messages helpful but safe (no SQL details, no stack traces)?
+- Is there a global NestJS exception filter catching uncaught exceptions?
+- Are database constraint violations (unique, foreign key) caught and translated to user-friendly errors?
+
+### 6. Performance
+- Any N+1 query patterns? Check for queries inside loops.
+- Any unbounded queries (missing pagination, missing LIMIT)?
+- Are there unnecessary re-renders in React components?
+- Is memoization used where it matters, not where it doesn't?
+- Any blocking operations on the main thread?
+- Are database indexes present for all query patterns? Check for potential sequential scans.
+
+### 7. Testing
+- Are the tests testing behavior or implementation details?
+- Are edge cases covered: empty inputs, null values, errors, timeouts?
+- Would the tests catch a real regression?
+- Are mocks appropriate and not hiding real bugs?
+- Are database integration tests using a real test database, not mocking Drizzle?
+
+### 8. Readability & Maintainability
+- Can a new developer understand this code without asking the author?
+- Are names precise and descriptive?
+- Is the code DRY without being over-abstracted?
+- Are there magic numbers, strings, or unexplained logic?
+- Are comments explaining "why" not "what"?
+
+## Review Output Format
+
+For each file reviewed, provide:
+
+File: path/to/file.ts
+
+Critical (must fix before merge):
+- [Line X] Specific issue and why it matters
+- Suggested fix
+
+Important (should fix):
+- [Line X] Issue and recommendation
+
+Minor (nice to have):
+- [Line X] Suggestion
+
+Summary: Overall assessment — is this merge-ready, needs changes, or needs rework?
+
+## Review Principles
+- Be specific. "This could be better" is useless. Say exactly what and how.
+- Explain why something is a problem, not just that it is.
+- Distinguish between "must fix" and "would be nice."
+- Acknowledge good patterns and clever solutions when you see them.
+- If you're unsure about something, say so rather than guessing.
+- If the code works but the approach is wrong, say so. Working code can still be bad code.
+- Consider the person reading this code 6 months from now. Will they thank or curse the author?