@olives/devos 2.1.0

package/.agents/skills/deployment-checklist/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: deployment-checklist
+description: Pre-deployment verification checklist to be run by the DevOps agent before every production deployment.
+---
+
+# Deployment Checklist
+
+> Run this checklist before every production deployment. No exceptions.
+> The DevOps agent must verify each item and present this completed checklist for human approval.
+
+---
+
+## Pre-Deployment (Before Anything Runs)
+
+### Code Quality
+- [ ] All CI checks passing (lint, typecheck, tests, build)
+- [ ] Security scan completed — no CRITICAL or HIGH findings
+- [ ] Code review approved (at least one human reviewer)
+- [ ] No `console.log`, `print()`, or `dd()` in code going to production
+- [ ] No hardcoded secrets or environment values
+- [ ] `.env.example` updated with any new variables
+
+### Database
+- [ ] All migrations tested against a staging database first
+- [ ] Migration is reversible, or a rollback plan is documented
+- [ ] No destructive migration runs without a database backup taken immediately before
+- [ ] Query performance checked for any new queries on large tables (EXPLAIN ANALYZE)
+
+### Dependencies
+- [ ] No packages with known critical CVEs
+- [ ] No packages installed that aren't in `package.json` / `requirements.txt` / `composer.json`
+- [ ] Lock file committed (`package-lock.json`, `composer.lock`, `poetry.lock`)
+
+### Environment
+- [ ] All required environment variables set in production environment
+- [ ] No development-only config bleeding into production (DEBUG=False, etc.)
+- [ ] Third-party API keys are production keys (not dev/test keys)
+- [ ] CORS configuration correct for production domain
+- [ ] Rate limiting configured on auth and sensitive endpoints
+
+---
+
+## Deployment Execution
+
+### Staging First
+- [ ] Deployed to staging environment
+- [ ] Smoke test on staging: [list your key user flows here]
+- [ ] No unexpected errors in staging logs for 10+ minutes
+
+### Production
+- [ ] Deployment window communicated if downtime expected
+- [ ] Database backup taken immediately before migration (if applicable)
+- [ ] Deployment executed
+- [ ] Migration applied and verified
+
+---
+
+## Post-Deployment Verification
+
+### Immediate (first 5 minutes)
+- [ ] Application loads without errors
+- [ ] Authentication flow works (login, logout)
+- [ ] Core feature smoke test passes
+- [ ] No spike in error rate in logs/monitoring
+
+### First 30 Minutes
+- [ ] Monitor error logs for anomalies
+- [ ] Check performance metrics (response times, memory, CPU)
+- [ ] Verify background jobs are processing (if applicable)
+- [ ] Test any user-facing features that changed in this deployment
+
+---
+
+## Rollback Procedure
+
+**If something goes wrong:**
+
+1. **Assess severity.** Is this affecting all users or a subset? Is data at risk?
+2. **Communicate.** Notify relevant stakeholders immediately.
+3. **Execute rollback.** Each deployment should have a documented rollback command ready before deployment begins.
+4. **Verify.** Confirm rollback was successful.
+5. **Post-mortem.** Document what happened and why within 24 hours.
+
+```bash
+# Example rollback commands (fill in for your platform)
+
+# Vercel — instant rollback to previous deployment
+vercel rollback [deployment-url]
+
+# Railway
+railway rollback
+
+# Docker — roll back to previous image tag
+docker pull your-image:previous-tag
+docker-compose up -d
+
+# Database migration rollback (Laravel)
+php artisan migrate:rollback
+
+# Database migration rollback (Django)
+python manage.py migrate app_name 0005  # previous migration number
+```
+
+---
+
+## Deployment Sign-off
+
+Before executing:
+
+```
+Deployment: [version / feature name]
+Prepared by: [agent or person]
+Checklist completed: [ ]
+Human approval: [ ] Confirmed by: ________
+Deployment time: ________
+```
+
+**This deployment does not proceed without a human completing the sign-off above.**
+

