@olives/devos 2.1.0

package/.agents/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md

@@ -0,0 +1,55 @@
+---
+title: Use Lowercase Identifiers for Compatibility
+impact: MEDIUM
+impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
+tags: naming, identifiers, case-sensitivity, schema, conventions
+---
+
+## Use Lowercase Identifiers for Compatibility
+
+PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
+
+**Incorrect (mixed-case identifiers):**
+
+```sql
+-- Quoted identifiers preserve case but require quotes everywhere
+CREATE TABLE "Users" (
+  "userId" bigint PRIMARY KEY,
+  "firstName" text,
+  "lastName" text
+);
+
+-- Must always quote or queries fail
+SELECT "firstName" FROM "Users" WHERE "userId" = 1;
+
+-- This fails - Users becomes users without quotes
+SELECT firstName FROM Users;
+-- ERROR: relation "users" does not exist
+```
+
+**Correct (lowercase snake_case):**
+
+```sql
+-- Unquoted lowercase identifiers are portable and tool-friendly
+CREATE TABLE users (
+  user_id bigint PRIMARY KEY,
+  first_name text,
+  last_name text
+);
+
+-- Works without quotes, recognized by all tools
+SELECT first_name FROM users WHERE user_id = 1;
+```
+
+Common sources of mixed-case identifiers:
+
+```sql
+-- ORMs often generate quoted camelCase - configure them to use snake_case
+-- Migrations from other databases may preserve original casing
+-- Some GUI tools quote identifiers by default - disable this
+
+-- If stuck with mixed-case, create views as a compatibility layer
+CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
+```
+
+Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)

package/.agents/skills/supabase-postgres-best-practices/references/schema-partitioning.md

@@ -0,0 +1,55 @@
+---
+title: Partition Large Tables for Better Performance
+impact: MEDIUM-HIGH
+impactDescription: 5-20x faster queries and maintenance on large tables
+tags: partitioning, large-tables, time-series, performance
+---
+
+## Partition Large Tables for Better Performance
+
+Partitioning splits a large table into smaller pieces, improving query performance and maintenance operations.
+
+**Incorrect (single large table):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz,
+  data jsonb
+);
+
+-- 500M rows, queries scan everything
+select * from events where created_at > '2024-01-01';  -- Slow
+vacuum events;  -- Takes hours, locks table
+```
+
+**Correct (partitioned by time range):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz not null,
+  data jsonb
+) partition by range (created_at);
+
+-- Create partitions for each month
+create table events_2024_01 partition of events
+  for values from ('2024-01-01') to ('2024-02-01');
+
+create table events_2024_02 partition of events
+  for values from ('2024-02-01') to ('2024-03-01');
+
+-- Queries only scan relevant partitions
+select * from events where created_at > '2024-01-15';  -- Only scans events_2024_01+
+
+-- Drop old data instantly
+drop table events_2023_01;  -- Instant vs DELETE taking hours
+```
+
+When to partition:
+
+- Tables > 100M rows
+- Time-series data with date-based queries
+- Need to efficiently drop old data
+
+Reference: [Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html)

package/.agents/skills/supabase-postgres-best-practices/references/schema-primary-keys.md

@@ -0,0 +1,61 @@
+---
+title: Select Optimal Primary Key Strategy
+impact: HIGH
+impactDescription: Better index locality, reduced fragmentation
+tags: primary-key, identity, uuid, serial, schema
+---
+
+## Select Optimal Primary Key Strategy
+
+Primary key choice affects insert performance, index size, and replication
+efficiency.
+
+**Incorrect (problematic PK choices):**
+
+```sql
+-- identity is the SQL-standard approach
+create table users (
+  id serial primary key  -- Works, but IDENTITY is recommended
+);
+
+-- Random UUIDs (v4) cause index fragmentation
+create table orders (
+  id uuid default gen_random_uuid() primary key  -- UUIDv4 = random = scattered inserts
+);
+```
+
+**Correct (optimal PK strategies):**
+
+```sql
+-- Use IDENTITY for sequential IDs (SQL-standard, best for most cases)
+create table users (
+  id bigint generated always as identity primary key
+);
+
+-- For distributed systems needing UUIDs, use UUIDv7 (time-ordered)
+-- Requires pg_uuidv7 extension: create extension pg_uuidv7;
+create table orders (
+  id uuid default uuid_generate_v7() primary key  -- Time-ordered, no fragmentation
+);
+
+-- Alternative: time-prefixed IDs for sortable, distributed IDs (no extension needed)
+create table events (
+  id text default concat(
+    to_char(now() at time zone 'utc', 'YYYYMMDDHH24MISSMS'),
+    gen_random_uuid()::text
+  ) primary key
+);
+```
+
+Guidelines:
+
+- Single database: `bigint identity` (sequential, 8 bytes, SQL-standard)
+- Distributed/exposed IDs: UUIDv7 (requires pg_uuidv7) or ULID (time-ordered, no
+  fragmentation)
+- `serial` works but `identity` is SQL-standard and preferred for new
+  applications
+- Avoid random UUIDs (v4) as primary keys on large tables (causes index
+  fragmentation)
+
+Reference:
+[Identity Columns](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-GENERATED-IDENTITY)

