docs: consolidate copilot governance and add medassist skills (#160)

.github/skills/README.md

@@ -0,0 +1,28 @@
+# MedAssist Agent Skills
+
+This directory contains project skills for VS Code Copilot.
+
+Each skill lives in its own folder and must include a `SKILL.md` file.
+
+## Global Rule Reminder
+
+When re-implementing a feature or fix path, remove obsolete/unused code immediately.
+Do not leave dead code behind.
+Also follow the canonical global engineering rules in `AGENTS.md`.
+Use one governance source to avoid duplicated or conflicting policy text.
+
+## Skills
+
+- `medassist-karpathy-core` — enforce assumption clarity, simplicity, surgical diffs, and verifiable execution.
+- `medassist-architecture-guard` — enforce frontend/backend boundary and `/api/*` data-flow conventions.
+- `medassist-db-compat-check` — enforce backward-compatible SQLite/Drizzle schema changes.
+- `medassist-i18n-enforcer` — enforce translation-key-only UI copy with EN/DE parity.
+- `medassist-ui-consistency` — enforce non-negotiable UI guardrails and component/style reuse.
+- `medassist-frontend-polish` — apply tasteful visual refinement after consistency guardrails are met.
+- `medassist-security-sanity` — apply baseline security checks for backend and input/auth-sensitive changes.
+- `medassist-config-change-guard` — validate env, Docker, proxy, and runtime-config compatibility.
+- `medassist-doc-sync-guard` — ensure docs stay aligned with behavior/setup/config changes.
+- `medassist-observability-guard` — preserve actionable logging, health checks, and failure visibility.
+- `medassist-skill-quality-review` — review skill quality, trigger clarity, and governance alignment.
+- `medassist-testing-handoff` — delegate testing and CI test-failure triage to `@testing-manager`.
+- `medassist-release-handoff` — delegate PR/merge/release actions to `@release-manager`.

.github/skills/medassist-architecture-guard/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: medassist-architecture-guard
+description: Guard MedAssist architectural boundaries and route/data-flow conventions when changing backend or frontend code, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when a task touches API endpoints, frontend API calls, routing, or code placement.
+
+## Goals
+
+- Keep responsibilities in the correct layer.
+- Preserve MedAssist proxy and routing conventions.
+- Prevent architecture drift and cross-layer anti-patterns.
+
+## Required Checks
+
+1. Frontend network calls use `/api/*` paths.
+2. Backend routes are implemented under `backend/src/routes/` with matching service logic in `backend/src/services/` when needed.
+3. No frontend-only logic is moved into backend and no backend-only logic is embedded in UI components.
+4. Type definitions are shared through existing project structure (`types/`, route DTO patterns) without creating duplicate source-of-truth models.
+
+## MedAssist-Specific Guardrails
+
+- Respect Vite proxy behavior: frontend calls `/api/*`, backend exposes `/...` routes.
+- Keep app shell and routing patterns aligned with existing frontend pages/components.
+- Prefer minimal, local changes over broad restructures.
+
+## Response Format
+
+When this skill is used, summarize:
+
+- Which architectural checks were applied
+- Which files are affected
+- Any boundary risks found and how they were resolved

.github/skills/medassist-config-change-guard/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: medassist-config-change-guard
+description: Validate MedAssist configuration changes across env vars, Docker compose, proxy settings, and runtime defaults, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when changes touch `.env`, Docker files, Vite proxy settings, runtime defaults, or app startup behavior.
+
+## Objective
+
+Prevent configuration drift and broken local/CI environments.
+
+## Required Checks
+
+1. New/changed config has safe defaults.
+2. Env changes are backward-compatible where feasible.
+3. Docker/dev runtime changes remain consistent across services.
+4. Frontend/backend URL/proxy conventions remain valid (`/api/*`).
+5. Documentation reflects configuration changes.
+
+## Files to Prioritize
+
+- `.env.example`
+- `docker-compose.yml`
+- `docker-compose.dev.yml`
+- `frontend/vite.config.ts`
+- Relevant package scripts and startup files
+
+## Anti-Patterns
+
+- Hidden required env vars with no defaults.
+- Inconsistent host/port/proxy settings across environments.
+- Config changes without doc updates.
+
+## Response Format
+
+Report:
+
+- Config files reviewed
+- Compatibility impact (none/low/high)
+- Required follow-up updates
+- Final readiness recommendation

.github/skills/medassist-db-compat-check/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: medassist-db-compat-check
+description: Enforce backward-compatible database changes for MedAssist SQLite and Drizzle migrations, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill for any feature or fix that adds or reads persisted data.
+
+## Mandatory Sequence
+
+For every new persisted field/column:
+
+1. Add the column in `backend/src/db/schema.ts` with `NOT NULL DEFAULT <value>`.
+2. Generate migration with Drizzle Kit.
+3. Add matching `ALTER TABLE` logic in `backend/src/db/client.ts` inside `runAlterMigrations()`.
+4. Read values null-safe in routes/services (`?? defaultValue`).
+
+## Hard Rules
+
+- Never remove or rename existing columns.
+- Never add non-null columns without defaults.
+- Never read newly added fields without fallback.
+- Never manually edit generated Drizzle SQL migrations.
+
+## Verification Checklist
+
+- Schema update exists.
+- Generated migration exists.
+- Alter migration for existing DBs exists.
+- Runtime reads are fallback-safe.
+
+## Response Format
+
+Report these items explicitly:
+
+- New/changed columns
+- Added alter-migration statements
+- Null-safe read locations
+- Remaining migration risk (if any)

.github/skills/medassist-doc-sync-guard/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: medassist-doc-sync-guard
+description: Ensure MedAssist documentation stays aligned with behavior changes in APIs, configuration, setup, and operations, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when code changes alter behavior, setup steps, environment variables, user workflows, or operational commands.
+
+## Objective
+
+Keep docs consistent with actual product behavior and avoid stale setup/run guidance.
+
+## Required Checks
+
+1. If API behavior changed, verify relevant docs are updated.
+2. If ENV/config changed, update documented variables/defaults.
+3. If workflow/commands changed, update setup/run instructions.
+4. If user-facing behavior changed, update user-facing description.
+
+## Candidate Documentation Files
+
+- `README.md`
+- `docs/PROJECT_SETUP.md`
+- `docs/TECH_STACK.md`
+
+## Anti-Patterns
+
+- Shipping behavior changes without docs updates.
+- Updating docs with speculative/unverified commands.
+- Duplicating conflicting instructions across files.
+
+## Response Format
+
+Return:
+
+- Doc files that should change
+- Proposed update summary per file
+- Any intentionally skipped docs and reason

.github/skills/medassist-frontend-polish/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: medassist-frontend-polish
+description: Improve frontend visual quality within the existing MedAssist design system, without introducing new themes, font stacks, or disruptive UI patterns, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when the user wants UI improvements, better styling, or a more polished frontend, but the feature must stay consistent with MedAssist product UX.
+
+## Scope
+
+This is the **visual enhancement skill**.
+It refines quality *within* existing product conventions.
+
+Apply `medassist-ui-consistency` rules first, then use this skill for tasteful polish.
+
+## Do Not Use This Skill For
+
+- Replacing base UI patterns/components with new ones.
+- New design-system direction, visual identity, or broad layout language changes.
+- Marketing/brand-experiment pages that intentionally break product conventions.
+
+## Objective
+
+Deliver production-grade visual refinement that feels intentionally designed while remaining fully consistent with existing MedAssist components, spacing, typography, and interaction patterns.
+
+## Strict Constraints
+
+- Reuse existing components and patterns first (`ConfirmModal`, `MedicationAvatar`, existing form/button/layout patterns).
+- Do not introduce new global theme systems, font families, or visual identity changes.
+- Do not invent new UX flows, pages, or interaction models unless explicitly requested.
+- Keep frontend text i18n-safe: use `t("...")` and EN/DE keys.
+- Respect accessibility and readability over decorative effects.
+
+## Allowed Enhancements
+
+- Better spacing rhythm and visual hierarchy.
+- Cleaner grouping, alignment, and density adjustments.
+- Improved states (hover, focus, disabled, loading) using existing style language.
+- Subtle transitions/micro-interactions that do not distract and do not change behavior.
+- Consistent empty/error/success presentation using existing UI conventions.
+
+## Not Allowed
+
+- Random aesthetic overhauls.
+- New color systems or hardcoded ad-hoc colors that break current theme tokens.
+- Heavy animation, parallax, or attention-stealing motion.
+- Typography experiments that diverge from current product style.
+- "Creative" layout changes that reduce usability or consistency.
+
+## Implementation Workflow
+
+1. Confirm `medassist-ui-consistency` guardrails are satisfied.
+2. Identify existing components and CSS patterns to reuse.
+3. Define the smallest visual changes that improve clarity and quality.
+4. Apply refinements in-place without changing core behavior.
+5. Validate consistency across neighboring views/components.
+6. Ensure i18n and accessibility are preserved.
+
+## Response Format
+
+When using this skill, report:
+
+- Reused components and style primitives
+- Specific polish improvements applied
+- Any trade-offs/constraints respected
+- Confirmation that no new design system or disruptive UX pattern was introduced

.github/skills/medassist-i18n-enforcer/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: medassist-i18n-enforcer
+description: Enforce MedAssist i18n rules so UI copy is always translation-key based for English and German, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when changing frontend UI text, form labels, alerts, dialogs, or page content.
+
+## Rules
+
+- Do not hardcode new user-facing strings in React components.
+- Use translation keys via `t("...")`.
+- Add or update matching keys in:
+  - `frontend/src/i18n/en.json`
+  - `frontend/src/i18n/de.json`
+- Keep semantic key naming consistent with existing namespaces.
+
+## Validation
+
+1. Every new UI string has a key.
+2. English and German entries are both present.
+3. No fallback-to-English hardcoded text remains in JSX.
+
+## Response Format
+
+List:
+
+- New keys added
+- Files where keys were used
+- Any intentionally unchanged text and reason

.github/skills/medassist-observability-guard/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: medassist-observability-guard
+description: Ensure MedAssist changes preserve actionable logging, health checks, and clear operational error visibility, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when changes affect backend services, schedulers, integrations, startup flow, or failure handling.
+
+## Objective
+
+Maintain operational visibility so failures are detectable, diagnosable, and actionable.
+
+## Required Checks
+
+1. Critical paths keep clear error reporting.
+2. Health-check behavior remains intact and meaningful.
+3. Logs contain actionable context without leaking secrets.
+4. Errors are surfaced with enough detail for debugging.
+5. Silent failure paths are avoided.
+
+## MedAssist Focus Areas
+
+- `backend/src/index.ts`
+- `backend/src/routes/health.ts`
+- `backend/src/services/*`
+- Scheduler and notification flows
+
+## Anti-Patterns
+
+- Swallowed exceptions.
+- Generic logs with no context.
+- Missing visibility for background failures.
+
+## Response Format
+
+Return:
+
+- Observability touchpoints reviewed
+- Gaps found and suggested fixes
+- Operational risk level

.github/skills/medassist-release-handoff/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: medassist-release-handoff
+description: Enforce MedAssist release ownership by preventing remote git/release actions by normal agents and delegating to release-manager, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when a request includes branch push, PR creation, merge, tagging, release notes publishing, or release orchestration.
+
+## Ownership Rules
+
+- Remote git/release actions are owned by `@release-manager`.
+- Normal agent/Copilot must not perform:
+  - `git push`
+  - PR creation/merge
+  - tag/release creation
+
+## Required Behavior
+
+1. Perform local code edits only.
+2. Summarize local changes clearly.
+3. Provide handoff instruction to `@release-manager` for shipping steps.
+
+## Response Format
+
+When this skill applies, return:
+
+- "Release handoff required"
+- Delegate target: `@release-manager`
+- Shipping checklist (branch, PR, CI, merge, release)

.github/skills/medassist-security-sanity/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: medassist-security-sanity
+description: Apply baseline security checks to MedAssist code changes, especially for backend routes, auth flows, and input handling, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when a change touches backend routes, auth/session logic, file handling, imports/exports, or external input.
+
+## Objective
+
+Prevent common security regressions with fast, practical checks during implementation.
+
+## Required Checks
+
+1. Validate and sanitize external input at API boundaries.
+2. Enforce auth/authz server-side for protected actions.
+3. Ensure secrets/tokens are never hardcoded or logged.
+4. Avoid information leakage in error responses.
+5. Keep permission-sensitive operations explicit and auditable.
+
+## MedAssist Focus Areas
+
+- Route handlers in `backend/src/routes/`.
+- Auth-related code in `backend/src/plugins/` and auth routes.
+- Data import/export and sharing endpoints.
+- File/image upload and serving paths.
+
+## Anti-Patterns
+
+- Trusting frontend-only checks.
+- Accepting unchecked query/body/path input.
+- Returning raw internal errors to clients.
+- Weak defaults for sensitive operations.
+
+## Response Format
+
+Report:
+
+- Security-sensitive files reviewed
+- Findings by severity (critical/major/minor)
+- Concrete remediation actions
+- Residual risk (if any)

.github/skills/medassist-skill-quality-review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: medassist-skill-quality-review
+description: Review MedAssist skills for trigger quality, scope boundaries, and conflicts with AGENTS governance, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when creating or modifying any skill under `.github/skills/`.
+
+## Objective
+
+Keep skills discoverable, non-overlapping, and aligned with canonical governance in `AGENTS.md`.
+
+## Required Checks
+
+1. Frontmatter has clear `name` and specific `description` trigger language.
+2. Scope boundaries are explicit (`when to use` / `do not use`).
+3. No conflicts with `AGENTS.md` ownership rules.
+4. No policy duplication that can drift from canonical governance.
+5. References to related skills are explicit where workflows chain.
+
+## Quality Signals
+
+- Trigger phrases are concrete and task-shaped.
+- Instructions are concise, actionable, and deterministic.
+- Response format is clear and useful for downstream handoff.
+
+## Anti-Patterns
+
+- Vague descriptions that match everything.
+- Duplicate skills with overlapping responsibilities.
+- Contradictory ownership guidance.
+- Long policy blocks copied from other files.
+
+## Response Format
+
+Return:
+
+- Scope/trigger issues found
+- Overlap/conflict findings
+- Suggested minimal edits
+- Final pass/fail recommendation

.github/skills/medassist-testing-handoff/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: medassist-testing-handoff
+description: Enforce MedAssist testing ownership by delegating test planning, execution, and CI test failure triage to testing-manager, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill whenever a task includes writing tests, running tests, or diagnosing test-related CI failures.
+
+## Ownership Rules
+
+- Test planning, implementation, and execution are owned by `@testing-manager`.
+- CI test-failure triage (`test.yml`, `e2e.yml`) is owned by `@testing-manager`.
+- Normal coding agent should hand off testing tasks instead of executing testing workflows directly.
+
+## Handoff Template
+
+Use this structure for delegation:
+
+1. Scope: feature/fix and affected files
+2. Expected behavior
+3. Suggested test layers (unit/integration/e2e)
+4. CI failure context (if applicable)
+
+## Response Format
+
+When triggered, output:
+
+- "Testing handoff required"
+- Delegate target: `@testing-manager`
+- Minimal handoff brief (scope + expected behavior)

.github/skills/medassist-ui-consistency/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: medassist-ui-consistency
+description: Enforce non-negotiable MedAssist UI guardrails by reusing existing components, styles, and interaction patterns, including equivalent requests phrased in German.
+---
+
+# Skill Instructions
+
+Use this skill when implementing or editing UI flows, modals, buttons, forms, schedule views, or settings screens.
+
+## Scope
+
+This is the **guardrail skill** for UI work.
+Use it to enforce consistency and prevent design drift.
+
+Use `medassist-frontend-polish` only after these guardrails are satisfied.
+
+## Do Not Use This Skill For
+
+- Creative visual redesign requests where no product consistency constraints apply.
+- Marketing-style one-off pages outside MedAssist product UI conventions.
+
+## Rules
+
+- Reuse existing components (for example `ConfirmModal`, `MedicationAvatar`) before creating new primitives.
+- Keep spacing, typography, and button styles aligned with existing patterns.
+- Avoid custom inline modal/button patterns that diverge from project design.
+- Prefer extending existing CSS classes/styles instead of introducing parallel styling systems.
+
+## Decision Heuristics
+
+1. If an equivalent component exists, reuse it.
+2. If small variant is needed, extend existing styles minimally.
+3. If a new component is unavoidable, match existing naming and structure conventions.
+
+## Response Format
+
+Provide:
+
+- Reused components/styles
+- Any new UI element and why reuse was not possible
+- Consistency risks reviewed
+- Confirmation that `medassist-frontend-polish` constraints remain compatible (if polish work is also requested)