cfsa-antigravity 3.0.2 → 3.1.0

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

@@ -0,0 +1,205 @@
+---
+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 any database paradigm.
+---
+
+# Database Schema Design
+
+## Overview
+
+Design scalable, well-structured database schemas with proper relationships, constraints, and data types. This skill covers universal data modeling principles. For paradigm-specific patterns, see references.
+
+## When to Use
+
+- New database schema design
+- Data model planning
+- Relationship design (1:1, 1:N, N:N, graph edges)
+- Normalization or denormalization analysis
+- Constraint and validation planning
+- Performance optimization at schema level
+- Cross-store entity consistency
+
+## Paradigm-Specific References
+
+After reading the methodology below, read the reference matching your surface's Databases column in the surface stack map (`.codex/instructions/tech-stack.md`):
+
+| Paradigm | Reference | Example Stores |
+|----------|-----------|----------------|
+| Relational | `references/relational.md` | PostgreSQL, MySQL, SQLite |
+| Document | `references/document.md` | MongoDB, Firestore, CouchDB |
+| Graph | `references/graph.md` | SurrealDB, Neo4j, ArangoDB |
+| Key-Value | `references/key-value.md` | Redis, DynamoDB, Memcached |
+
+---
+
+## Universal Data Modeling Principles
+
+### 1. Entity Identification
+
+Start with the domain:
+1. **Identify nouns** — these become entities/tables/collections
+2. **Identify relationships** — how entities connect
+3. **Identify attributes** — what data each entity holds
+4. **Identify cardinality** — one-to-one, one-to-many, many-to-many
+
+### 2. Normalization vs Denormalization
+
+**Normalization** reduces data duplication at the cost of join complexity:
+- **1NF** — Eliminate repeating groups (no arrays/CSVs in a single field)
+- **2NF** — Remove partial dependencies (every non-key attribute depends on the WHOLE key)
+- **3NF** — Remove transitive dependencies (non-key attributes don't depend on each other)
+
+**Denormalization** trades storage for read performance:
+- Embed frequently co-read data together
+- Pre-compute aggregates for dashboards
+- Duplicate data intentionally (with consistency strategy)
+
+**Decision framework:**
+- Write-heavy, consistency-critical → normalize
+- Read-heavy, latency-sensitive → denormalize
+- Mixed → normalize core, denormalize read models
+
+### 3. Relationship Patterns
+
+| Pattern | Relational | Document | Graph |
+|---------|-----------|----------|-------|
+| **One-to-One** | Foreign key with UNIQUE | Embed subdocument | Edge with cardinality constraint |
+| **One-to-Many** | Foreign key on child | Embed array OR reference | Edge from parent to children |
+| **Many-to-Many** | Junction/join table | Array of references on both sides | Direct edges |
+| **Hierarchical** | Self-referencing FK | Nested documents | Recursive graph traversal |
+
+### 4. Access Pattern Design
+
+Schema design is driven by how data is **queried**, not just how it's structured:
+
+1. **List your read queries** — what does the UI need to display?
+2. **List your write queries** — what creates/updates data?
+3. **Design schema to serve the reads** — not the other way around
+4. **Index for query patterns** — not for every possible query
+
+### 5. Constraint Strategy
+
+Every schema must enforce:
+- **Required fields** — NOT NULL / required validators
+- **Uniqueness** — unique constraints on natural keys (email, SKU, slug)
+- **Referential integrity** — foreign keys, references, or application-level checks
+- **Domain constraints** — CHECK constraints, enums, value ranges
+- **Cascade behavior** — what happens when parent is deleted (CASCADE, SET NULL, RESTRICT)
+
+### 6. ID Strategy
+
+| Strategy | When to Use |
+|----------|-------------|
+| **UUID v4** | Default choice. No ordering, globally unique, no collision |
+| **UUID v7** | When you need time-sortable UUIDs (better index performance) |
+| **Auto-increment** | Simple cases, single-database, non-distributed |
+| **ULID** | Time-sortable, lexicographically sortable, URL-safe |
+| **Natural key** | When domain provides a unique identifier (ISBN, SSN) — use with caution |
+
+---
+
+## Schema Design Checklist
+
+- [ ] Identify entities and relationships
+- [ ] Choose ID strategy
+- [ ] Apply normalization rules (or consciously denormalize with rationale)
+- [ ] Define primary keys for all entities
+- [ ] Create foreign keys / references for relationships
+- [ ] Add constraints for data integrity
+- [ ] Select appropriate data types
+- [ ] Plan indexes for common queries
+- [ ] Design for scalability
+- [ ] Document entity purposes and relationships
+- [ ] Plan for schema evolution
+
+## Common Pitfalls
+
+❌ Don't skip normalization for convenience
+❌ Don't use unbounded text types for all string fields
+❌ Don't forget referential integrity constraints
+❌ Don't use mutable natural keys as primary keys
+❌ Don't store computed values without a cache invalidation strategy
+❌ Don't design schema without knowing query patterns
+
+✅ DO use UUIDs or equivalent for primary keys
+✅ DO normalize data unless you have a measured performance reason not to
+✅ DO add validation constraints at the schema level
+✅ DO index foreign keys and common query fields
+✅ DO use timestamps for audit trails
+
+---
+
+## 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 `ideation-index.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 ideation-index.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 `.codex/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 adds a database skill to the Databases column of the relevant surface row in the surface stack map.
+
+### Sub-step E — Write Persistence Map
+
+After all stores are confirmed, write to `.memory/wiki/specs/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 database skills listed in the Databases column of the surface stack map (`.codex/instructions/tech-stack.md`) 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/.codex/skills/database-schema-design/references/relational.md

@@ -0,0 +1,228 @@
+# Relational Database Schema Patterns
+
+Paradigm-specific patterns for the `database-schema-design` skill. Read `SKILL.md` first for universal methodology.
+
+Covers: **PostgreSQL**, **MySQL**, **SQLite**
+
+---
+
+## Normalization Examples
+
+### First Normal Form (1NF) — 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) — Remove Partial Dependencies
+
+```sql
+-- 2NF: separate tables for partial deps
+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) — Remove Transitive Dependencies
+
+```sql
+-- 3NF: separate lookup 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)
+);
+```
+
+---
+
+## Relationship Patterns
+
+### One-to-Many
+
+```sql
+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
+);
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+```
+
+### One-to-One
+
+```sql
+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
+);
+```
+
+### Many-to-Many (Junction Table)
+
+```sql
+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
+
+```sql
+-- NOT NULL, UNIQUE, CHECK, DEFAULT
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  sku VARCHAR(100) NOT NULL UNIQUE,
+  price DECIMAL(10,2) NOT NULL CHECK (price > 0),
+  status VARCHAR(20) NOT NULL CHECK (status IN ('active', 'archived', 'draft'))
+);
+
+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
+
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255),
+  name TEXT,
+  age SMALLINT,
+  balance DECIMAL(15,2),       -- Financial data (precise)
+  is_active BOOLEAN DEFAULT true,
+  birth_date DATE,
+  last_login TIMESTAMP WITH TIME ZONE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSONB,
+  tags TEXT[] DEFAULT ARRAY[]::TEXT[]  -- PostgreSQL arrays
+);
+```
+
+### MySQL
+
+```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
+
+```sql
+-- Add column with default (backward compatible)
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+
+-- 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;
+```
+
+---
+
+## Performance: Partitioning
+
+```sql
+-- PostgreSQL: 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');
+```
+
+---
+
+## 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)

