cfsa-antigravity 1.0.0

package/template/.agent/skills/database-schema-design/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: database-schema-design
+description: Design database schemas with normalization, relationships, and constraints. Use when creating new database schemas, designing tables, or planning data models for PostgreSQL and MySQL.
+---
+
+# Database Schema Design
+
+## Overview
+
+Design scalable, normalized database schemas with proper relationships, constraints, and data types. Includes normalization techniques, relationship patterns, and constraint strategies.
+
+## When to Use
+
+- New database schema design
+- Data model planning
+- Table structure definition
+- Relationship design (1:1, 1:N, N:N)
+- Normalization analysis
+- Constraint and trigger planning
+- Performance optimization at schema level
+
+## Normalization Strategy
+
+### First Normal Form (1NF)
+
+**PostgreSQL - Eliminate Repeating Groups:**
+
+```sql
+-- NOT 1NF: repeating group in single column
+CREATE TABLE orders_bad (
+  id UUID PRIMARY KEY,
+  customer_name VARCHAR(255),
+  product_ids VARCHAR(255)  -- "1,2,3" - repeating group
+);
+
+-- 1NF: separate table for repeating data
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_name VARCHAR(255),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE order_items (
+  id UUID PRIMARY KEY,
+  order_id UUID NOT NULL,
+  product_id UUID NOT NULL,
+  quantity INTEGER NOT NULL,
+  FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
+);
+```
+
+### Second Normal Form (2NF)
+
+**PostgreSQL - Remove Partial Dependencies:**
+
+```sql
+-- NOT 2NF: non-key attribute depends on part of composite key
+CREATE TABLE enrollment_bad (
+  student_id UUID,
+  course_id UUID,
+  professor_name VARCHAR(255),  -- depends on course_id only
+  PRIMARY KEY (student_id, course_id)
+);
+
+-- 2NF: separate tables
+CREATE TABLE enrollments (
+  id UUID PRIMARY KEY,
+  student_id UUID NOT NULL,
+  course_id UUID NOT NULL,
+  FOREIGN KEY (student_id) REFERENCES students(id),
+  FOREIGN KEY (course_id) REFERENCES courses(id),
+  UNIQUE(student_id, course_id)
+);
+
+CREATE TABLE courses (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255),
+  professor_id UUID NOT NULL,
+  FOREIGN KEY (professor_id) REFERENCES professors(id)
+);
+```
+
+### Third Normal Form (3NF)
+
+**PostgreSQL - Remove Transitive Dependencies:**
+
+```sql
+-- NOT 3NF: transitive dependency (customer_city depends on customer_state)
+CREATE TABLE orders_bad (
+  id UUID PRIMARY KEY,
+  customer_city VARCHAR(100),
+  customer_state VARCHAR(50),
+  state_tax_rate DECIMAL(5,3)  -- depends on customer_state
+);
+
+-- 3NF: separate tables
+CREATE TABLE states (
+  id UUID PRIMARY KEY,
+  code VARCHAR(2) UNIQUE,
+  name VARCHAR(100),
+  tax_rate DECIMAL(5,3)
+);
+
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_city VARCHAR(100),
+  state_id UUID NOT NULL,
+  FOREIGN KEY (state_id) REFERENCES states(id)
+);
+```
+
+## Table Design Patterns
+
+### Entity-Relationship Patterns
+
+**PostgreSQL - One-to-Many:**
+
+```sql
+-- One user has many orders
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL,
+  order_date TIMESTAMP DEFAULT NOW(),
+  total DECIMAL(10,2),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  INDEX idx_user_id (user_id)
+);
+```
+
+**PostgreSQL - One-to-One:**
+
+```sql
+-- One user has one profile
+CREATE TABLE user_profiles (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID UNIQUE NOT NULL,
+  bio TEXT,
+  avatar_url VARCHAR(500),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+```
+
+**PostgreSQL - Many-to-Many:**
+
+```sql
+-- Students and courses (many-to-many)
+CREATE TABLE students (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255)
+);
+
+CREATE TABLE courses (
+  id UUID PRIMARY KEY,
+  title VARCHAR(255)
+);
+
+-- Junction table
+CREATE TABLE course_enrollments (
+  id UUID PRIMARY KEY,
+  student_id UUID NOT NULL,
+  course_id UUID NOT NULL,
+  enrolled_at TIMESTAMP DEFAULT NOW(),
+  FOREIGN KEY (student_id) REFERENCES students(id) ON DELETE CASCADE,
+  FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE,
+  UNIQUE(student_id, course_id)
+);
+```
+
+## Constraint Strategy
+
+**PostgreSQL - Data Integrity:**
+
+```sql
+-- NOT NULL constraints
+CREATE TABLE products (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  sku VARCHAR(100) NOT NULL,
+  price DECIMAL(10,2) NOT NULL
+);
+
+-- UNIQUE constraints
+ALTER TABLE products
+ADD CONSTRAINT unique_sku UNIQUE(sku);
+
+-- CHECK constraints
+ALTER TABLE products
+ADD CONSTRAINT price_positive CHECK (price > 0);
+
+ALTER TABLE orders
+ADD CONSTRAINT valid_status
+CHECK (status IN ('pending', 'processing', 'completed', 'cancelled'));
+
+-- DEFAULT values
+CREATE TABLE audit_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  table_name VARCHAR(100) NOT NULL,
+  operation VARCHAR(10) NOT NULL,
+  user_id UUID,
+  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## Data Type Selection
+
+**PostgreSQL - Optimal Data Types:**
+
+```sql
+CREATE TABLE users (
+  -- Identifiers
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- Text fields
+  email VARCHAR(255),          -- Fixed length for emails
+  name TEXT,                   -- Unbounded text
+  bio TEXT,
+
+  -- Numeric data
+  age SMALLINT,                -- 0-32767
+  balance DECIMAL(15,2),       -- Financial data (precise)
+  rating NUMERIC(3,1),         -- Range 0.0-9.9
+
+  -- Boolean
+  is_active BOOLEAN DEFAULT true,
+  email_verified BOOLEAN,
+
+  -- Dates and Times
+  birth_date DATE,
+  last_login TIMESTAMP WITH TIME ZONE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  -- JSON/Binary
+  metadata JSONB,
+  profile_image BYTEA,
+
+  -- Arrays (PostgreSQL specific)
+  tags TEXT[] DEFAULT ARRAY[]::TEXT[]
+);
+```
+
+**MySQL - Compatible Data Types:**
+
+```sql
+CREATE TABLE users (
+  id CHAR(36) PRIMARY KEY,       -- UUID as CHAR
+
+  email VARCHAR(255),
+  name VARCHAR(255),
+
+  age TINYINT UNSIGNED,
+  balance DECIMAL(15,2),
+
+  is_active BOOLEAN DEFAULT true,
+
+  birth_date DATE,
+  last_login TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  metadata JSON,
+
+  KEY idx_email (email)
+);
+```
+
+## Schema Evolution
+
+**PostgreSQL - Backward Compatible Changes:**
+
+```sql
+-- Add column with default
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+
+-- Add column for new feature
+ALTER TABLE orders
+ADD COLUMN notes TEXT DEFAULT '';
+
+-- Add constraint on new column
+ALTER TABLE orders
+ADD CONSTRAINT check_notes CHECK (LENGTH(notes) <= 500);
+
+-- Deprecate column safely
+ALTER TABLE users RENAME COLUMN old_field TO old_field_deprecated;
+```
+
+**MySQL - Schema Changes:**
+
+```sql
+-- Add column with default
+ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT '';
+
+-- Add multiple columns
+ALTER TABLE orders
+ADD COLUMN notes TEXT DEFAULT '',
+ADD COLUMN internal_status VARCHAR(50);
+
+-- Modify column
+ALTER TABLE users MODIFY COLUMN bio TEXT;
+```
+
+## Performance Considerations
+
+**PostgreSQL - Partitioning Large Tables:**
+
+```sql
+-- Partition by date range for time-series data
+CREATE TABLE events (
+  id UUID PRIMARY KEY,
+  user_id UUID NOT NULL,
+  event_type VARCHAR(100),
+  created_at TIMESTAMP NOT NULL
+) PARTITION BY RANGE (DATE_TRUNC('month', created_at));
+
+CREATE TABLE events_2024_01 PARTITION OF events
+FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
+```
+
+## Schema Design Checklist
+
+- Identify entities and relationships
+- Apply normalization rules (1NF, 2NF, 3NF)
+- Define primary keys for all tables
+- Create foreign keys for relationships
+- Add constraints for data integrity
+- Select appropriate data types
+- Plan indexes for common queries
+- Design for scalability (denormalization if needed)
+- Document table purposes and relationships
+- Plan for schema evolution
+
+## Common Pitfalls
+
+❌ Don't skip normalization for convenience
+❌ Don't use VARCHAR(MAX) for all text fields
+❌ Don't forget to add foreign key constraints
+❌ Don't use natural keys as primary keys
+❌ Don't store calculated values in base tables
+
+✅ DO use UUIDs or sequences for primary keys
+✅ DO normalize data appropriately
+✅ DO add CHECK constraints for data validity
+✅ DO create indexes on foreign keys
+✅ DO use TIMESTAMP for audit trails
+
+## Resources
+
+- [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html)
+- [MySQL Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html)
+- [Database Normalization Guide](https://en.wikipedia.org/wiki/Database_normalization)
+- [Draw.io](https://draw.io/) - Schema diagram tool
+
+## Persistence Map Interview
+
+This interview runs during `/create-prd-stack` Sub-steps A–E. It maps every feature to its query types, then selects the right store for each query type.
+
+### Sub-step A — Feature-to-Query Table
+
+Walk through every major feature in `vision.md` and ask: "What does this feature need to find, store, relate, and rank/search?"
+
+Build the following table:
+
+| Feature | Find | Store | Relate | Rank/Search |
+|---------|------|-------|--------|-------------|
+| (from vision.md) | … | … | … | … |
+
+Present and confirm the table with the user before proceeding to Sub-step B.
+
+### Sub-step B — Registry-First Skill Search
+
+Before presenting any store options, read `.agent/skills/find-skills/SKILL.md` and run `npx skills find [query type or store name]` for each query type that appeared in the table.
+
+If the registry returns a skill, install it first. The bundled skill library is a fallback only.
+
+### Sub-step C — Store Selection Per Query Type
+
+Present store options only for query types that appeared in the table:
+
+- Skip `DATABASE_VECTOR` if no Rank/Search requirement appeared.
+- Skip `DATABASE_GRAPH` if no Relate requirement appeared.
+
+Use constraint-first per-axis flow: constraint questions → filter → present → confirm.
+
+### Sub-step D — Bootstrap Per Confirmed Store
+
+For each confirmed store, fire bootstrap with its specific sub-key:
+
+- e.g., `DATABASE_PRIMARY=PostgreSQL`, `DATABASE_VECTOR=Qdrant`
+- One bootstrap call per sub-key.
+- Each confirmation appends to `{{DATABASE_SKILLS}}`.
+
+### Sub-step E — Write Persistence Map
+
+After all stores are confirmed, write to `docs/plans/architecture-draft.md` as a locked section titled `## Persistence Map`.
+
+Must include:
+- The feature-to-query table from Sub-step A
+- A mapping of each query type to its canonical store with rationale
+
+## Cross-Store Entity Consistency Protocol
+
+### Triggering Rule
+
+This protocol runs for every entity that spans more than one store.
+
+### The 4 Questions
+
+For each cross-store entity, answer the following in order:
+
+1. **Canonical ID** — Single identifier tying representations together. Must be the primary store's UUID stored as a property in every other store — never the graph store's or vector store's internal ID.
+
+2. **Creation sequence** — Which store is written first. Recovery mechanism for partial write failures (Saga pattern, compensating transaction, or async retry queue — name which).
+
+3. **Deletion cascade** — Cleanup order, mechanism (application-layer sequential deletes, DB-level triggers, or background job — name which).
+
+4. **Read strategy** — Whether a read requires data from multiple stores. Name the application-layer join pattern explicitly.
+
+### Skill Instruction
+
+Read all skills in `{{DATABASE_SKILLS}}` for advice on each store's transaction semantics and consistency guarantees before completing this step.
+
+### Output
+
+Write the completed cross-store consistency table to `architecture-draft.md` as part of the `## Data Strategy` section.

