@jterrats/open-orchestra 0.1.0

package/rules/agent-collaboration.mdc

@@ -0,0 +1,58 @@
+---
+description: Cross-agent collaboration, handoffs, and decision protocol — stack-agnostic
+alwaysApply: true
+---
+
+# Agent Collaboration
+
+Agents must collaborate through explicit artifacts and review checkpoints. Parallel work is allowed only when responsibilities, inputs, and outputs are clear.
+
+## Shared Context
+- Start with a shared task brief: goal, backlog item, constraints, assumptions, risks, and definition of done.
+- Confirm the GitHub issue exists and has been technically refined before starting each work block.
+- Keep a visible decision log for architecture choices, scope cuts, security exceptions, and release trade-offs.
+- Treat unresolved questions as blockers when they affect user value, data contracts, security, or deployment.
+
+## User Alignment Gate
+- Before implementation, discuss the proposed solution and architecture with the user.
+- Present the plan in concrete terms: scope, files or modules likely to change, domain/model changes, service/integration changes, controller/entry-point changes, data flow, risks, trade-offs, test strategy, and expected evidence.
+- Do not start coding when the architecture, acceptance criteria, or user-visible behavior is ambiguous.
+- If the task is a trivial mechanical edit, state that no architecture decision is involved and proceed with the smallest safe change.
+- If new information invalidates the agreed plan, pause and realign with the user before continuing.
+
+## Collaboration Flow
+- Product Owner and Analyst define acceptance criteria before Developer or QA treat the task as ready.
+- Architect and Security review designs before implementation when work touches boundaries, data, auth, infra, or external integrations.
+- UX/UI Designer reviews user-facing flows before implementation when the task changes screens, copy, navigation, onboarding, or accessibility.
+- SRE, DBA, Compliance/Privacy, and Release Manager review before release when reliability, database, regulatory, or rollout risk is material.
+- Developer starts implementation only after the user alignment gate and required role reviews are complete.
+- Developer shares implementation notes, unit test evidence, and changed behavior with QA, DevOps, and Security before final verification.
+- QA, DevOps, and Security report release blockers back to Product Owner for go/no-go decisions.
+- Developer work must pass through QA review before release approval.
+
+## Handoff Contract
+- Every handoff must include: current status, files or components touched, decisions made, risks, test evidence, and remaining work.
+- Do not hand off vague ownership such as "finish the backend". Name the exact module, behavior, or artifact.
+- If another agent's output is incomplete or contradictory, pause and reconcile before building on it.
+- Developer-to-QA handoff must include unit tests added or updated, exact test commands run, known gaps, and any recommended Playwright coverage.
+
+## Parallel Work Rules
+- Split work by stable boundaries: feature slice, module, test suite, infrastructure component, or documentation artifact.
+- Agents working in parallel must publish assumptions early and update them when code or requirements change.
+- Avoid duplicate edits to the same files. If overlap is unavoidable, assign one integration owner.
+
+## Review Protocol
+- Review from the role's responsibility, not personal preference.
+- Findings must include severity, affected artifact, expected behavior, actual risk, and a concrete recommendation.
+- Approval means the reviewer accepts the residual risk for their role.
+
+## Conflict Resolution
+- Product value conflicts are resolved by Product Owner with Product Manager input.
+- Technical direction conflicts are resolved by Architect with Developer and DevOps input.
+- Verification conflicts are resolved by QA using acceptance criteria and reproducible evidence.
+- Security conflicts are resolved by Security unless the Product Owner records explicit risk acceptance.
+- UX conflicts are resolved by UX/UI Designer with Product Owner input.
+- Reliability conflicts are resolved by SRE with DevOps and Architect input.
+- Data and database conflicts are resolved by Data Engineer or DBA according to ownership.
+- Release timing conflicts are resolved by Release Manager with Product Owner input.
+- Compliance and privacy conflicts are resolved by Compliance/Privacy unless formal risk acceptance is recorded.

package/rules/agent-roles.mdc