package/.agents/skills/design/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: design
+description: UI/UX design principles and core philosophy. Defines typography, color, layout, spacing, and interaction states. Use when an agent is working on UI, design systems, or visual components.
+---
+
+# Design Skill — AI Agent Design Principles
+
+> Load this when an agent is working on UI, design systems, or visual components.
+> This defines how we think about design — not just what things look like, but why.
+
+---
+
+## Core Philosophy
+
+Design is not decoration. Every visual decision should make the product easier to understand and use. When in doubt, remove something rather than add it.
+
+---
+
+## Before Touching Any UI
+
+1. **Understand the user's job.** What are they trying to accomplish? Design for that task, not the technology behind it.
+2. **Read the existing design system.** Match existing components before creating new ones. Every new component is maintenance debt.
+3. **Name things as users know them.** Not "webhook configuration" — "notification settings". Not "auth token" — "your API key".
+
+---
+
+## Typography
+
+- Define a type scale before building. Don't pick font sizes ad hoc.
+- Maximum 2 font families per product (display + body). Add a mono face only if showing code.
+- Line length: 60-75 characters for body text. Wider than this hurts readability.
+- Line height: 1.5 for body, 1.2-1.3 for headings.
+
+Suggested scale:
+```
+xs: 12px
+sm: 14px
+base: 16px
+lg: 18px
+xl: 20px
+2xl: 24px
+3xl: 30px
+4xl: 36px
+```
+
+---
+
+## Color
+
+- Build with semantic tokens, not raw hex values in components.
+  - `color-primary` not `#3B82F6`
+  - `color-danger` not `#EF4444`
+  - `color-text-muted` not `#6B7280`
+- Every color must pass WCAG AA contrast (4.5:1 for text, 3:1 for large text and UI elements)
+- Dark mode: design both modes from the start — retrofitting is painful
+- Don't use color alone to convey meaning (for accessibility)
+
+---
+
+## Layout & Spacing
+
+- Use a spacing scale (4px base unit is standard): 4, 8, 12, 16, 24, 32, 48, 64
+- Consistent internal spacing within components, consistent spacing between components
+- White space is a design element — use it deliberately, not to fill gaps
+- Mobile-first: design for the smallest screen that matters, then enhance
+
+---
+
+## Components
+
+### Writing Component Copy
+- Labels label — they say what the field is, not instructions
+- Placeholders are examples, not labels — they disappear on focus
+- Buttons say what happens: "Save changes", not "Submit"
+- Error messages say what went wrong and how to fix it: "Email already registered — try logging in"
+- Empty states invite action: "No cases yet — report the first one"
+
+### Interaction States
+Every interactive component must have:
+- Default
+- Hover
+- Focus (keyboard-navigable, visible outline)
+- Active / pressed
+- Disabled (with explanation if not obvious why)
+- Loading (if async)
+- Error (if validation applies)
+
+---
+
+## Accessibility Non-Negotiables
+
+- All images have meaningful `alt` text (or `alt=""` if decorative)
+- All forms have `<label>` elements associated with inputs
+- Focus order follows visual order
+- Interactive elements are reachable by keyboard
+- Don't rely on hover alone to reveal information
+- Minimum touch target size: 44x44px on mobile
+
+---
+
+## Animation
+
+- Animation should serve the interface — transitions, loading states, feedback
+- Never animate for decoration alone
+- Respect `prefers-reduced-motion` — always provide a no-motion alternative
+- Duration guide:
+  - Micro-interactions (hover, toggle): 100-200ms
+  - Page transitions: 200-350ms
+  - Loading / skeleton states: match expected wait time
+
+---
+
+## Forbidden Patterns
+
+- Placeholder text as the only label (disappears when user types)
+- Tooltips on mobile (no hover on touch)
+- Auto-playing video or audio
+- Disabling paste in password fields
+- Infinite scroll without a way to reach the footer
+- Carousels that auto-advance
+- Hiding content behind hover on mobile
+- Modals that block users from copying text (e.g. phone numbers, addresses)
+
+---
+
+## Design Tokens (Start Every Project With These)
+
+```css
+:root {
+  /* Colors — replace with your brand */
+  --color-primary: ;
+  --color-primary-hover: ;
+  --color-danger: ;
+  --color-success: ;
+  --color-warning: ;
+  --color-text: ;
+  --color-text-muted: ;
+  --color-background: ;
+  --color-surface: ;
+  --color-border: ;
+
+  /* Typography */
+  --font-display: ;
+  --font-body: ;
+  --font-mono: ;
+
+  /* Spacing */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+
+  /* Radii */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+}
+```
+
+

