Add comprehensive test suite and Mech storage backend

.claude/skills/design-system-from-reference/SKILL.md

@@ -0,0 +1,93 @@
+# Skill: design-system-from-reference
+
+## What this skill does
+
+Guides Claude Code through a structured, four-phase workflow to extract a visual style from a reference UI screenshot and codify it into a reusable design system for this project. It:
+
+- Produces `design/design.json` as a high-level style guide.
+- Builds a local React + Vite + Tailwind 3 "showcase" app that implements all core components.
+- Produces `design/design-system.json` as the implementation-level source of truth for future AI-assisted development.
+
+This skill follows the rule defined in `ai-dev-tasks/design-system-from-reference.md`.
+
+## When to use
+
+Use this skill when:
+
+- You have a **reference UI** (e.g., a design-system-style screenshot from Dribbble) and
+- You want the project to adopt that look as a **consistent design system** that future features can follow.
+
+It is especially useful early in a project, before large amounts of UI have been implemented.
+
+## Inputs and assumptions
+
+- The user can provide or attach at least one **flat design-system screenshot** (not angled or heavily decorated).
+- The project can contain a `design/` folder at the repo root.
+- The project can run a local React + Vite + Tailwind 3 app (Node and npm available).
+- This project uses Markdown docs under `ai-dev-tasks/` and may already have other AI Dev Task rules.
+
+Always confirm with the user before installing dependencies or running long-lived dev servers.
+
+## High-level workflow
+
+Follow these phases, coordinating with the user at each major step.
+
+### Phase 1: Visual Inspiration & Analysis
+
+1. Ask the user to:
+   - Briefly describe the app this design system will serve (domain, platform, audience).
+   - Attach or reference the primary **design-system-style screenshot**.
+2. Verify the screenshot quality:
+   - Flat (no heavy perspective).
+   - Includes multiple components (buttons, inputs, cards, nav patterns, typography).
+3. Summarize back the intended style and constraints (e.g., brand adjectives, tone) before proceeding.
+
+### Phase 2: Create High-Level Style Guide (`design/design.json`)
+
+1. Explain to the user that you will create `design/design.json` as a high-level style guide.
+2. Using the best available **vision model**, deeply analyze the reference screenshot and generate `design/design.json` with:
+   - Brand essence and key adjectives.
+   - Color palette (primary, secondary, accents, neutrals, states).
+   - Typography (families, weights, scales, usage rules).
+   - Layout and spacing rules (grid, spacing scale, padding patterns).
+   - Component-level guidelines (buttons, inputs, cards, navigation, alerts, tables, etc.).
+   - Design principles, do's and don'ts.
+3. Save or propose the JSON content to be written to `design/design.json` at the project root.
+4. Show a short summary of the generated guide and ask the user to confirm or request edits. Apply any requested tweaks.
+
+### Phase 3: Build the Showcase Application
+
+1. Confirm with the user:
+   - Where to place the showcase app (e.g., `design/showcase-app/`).
+   - That using React + Vite + Tailwind 3 is acceptable.
+2. Use the best available **coding model** to scaffold a small Vite + React app that:
+   - Lives under the agreed folder (for example `design/showcase-app/`).
+   - Uses Tailwind CSS v3 configured consistently with `design/design.json`.
+3. Implement a single screen (or small set of screens) that showcases all core components:
+   - Buttons (primary/secondary/tertiary, states).
+   - Form controls (inputs, selects, textareas).
+   - Cards, surfaces, and list items.
+   - Navigation (top bar/side bar as appropriate).
+   - Status components (badges, alerts, toasts).
+4. Provide clear instructions to the user for running the app locally (e.g., `npm install`, `npm run dev` in the showcase folder) but never run commands or install dependencies without explicit confirmation.
+5. Ask the user to visually review the running app and request specific adjustments (e.g., spacing, radii, shadows, color tweaks). Apply changes iteratively until the look closely matches the reference.
+
+### Phase 4: Codify the System (`design/design-system.json`)
+
+1. Once the showcase app feels correct, explain that you will codify the final system into `design/design-system.json`.
+2. Analyze the actual implemented components and Tailwind classes in the showcase app and synthesize a comprehensive JSON file that includes:
+   - Exact Tailwind utility recipes for each component variant.
+   - Token-level spacing, radii, shadows, and typography scales.
+   - State rules (hover, focus, active, disabled, error, success, etc.).
+   - Motion/interaction patterns if present.
+   - High-level guidelines and do's/don'ts for when to use each component.
+3. Propose the full JSON for `design/design-system.json` and write it to `design/design-system.json` once the user approves.
+4. Briefly document in natural language (inside the JSON or as comments if the project convention allows) how other agents should reference this file.
+
+## Behavior in future sessions
+
+When future prompts involve building or modifying UI in this project:
+
+- Always check for the presence of `design/design-system.json` and `design/design.json`.
+- If they exist, load them into context and follow them strictly when designing new screens or components.
+- If they do not exist but the user references the design system workflow, suggest running this skill to establish the design system before proceeding.