@@ -0,0 +1,105 @@
+---
+description: Role-based agent responsibilities for software delivery — stack-agnostic
+alwaysApply: true
+---
+
+# Agent Roles
+
+Use roles to force complete thinking, not to create silos. A single agent may cover multiple roles, but it must state which role is active when making a decision.
+
+## Role Selection
+- Start every non-trivial task by identifying the needed roles and the lead role.
+- Do not activate every role by default. Choose the smallest set that covers product intent, UX, technical design, implementation, verification, delivery, reliability, data, compliance, documentation, and risk.
+- If a role is skipped, state why the task does not need it.
+
+## Product Owner
+- Owns user value, acceptance criteria, scope boundaries, and release readiness.
+- Converts vague requests into concrete outcomes, non-goals, constraints, and acceptance tests.
+- Rejects implementation work when the problem statement, priority, or done criteria are unclear.
+
+## Product Manager
+- Owns product strategy, trade-offs, sequencing, and success metrics.
+- Connects work to business value, user segments, adoption risks, and roadmap fit.
+- Forces scope cuts when the requested solution is larger than the validated problem.
+
+## Analyst
+- Owns requirements discovery, domain modeling, process mapping, and edge cases.
+- Identifies actors, workflows, state transitions, data definitions, and reporting needs.
+- Documents assumptions and open questions before they become hidden implementation decisions.
+
+## Architect
+- Owns system boundaries, integration contracts, data flow, and long-term maintainability.
+- Chooses patterns that fit the existing codebase and records meaningful trade-offs.
+- Blocks designs that violate security, scalability, testability, or clean architecture constraints.
+- Discusses the proposed architecture with the user before implementation begins.
+
+## Developer
+- Owns implementation quality, local consistency, refactoring discipline, and maintainable code.
+- Keeps changes small, typed, tested, and aligned with existing patterns.
+- Does not start coding until acceptance criteria and technical boundaries are clear enough.
+- Confirms the agreed implementation approach before editing files, except for trivial mechanical changes.
+
+## QA
+- Owns verification strategy, test coverage, regression risk, and release confidence.
+- Defines happy paths, failure paths, boundary cases, and non-functional checks.
+- Challenges work that has implementation but no credible test plan.
+
+## DevOps
+- Owns deployment, CI/CD, observability, runtime configuration, rollback, and operational readiness.
+- Verifies environment segregation, infrastructure as code, migrations, secrets, and runbooks.
+- Blocks releases that cannot be deployed, monitored, rolled back, or supported.
+
+## Security
+- Owns threat modeling, abuse cases, data classification, identity, secrets, and dependency risk.
+- Reviews authentication, authorization, input handling, logging, encryption, and third-party exposure.
+- Treats security findings as release blockers unless explicitly risk-accepted by the Product Owner.
+
+## UX/UI Designer
+- Owns user experience, interaction design, accessibility, responsive behavior, UI copy, and flow clarity.
+- Reviews user-facing work for mobile-first behavior, empty/loading/error/success states, tooltips, and usability.
+- Blocks user-facing releases that are confusing, inaccessible, or broken on target viewports.
+
+## SRE / Reliability Engineer
+- Owns SLOs, error budgets, incident response, capacity, resilience, and production reliability.
+- Reviews observability, alerts, dashboards, saturation, failover, degradation, and post-release monitoring.
+- Blocks releases that cannot be operated, monitored, scaled, or recovered within agreed RTO/RPO.
+
+## Data Engineer / Data Analyst
+- Owns data pipelines, analytics models, reporting definitions, data quality, lineage, and metric correctness.
+- Verifies dashboards, business metrics, ETL/ELT jobs, aggregation logic, and data freshness.
+- Blocks decisions based on ambiguous, unvalidated, or inconsistent data definitions.
+
+## DBA / Database Engineer
+- Owns database performance, indexes, locking, migrations, replication, backups, partitioning, and restore safety.
+- Reviews schema changes, query plans, backfills, constraints, transaction scope, and production data risk.
+- Blocks migrations that are unsafe, irreversible without plan, unbounded, or likely to cause downtime.
+
+## Tech Lead / Engineering Manager
+- Owns technical coordination, sequencing, ownership boundaries, integration planning, and delivery coherence.
+- Splits work across agents or teams, assigns integration ownership, and manages technical debt trade-offs.
+- Ensures the final solution is cohesive across product, architecture, implementation, QA, DevOps, and security.
+
+## Release Manager
+- Owns release coordination, go/no-go checklist, release window, communication, rollout, and rollback readiness.
+- Verifies versioning, changelog, migrations, feature flags, deployment order, and post-release monitoring.
+- Blocks releases without clear owner, rollback path, evidence, or stakeholder communication.
+
+## Support / Customer Success
+- Owns customer impact, support readiness, FAQs, known issues, user communication, and feedback loops.
+- Reviews user-facing changes for diagnosability, help text, recovery paths, and support escalation needs.
+- Feeds production incidents, tickets, and user pain back into Product Owner and QA workflows.
+
+## Compliance / Privacy
+- Owns regulatory requirements, privacy obligations, retention, consent, auditability, and data processing risk.
+- Reviews PII, restricted data, data residency, retention policies, access logs, consent, and third-party processors.
+- Blocks releases that violate compliance obligations unless explicit executive-level risk acceptance is recorded.
+
+## Content / Technical Writer
+- Owns user docs, technical docs, runbooks, release notes, changelogs, API examples, and help content.
+- Ensures documentation is accurate, actionable, current, and aligned with shipped behavior.
+- Blocks delivery when required docs or operational runbooks are missing for impacted users or operators.
+
+## Game Designer
+- Owns game mechanics, progression, difficulty, economy, onboarding, feedback loops, and player engagement.
+- Reviews game UX for controls, tutorials, HUD clarity, reward loops, failure recovery, and accessibility options.
+- Blocks game changes that break core loops, progression balance, or player comprehension.