package/template/.codex/skills/decompose-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: decompose-architecture
+description: Decompose approved architecture design into IA shards and layered spec structure, then validate dependencies and tracking outputs
+parameters:
+  - name: architecture_doc
+    type: string
+    required: false
+    description: Optional explicit architecture-design file path; defaults to latest dated file
+---
+
+## Overview
+
+Runs decomposition in two shards: structure → validate.
+
+
+## Prerequisites
+
+1. Approved `.memory/wiki/specs/*-architecture-design.md` exists
+2. `.memory/wiki/specs/ideation/ideation-index.md` exists
+3. If surfaces include web/mobile/desktop, `.memory/wiki/specs/design-system.md` should exist before FE specification work
+
+## Step-by-Step
+
+### Step 0 — Architecture readiness and consistency gates
+
+1. Locate latest dated architecture design document if no explicit path is provided.
+2. Validate `**Status**: Approved` is present.
+3. Read ideation index and compare structural classification with architecture project type.
+4. If mismatch is detected: stop and require decision propagation/resolution before decomposition.
+
+### Step 1 — Domain boundary analysis
+
+1. Load architecture-mapping and shard-boundary analysis guidance.
+2. Walk ideation fractal structure to identify domain boundaries.
+3. Build boundary table and assign shard numbers (`00-*` foundation, then dependency order).
+4. Present decomposition proposal and require explicit approval.
+5. Write `.memory/wiki/specs/ia/decomposition-plan.md` immediately after approval.
+
+### Step 2 — Run structure shard
+
+Call skill: `decompose-architecture-structure`
+
+Expected outputs:
+- `.memory/wiki/specs/ia/*.md` shard skeletons (including mandatory `00-infrastructure.md`)
+- `.memory/wiki/specs/ia/index.md`
+- `.memory/wiki/specs/be/index.md`
+- `.memory/wiki/specs/fe/index.md`
+- `.memory/wiki/specs/index.md`
+
+### Step 3 — Run validate shard
+
+Call skill: `decompose-architecture-validate`
+
+Expected outputs:
+- deep dive skeletons under `.memory/wiki/specs/ia/deep-dives/`
+- shard type annotations and dependency validation results
+- updated feature ledger IA assignments (when ledger exists)
+- generated spec pipeline tracker
+
+## Completion Checklist
+
+- [ ] Architecture status and consistency gates passed
+- [ ] Domain boundaries approved and written
+- [ ] Structure shard completed
+- [ ] Validate shard completed
+- [ ] Review request issued for decomposition outputs
+- [ ] Next valid command recommendation emitted
+
+## Next Steps
+
+After explicit approval, the only valid next command is:
+- `/write-architecture-spec` (starting from the lowest-numbered pending shard)