package/template/.agent/skills/deployment-procedures/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: deployment-procedures
+description: Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Deployment Procedures
+
+> Deployment principles and decision-making for safe production releases.
+> **Learn to THINK, not memorize scripts.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **deployment principles**, not bash scripts to copy.
+
+- Every deployment is unique
+- Understand the WHY behind each step
+- Adapt procedures to your platform
+
+---
+
+## 1. Platform Selection
+
+### Decision Tree
+
+```
+What are you deploying?
+│
+├── Static site / JAMstack
+│   └── Vercel, Netlify, Cloudflare Pages
+│
+├── Simple web app
+│   ├── Managed → Railway, Render, Fly.io
+│   └── Control → VPS + PM2/Docker
+│
+├── Microservices
+│   └── Container orchestration
+│
+└── Serverless
+    └── Edge functions, Lambda
+```
+
+### Each Platform Has Different Procedures
+
+| Platform | Deployment Method |
+|----------|------------------|
+| **Vercel/Netlify** | Git push, auto-deploy |
+| **Railway/Render** | Git push or CLI |
+| **VPS + PM2** | SSH + manual steps |
+| **Docker** | Image push + orchestration |
+| **Kubernetes** | kubectl apply |
+
+---
+
+## 2. Pre-Deployment Principles
+
+### The 4 Verification Categories
+
+| Category | What to Check |
+|----------|--------------|
+| **Code Quality** | Tests passing, linting clean, reviewed |
+| **Build** | Production build works, no warnings |
+| **Environment** | Env vars set, secrets current |
+| **Safety** | Backup done, rollback plan ready |
+
+### Pre-Deployment Checklist
+
+- [ ] All tests passing
+- [ ] Code reviewed and approved
+- [ ] Production build successful
+- [ ] Environment variables verified
+- [ ] Database migrations ready (if any)
+- [ ] Rollback plan documented
+- [ ] Team notified
+- [ ] Monitoring ready
+
+---
+
+## 3. Deployment Workflow Principles
+
+### The 5-Phase Process
+
+```
+1. PREPARE
+   └── Verify code, build, env vars
+
+2. BACKUP
+   └── Save current state before changing
+
+3. DEPLOY
+   └── Execute with monitoring open
+
+4. VERIFY
+   └── Health check, logs, key flows
+
+5. CONFIRM or ROLLBACK
+   └── All good? Confirm. Issues? Rollback.
+```
+
+### Phase Principles
+
+| Phase | Principle |
+|-------|-----------|
+| **Prepare** | Never deploy untested code |
+| **Backup** | Can't rollback without backup |
+| **Deploy** | Watch it happen, don't walk away |
+| **Verify** | Trust but verify |
+| **Confirm** | Have rollback trigger ready |
+
+---
+
+## 4. Post-Deployment Verification
+
+### What to Verify
+
+| Check | Why |
+|-------|-----|
+| **Health endpoint** | Service is running |
+| **Error logs** | No new errors |
+| **Key user flows** | Critical features work |
+| **Performance** | Response times acceptable |
+
+### Verification Window
+
+- **First 5 minutes**: Active monitoring
+- **15 minutes**: Confirm stable
+- **1 hour**: Final verification
+- **Next day**: Review metrics
+
+---
+
+## 5. Rollback Principles
+
+### When to Rollback
+
+| Symptom | Action |
+|---------|--------|
+| Service down | Rollback immediately |
+| Critical errors | Rollback |
+| Performance >50% degraded | Consider rollback |
+| Minor issues | Fix forward if quick |
+
+### Rollback Strategy by Platform
+
+| Platform | Rollback Method |
+|----------|----------------|
+| **Vercel/Netlify** | Redeploy previous commit |
+| **Railway/Render** | Rollback in dashboard |
+| **VPS + PM2** | Restore backup, restart |
+| **Docker** | Previous image tag |
+| **K8s** | kubectl rollout undo |
+
+### Rollback Principles
+
+1. **Speed over perfection**: Rollback first, debug later
+2. **Don't compound errors**: One rollback, not multiple changes
+3. **Communicate**: Tell team what happened
+4. **Post-mortem**: Understand why after stable
+
+---
+
+## 6. Zero-Downtime Deployment
+
+### Strategies
+
+| Strategy | How It Works |
+|----------|--------------|
+| **Rolling** | Replace instances one by one |
+| **Blue-Green** | Switch traffic between environments |
+| **Canary** | Gradual traffic shift |
+
+### Selection Principles
+
+| Scenario | Strategy |
+|----------|----------|
+| Standard release | Rolling |
+| High-risk change | Blue-green (easy rollback) |
+| Need validation | Canary (test with real traffic) |
+
+---
+
+## 7. Emergency Procedures
+
+### Service Down Priority
+
+1. **Assess**: What's the symptom?
+2. **Quick fix**: Restart if unclear
+3. **Rollback**: If restart doesn't help
+4. **Investigate**: After stable
+
+### Investigation Order
+
+| Check | Common Issues |
+|-------|--------------|
+| **Logs** | Errors, exceptions |
+| **Resources** | Disk full, memory |
+| **Network** | DNS, firewall |
+| **Dependencies** | Database, APIs |
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Deploy on Friday | Deploy early in week |
+| Rush deployment | Follow the process |
+| Skip staging | Always test first |
+| Deploy without backup | Backup before deploy |
+| Walk away after deploy | Monitor for 15+ min |
+| Multiple changes at once | One change at a time |
+
+---
+
+## 9. Decision Checklist
+
+Before deploying:
+
+- [ ] **Platform-appropriate procedure?**
+- [ ] **Backup strategy ready?**
+- [ ] **Rollback plan documented?**
+- [ ] **Monitoring configured?**
+- [ ] **Team notified?**
+- [ ] **Time to monitor after?**
+
+---
+
+## 10. Best Practices
+
+1. **Small, frequent deploys** over big releases
+2. **Feature flags** for risky changes
+3. **Automate** repetitive steps
+4. **Document** every deployment
+5. **Review** what went wrong after issues
+6. **Test rollback** before you need it
+
+---
+
+> **Remember:** Every deployment is a risk. Minimize risk through preparation, not speed.