package/rules/ai-assisted-development.mdc

@@ -0,0 +1,31 @@
+---
+description: Safe and verifiable AI-assisted software development practices
+alwaysApply: true
+---
+
+# AI-Assisted Development
+
+AI-generated work must meet the same engineering bar as human-written work. Speed does not replace verification.
+
+## Grounding
+- Inspect the existing codebase before proposing or editing code.
+- Do not invent APIs, files, dependencies, commands, environment variables, or product requirements.
+- When uncertain, state the assumption, verify locally, or ask the user before implementation.
+- Prefer existing project patterns over generic generated patterns.
+
+## Implementation
+- Keep AI-generated changes scoped to the agreed plan.
+- Do not rewrite unrelated code, rename public APIs, or reformat broad areas without explicit need.
+- Add tests and evidence for AI-generated behavior like any other change.
+- Generated code must be understandable, maintainable, typed, and aligned with security rules.
+
+## Review
+- Treat AI output as untrusted until reviewed.
+- Check generated code for hallucinated imports, broken edge cases, security regressions, and excessive abstraction.
+- Do not accept generated explanations as proof. Use tests, builds, type checks, docs, or runtime evidence.
+- Record prompts, assumptions, or model-specific behavior when they materially affect product behavior or repeatability.
+
+## User Alignment
+- Discuss the approach with the user before non-trivial AI-assisted implementation.
+- Explain trade-offs clearly and identify risks introduced by generated code.
+- If generated code reveals a better or riskier path than agreed, pause and realign before continuing.

package/rules/api-design.mdc

@@ -0,0 +1,31 @@
+---
+description: API contract, versioning, idempotency, and compatibility standards
+alwaysApply: true
+---
+
+# API Design
+
+APIs are product contracts. Design them for clarity, compatibility, safety, and operability before implementation.
+
+## Contracts
+- Define request, response, error shape, authentication, authorization, pagination, filtering, sorting, and rate limits before coding.
+- Use stable field names and explicit types. Avoid ambiguous blobs such as `metadata` unless the schema is documented.
+- Use consistent naming, casing, date formats, IDs, and enum values across endpoints.
+- Public API changes require examples for success, validation failure, authorization failure, and unexpected failure.
+
+## Compatibility
+- Prefer backward-compatible changes: add optional fields before removing or renaming anything.
+- Version breaking changes intentionally and document migration steps.
+- Do not leak internal models directly as API responses.
+- Keep error codes stable even when error messages improve.
+
+## Safety
+- Use idempotency keys for retryable create, payment, provisioning, email, or side-effecting operations.
+- Validate input at the boundary and return user-safe errors.
+- Enforce authorization per resource, not just per endpoint.
+- Apply rate limits and abuse protection for public or high-cost endpoints.
+
+## Testing
+- Add contract tests for request/response shape and error cases.
+- Add backward-compatibility tests when changing existing APIs.
+- Include tests for pagination, filtering, authorization, and idempotency when applicable.

package/rules/architecture-decisions.mdc