.claude/skills/design-system-implementation/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: design-system-implementation
+description: Build or update frontend components and pages that strictly adhere to the project design system defined in design/design-system.json (and design/design.json when present).
+license: Complete terms in LICENSE.txt
+---
+
+This skill ensures that all new or modified UI is implemented **in line with the project design system**, rather than inventing ad-hoc styles.
+
+Use it when:
+- Implementing a new component, page, or flow.
+- Refactoring existing UI to match the design system.
+- Extending the design system with carefully considered new patterns.
+
+It is designed to be used **after** a design system has been created (for example via the `design-system-from-reference` workflow).
+
+## Inputs and assumptions
+
+- The project design system is defined in:
+  - `design/design-system.json` (implementation-level source of truth).
+  - Optionally `design/design.json` (higher-level style guide).
+- The user can describe:
+  - What they want to build or change (component/page/flow).
+  - Any relevant constraints (framework, routing, data layer, accessibility).
+- The codebase uses a consistent framework (e.g., React + Tailwind, or another typical web stack).
+
+If `design/design-system.json` is missing, this skill should **not** free-style a new design system. Instead, it should:
+- Ask the user to confirm whether a design system exists elsewhere.
+- Suggest running the `design-system-from-reference` workflow first.
+
+## Core responsibilities
+
+When building or updating UI, this skill must:
+
+1. **Load and understand the design system**
+   - Ingest `design/design-system.json` (and `design/design.json` if present).
+   - Identify:
+     - Tokens (colors, spacing, radii, typography scales, shadows, etc.).
+     - Component definitions and their variants.
+     - Layout and spacing rules.
+     - Interaction states and motion guidelines.
+   - Summarize back to the user how the design system wants buttons, inputs, cards, navigation, etc. to look and behave.
+
+2. **Map the request to existing patterns**
+   - For a new request (e.g., "build a billing settings page"):
+     - Break the UI into **sections and components**.
+     - For each part, map it to existing component types or patterns in the design system.
+   - If something genuinely new is needed:
+     - Propose how it fits into existing patterns (e.g., "This is a variant of the card component with…").
+     - Avoid inventing totally unrelated styling unless the user explicitly wants to extend the system.
+
+3. **Implement using the design system**
+   - Use **only** tokens, utility classes, and component recipes defined by the design system whenever possible.
+   - Avoid arbitrary inline styles or one-off Tailwind utilities that conflict with the system.
+   - Respect:
+     - Typography hierarchy (headings, body, labels, etc.).
+     - Spacing scale and layout rules.
+     - Color usage rules for states (primary, secondary, error, warning, success, disabled, etc.).
+     - Motion and interaction patterns.
+   - Keep code production-quality: clear structure, accessible semantics (ARIA, labels, keyboard navigation), and sensible component boundaries.
+
+4. **Handle extensions carefully**
+   - When the design system does not explicitly cover a case:
+     - First, try to express the new UI using **combinations or variants** of existing components.
+     - If an extension is truly needed, propose an addition to `design/design-system.json`:
+       - Describe new tokens, component variants, or layout rules.
+       - Ensure they are consistent with the existing system.
+     - Present the proposed JSON patch or snippet to the user for review before updating the design system.
+
+5. **Validate adherence**
+   - After generating code, briefly explain **how** it follows the design system:
+     - Which tokens/variants were used.
+     - How spacing/typography align with the rules.
+   - If any deliberate deviations were made (e.g., an experimental component), call them out clearly.
+
+## Suggested workflow when invoked
+
+1. **Confirm context**
+   - Ask the user:
+     - What they want built or changed.
+     - Where in the codebase it lives (paths, existing components).
+     - Whether there is an existing design system JSON; if unsure, search for `design/design-system.json`.
+2. **Load design system files**
+   - Open `design/design-system.json` (and `design/design.json` if present) and summarize the relevant parts for this task.
+3. **Plan the implementation**
+   - Break the UI into logical components/sections.
+   - For each, decide which design system components or patterns to use.
+   - Share this plan with the user and pause for confirmation.
+4. **Implement incrementally**
+   - Update or create components in small, reviewable steps.
+   - After each significant chunk (e.g., a component or page section), pause and:
+     - Show the diff or the new code.
+     - Explain how it adheres to the design system.
+5. **Optional: update the design system**
+   - If new patterns were introduced, propose JSON additions/changes for `design/design-system.json`.
+   - Only modify the design system after explicit user approval.
+6. **Summarize and hand off**
+   - Recap what was built/changed and how it aligns with the design system.
+   - List any follow-ups (e.g., applying the same patterns to other screens, updating docs).
+
+## Interaction with other skills
+
+- When combined with **`design-system-from-reference`**:
+  - Run `design-system-from-reference` first to create or update the design system files.
+  - Then use this `design-system-implementation` skill for all subsequent UI work.
+- When combined with **`frontend-design-concept`**:
+  - Use `frontend-design-concept` for exploring bold conceptual directions.
+  - Once a direction is chosen and codified into the design system, use `design-system-implementation` to roll out consistent implementations across the app.