package/.agents/skills/supabase-postgres-best-practices/references/security-privileges.md

@@ -0,0 +1,54 @@
+---
+title: Apply Principle of Least Privilege
+impact: MEDIUM
+impactDescription: Reduced attack surface, better audit trail
+tags: privileges, security, roles, permissions
+---
+
+## Apply Principle of Least Privilege
+
+Grant only the minimum permissions required. Never use superuser for application queries.
+
+**Incorrect (overly broad permissions):**
+
+```sql
+-- Application uses superuser connection
+-- Or grants ALL to application role
+grant all privileges on all tables in schema public to app_user;
+grant all privileges on all sequences in schema public to app_user;
+
+-- Any SQL injection becomes catastrophic
+-- drop table users; cascades to everything
+```
+
+**Correct (minimal, specific grants):**
+
+```sql
+-- Create role with no default privileges
+create role app_readonly nologin;
+
+-- Grant only SELECT on specific tables
+grant usage on schema public to app_readonly;
+grant select on public.products, public.categories to app_readonly;
+
+-- Create role for writes with limited scope
+create role app_writer nologin;
+grant usage on schema public to app_writer;
+grant select, insert, update on public.orders to app_writer;
+grant usage on sequence orders_id_seq to app_writer;
+-- No DELETE permission
+
+-- Login role inherits from these
+create role app_user login password 'xxx';
+grant app_writer to app_user;
+```
+
+Revoke public defaults:
+
+```sql
+-- Revoke default public access
+revoke all on schema public from public;
+revoke all on all tables in schema public from public;
+```
+
+Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)