@@ -0,0 +1,27 @@
+---
+description: Lightweight architecture decision records and design documentation
+alwaysApply: true
+---
+
+# Architecture Decisions
+
+Important architecture choices must be recorded briefly. The goal is traceability, not bureaucracy.
+
+## When to Record an ADR
+- Record an ADR when changing system boundaries, data ownership, integration contracts, authentication, authorization, infrastructure, deployment, or storage patterns.
+- Record an ADR when choosing a new framework, library, cloud service, messaging pattern, database, or testing strategy.
+- Record an ADR when a decision has meaningful trade-offs, migration cost, security impact, or rollback complexity.
+
+## ADR Format
+- Title: short decision name.
+- Status: proposed, accepted, superseded, or rejected.
+- Context: problem, constraints, and forces.
+- Decision: chosen approach.
+- Consequences: benefits, costs, risks, and follow-up work.
+- Alternatives considered: at least one reasonable option and why it was not chosen.
+
+## Decision Hygiene
+- Keep ADRs concise and link them from PRs when relevant.
+- Supersede old ADRs instead of rewriting history.
+- If a decision is reversed, record why new information changed the outcome.
+- Architecture decisions must align with security, testing, observability, and delivery quality gates.

package/rules/code-review-engineering.mdc

@@ -0,0 +1,34 @@
+---
+description: Engineering code review standards, checklists, and approval expectations
+alwaysApply: true
+---
+
+# Code Review Engineering
+
+Code review protects behavior, users, operations, and maintainability. Review risk before style.
+
+## Review Order
+- Review behavior, data safety, security, reliability, and user impact before naming or formatting.
+- Check whether the change matches the agreed solution, acceptance criteria, and Definition of Done.
+- Verify tests cover meaningful behavior, failure paths, and regression risk.
+- Confirm evidence: commands run, screenshots, logs, traces, benchmarks, or QA results when relevant.
+
+## Required Checks
+- API changes: contract, compatibility, auth, validation, rate limits, and error shape.
+- Data changes: migrations, indexes, constraints, backfills, rollback, and sensitive data handling.
+- UI changes: responsive layout, accessibility, copy, states, and screenshots.
+- Async changes: idempotency, retries, timeout, DLQ, and observability.
+- Infra changes: plan output, least privilege, cost, scalability, rollback, and drift risk.
+- Static analysis: pre-commit hook, lint, typecheck, secret scan, dependency scan, and SAST status.
+
+## Review Findings
+- Findings must include severity, file or artifact, risk, expected behavior, and concrete recommendation.
+- Do not approve unresolved blockers, failing CI, missing tests, or undocumented risk acceptance.
+- Nitpicks must not block unless they hide real maintainability, readability, or consistency risk.
+- If the change is too large to review reliably, request split PRs or staged rollout.
+
+## Self-Review
+- Authors must review their own diff before requesting review.
+- Remove debug code, dead code, unrelated formatting, and accidental files.
+- Summarize architectural decisions, trade-offs, test evidence, and known gaps in the PR.
+- Confirm static analysis and required hooks passed before requesting review.

package/rules/concurrency-async.mdc

@@ -0,0 +1,32 @@
+---
+description: Concurrency, async jobs, retries, idempotency, and distributed workflow rules
+alwaysApply: true
+---
+
+# Concurrency & Async
+
+Concurrent and asynchronous work must be idempotent, observable, and safe under retries, partial failure, and duplicate delivery.
+
+## Concurrency Control
+- Identify shared mutable state before implementation.
+- Use transactions, optimistic concurrency, locks, leases, or compare-and-swap when multiple writers can collide.
+- Avoid relying on timing, sleep, or process-local memory for correctness.
+- Document ordering assumptions and what happens when events arrive late, duplicated, or out of order.
+
+## Async Jobs
+- Jobs must have owner, trigger, payload schema, retry policy, timeout, dead-letter handling, and observability.
+- Payloads should carry stable IDs, not large snapshots, unless snapshots are required for correctness.
+- Long-running jobs must report progress and support safe resume or retry.
+- Background work must not hide user-visible failures without surfacing status or recovery.
+
+## Retries
+- Retried operations must be idempotent or protected with idempotency keys.
+- Use bounded retries with exponential backoff and jitter.
+- Do not retry validation errors, authorization errors, or deterministic business rule failures.
+- Record retry exhaustion as an operational signal.
+
+## Distributed Workflows
+- Prefer explicit state machines for multi-step workflows.
+- Define compensation or forward-fix behavior for partial failure.
+- Use durable queues or workflow engines for critical multi-step processes instead of in-memory orchestration.
+- Emit events or audit entries for important state transitions.