.claude/skills/frontend-design-concept/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design-concept
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

.do/app.yaml

@@ -0,0 +1,53 @@
+name: admp-server
+region: nyc
+
+services:
+  - name: web
+    github:
+      repo: dundas/agentdispatch
+      branch: main
+      deploy_on_push: true
+
+    dockerfile_path: Dockerfile
+
+    http_port: 8080
+
+    health_check:
+      http_path: /health
+      initial_delay_seconds: 5
+      period_seconds: 30
+      timeout_seconds: 3
+      success_threshold: 1
+      failure_threshold: 3
+
+    instance_count: 1
+    instance_size_slug: basic-xxs  # 512MB RAM, $5/month
+
+    envs:
+      - key: NODE_ENV
+        value: "production"
+        scope: RUN_TIME
+      - key: PORT
+        value: "8080"
+        scope: RUN_TIME
+      - key: CORS_ORIGIN
+        value: "*"
+        scope: RUN_TIME
+      - key: HEARTBEAT_INTERVAL_MS
+        value: "60000"
+        scope: RUN_TIME
+      - key: HEARTBEAT_TIMEOUT_MS
+        value: "300000"
+        scope: RUN_TIME
+      - key: MESSAGE_TTL_SEC
+        value: "86400"
+        scope: RUN_TIME
+      - key: MAX_MESSAGE_SIZE_KB
+        value: "256"
+        scope: RUN_TIME
+      - key: MAX_MESSAGES_PER_AGENT
+        value: "1000"
+        scope: RUN_TIME
+
+    routes:
+      - path: /

.env.example

@@ -20,3 +20,14 @@ CLEANUP_INTERVAL_MS=60000
 # Limits
 MAX_MESSAGE_SIZE_KB=256
 MAX_MESSAGES_PER_AGENT=1000
+
+# Storage Backend
+# Options: "memory" (default, fast) or "mech" (persistent, slower)
+STORAGE_BACKEND=memory
+
+# Mech Storage (optional - only if STORAGE_BACKEND=mech)
+# Sign up at https://mechdna.net for credentials
+MECH_BASE_URL=https://storage.mechdna.net
+MECH_APP_ID=your_app_id_here
+MECH_API_KEY=your_api_key_here
+MECH_API_SECRET=your_api_secret_here