package/.agents/skills/supabase-postgres-best-practices/references/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/.agents/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,63 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
+```sql
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    -- always check the calling user's identity inside the function
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select private.is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/.agents/skills/task-contract/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: task-contract
+description: Defines the standard contract format for sub-task delegation between agents.
+---
+
+# Task Contract
+
+When delegating a task to another agent, you MUST provide a contract in this format:
+
+```
+[TASK CONTRACT]
+To: <Agent Role>
+From: <Your Role>
+Task: <Short Name>
+
+## Context
+Provide necessary context, links to CODING_STANDARDS.md, or prior work.
+
+## Deliverable
+Exactly what must be produced (e.g. file paths, test results).
+
+## Acceptance Criteria
+1. Must pass tests...
+2. Must follow standards...
+3. ...
+
+## Boundary
+What the agent should NOT do (e.g. do not touch DB schema).
+```

package/.agents/skills/token-optimization/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: token-optimization
+description: Rules for minimizing token consumption across all agent interactions without sacrificing output quality. Applies to all agents to keep context focused and costs low.
+---
+
+# Token Optimization Skill
+
+> **Goal**: Minimize token consumption across all agent interactions without sacrificing output quality.
+
+## Why This Matters
+Every agent interaction costs tokens. Unnecessary verbosity, redundant context loading, and multi-turn loops can 10x the cost of a task. This skill defines how all agents should behave to keep costs low.
+
+## Rules for All Agents
+
+### 1. Be Concise in Output
+- No preamble. No "Sure, I'd be happy to help." Start with the answer.
+- Use bullet points and tables over prose where possible.
+- Do not repeat the question back in the response.
+
+### 2. Single-Shot Over Multi-Turn
+- Prefer one well-structured prompt that gets the full answer, over a chain of follow-up questions.
+- When the Architect grills a project, it does so in a single zero-shot pass, not a simulated interview loop.
+
+### 3. Load Only Relevant Context
+- Do not load all agent prompts at once. Load only the prompt for the active agent.
+- Do not load the full `CODING_STANDARDS.md` when only one section is relevant — reference the section name.
+- Avoid pasting entire files into context when a line range or summary would suffice.
+
+### 4. Minimize Intermediate Reporting
+- Agents should report their final output, not narrate their thinking process step by step.
+- The Orchestrator should summarize delegations in a single block, not one message per agent.
+
+### 5. Reuse, Don't Repeat
+- If a Researcher already confirmed a package version, do not ask the Researcher again in the same session.
+- If a Reviewer approves code, do not re-review it unless the code changed.
+
+### 6. Structured Output Formats
+- Use the defined output templates (see each agent's prompt). Structured outputs are faster to parse, shorter, and more useful than free-form prose.
+
+

package/.agents/skills/ui-designer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ui-designer
+description: Craft one-of-a-kind, ship-ready frontend interfaces with elevated design quality. Apply this skill whenever the user wants to build web components, pages, artifacts, posters, or applications (for example, websites, landing pages, dashboards, React components, HTML/CSS layouts, or any task that involves styling or beautifying a web UI). Produces inventive, refined code and UI design that sidesteps cookie-cutter AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+Use this skill to produce singular, deployment-ready frontend interfaces that escape the bland "AI slop" look. Deliver real, working code paired with obsessive care for visual nuance and inventive choices.
+
+Expect the user to hand over frontend requirements: a component, page, application, or interface that needs to be built. Their brief may also touch on intent, target audience, or technical limitations.
+
+## Setting the Visual Direction
+
+Do not start coding until you've absorbed the context and committed to a DARING visual direction. Work through these four questions first:
+
+- **Purpose** — Which problem is this interface tackling, and who will be using it?
+- **Tone** — Pick something extreme: ruthlessly minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian — and many more besides. Treat these flavors as launchpads, then craft a version that genuinely embodies the direction you've picked.
+- **Constraints** — The technical boundaries you must operate inside (framework, performance, accessibility).
+- **Differentiation** — What turns this into something UNFORGETTABLE? Which single element will stick in someone's memory?
+
+**CRITICAL**: Settle on one unambiguous conceptual direction and execute it with precision. Audacious maximalism and pared-back minimalism are both valid — what matters is deliberateness, not loudness.
+
+## The Bar for Shipped Output
+
+Whatever you build (HTML/CSS/JS, React, Vue, or similar) must be:
+
+- Production-ready and operational
+- Striking enough to stick in memory
+- Anchored in a single, intentional aesthetic point of view
+- Polished obsessively down to the smallest detail
+
+## Levers of Craft
+
+Concentrate on:
+
+- **Typography** — Pick fonts that are striking, distinctive, and full of personality. Don't fall back on commonplace stacks like Arial and Inter; instead, select unconventional typefaces with real character that lift the interface — surprising, characterful choices. Pair a memorable display face with a refined body face.
+- **Color & Theme** — Commit to a unified visual identity. Rely on CSS variables to keep everything coherent. A bold dominant color punctuated by crisp accents will outperform a flat, evenly-weighted palette every time.
+- **Motion** — Use animation for effects and micro-interactions. For raw HTML, prefer CSS-only solutions first. In React, use the Motion library when it's available. Concentrate animation on high-impact moments: one carefully choreographed page entrance with staggered reveals (via animation-delay) creates more delight than a smattering of tiny touches. Add scroll-triggered transitions and hover states that surprise.
+- **Spatial Composition** — Layouts that defy expectation. Asymmetry. Overlapping forms. Diagonal flow. Components that crack the grid. Lavish whitespace OR controlled density.
+- **Backgrounds & Visual Details** — Build atmosphere and depth instead of defaulting to flat colors. Add contextual effects and textures that echo the broader aesthetic. Employ inventive treatments such as gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+## Aesthetics to Reject
+
+NEVER fall back on stock AI-styled aesthetics: the worn-out font stacks (Inter, Roboto, Arial, system fonts), tired color combinations (purple gradients over white backgrounds being a notorious offender), predictable layout and component templates, or assembly-line designs that ignore the specific context.
+
+Read the brief imaginatively and make surprising decisions that feel authentically crafted for the situation at hand. No two designs should look alike. Rotate between light and dark themes, between different typefaces, between different aesthetic registers. NEVER settle into the same safe defaults (Space Grotesk, for instance) across multiple generations.
+
+## Calibrating Effort to Vision
+
+**IMPORTANT**: Scale code complexity to fit the aesthetic intent. Maximalist work demands rich code thick with animation and effects. Minimalist or refined work demands discipline, precision, and meticulous attention to spacing, typography, and quiet details. Elegance emerges from executing the vision faithfully.
+
+Keep in mind: Claude is capable of remarkable creative output. Don't play it safe — show what becomes possible when you step outside convention and fully commit to a singular vision.
+
+## Picking Contextual Imagery
+
+Bundled with this skill is a script at `scripts/find-relevant-image.py` that selects a contextually fitting image from a curated, static database. It compares your description against the tags stored beside each image to identify the best match, while keeping the underlying resources current by checking if the installed skill is at the latest version, and prompting the user if update is available.
+
+The image catalog lives in `assets/images.csv` with columns `image-id`, `filename`, `tags`, and `image-base64`. For each entry, the script tallies how many of its tags appear in your description, selects the top scorer, verifies the decoded file via the `file` command, and saves it into the output directory. The output filename is dictated by the image metadata — the caller does not supply it.
+
+### Invocation
+
+```bash
+python scripts/find-relevant-image.py "<description>"
+```
+
+**Arguments:**
+- `description` - A description of where and how the image will be used (e.g. `"hero banner for a travel blog about Japanese temples"`)
+
+The selected image lands in `scripts/outputs/` (auto-created if missing). The complete output path is printed to stdout.
+
+**Example:**
+```bash
+python scripts/find-relevant-image.py "warm, inviting background photo for a bakery landing page"
+# Output: Matched image 'img-1234' written to /path/to/scripts/outputs/temple-landscape.png
+```
+
+Invoke this script whenever a frontend design calls for a real image rather than a placeholder — it locates one that fits the design context instead of dropping in a generic stock photo.