package/rules/configuration-management.mdc

@@ -0,0 +1,31 @@
+---
+description: Runtime configuration, feature flags, environment variables, and typed config rules
+alwaysApply: true
+---
+
+# Configuration Management
+
+Configuration changes product behavior. Treat config as code, validate it, and make ownership explicit.
+
+## Config Design
+- Separate build-time config from runtime config.
+- Validate required configuration at startup with typed schemas and clear failure messages.
+- Use safe defaults only when they are genuinely safe for every environment.
+- Do not scatter raw environment variable reads across the codebase. Centralize config loading.
+
+## Feature Flags
+- Every feature flag needs owner, purpose, default, rollout plan, cleanup plan, and expiration condition.
+- Flags must fail safe when config is unavailable.
+- Avoid long-lived flags that create permanent parallel behavior.
+- Test both enabled and disabled paths for risky flags.
+
+## Environment Management
+- Keep dev, staging, and production configuration isolated.
+- Do not use production secrets, endpoints, or customer data in local or test environments.
+- Document required environment variables, allowed values, and examples.
+- Configuration changes that affect deployment need release notes and rollback steps.
+
+## Secrets
+- Secrets are not configuration files. Use approved secret managers and runtime injection.
+- Never log secret values, tokens, connection strings, or signed URLs.
+- Rotate secrets when access scope, ownership, or exposure risk changes.

package/rules/data-modeling-domain.mdc

@@ -0,0 +1,31 @@
+---
+description: Data modeling, domain boundaries, invariants, and migration discipline
+alwaysApply: true
+---
+
+# Data Modeling & Domain
+
+Data models encode business rules. Treat schema, state, and naming decisions as long-lived product contracts.
+
+## Domain Modeling
+- Use domain language in types, tables, events, and functions. Avoid generic names such as `data`, `item`, `payload`, or `status` without context.
+- Document core invariants: what must always be true, who can change it, and what events change it.
+- Model state transitions explicitly. Avoid free-form status values without an allowed transition map.
+- Use value objects or narrow types for money, dates, IDs, units, quantities, and other rule-heavy values.
+
+## Ownership
+- Assign a clear owner for each data model or bounded context.
+- Do not let unrelated modules write directly to another context's data without an explicit service, event, or contract.
+- Keep derived data traceable to its source of truth.
+
+## Schema Design
+- Design indexes from real query patterns and cardinality, not guesses.
+- Use constraints for invariants the database can enforce.
+- Avoid nullable fields unless the meaning of null is explicit.
+- Classify sensitive fields at design time and apply encryption, tokenization, retention, and audit rules when needed.
+
+## Migrations
+- Migrations must be backward-compatible when possible and safe for rolling deploys.
+- Separate expand, backfill, switch, and contract phases for risky schema changes.
+- Backfills must be resumable, observable, and rate-limited when touching production-scale data.
+- Add rollback or forward-fix instructions for every non-trivial migration.

package/rules/delivery-quality-gates.mdc

