@jterrats/open-orchestra 0.1.0

package/rules/git-discipline.mdc

@@ -0,0 +1,39 @@
+---
+description: Git workflow and commit hygiene — stack-agnostic
+alwaysApply: true
+---
+
+# Git Discipline
+
+## Commits
+- Each commit must compile and pass tests. Never commit broken code.
+- Ask for a **Backlog Item ID** before suggesting a commit message.
+- Use Conventional Commits with the backlog item as scope: `type(ID): short description` (e.g., `feat(SA-42): add profile auto-detection`).
+- Use imperative, lowercase summaries under 72 characters when practical.
+- Body: numbered list of changes + a paragraph explaining the value proposition.
+- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`, `style`, `revert`.
+- Mark breaking changes with `!` after the type or scope and include a `BREAKING CHANGE:` footer.
+- Do not mix unrelated semantic types in one commit. Split mixed work into separate commits.
+
+## Git Hooks
+- A version-controlled pre-commit hook must run static analysis before every commit.
+- Never bypass hooks with `--no-verify` unless the user explicitly approves and a follow-up item records the reason.
+- For hook tooling and required checks, see **static-analysis-githooks.mdc**.
+
+## Atomic Changes
+- One logical change per commit. Don't mix a bug fix with a refactor with a new feature.
+- If a refactor is needed before a feature, commit the refactor first, then the feature.
+
+## Branches
+- Branch from the latest main/develop. Rebase before opening a PR if your branch is stale.
+- Branch names: `type/ID-short-description` (e.g., `feat/SA-42-profile-detection`).
+
+## Pull Requests
+- PR title follows the same `type(ID): description` format as commits.
+- PR body must include: summary (1-3 bullets), test plan, and any manual verification steps.
+- Keep PRs small (<400 lines changed). If larger, split into stacked PRs or feature flags.
+- PRs must link the backlog item and list any breaking changes, migrations, feature flags, or risk acceptances.
+
+## Code Review
+- Review your own diff before requesting review. Catch the obvious issues yourself.
+- Never approve a PR with unresolved conversations, failing CI, or missing tests.

package/rules/infra-data-encryption.mdc

@@ -0,0 +1,81 @@
+---
+description: Infrastructure, data handling, encryption, and environment rules — stack-agnostic
+alwaysApply: true
+---
+
+# Infrastructure, Data & Encryption
+
+When a project involves databases, cloud infrastructure, sensitive data, or multi-environment deployments, these rules apply without exception.
+
+For DevOps tool categories, observability, SLOs, downtime strategy, scalability gates, and infrastructure reporting, see **devops-tooling.mdc**.
+
+## Environment Segregation
+
+- **Isolated environments**: dev, staging, and production must be fully isolated — separate accounts/subscriptions, separate credentials, separate network boundaries.
+- **No credential sharing**: each environment has its own secrets, service accounts, and IAM roles. Never reuse production credentials in dev/staging.
+- **Promotion flow**: code moves through environments via CI/CD pipelines only. No manual deploys to staging or production.
+- **Feature flags over environment branches**: prefer runtime feature flags to long-lived environment branches.
+
+## Infrastructure as Code (IaC)
+
+- **All infrastructure must be reproducible**: use Terraform, Pulumi, CloudFormation, Bicep, or equivalent. No manual console/portal changes in staging or production.
+- **State management**: IaC state files must be stored remotely (S3 + DynamoDB, Azure Blob, GCS) with locking. Never commit `.tfstate` to git.
+- **Modular composition**: extract reusable modules for networking, compute, storage. Follow the same SRP principle as application code.
+- **Drift detection**: run plan/preview in CI on every PR that touches infra. Alert on drift between declared and actual state.
+- **Tagging & cost visibility**: every resource must be tagged with `project`, `environment`, and `owner`. Enable cost alerts per tag.
+
+## Database
+
+- **Migrations are version-controlled**: use a migration framework (Flyway, Liquibase, Alembic, Prisma Migrate, knex). Never run DDL manually in production.
+- **Migrations must be idempotent and reversible**: every `up` must have a corresponding `down`. Test rollbacks in staging.
+- **Schema reviews**: DDL changes require the same review rigor as application code. Assess impact on indexes, constraints, and existing data.
+- **Connection pooling**: always use connection pools (PgBouncer, HikariCP, etc.). Never open unbounded connections from application code.
+- **Read replicas & caching**: for read-heavy workloads, use replicas. Cache hot data (Redis, Memcached) with explicit TTLs and invalidation strategies.
+
+## Encryption
+
+### At Rest
+- **Default-on**: all databases, object storage (S3, Blob, GCS), and backups must have encryption at rest enabled. Use AES-256 or equivalent.
+- **Key management**: use cloud KMS (AWS KMS, Azure Key Vault, GCP Cloud KMS). Application-managed keys only when KMS is not available.
+- **Key rotation**: automate key rotation (annually minimum). Document the rotation procedure.
+
+### In Transit
+- **TLS 1.2+ everywhere**: no plain HTTP, no self-signed certificates in staging or production. Enforce HSTS where applicable.
+- **mTLS for service-to-service**: when services communicate over a network, prefer mutual TLS or service mesh (Istio, Linkerd).
+- **Certificate management**: automate certificate provisioning (Let's Encrypt, ACM, cert-manager). Never commit private keys to repositories.
+
+### Sensitive Fields
+- **Passwords**: never store plaintext. Use bcrypt, scrypt, or argon2 with per-user salt. Never MD5 or SHA-family for password hashing.
+- **PII classification**: classify data fields at design time (public, internal, confidential, restricted). Document the classification in the data model.
+- **Column-level encryption / tokenization**: for SSN, credit card numbers, health data — apply field-level encryption or tokenize before storage.
+- **Audit trail**: log access to sensitive data (who, when, what). Use database audit logging or application-level audit events.
+
+## Secrets Management
+
+- **Use a vault**: AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or GCP Secret Manager. Never `.env` files baked into container images.
+- **Inject at runtime**: secrets are injected as environment variables at deployment time, never embedded in source code, config files, or CI logs.
+- **Rotate on schedule**: automated rotation for database passwords, API keys, and service account credentials. Define rotation cadence per sensitivity.
+- **Least privilege for secrets**: services access only the secrets they need. Use IAM policies / access policies to restrict scope.
+
+## Scalability
+
+- **Horizontal over vertical**: design stateless services that scale out. Externalize state to databases, caches, or queues.
+- **Rate limiting & throttling**: all public-facing APIs must implement rate limits. Internal services should have circuit breakers.
+- **Async where possible**: offload long-running work to queues (SQS, Service Bus, RabbitMQ, Pub/Sub). Keep HTTP request handlers fast.
+- **Observability**: metrics (latency, throughput, error rate), structured logs, and distributed tracing (OpenTelemetry) are mandatory for production services.
+- **Load testing**: run load tests in staging before major releases. Define SLOs (latency p95/p99, availability %) and alert when breached.
+
+## Vulnerability Management
+
+- **Dependency scanning**: run `npm audit`, `pip audit`, Snyk, or Dependabot on every PR. Block merge on critical/high CVEs.
+- **Container scanning**: scan images for OS and library vulnerabilities before pushing to registry.
+- **SAST/DAST**: integrate static analysis (CodeQL, SonarQube, Semgrep) and dynamic analysis in CI pipelines.
+- **Patch cadence**: critical CVEs patched within 48 hours. High within 1 week. Medium within 1 sprint.
+- **Incident response**: document the runbook for security incidents. Include contacts, escalation paths, and communication templates.
+
+## Backup & Disaster Recovery
+
+- **Automated backups**: daily minimum for databases. Retention per compliance requirements (minimum 30 days).
+- **Tested restores**: restore from backup at least quarterly. An untested backup is not a backup.
+- **RPO/RTO per environment**: define Recovery Point Objective and Recovery Time Objective. Production RPO < 1 hour is a common baseline.
+- **Multi-region for critical workloads**: if uptime SLA requires it, deploy active-passive or active-active across regions.

package/rules/performance-reliability.mdc

@@ -0,0 +1,32 @@
+---
+description: Performance budgets, reliability design, caching, and scalability safeguards
+alwaysApply: true
+---
+
+# Performance & Reliability
+
+Performance and reliability must be designed, measured, and protected. Do not optimize blindly or defer obvious scalability risks.
+
+## Budgets
+- Define expected latency, throughput, payload size, memory, storage, and concurrency for high-impact flows.
+- User-facing flows should consider p95 and p99 latency, not only averages.
+- Establish performance budgets for page weight, render time, API latency, and query count when applicable.
+- If no budget exists, propose one before making risky design choices.
+
+## Hot Paths
+- Avoid N+1 queries, unbounded loops with I/O, repeated serialization, and large synchronous work on request paths.
+- Paginate or stream large datasets. Do not load unbounded result sets into memory.
+- Keep expensive work outside user-facing request paths through queues, jobs, or precomputation.
+- Measure before and after performance changes and report the evidence.
+
+## Caching
+- Cache only with clear ownership, TTL, invalidation strategy, and stale-data behavior.
+- Do not cache sensitive data unless storage, access, and expiration controls are explicit.
+- Prefer simple, observable cache strategies before multi-layer cache complexity.
+- Document cache keys and invalidation triggers for shared caches.
+
+## Reliability
+- Design for graceful degradation when dependencies fail.
+- Add timeouts, retries, backoff, and circuit breakers for networked dependencies.
+- Use bulkheads or queues to protect critical paths from non-critical workload spikes.
+- Reliability-sensitive changes need load, stress, or synthetic tests when practical.

package/rules/readiness-done.mdc

@@ -0,0 +1,32 @@
+---
+description: Definition of Ready and Definition of Done for agent delivery
+alwaysApply: true
+---
+
+# Readiness & Done
+
+Work must not start or finish by intuition. Use explicit entry and exit criteria so agents, users, and reviewers share the same expectations.
+
+## Definition of Ready
+- Backlog item ID, user goal, acceptance criteria, non-goals, constraints, and priority are known.
+- Backlog item exists as a GitHub issue and is technically refined before implementation.
+- The proposed solution and architecture have been discussed with the user when the task is non-trivial.
+- Required roles are identified, including the lead role and any mandatory reviewers.
+- Data, API, UI, security, infrastructure, and migration impacts are either understood or explicitly marked as out of scope.
+- Test strategy, expected evidence, and QA handoff expectations are clear.
+- Implementation order is clear: models/domain first, service/integration second, controllers/entry points third.
+
+## Not Ready
+- Do not start implementation when acceptance criteria, target user behavior, data contracts, or security implications are ambiguous.
+- Do not start implementation from chat context alone when no refined GitHub issue exists.
+- Do not fill missing product decisions with hidden implementation assumptions.
+- If blocked, state the missing decision and propose the smallest useful next step.
+
+## Definition of Done
+- Acceptance criteria are met and any deviations are documented.
+- Code is implemented with focused unit tests for changed business logic.
+- QA has a test plan, execution result, evidence, and unresolved risk list.
+- User-facing work has responsive, accessibility, copy, and state checks when applicable.
+- Documentation, ADRs, migrations, release notes, or runbooks are updated when impacted.
+- Security, DevOps, and QA blockers are resolved or explicitly risk-accepted by the Product Owner.
+- Final handoff includes changed files or components, commands run, test results, evidence, known gaps, and follow-up backlog items.

package/rules/release-rollback.mdc

@@ -0,0 +1,32 @@
+---
+description: Release readiness, rollout, rollback, and post-release monitoring
+alwaysApply: true
+---
+
+# Release & Rollback
+
+Every release must be deployable, observable, and reversible. A feature is not ready if the team cannot monitor it or recover from it.
+
+For rollout tooling, synthetic monitoring, SLOs, on-call, and operational reporting categories, see **devops-tooling.mdc**.
+
+## Release Readiness
+- Confirm Definition of Done, QA evidence, security review, migration status, and unresolved risks before release.
+- Identify deployment target, release owner, release window, affected users, and communication needs.
+- List feature flags, configuration changes, migrations, background jobs, and third-party dependencies.
+- Verify observability exists for the changed behavior: logs, metrics, traces, dashboards, and alerts when applicable.
+
+## Rollout Strategy
+- Prefer small, reversible releases over large batches.
+- Use feature flags, canaries, phased rollout, or dark launch for risky user-facing or infrastructure changes.
+- Database changes must be backward compatible when possible and safe across rolling deploys.
+- Long-running migrations must have progress monitoring and an interruption plan.
+
+## Rollback Plan
+- Every release must state how to rollback code, configuration, feature flags, and migrations.
+- If rollback is not possible, document the forward-fix plan and get Product Owner risk acceptance before release.
+- Do not release when rollback depends on manual guesswork or undocumented production console changes.
+
+## Post-Release
+- Monitor agreed signals after release: errors, latency, saturation, conversion, usage, and user-facing failures.
+- Define who watches the release and for how long.
+- Capture incidents, regressions, and follow-up work as backlog items.

package/rules/rule-composition.mdc

@@ -0,0 +1,28 @@
+---
+description: Rule file composition and modular loading strategy for agent instructions
+alwaysApply: true
+---
+
+# Rule Composition
+
+Prefer small, focused rule files referenced from a concise root file. Large monolithic instruction files are harder to maintain, easier to contradict, and waste context on rules that may not apply to the current task.
+
+## Root Files
+- Root files such as `AGENTS.md` and `CLAUDE.md` must act as entry points, not full manuals.
+- Keep root files limited to universal rules, role summaries, and pointers to specialized rule files.
+- If a section grows beyond a short summary, extract it to `rules/*.mdc` and keep only the operating principle in the root file.
+
+## Specialized Rules
+- Use one rule file per responsibility area: architecture, API design, data modeling, frontend, performance, concurrency, testing, security, delivery, collaboration, infrastructure, DevOps tooling, or product.
+- Each rule file must have a clear `description` and a single reason to change.
+- Avoid duplicating detailed guidance across files. Put the source of truth in one rule and summarize it elsewhere.
+
+## Skill-Like Loading
+- Treat specialized rule files like skills: load the relevant rule only when the task needs that domain.
+- For broad delivery work, load roles, collaboration, readiness/done, API design, data modeling, frontend, performance, concurrency, testing, security, delivery quality gates, UX/UI, release/rollback, DevOps tooling, documentation, dependency, config, code review, and AI-assisted development rules together.
+- For narrow edits, load the smallest set of rules that can govern the change safely.
+
+## Maintenance
+- Prefer adding a new focused rule file over expanding an unrelated one.
+- Review root files periodically and remove details that have moved into specialized rules.
+- If two rules conflict, keep the stricter safety, security, or quality requirement and record the decision.

package/rules/security-guardrails.mdc

@@ -0,0 +1,37 @@
+---
+description: Security non-negotiables for all codebases — stack-agnostic
+alwaysApply: true
+---
+
+# Security Guardrails
+
+These are non-negotiable. Violations must be fixed before code review.
+
+## Input Handling
+- **No shell interpolation.** Use array-based APIs (`execFile`, `spawn` with args array) instead of `exec` with template literals. This prevents command injection.
+- **No raw innerHTML with dynamic data.** Escape all user-provided values or use `textContent` + `createElement`. This prevents XSS.
+- **Validate external input.** URLs must start with `https://` before `fetch()`. File paths must be within expected directories (no path traversal).
+- Security review is required for auth, authorization, identity, secrets, PII, payments, file paths, shell/process execution, network calls, dependency changes, encryption, TLS, cookies, sessions, CORS, webhooks, or infrastructure.
+
+## Secrets
+- **Never hardcode credentials, tokens, API keys, or connection strings.** Use environment variables, secret managers, or Named Credentials.
+- Files that may contain secrets (`.env`, `credentials.json`, `*.pem`, `*.key`) must be in `.gitignore`.
+- If a secret is accidentally committed, rotate it immediately — removing from git history is not enough.
+
+## Dependencies
+- Pin dependency versions in lockfiles. Review changelogs before major upgrades.
+- Never install packages from untrusted sources or run `npx` on unvetted packages in CI.
+- For full dependency policy, supply chain review, and update workflow, see **dependency-management.mdc**.
+
+## Static Analysis
+- Static analysis and secret scanning must run before commit and in CI.
+- For hook policy and tool categories, see **static-analysis-githooks.mdc**.
+
+## Error Exposure
+- Never return stack traces, internal paths, or database errors to end users. Log them server-side, show a generic message client-side.
+- Distinguish between expected errors (user input) and unexpected errors (bugs). Only unexpected errors should alert/log at error level.
+
+## Infrastructure & Data
+
+- For databases, encryption, IaC, environment segregation, secrets management, scalability, and vulnerability management, see **infra-data-encryption.mdc**.
+- Production networked services must consider TLS 1.2+, certificate management, HSTS where applicable, secure cookies, least privilege, and secret rotation.

package/rules/solid-architecture.mdc

@@ -0,0 +1,32 @@
+---
+description: SOLID principles and clean architecture guardrails — stack-agnostic
+alwaysApply: true
+---
+
+# SOLID & Clean Architecture
+
+## Single Responsibility (SRP)
+- One module = one reason to change. If a file mixes UI rendering with business logic, data access with orchestration, or config with behavior — split it.
+- Max **300 lines per file**. Max **30 lines per function**. Max **5 parameters** (use options object beyond that).
+- Template literals embedding >20 lines of CSS, JS, or HTML must be extracted to separate files.
+
+## Open/Closed (OCP)
+- Prefer data-driven designs over per-variant functions. Use config maps + one generic function instead of N nearly-identical functions.
+- Use handler/strategy maps (`Record<EventType, Handler>`) instead of `switch` statements with >5 cases.
+
+## Liskov Substitution (LSP)
+- Subclasses/implementations must honor the contract of their parent. Never override a method to throw "not supported" — redesign the hierarchy instead.
+
+## Interface Segregation (ISP)
+- No `Record<string, unknown>`, `any`, or `object` in public APIs. Define narrow, purpose-specific types.
+- Use TypeScript generics (`<T>`) instead of loose types + inline `as` casts.
+
+## Dependency Inversion (DIP)
+- Import from barrel exports (`index.ts`), not deep internal paths. Every public symbol must be re-exported from the package barrel.
+- Use static `import` statements. Never use `require()` in TypeScript unless technically justified and documented.
+- Depend on abstractions (interfaces/types), not concrete implementations, when crossing module boundaries.
+
+## Separation of Concerns
+- **View layer**: layout and event binding only. No business logic, no data fetching.
+- **Service layer**: orchestration, external calls, state mutations.
+- **Data layer**: queries, I/O, serialization. No UI references.

package/rules/static-analysis-githooks.mdc

@@ -0,0 +1,32 @@
+---
+description: Static analysis tooling and mandatory pre-commit hook policy
+alwaysApply: true
+---
+
+# Static Analysis & Git Hooks
+
+Every project must run fast static analysis before commit and deeper analysis in CI. Hooks are guardrails, not replacements for review or tests.
+
+## Required Tooling
+- TypeScript/JavaScript: TypeScript typecheck, ESLint, Prettier or project formatter, dependency audit, and secret scanning.
+- Web/UI: lint accessibility rules where available and keep Playwright smoke checks available for critical flows.
+- Python: Ruff, mypy or pyright, Bandit, dependency audit, and formatter when Python code exists.
+- Infrastructure: Checkov, tfsec, or equivalent IaC scanner when Terraform, OpenTofu, Bicep, CloudFormation, or Kubernetes manifests exist.
+- Security: Semgrep or CodeQL for SAST, plus Trivy or Grype for containers when images are built.
+
+## Pre-Commit Hook
+- A pre-commit hook is mandatory before any commit.
+- The hook must run only fast checks suitable for local feedback: formatting check, lint, typecheck for touched packages when practical, secret scan, and staged-file validation.
+- The hook must fail closed. If analysis fails, the commit must not proceed.
+- Do not bypass hooks with `--no-verify` unless the user explicitly approves and a follow-up item records the reason.
+- Hook configuration must be version-controlled and reproducible for every contributor.
+
+## Pre-Push / CI
+- Slower checks belong in pre-push or CI: full test suite, Playwright E2E, SAST, dependency scan, container scan, IaC scan, and build.
+- CI must run at least the same checks as local hooks, plus deeper project-wide checks.
+- PRs cannot be approved when static analysis, typecheck, security scan, or required hooks fail.
+
+## Evidence
+- Developer handoff must include exact static analysis commands run and results.
+- CI evidence must link failed checks to logs and responsible owners.
+- Any deferred static analysis finding needs severity, owner, rationale, and follow-up backlog item.

package/rules/testing-discipline.mdc

@@ -0,0 +1,42 @@
+---
+description: TDD, BDD, and testing best practices — stack-agnostic
+alwaysApply: true
+---
+
+# Testing Discipline
+
+## Test-Driven Development (TDD)
+- Write the test **before** or **alongside** the implementation. At minimum, tests must exist before the PR.
+- Red → Green → Refactor. Start with a failing test, make it pass with minimal code, then clean up.
+- Every development task must include unit tests for new or changed business logic before it is handed to QA.
+
+## Behavior-Driven Development (BDD)
+- Test **behavior**, not implementation. Test what the function does, not how it does it.
+- Name tests as specifications: `it('rejects orders with zero quantity')`, not `it('test1')`.
+- One assertion per test method. If you need multiple, it's multiple behaviors — split them.
+
+## Test Structure
+- **Arrange → Act → Assert.** Separate setup, execution, and verification with blank lines.
+- Use factory functions or builders for test data — never copy-paste fixtures across test files.
+- Tests must be deterministic. No reliance on system clock, network, or random values without seeding.
+
+## Sync Tests
+- If data is duplicated across packages (e.g., type definitions, config arrays), a test must assert both copies are identical.
+- Schema changes in a source of truth must break a test somewhere — if they don't, add one.
+
+## Coverage
+- Target **90%+ line coverage** for business logic. Infrastructure/glue code can be lower.
+- Coverage is a floor, not a goal. 100% coverage with bad assertions is worse than 80% with good ones.
+
+## E2E / Integration
+- Prefer Playwright for browser-based E2E, smoke, and regression automation.
+- Use the Page Object pattern for UI tests. Selectors live in page objects, not test bodies.
+- Tag tests by speed/scope (`@smoke`, `@regression`) so CI can run fast feedback loops.
+- Capture evidence for E2E failures with traces, screenshots, or videos when supported by the framework.
+
+## QA Handoff
+- Developer must provide QA with test commands run, pass/fail results, covered scenarios, and known gaps.
+- QA must produce a test plan before release approval.
+- QA and Developer must decide which manual checks should be automated, preferring Playwright for browser flows.
+- User-facing QA plans must include responsive, accessibility, copy, tooltip, loading, empty, error, success, and recovery-state checks.
+- API, data, async, performance, and config changes must include targeted regression checks for contract, migration, idempotency, latency, and environment behavior when applicable.

package/rules/ux-ui-product-experience.mdc

@@ -0,0 +1,51 @@
+---
+description: Mobile-first UX/UI, responsive design, user flows, and game guidance
+alwaysApply: true
+---
+
+# UX/UI Product Experience
+
+User-facing work must be designed around real user flows, not isolated screens. Every interface must be usable, responsive, accessible, and clear for the intended audience.
+
+## Mobile First
+- Design the smallest practical viewport first, then enhance for tablet and desktop.
+- Primary actions must remain reachable on mobile without awkward scrolling or hidden controls.
+- Text, buttons, forms, modals, menus, and navigation must not overflow or overlap at common mobile widths.
+- Touch targets must be large enough for fingers and spaced to avoid accidental taps.
+
+## Responsive Behavior
+- Define responsive layouts intentionally: stacking, wrapping, truncation, sticky areas, and overflow behavior must be planned.
+- Test key screens at mobile, tablet, and desktop breakpoints before considering UI work complete.
+- Avoid fixed-width layouts unless the format requires it. Use responsive constraints, flexible grids, and sensible max widths.
+- Dynamic content, translated text, loading states, empty states, and error states must fit without breaking the layout.
+
+## User Flows
+- Start UX work by identifying the end user, their goal, entry point, success path, failure path, and exit path.
+- Do not optimize a screen while ignoring the full workflow before and after it.
+- Every critical flow must include loading, empty, error, success, validation, and recovery states.
+- Navigation should make the user's current location, available actions, and next step obvious.
+
+## UI Copy
+- Use friendly, descriptive text that tells users what happened and what they can do next.
+- Buttons should describe the action, not the implementation detail.
+- Error messages must be specific, human-readable, and safe to show publicly.
+- Tooltips should clarify unfamiliar icons, disabled controls, abbreviations, and advanced options.
+
+## Accessibility
+- Preserve keyboard navigation, focus states, semantic structure, and readable contrast.
+- Forms need labels, validation messages, and clear relationships between fields and errors.
+- Do not rely on color alone to communicate status or severity.
+- Motion and animation must not block comprehension and should respect reduced-motion preferences when the platform supports it.
+
+## Game UX/UI
+- Games must teach controls, objectives, feedback loops, and failure recovery inside the experience.
+- Provide contextual guides, tutorials, onboarding hints, or progressive prompts when mechanics are introduced.
+- HUD elements must prioritize player state, goals, available actions, and urgent threats without covering gameplay.
+- Menus, pause screens, settings, inventory, upgrades, and dialogs must be navigable with the target input methods.
+- Feedback must be immediate and readable: input response, hit/miss, damage, rewards, progress, cooldowns, and blocked actions.
+- Difficulty, accessibility, and assistive options should be available when they meaningfully improve player inclusion.
+
+## Evidence
+- UI delivery must include screenshots or recordings for the primary responsive breakpoints when practical.
+- Game UI delivery must include evidence of onboarding, HUD readability, and input flow on the target device or viewport.
+- QA plans for user-facing work must include UX checks, not only functional assertions.

package/rules/work-intake-sequencing.mdc

@@ -0,0 +1,39 @@
+---
+description: Work intake, GitHub issue readiness, technical refinement, and implementation sequencing
+alwaysApply: true
+---
+
+# Work Intake & Sequencing
+
+Every work block must start from a refined GitHub issue and follow a safe implementation order. Do not start coding from chat context alone.
+
+## GitHub Issue Gate
+- Before starting a work block, confirm the GitHub issue exists and record its issue number.
+- The issue must include user story or job-to-be-done, acceptance criteria, priority, scope, non-goals, technical notes, test expectations, and risk areas.
+- If the issue is missing or vague, create or refine it before implementation.
+- Use the issue number as the Backlog Item ID for commits and PRs.
+
+## Technical Refinement
+- Refine the solution with expected files/modules, domain model changes, service/integration changes, controller/CLI/API changes, data flow, failure modes, and test plan.
+- Identify impacted roles before coding: Architect, Developer, QA, Security, DevOps, SRE, DBA, UX/UI, Compliance/Privacy, Technical Writer, or Game Designer.
+- Record assumptions and open questions. Block implementation when a decision affects user behavior, data contracts, security, deployment, or compliance.
+
+## Implementation Order
+- Start with models and domain: types, schemas, entities, value objects, invariants, and validation.
+- Then implement service and integration layer: orchestration, repositories, adapters, provider interfaces, external APIs, and side effects.
+- Then implement controllers and entry points: CLI commands, API routes, UI handlers, jobs, and web controllers.
+- Finally wire evidence: unit tests, integration tests, Playwright or smoke tests, static analysis, docs, and handoff.
+
+## Security Review Trigger
+- Run a security review when work touches auth, authorization, identity, secrets, PII, payments, file paths, shell/process execution, network calls, dependency changes, encryption, TLS, cookies, sessions, CORS, webhooks, or infrastructure.
+- Production networked services must consider TLS 1.2+, certificate management, HSTS where applicable, secure cookies, least privilege, and secret rotation.
+- If security is out of scope, state why. If uncertain, involve Security before implementation.
+
+## Block Start Checklist
+- GitHub issue exists and is refined.
+- User alignment gate is complete for non-trivial work.
+- Domain/model changes are understood.
+- Service/integration boundaries are understood.
+- Controller/entry-point changes are understood.
+- Test, QA, static analysis, and evidence plan are clear.
+- Security/DevOps/SRE/DBA/Compliance review needs are explicitly included or excluded with rationale.