@namch/agent-assistant 1.0.0 → 1.0.2

package/skills/multi-agent-brainstorming/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: multi-agent-brainstorming
+description: >
+  Use this skill when a design or idea requires higher confidence,
+  risk reduction, or formal review. This skill orchestrates a
+  structured, sequential multi-agent design review where each agent
+  has a strict, non-overlapping role. It prevents blind spots,
+  false confidence, and premature convergence.
+---
+
+# Multi-Agent Brainstorming (Structured Design Review)
+
+## Purpose
+
+Transform a single-agent design into a **robust, review-validated design**
+by simulating a formal peer-review process using multiple constrained agents.
+
+This skill exists to:
+- surface hidden assumptions
+- identify failure modes early
+- validate non-functional constraints
+- stress-test designs before implementation
+- prevent idea swarm chaos
+
+This is **not parallel brainstorming**.
+It is **sequential design review with enforced roles**.
+
+---
+
+## Operating Model
+
+- One agent designs.
+- Other agents review.
+- No agent may exceed its mandate.
+- Creativity is centralized; critique is distributed.
+- Decisions are explicit and logged.
+
+The process is **gated** and **terminates by design**.
+
+---
+
+## Agent Roles (Non-Negotiable)
+
+Each agent operates under a **hard scope limit**.
+
+### 1️⃣ Primary Designer (Lead Agent)
+
+**Role:**
+- Owns the design
+- Runs the standard `brainstorming` skill
+- Maintains the Decision Log
+
+**May:**
+- Ask clarification questions
+- Propose designs and alternatives
+- Revise designs based on feedback
+
+**May NOT:**
+- Self-approve the final design
+- Ignore reviewer objections
+- Invent requirements post-lock
+
+---
+
+### 2️⃣ Skeptic / Challenger Agent
+
+**Role:**
+- Assume the design will fail
+- Identify weaknesses and risks
+
+**May:**
+- Question assumptions
+- Identify edge cases
+- Highlight ambiguity or overconfidence
+- Flag YAGNI violations
+
+**May NOT:**
+- Propose new features
+- Redesign the system
+- Offer alternative architectures
+
+Prompting guidance:
+> “Assume this design fails in production. Why?”
+
+---
+
+### 3️⃣ Constraint Guardian Agent
+
+**Role:**
+- Enforce non-functional and real-world constraints
+
+Focus areas:
+- performance
+- scalability
+- reliability
+- security & privacy
+- maintainability
+- operational cost
+
+**May:**
+- Reject designs that violate constraints
+- Request clarification of limits
+
+**May NOT:**
+- Debate product goals
+- Suggest feature changes
+- Optimize beyond stated requirements
+
+---
+
+### 4️⃣ User Advocate Agent
+
+**Role:**
+- Represent the end user
+
+Focus areas:
+- cognitive load
+- usability
+- clarity of flows
+- error handling from user perspective
+- mismatch between intent and experience
+
+**May:**
+- Identify confusing or misleading aspects
+- Flag poor defaults or unclear behavior
+
+**May NOT:**
+- Redesign architecture
+- Add features
+- Override stated user goals
+
+---
+
+### 5️⃣ Integrator / Arbiter Agent
+
+**Role:**
+- Resolve conflicts
+- Finalize decisions
+- Enforce exit criteria
+
+**May:**
+- Accept or reject objections
+- Require design revisions
+- Declare the design complete
+
+**May NOT:**
+- Invent new ideas
+- Add requirements
+- Reopen locked decisions without cause
+
+---
+
+## The Process
+
+### Phase 1 — Single-Agent Design
+
+1. Primary Designer runs the **standard `brainstorming` skill**
+2. Understanding Lock is completed and confirmed
+3. Initial design is produced
+4. Decision Log is started
+
+No other agents participate yet.
+
+---
+
+### Phase 2 — Structured Review Loop
+
+Agents are invoked **one at a time**, in the following order:
+
+1. Skeptic / Challenger
+2. Constraint Guardian
+3. User Advocate
+
+For each reviewer:
+- Feedback must be explicit and scoped
+- Objections must reference assumptions or decisions
+- No new features may be introduced
+
+Primary Designer must:
+- Respond to each objection
+- Revise the design if required
+- Update the Decision Log
+
+---
+
+### Phase 3 — Integration & Arbitration
+
+The Integrator / Arbiter reviews:
+- the final design
+- the Decision Log
+- unresolved objections
+
+The Arbiter must explicitly decide:
+- which objections are accepted
+- which are rejected (with rationale)
+
+---
+
+## Decision Log (Mandatory Artifact)
+
+The Decision Log must record:
+
+- Decision made
+- Alternatives considered
+- Objections raised
+- Resolution and rationale
+
+No design is considered valid without a completed log.
+
+---
+
+## Exit Criteria (Hard Stop)
+
+You may exit multi-agent brainstorming **only when all are true**:
+
+- Understanding Lock was completed
+- All reviewer agents have been invoked
+- All objections are resolved or explicitly rejected
+- Decision Log is complete
+- Arbiter has declared the design acceptable
+- 
+If any criterion is unmet:
+- Continue review
+- Do NOT proceed to implementation
+If this skill was invoked by a routing or orchestration layer, you MUST report the final disposition explicitly as one of: APPROVED, REVISE, or REJECT, with a brief rationale.
+---
+
+## Failure Modes This Skill Prevents
+
+- Idea swarm chaos
+- Hallucinated consensus
+- Overconfident single-agent designs
+- Hidden assumptions
+- Premature implementation
+- Endless debate
+
+---
+
+## Key Principles
+
+- One designer, many reviewers
+- Creativity is centralized
+- Critique is constrained
+- Decisions are explicit
+- Process must terminate
+
+---
+
+## Final Reminder
+
+This skill exists to answer one question with confidence:
+
+> “If this design fails, did we do everything reasonable to catch it early?”
+
+If the answer is unclear, **do not exit this skill**.
+