@@ -0,0 +1,40 @@
+---
+description: Required delivery flow from development through QA automation and evidence
+alwaysApply: true
+---
+
+# Delivery Quality Gates
+
+Development work is not complete when code compiles. Every implementation must move through developer verification, QA review, automation planning, and evidence capture.
+
+## Developer Gate
+- Developer delivers code with unit tests for new or changed business logic.
+- Unit tests must cover success paths, failure paths, and relevant boundary cases.
+- Developer must run the focused unit test suite and report the exact command and result.
+- If unit tests are not feasible, Developer must document the technical reason and propose the smallest testable refactor.
+- Developer must address API, data, frontend, performance, concurrency, config, and AI-assisted development rules when the change touches those areas.
+
+## QA Gate
+- QA receives the Developer handoff before release approval.
+- QA must produce a test plan covering acceptance criteria, regression areas, edge cases, data setup, and environment assumptions.
+- QA must execute or explicitly defer each test case with a reason.
+- QA findings must include severity, reproduction steps, expected result, actual result, and evidence.
+
+## Automation Gate
+- QA and Developer must identify which manual checks should become automated tests.
+- Prefer Playwright for browser-based E2E, smoke, and regression flows.
+- Use Page Object pattern for Playwright suites. Selectors belong in page objects or stable test helpers, not scattered through test bodies.
+- Automated tests must be deterministic and avoid real network, clock, or randomness unless controlled by fixtures, mocks, or seeded data.
+
+## Evidence Gate
+- Every completed delivery must include test evidence: commands run, pass/fail result, logs or screenshots when relevant, and unresolved risks.
+- Playwright evidence should include trace, screenshot, or video for failed E2E cases when the framework supports it.
+- User-facing delivery should include screenshots or recordings for key responsive breakpoints when practical.
+- Manual QA evidence should include tested build/version, environment, browser/device when relevant, and timestamp.
+- Release approval requires visible evidence from Developer and QA, not just a verbal status.
+
+## Release Decision
+- Product Owner gives go/no-go using QA results, automation status, unresolved defects, and risk acceptance.
+- Security, DevOps, or QA blockers cannot be bypassed without explicit Product Owner risk acceptance.
+- A delivery with deferred tests must include the follow-up backlog item and owner before release.
+- Release approval must satisfy Definition of Done, release readiness, rollback, and documentation requirements when applicable.

package/rules/dependency-management.mdc

@@ -0,0 +1,31 @@
+---
+description: Dependency updates, lockfiles, supply chain review, and vulnerability handling
+alwaysApply: true
+---
+
+# Dependency Management
+
+Dependencies are part of the product attack surface and runtime behavior. Treat them as code.
+
+## Adding Dependencies
+- Prefer the standard library or existing project dependencies before adding a new package.
+- Justify every new runtime dependency with purpose, maintenance status, license, security posture, and alternatives considered.
+- Do not add dependencies for trivial utilities that can be implemented safely in a few lines.
+- Avoid packages with low maintenance, unclear ownership, known malware history, or broad install scripts.
+
+## Versioning
+- Pin dependency versions through lockfiles and commit lockfile updates with the package manifest.
+- Do not manually edit lockfiles unless the package manager requires it and the change is reviewed.
+- Major upgrades require changelog review, migration notes, test evidence, and rollback considerations.
+- Keep dependency updates atomic unless a coordinated upgrade is required.
+
+## Supply Chain Security
+- Run dependency scanning in CI and block critical or high vulnerabilities unless risk-accepted.
+- Never run unvetted package execution commands in CI.
+- Review transitive dependency risk when adding security-sensitive, build, auth, crypto, or deployment tooling.
+- Remove unused dependencies promptly.
+
+## Automation
+- Use Dependabot, Renovate, or equivalent for routine updates where possible.
+- Group low-risk patch updates, but keep major and security updates separate.
+- Security updates must include the vulnerability identifier, affected package, fixed version, test evidence, and any compensating controls.

package/rules/devops-tooling.mdc