package/.agents/skills/design-an-interface/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: design-an-interface
+description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+---
+
+# Design an Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** - types, methods, params
+2. **Usage examples** - how callers actually use it in practice
+3. **What it hides** - complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs - enforce radical difference
+- Don't skip comparison - the value is in contrast
+- Don't implement - this is purely about interface shape
+- Don't evaluate based on implementation effort

package/.agents/skills/expose-localhost/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: expose-localhost
+description: Expose a local service to the public internet using ngrok. Starts a tunnel, optionally adds OAuth or WAF via Traffic Policy. Use when asked to expose, tunnel, share, or make a local service publicly accessible.
+license: MIT
+metadata:
+  author: ngrok
+  version: "2.0"
+compatibility: Requires ngrok CLI installed and authenticated.
+---
+
+# Expose Localhost
+
+Expose a local service to the public internet using ngrok. Optionally add OAuth, OWASP protection, or rate limiting via Traffic Policy.
+
+## Prerequisites
+
+- ngrok CLI installed (`ngrok` command available)
+- Auth token configured (`ngrok config add-authtoken <TOKEN>`)
+
+## Workflow
+
+### Step 1: Pre-flight & Configuration
+
+Silently verify ngrok is ready:
+
+```bash
+ngrok config check
+```
+
+If auth token missing, tell user to run: `ngrok config add-authtoken <TOKEN>` (get token at https://dashboard.ngrok.com/get-started/your-authtoken)
+
+Then **ask all questions upfront** before doing anything:
+
+```
+Before I expose your service, I need a few details:
+
+1. **Port**: I see your app runs on port 3000. Is that correct?
+2. **Domain**: Use your dev domain, or do you have a custom domain?
+3. **Access control**: Open access, or require login (Google/GitHub/etc.)?
+4. **Save config?**: One-time setup, or save for reuse?
+```
+
+Do NOT mention cloud endpoints, reserved domains, or internal endpoints — those are advanced concepts the user shouldn't need to think about.
+
+**Detecting the port**: Check `package.json` scripts for `--port`, `.env` for `PORT=`, `docker-compose.yml` for port mappings.
+
+**Domains**: Most ngrok accounts have a free static dev domain (e.g., `something.ngrok-free.dev`). Running `ngrok http PORT` uses it automatically. Users can also provide a custom domain configured in the ngrok dashboard. Some accounts (especially new ones) may not have a dev domain yet — if ngrok fails with `ERR_NGROK_15013`, tell the user: "You don't have a dev domain yet. Claim your free one at https://dashboard.ngrok.com/domains — then we can try again."
+
+**If user requests OAuth**, also ask: "Should only specific people be able to access it? I can restrict by email address or email domain."
+
+After gathering answers, confirm and get a Y/n before proceeding.
+
+### Step 2: Start the Tunnel
+
+#### No security (simplest)
+
+```bash
+ngrok http {PORT} &
+sleep 3
+curl -s http://localhost:4040/api/tunnels | grep -o '"public_url":"[^"]*"' | head -1
+```
+
+With a specific domain, add `--url https://{DOMAIN}`.
+
+#### With security (Traffic Policy)
+
+Create the traffic policy file first, then start ngrok with it.
+
+**OAuth-only** (default when user requests auth):
+
+```yaml
+on_http_request:
+  - actions:
+      - type: oauth
+        config:
+          provider: google
+```
+
+Replace `google` with the chosen provider (google, github, microsoft, gitlab, linkedin, twitch).
+
+If the user requests OAuth, default to OAuth-only. Do NOT add OWASP or rate limiting unless explicitly asked — OAuth already blocks unauthenticated access.
+
+**OAuth with email restriction** — use a separate rule with a CEL expression to deny non-matching emails. Do NOT add an `allow` field to the OAuth action.
+
+Single email:
+
+```yaml
+on_http_request:
+  - actions:
+      - type: oauth
+        config:
+          provider: google
+  - expressions:
+      - "actions.ngrok.oauth.identity.email != 'user@example.com'"
+    actions:
+      - type: deny
+        config:
+          status_code: 403
+```
+
+Email domain:
+
+```yaml
+on_http_request:
+  - actions:
+      - type: oauth
+        config:
+          provider: google
+  - expressions:
+      - "!actions.ngrok.oauth.identity.email.endsWith('@your-company.com')"
+    actions:
+      - type: deny
+        config:
+          status_code: 403
+```
+
+Multiple emails — use `!(... in ['a@x.com', 'b@x.com'])` in the expression.
+
+**Open-access hardening** (no auth, but wants protection):
+
+```yaml
+on_http_request:
+  - actions:
+      - type: rate-limit
+        config:
+          name: default-rate-limit
+          algorithm: sliding_window
+          capacity: 200
+          rate: "60s"
+          bucket_key:
+            - conn.client_ip
+      - type: owasp-crs-request
+        config:
+          on_error: halt
+
+on_http_response:
+  - actions:
+      - type: owasp-crs-response
+        config:
+          on_error: halt
+```
+
+After writing the policy file, start ngrok:
+
+```bash
+ngrok http {PORT} --traffic-policy-file .ngrok/traffic-policy.yml &
+sleep 3
+curl -s http://localhost:4040/api/tunnels | grep -o '"public_url":"[^"]*"' | head -1
+```
+
+Add `--url https://{DOMAIN}` if using a specific domain.
+
+### Step 3: Handle Errors
+
+If a traffic policy action fails due to plan limitations:
+
+1. Tell the user which specific action requires an upgrade
+2. Offer to remove that action from the policy and retry
+3. Do NOT suggest switching to cloud endpoints as a workaround
+
+### Step 4: Persistent Configuration (If Requested)
+
+Save these files to the project:
+
+- **`.ngrok/traffic-policy.yml`** — the policy (if security was configured)
+- **`.ngrok/expose.sh`**:
+
+```bash
+#!/bin/bash
+set -e
+echo "Your service will be at: https://{DOMAIN}"
+ngrok http {PORT} --url https://{DOMAIN} --traffic-policy-file .ngrok/traffic-policy.yml
+```
+
+Omit `--traffic-policy-file` if no policy. Omit `--url` if no specific domain.
+
+Optionally add to `package.json`:
+
+```json
+{ "scripts": { "tunnel": "bash .ngrok/expose.sh" } }
+```
+
+## Teardown
+
+```bash
+pkill ngrok
+```
+
+## Cloud Endpoints (Advanced)
+
+Only use if the user explicitly needs a URL that persists after the agent stops (e.g., webhooks, long-lived integrations).
+
+Requires an API key: `ngrok config add-api-key <KEY>` (get at https://dashboard.ngrok.com/api-keys)
+
+1. Reserve domain: `ngrok api reserved-domains create --domain "{DOMAIN}"`
+2. Create cloud endpoint with a traffic policy that includes `forward-internal` as the **last** action:
+
+```bash
+ngrok api endpoints create --url "https://{DOMAIN}" --bindings public --traffic-policy "$(cat .ngrok/traffic-policy.yml)"
+```
+
+The traffic policy must end with:
+
+```yaml
+- type: forward-internal
+  config:
+    url: https://{NAME}.internal
+```
+
+3. Start the internal agent: `ngrok http {PORT} --url https://{NAME}.internal`
+4. Teardown: `ngrok api endpoints delete {ENDPOINT_ID}`

package/.agents/skills/expose-localhost/references/TROUBLESHOOTING.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+## OWASP False Positives
+
+The OWASP Core Rule Set may block legitimate requests that look like attacks. To fix, identify the rule ID from the ngrok dashboard and exclude it:
+
+```yaml
+- type: owasp-crs-request
+  config:
+    on_error: halt
+    exclude_rule_ids:
+      - 942100  # Example: SQL injection rule
+```
+
+## OAuth Callback URL
+
+For custom OAuth apps (not ngrok's managed providers), set the callback URL to:
+
+```
+https://idp.ngrok.com/oauth2/callback
+```
+
+Managed providers (Google, GitHub, Microsoft, GitLab, LinkedIn, Twitch) need no configuration.
+
+## Rate Limit 429s
+
+The default policy sets 200 requests/minute per IP. To adjust, change `capacity` in the rate-limit action and restart ngrok.