package/skills/neon-postgres/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: neon-postgres
+description: "Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres serverless."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Neon Postgres
+
+## Patterns
+
+### Prisma with Neon Connection
+
+Configure Prisma for Neon with connection pooling.
+
+Use two connection strings:
+- DATABASE_URL: Pooled connection for Prisma Client
+- DIRECT_URL: Direct connection for Prisma Migrate
+
+The pooled connection uses PgBouncer for up to 10K connections.
+Direct connection required for migrations (DDL operations).
+
+
+### Drizzle with Neon Serverless Driver
+
+Use Drizzle ORM with Neon's serverless HTTP driver for
+edge/serverless environments.
+
+Two driver options:
+- neon-http: Single queries over HTTP (fastest for one-off queries)
+- neon-serverless: WebSocket for transactions and sessions
+
+
+### Connection Pooling with PgBouncer
+
+Neon provides built-in connection pooling via PgBouncer.
+
+Key limits:
+- Up to 10,000 concurrent connections to pooler
+- Connections still consume underlying Postgres connections
+- 7 connections reserved for Neon superuser
+
+Use pooled endpoint for application, direct for migrations.
+
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | See docs |
+| Issue | high | See docs |
+| Issue | high | See docs |
+| Issue | medium | See docs |
+| Issue | medium | See docs |
+| Issue | low | See docs |
+| Issue | medium | See docs |
+| Issue | high | See docs |

package/skills/nextjs-supabase-auth/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: nextjs-supabase-auth
+description: "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Next.js + Supabase Auth
+
+You are an expert in integrating Supabase Auth with Next.js App Router.
+You understand the server/client boundary, how to handle auth in middleware,
+Server Components, Client Components, and Server Actions.
+
+Your core principles:
+1. Use @supabase/ssr for App Router integration
+2. Handle tokens in middleware for protected routes
+3. Never expose auth tokens to client unnecessarily
+4. Use Server Actions for auth operations when possible
+5. Understand the cookie-based session flow
+
+## Capabilities
+
+- nextjs-auth
+- supabase-auth-nextjs
+- auth-middleware
+- auth-callback
+
+## Requirements
+
+- nextjs-app-router
+- supabase-backend
+
+## Patterns
+
+### Supabase Client Setup
+
+Create properly configured Supabase clients for different contexts
+
+### Auth Middleware
+
+Protect routes and refresh sessions in middleware
+
+### Auth Callback Route
+
+Handle OAuth callback and exchange code for session
+
+## Anti-Patterns
+
+### ❌ getSession in Server Components
+
+### ❌ Auth State in Client Without Listener
+
+### ❌ Storing Tokens Manually
+
+## Related Skills
+
+Works well with: `nextjs-app-router`, `supabase-backend`