@@ -0,0 +1,55 @@
+---
+description: DevOps tool categories, operational design, scalability, observability, and reporting
+alwaysApply: true
+---
+
+# DevOps Tooling & Operations
+
+DevOps decisions must cover deployability, scalability, downtime strategy, observability, reporting, security, and recovery. Tools are selected by capability, not trend.
+
+## Stack by Category
+- **IaC**: Terraform, OpenTofu, Pulumi, CloudFormation, Bicep.
+- **CI/CD**: GitHub Actions, GitLab CI, CircleCI, Buildkite.
+- **GitOps / Deploy**: Argo CD, Flux, Helm, Kustomize.
+- **Containers / Orchestration**: Docker, Kubernetes, ECS/Fargate, Cloud Run.
+- **Scalability**: Kubernetes HPA/VPA, KEDA, autoscaling groups, managed load balancers, CDN.
+- **Downtime Strategy**: rolling deploys, blue-green, canary, dark launch, feature flags with LaunchDarkly, Unleash, or OpenFeature.
+- **Observability**: OpenTelemetry for instrumentation; Prometheus/Grafana for metrics; Loki, ELK, or OpenSearch for logs; Tempo or Jaeger for traces; Datadog, New Relic, or Dynatrace when SaaS is preferred.
+- **Alerting / On-Call**: Alertmanager, PagerDuty, Opsgenie, Grafana OnCall.
+- **SLO / Error Budgets**: Nobl9, Sloth, Pyrra, Grafana SLO, Datadog SLO.
+- **Infra Reporting / FinOps**: Kubecost, OpenCost, Infracost, cloud cost explorers, Grafana dashboards.
+- **Security DevOps**: Trivy, Grype, Snyk, Dependabot, Renovate, Checkov, tfsec, Semgrep, CodeQL.
+- **Secrets**: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, SOPS with age.
+- **Backups / DR**: Velero, cloud-native backups, database PITR, restore drills.
+- **Performance / Load Testing**: k6, Artillery, Locust, JMeter.
+- **Synthetic Monitoring**: Checkly, Grafana Cloud Synthetic Monitoring, Datadog Synthetics, Playwright scheduled checks.
+
+## Operational Design Gates
+- Every non-trivial system design must include scalability, downtime, observability, security, cost, and recovery considerations.
+- Do not approve infrastructure or release changes without deployment, rollback, monitoring, and ownership details.
+- Prefer managed services when they reduce operational risk without creating unacceptable lock-in or cost exposure.
+- Record tool choices and major operational trade-offs in an ADR when they affect long-term operations.
+
+## Scalability
+- Define expected traffic, data volume, concurrency, growth assumptions, and bottlenecks.
+- Prefer stateless compute, horizontal scaling, queue-based smoothing, caching, rate limits, and backpressure.
+- Autoscaling rules must name metrics, thresholds, min/max capacity, cooldown behavior, and failure modes.
+- High-traffic changes need load testing or a documented reason why it is not required.
+
+## Downtime & Availability
+- Choose a rollout strategy before release: rolling, canary, blue-green, dark launch, or feature-flagged rollout.
+- Database and API changes must be backward-compatible where possible.
+- Define RTO, RPO, degraded-mode behavior, and customer impact for critical services.
+- Runbooks must explain rollback and forward-fix paths.
+
+## Observability
+- Instrument services with logs, metrics, and traces using OpenTelemetry where practical.
+- Every production service needs dashboards for availability, latency, errors, saturation, and business-critical signals.
+- Alerts must be actionable, owned, and tied to user impact or clear operational risk.
+- Use correlation IDs or trace IDs to connect logs, traces, metrics, and user-reported issues.
+
+## Reporting
+- Infrastructure reporting must include cost, capacity, availability, error rate, latency, saturation, and deployment frequency where practical.
+- Dashboards should separate executive/product health, engineering debugging, and on-call response views.
+- Cost reporting must be tag-based and aligned to project, environment, owner, and major feature or service.
+- Reliability reporting should include SLOs, error budget burn, incidents, MTTR, and recurring failure themes.

package/rules/documentation-standards.mdc

@@ -0,0 +1,26 @@
+---
+description: Minimum documentation updates required for code, product, and operations changes
+alwaysApply: true
+---
+
+# Documentation Standards
+
+Documentation is part of delivery when behavior, operation, or integration changes. Keep it close to the thing it explains.
+
+## Update Documentation When
+- User-facing behavior, setup, configuration, API contracts, permissions, deployment, or operations change.
+- A new workflow, feature flag, environment variable, dependency, migration, or integration is introduced.
+- A bug fix changes expected behavior or removes a known limitation.
+
+## Minimum Artifacts
+- README or getting-started docs for setup, local development, and common commands.
+- API docs or contract examples for request, response, error, and auth changes.
+- Runbooks for operational tasks, incidents, migrations, rollback, and manual support procedures.
+- ADRs for important architecture choices.
+- Release notes for user-visible changes, breaking changes, migrations, and known risks.
+
+## Quality Bar
+- Documentation must be accurate, concise, and executable by someone who did not write the change.
+- Include commands, environment variables, expected outputs, and troubleshooting notes when relevant.
+- Do not duplicate source-of-truth configuration or type definitions in prose unless there is a sync check.
+- Remove obsolete docs in the same change that makes them obsolete.

package/rules/dry-clean-code.mdc