package/template/.codex/skills/decompose-architecture-structure/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: decompose-architecture-structure
+description: Create decomposition directory structure, IA shard skeletons, and all required layer indexes from approved decomposition plan
+parameters:
+  - name: strict
+    type: boolean
+    required: false
+    description: If true, fail on any missing shard skeleton or index artifact
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. `.memory/wiki/specs/ia/decomposition-plan.md` exists
+2. Decomposition plan contains a populated domain boundary table
+
+## Step-by-Step
+
+### Step 1 — Validate decomposition plan input
+
+1. Verify decomposition plan exists and has `## Domain Boundary Table`.
+2. If missing or incomplete: stop and return control to parent decomposition workflow.
+
+### Step 2 — Create layer-aware structure
+
+1. Preserve layer-first structure:
+   - `.memory/wiki/specs/ia/`
+   - `.memory/wiki/specs/be/`
+   - `.memory/wiki/specs/fe/`
+2. For multi-surface projects, create surface subdirectories under `be/` and `fe/` only.
+3. Ensure each new surface directory includes `.gitkeep` and `README.md`.
+
+### Step 3 — Seed IA shard skeletons
+
+1. Create mandatory `.memory/wiki/specs/ia/00-infrastructure.md` first.
+2. Create one IA shard skeleton per decomposition-plan shard using decomposition templates.
+3. Seed initial sub-feature references from ideation fractal mapping logic.
+4. Verify all expected shard files exist and are non-empty.
+5. Enforce shard-count thresholds from boundary analysis guidance.
+
+### Step 4 — Coverage and index generation
+
+1. Run Must Have domain coverage check (each Must domain must map to at least one shard).
+2. Create `.memory/wiki/specs/ia/index.md`.
+3. Create `.memory/wiki/specs/be/index.md`.
+4. Create `.memory/wiki/specs/fe/index.md`.
+5. Create or update `.memory/wiki/specs/index.md` using single- or multi-surface template variant.
+
+## Completion Checklist
+
+- [ ] decomposition-plan input validated
+- [ ] layer-first structure prepared
+- [ ] 00-infrastructure shard created
+- [ ] all planned shard skeletons created
+- [ ] Must Have domain coverage check passed
+- [ ] IA/BE/FE/master indexes created
+
+## Next Steps
+
+- Run `decompose-architecture-validate`

package/template/.codex/skills/decompose-architecture-validate/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: decompose-architecture-validate
+description: Validate shard load/dependencies, create deep-dive skeletons, update ledger assignments, and generate pipeline tracker
+parameters:
+  - name: strict
+    type: boolean
+    required: false
+    description: If true, fail on any unresolved dependency or missing coverage
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. Structure shard completed
+2. IA shard skeletons and indexes exist
+
+## Step-by-Step
+
+### Step 1 — Proactive shard load pre-check
+
+1. Evaluate each shard against shard-load thresholds using ideation domain signals.
+2. Flag overloaded shards for split review before dependency validation.
+
+### Step 2 — Deep dive candidate generation
+
+1. For each shard marked `Needs Deep Dive`, create skeleton file under `.memory/wiki/specs/ia/deep-dives/`.
+2. Add deep-dive references to parent IA shard files and IA index entries.
+
+### Step 3 — Shard annotation and dependency graph validation
+
+1. Annotate preliminary shard document type per classification table.
+2. Validate dependency graph:
+   - no circular dependencies
+   - cross-cutting shard directionality holds
+   - deep-dive references exist
+3. Enforce Must Have feature coverage across IA shards.
+4. If shard splits are needed, update decomposition plan and re-run coverage check before proceeding.
+
+### Step 4 — Feature ledger IA assignment (conditional)
+
+1. If `.memory/wiki/specs/feature-ledger.md` exists, map features to IA shards.
+2. Populate IA shard + IA status columns.
+3. Run orphan detection and stop for resolution if orphans are present.
+
+### Step 5 — Generate spec pipeline tracker and request review
+
+1. Generate tracker using spec pipeline generation protocol.
+2. Present outputs for review:
+   - IA directory/indexes
+   - deep dives
+   - BE/FE indexes
+   - master index
+   - tracker
+3. Stop and wait for explicit approval.
+
+## Completion Checklist
+
+- [ ] shard-load pre-check completed
+- [ ] deep-dive candidates generated and referenced
+- [ ] shard type annotations added
+- [ ] dependency graph validated
+- [ ] Must Have coverage validated
+- [ ] feature ledger assignment updated (if ledger exists)
+- [ ] spec pipeline tracker generated
+- [ ] review requested and workflow paused
+
+## Next Steps
+
+After approval, the only valid next command is:
+- `/write-architecture-spec`