package/skills/nosql-expert/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: nosql-expert
+description: "Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems."
+---
+
+# NoSQL Expert Patterns (Cassandra & DynamoDB)
+
+## Overview
+
+This skill provides professional mental models and design patterns for **distributed wide-column and key-value stores** (specifically Apache Cassandra and Amazon DynamoDB).
+
+Unlike SQL (where you model data entities), or document stores (like MongoDB), these distributed systems require you to **model your queries first**.
+
+## When to Use
+
+- **Designing for Scale**: Moving beyond simple single-node databases to distributed clusters.
+- **Technology Selection**: Evaluating or using **Cassandra**, **ScyllaDB**, or **DynamoDB**.
+- **Performance Tuning**: Troubleshooting "hot partitions" or high latency in existing NoSQL systems.
+- **Microservices**: Implementing "database-per-service" patterns where highly optimized reads are required.
+
+## The Mental Shift: SQL vs. Distributed NoSQL
+
+| Feature | SQL (Relational) | Distributed NoSQL (Cassandra/DynamoDB) |
+| :--- | :--- | :--- |
+| **Data modeling** | Model Entities + Relationships | Model **Queries** (Access Patterns) |
+| **Joins** | CPU-intensive, at read time | **Pre-computed** (Denormalized) at write time |
+| **Storage cost** | Expensive (minimize duplication) | Cheap (duplicate data for read speed) |
+| **Consistency** | ACID (Strong) | **BASE (Eventual)** / Tunable |
+| **Scalability** | Vertical (Bigger machine) | **Horizontal** (More nodes/shards) |
+
+> **The Golden Rule:** In SQL, you design the data model to answer *any* query. In NoSQL, you design the data model to answer *specific* queries efficiently.
+
+## Core Design Patterns
+
+### 1. Query-First Modeling (Access Patterns)
+
+You typically cannot "add a query later" without migration or creating a new table/index.
+
+**Process:**
+1.  **List all Entities** (User, Order, Product).
+2.  **List all Access Patterns** ("Get User by Email", "Get Orders by User sorted by Date").
+3.  **Design Table(s)** specifically to serve those patterns with a single lookup.
+
+### 2. The Partition Key is King
+
+Data is distributed across physical nodes based on the **Partition Key (PK)**.
+-   **Goal:** Even distribution of data and traffic.
+-   **Anti-Pattern:** Using a low-cardinality PK (e.g., `status="active"` or `gender="m"`) creates **Hot Partitions**, limiting throughput to a single node's capacity.
+-   **Best Practice:** Use high-cardinality keys (User IDs, Device IDs, Composite Keys).
+
+### 3. Clustering / Sort Keys
+
+Within a partition, data is sorted on disk by the **Clustering Key (Cassandra)** or **Sort Key (DynamoDB)**.
+-   This allows for efficient **Range Queries** (e.g., `WHERE user_id=X AND date > Y`).
+-   It effectively pre-sorts your data for specific retrieval requirements.
+
+### 4. Single-Table Design (Adjacency Lists)
+
+*Primary use: DynamoDB (but concepts apply elsewhere)*
+
+Storing multiple entity types in one table to enable pre-joined reads.
+
+| PK (Partition) | SK (Sort) | Data Fields... |
+| :--- | :--- | :--- |
+| `USER#123` | `PROFILE` | `{ name: "Ian", email: "..." }` |
+| `USER#123` | `ORDER#998` | `{ total: 50.00, status: "shipped" }` |
+| `USER#123` | `ORDER#999` | `{ total: 12.00, status: "pending" }` |
+
+-   **Query:** `PK="USER#123"`
+-   **Result:** Fetches User Profile AND all Orders in **one network request**.
+
+### 5. Denormalization & Duplication
+
+Don't be afraid to store the same data in multiple tables to serve different query patterns.
+-   **Table A:** `users_by_id` (PK: uuid)
+-   **Table B:** `users_by_email` (PK: email)
+
+*Trade-off: You must manage data consistency across tables (often using eventual consistency or batch writes).*
+
+## Specific Guidance
+
+### Apache Cassandra / ScyllaDB
+
+-   **Primary Key Structure:** `((Partition Key), Clustering Columns)`
+-   **No Joins, No Aggregates:** Do not try to `JOIN` or `GROUP BY`. Pre-calculate aggregates in a separate counter table.
+-   **Avoid `ALLOW FILTERING`:** If you see this in production, your data model is wrong. It implies a full cluster scan.
+-   **Writes are Cheap:** Inserts and Updates are just appends to the LSM tree. Don't worry about write volume as much as read efficiency.
+-   **Tombstones:** Deletes are expensive markers. Avoid high-velocity delete patterns (like queues) in standard tables.
+
+### AWS DynamoDB
+
+-   **GSI (Global Secondary Index):** Use GSIs to create alternative views of your data (e.g., "Search Orders by Date" instead of by User).
+    -   *Note:* GSIs are eventually consistent.
+-   **LSI (Local Secondary Index):** Sorts data differently *within* the same partition. Must be created at table creation time.
+-   **WCU / RCU:** Understand capacity modes. Single-table design helps optimize consumed capacity units.
+-   **TTL:** Use Time-To-Live attributes to automatically expire old data (free delete) without creating tombstones.
+
+## Expert Checklist
+
+Before finalizing your NoSQL schema:
+
+-   [ ] **Access Pattern Coverage:** Does every query pattern map to a specific table or index?
+-   [ ] **Cardinality Check:** Does the Partition Key have enough unique values to spread traffic evenly?
+-   [ ] **Split Partition Risk:** For any single partition (e.g., a single user's orders), will it grow indefinitely? (If > 10GB, you need to "shard" the partition, e.g., `USER#123#2024-01`).
+-   [ ] **Consistency Requirement:** Can the application tolerate eventual consistency for this read pattern?
+
+## Common Anti-Patterns
+
+❌ **Scatter-Gather:** Querying *all* partitions to find one item (Scan).
+❌ **Hot Keys:** Putting all "Monday" data into one partition.
+❌ **Relational Modeling:** Creating `Author` and `Book` tables and trying to join them in code. (Instead, embed Book summaries in Author, or duplicate Author info in Books).