@@ -0,0 +1,30 @@
+---
+description: DRY, naming, and clean code standards — stack-agnostic
+alwaysApply: true
+---
+
+# DRY & Clean Code
+
+## Don't Repeat Yourself
+- **Single Source of Truth for data.** If a constant, type, or config exists in one place, every consumer must import or derive from it — never copy-paste.
+- When two blocks share >5 lines of identical structure, extract a reusable function.
+- Cross-package type sharing: define once, import at build time, or add a sync test. Never maintain parallel copies.
+
+## Naming
+- Names must reveal intent. `processData()` is vague — `validateOrderItems()` is clear.
+- Booleans: prefix with `is`, `has`, `can`, `should` (e.g., `isValid`, `hasPermission`).
+- Functions that return a value: name by what they return. Functions that perform actions: name by the action.
+- No abbreviations except universally known ones (`id`, `url`, `db`, `config`).
+
+## Magic Values
+- No hardcoded timeouts, CLI commands, path segments, or error messages scattered in code. Define named constants at module scope or in a shared constants file.
+- Repeated inline styles or CSS values must be extracted to variables or design tokens.
+
+## Dead Code
+- Never commit commented-out code, `console.log` debris, or unused imports. Delete them — git preserves history.
+- Never commit `eslint-disable`, `@SuppressWarnings`, or `// @ts-ignore` without a linked issue explaining why.
+
+## Comments
+- Code should be self-documenting. Comments explain **why**, not **what**.
+- Delete obvious comments: `// increment counter`, `// return result`, `// handle error`.
+- Acceptable: non-obvious business rules, performance trade-offs, workarounds with linked tickets.

package/rules/error-handling.mdc

@@ -0,0 +1,28 @@
+---
+description: Error handling and observability standards — stack-agnostic
+alwaysApply: true
+---
+
+# Error Handling & Observability
+
+## Never Swallow Errors
+- Empty `catch {}` blocks are forbidden. At minimum: log the error, propagate it, or convert it to a user-friendly message.
+- If an error is intentionally ignored, add a comment explaining why (e.g., `// best-effort: alias set failure doesn't block auth`).
+
+## Error Types
+- Distinguish **operational errors** (expected: bad input, network timeout, auth failure) from **programmer errors** (bugs: null reference, type mismatch).
+- Operational errors: handle gracefully, inform the user, retry if appropriate.
+- Programmer errors: crash fast, log with full context, fix the code.
+
+## User-Facing Errors
+- Never show stack traces, internal paths, or raw exception messages to users.
+- Use localized strings (Custom Labels, i18n keys, constants) for all user-visible error messages. Never hardcode error text in the UI.
+
+## Logging
+- Before writing `try-catch`, scan for an existing logging framework in the project. Use it.
+- Log at the right level: `error` for unexpected failures, `warn` for degraded behavior, `info` for significant events, `debug` for diagnostic detail.
+- Include context in log entries: operation name, relevant IDs, duration. A log line like `"Error occurred"` is useless.
+
+## Fail Fast
+- Validate inputs at function entry (guard clauses), not deep in the call stack.
+- Prefer early `return` or `throw` over deeply nested `if/else` chains.

package/rules/frontend-engineering.mdc

@@ -0,0 +1,32 @@
+---
+description: Frontend architecture, state management, accessibility, and UI implementation standards
+alwaysApply: true
+---
+
+# Frontend Engineering
+
+Frontend code must keep user experience, state, accessibility, and maintainability aligned.
+
+## Architecture
+- Separate presentation, state orchestration, data access, and domain logic.
+- Keep components small and purpose-specific. Extract hooks, services, or view models when logic grows.
+- Prefer existing design system components, tokens, and layout primitives over custom styling.
+- Do not duplicate API types, validation schemas, or constants when they can be imported or generated.
+
+## State
+- Separate local UI state from server/cache state.
+- Keep state ownership close to the component or workflow that owns it.
+- Avoid global state for data that is route-local, form-local, or derivable.
+- Model loading, empty, error, success, stale, and optimistic states explicitly.
+
+## Forms
+- Forms need labels, validation, helper text, disabled states, submission states, and recovery paths.
+- Validate on the client for feedback and on the server for authority.
+- Preserve user input when validation fails.
+- Avoid destructive default actions and require confirmation for irreversible operations.
+
+## Accessibility & Responsive
+- Preserve semantic HTML, keyboard navigation, focus states, readable contrast, and screen reader labels.
+- Test common mobile, tablet, and desktop widths for user-facing flows.
+- Do not hide required information behind hover-only interactions.
+- Use tooltips for clarification, not as the only way to complete a task.