cfsa-antigravity 1.0.0

package/template/.agent/skills/migration-management/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: database-migration-management
+description: Manage database migrations and schema versioning. Use when planning migrations, version control, rollback strategies, or data transformations in PostgreSQL and MySQL.
+---
+
+# Database Migration Management
+
+## Overview
+
+Implement robust database migration systems with version control, rollback capabilities, and data transformation strategies. Includes migration frameworks and production deployment patterns.
+
+## When to Use
+
+- Schema versioning and evolution
+- Data transformations and cleanup
+- Adding/removing tables and columns
+- Index creation and optimization
+- Migration testing and validation
+- Rollback planning and execution
+- Multi-environment deployments
+
+## Migration Framework Setup
+
+### PostgreSQL - Schema Versioning
+
+```sql
+-- Create migrations tracking table
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INTEGER,
+  checksum VARCHAR(64)
+);
+
+-- Create migration log table
+CREATE TABLE migration_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  version BIGINT NOT NULL,
+  status VARCHAR(20) NOT NULL,
+  error_message TEXT,
+  rolled_back_at TIMESTAMP,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Function to record migration
+CREATE OR REPLACE FUNCTION record_migration(
+  p_version BIGINT,
+  p_name VARCHAR,
+  p_duration_ms INTEGER
+) RETURNS void AS $$
+BEGIN
+  INSERT INTO schema_migrations (version, name, duration_ms)
+  VALUES (p_version, p_name, p_duration_ms)
+  ON CONFLICT (version) DO UPDATE
+  SET executed_at = CURRENT_TIMESTAMP;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### MySQL - Migration Tracking
+
+```sql
+-- Create migrations table for MySQL
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INT,
+  checksum VARCHAR(64)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Migration status table
+CREATE TABLE migration_status (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  version BIGINT NOT NULL,
+  status ENUM('pending', 'completed', 'failed', 'rolled_back'),
+  error_message TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+## Common Migration Patterns
+
+### Adding Columns
+
+**PostgreSQL - Safe Column Addition:**
+
+```sql
+-- Migration: 20240115_001_add_phone_to_users.sql
+
+-- Add column with default (non-blocking)
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '';
+
+-- Add constraint after population
+ALTER TABLE users
+ADD CONSTRAINT phone_format
+CHECK (phone = '' OR phone ~ '^\+?[0-9\-\(\)]{10,}$');
+
+-- Create index
+CREATE INDEX CONCURRENTLY idx_users_phone ON users(phone);
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_users_phone;
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+**MySQL - Column Addition:**
+
+```sql
+-- Migration: 20240115_001_add_phone_to_users.sql
+
+-- Add column with ALTER
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '',
+ADD INDEX idx_phone (phone);
+
+-- Rollback:
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+### Renaming Columns
+
+**PostgreSQL - Column Rename:**
+
+```sql
+-- Migration: 20240115_002_rename_user_name_columns.sql
+
+-- Rename columns
+ALTER TABLE users RENAME COLUMN user_name TO full_name;
+ALTER TABLE users RENAME COLUMN user_email TO email_address;
+
+-- Update indexes
+REINDEX TABLE users;
+
+-- Rollback:
+-- ALTER TABLE users RENAME COLUMN email_address TO user_email;
+-- ALTER TABLE users RENAME COLUMN full_name TO user_name;
+```
+
+### Creating Indexes Non-blocking
+
+**PostgreSQL - Concurrent Index Creation:**
+
+```sql
+-- Migration: 20240115_003_add_performance_indexes.sql
+
+-- Create indexes without blocking writes
+CREATE INDEX CONCURRENTLY idx_orders_user_created
+ON orders(user_id, created_at DESC);
+
+CREATE INDEX CONCURRENTLY idx_products_category_active
+ON products(category_id)
+WHERE active = true;
+
+-- Verify index creation
+SELECT schemaname, tablename, indexname, idx_scan
+FROM pg_stat_user_indexes
+WHERE indexname LIKE 'idx_%';
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_orders_user_created;
+-- DROP INDEX CONCURRENTLY idx_products_category_active;
+```
+
+**MySQL - Online Index Creation:**
+
+```sql
+-- Migration: 20240115_003_add_performance_indexes.sql
+
+-- Create indexes with ALGORITHM=INPLACE and LOCK=NONE
+ALTER TABLE orders
+ADD INDEX idx_user_created (user_id, created_at),
+ALGORITHM=INPLACE, LOCK=NONE;
+
+-- Monitor progress
+SELECT * FROM INFORMATION_SCHEMA.PROCESSLIST
+WHERE INFO LIKE 'ALTER TABLE%';
+```
+
+### Data Transformations
+
+**PostgreSQL - Data Cleanup Migration:**
+
+```sql
+-- Migration: 20240115_004_normalize_email_addresses.sql
+
+-- Normalize existing email addresses
+UPDATE users
+SET email = LOWER(TRIM(email))
+WHERE email != LOWER(TRIM(email));
+
+-- Remove duplicates by keeping latest
+DELETE FROM users
+WHERE id NOT IN (
+  SELECT DISTINCT ON (LOWER(email)) id
+  FROM users
+  ORDER BY LOWER(email), created_at DESC
+);
+
+-- Rollback: Restore from backup (no safe rollback for data changes)
+```
+
+**MySQL - Bulk Data Update:**
+
+```sql
+-- Migration: 20240115_004_update_product_categories.sql
+
+-- Update multiple rows with JOIN
+UPDATE products p
+JOIN category_mapping cm ON p.old_category = cm.old_name
+SET p.category_id = cm.new_category_id
+WHERE p.old_category IS NOT NULL;
+
+-- Verify update
+SELECT COUNT(*) as updated_count
+FROM products
+WHERE category_id IS NOT NULL;
+```
+
+### Table Structure Changes
+
+**PostgreSQL - Alter Table Migration:**
+
+```sql
+-- Migration: 20240115_005_modify_order_columns.sql
+
+-- Add new column
+ALTER TABLE orders
+ADD COLUMN status_updated_at TIMESTAMP;
+
+-- Add constraint
+ALTER TABLE orders
+ADD CONSTRAINT valid_status
+CHECK (status IN ('pending', 'processing', 'completed', 'cancelled'));
+
+-- Set default for existing records
+UPDATE orders
+SET status_updated_at = updated_at
+WHERE status_updated_at IS NULL;
+
+-- Make column NOT NULL
+ALTER TABLE orders
+ALTER COLUMN status_updated_at SET NOT NULL;
+
+-- Rollback:
+-- ALTER TABLE orders DROP COLUMN status_updated_at;
+-- ALTER TABLE orders DROP CONSTRAINT valid_status;
+```
+
+## Testing Migrations
+
+**PostgreSQL - Test in Transaction:**
+
+```sql
+-- Test migration in transaction (will be rolled back)
+BEGIN;
+
+-- Run migration statements
+ALTER TABLE users ADD COLUMN test_column VARCHAR(255);
+
+-- Validate data
+SELECT COUNT(*) FROM users;
+SELECT COUNT(DISTINCT email) FROM users;
+
+-- Rollback if issues found
+ROLLBACK;
+
+-- Or commit if all good
+COMMIT;
+```
+
+**Validate Migration:**
+
+```sql
+-- Check migration was applied
+SELECT version, name, executed_at FROM schema_migrations
+WHERE version = 20240115005;
+
+-- Verify table structure
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = 'users'
+ORDER BY ordinal_position;
+```
+
+## Rollback Strategies
+
+**PostgreSQL - Bidirectional Migrations:**
+
+```sql
+-- Migration file: 20240115_006_add_user_status.sql
+
+-- ===== UP =====
+CREATE TYPE user_status AS ENUM ('active', 'suspended', 'deleted');
+ALTER TABLE users ADD COLUMN status user_status DEFAULT 'active';
+
+-- ===== DOWN =====
+-- ALTER TABLE users DROP COLUMN status;
+-- DROP TYPE user_status;
+```
+
+**Rollback Execution:**
+
+```sql
+-- Function to rollback to specific version
+CREATE OR REPLACE FUNCTION rollback_to_version(p_target_version BIGINT)
+RETURNS TABLE (version BIGINT, name VARCHAR, status VARCHAR) AS $$
+BEGIN
+  -- Execute down migrations in reverse order
+  RETURN QUERY
+  SELECT m.version, m.name, 'rolled_back'::VARCHAR
+  FROM schema_migrations m
+  WHERE m.version > p_target_version
+  ORDER BY m.version DESC;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+## Production Deployment
+
+**Safe Migration Checklist:**
+
+- Test migration on production-like database
+- Verify backup exists before migration
+- Schedule during low-traffic window
+- Monitor table locks and long-running queries
+- Have rollback plan ready
+- Test rollback procedure
+- Document all changes
+- Run in transaction when possible
+- Verify data integrity after migration
+- Update application code coordinated with migration
+
+**PostgreSQL - Long Transaction Safety:**
+
+```sql
+-- Use statement timeout to prevent hanging migrations
+SET statement_timeout = '30min';
+
+-- Use lock timeout to prevent deadlocks
+SET lock_timeout = '5min';
+
+-- Run migration with timeouts
+ALTER TABLE large_table
+ADD COLUMN new_column VARCHAR(255),
+ALGORITHM='INPLACE';
+```
+
+## Migration Examples
+
+**Combined Migration - Multiple Changes:**
+
+```sql
+-- Migration: 20240115_007_refactor_user_tables.sql
+
+BEGIN;
+
+-- 1. Create new column with data from old column
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+UPDATE users SET full_name = first_name || ' ' || last_name;
+
+-- 2. Add indexes
+CREATE INDEX idx_users_full_name ON users(full_name);
+
+-- 3. Add new constraint
+ALTER TABLE users
+ADD CONSTRAINT email_unique UNIQUE(email);
+
+-- 4. Drop old columns (after verification)
+-- ALTER TABLE users DROP COLUMN first_name;
+-- ALTER TABLE users DROP COLUMN last_name;
+
+COMMIT;
+```
+
+## Resources
+
+- [Flyway - Java Migration Tool](https://flywaydb.org/)
+- [Liquibase - Database Changelog](https://www.liquibase.org/)
+- [Alembic - Python Migration](https://alembic.sqlalchemy.org/)
+- [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
+- [MySQL ALTER TABLE](https://dev.mysql.com/doc/refman/8.0/en/alter-table.html)

package/template/.agent/skills/minimalist-surgical-development/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: minimalist-surgical-development
+description: Use when editing an existing codebase and the goal is minimal, standard, and non-invasive changes - prioritizes simplest solution, standard libraries first, and surgical modification without unsolicited refactors
+---
+
+# Minimalist & Surgical Development
+
+## Overview
+
+**Code like Kent Beck.** This skill keeps changes small and conventional: solve the stated problem with the least code and the least disruption to existing structure.
+
+## Use when...
+
+- The request emphasizes “minimal changes”, “surgical fix”, “preserve structure”, “don’t refactor”
+- The task is to modify existing code rather than build from scratch
+- There is temptation to introduce new abstractions, frameworks, or large rewrites
+
+## Symptoms / keywords
+
+- “minimal”, “surgical”, “small diff”, “don’t touch unrelated”, “keep style”, “no refactor”, “standard library first”, “YAGNI”, “KISS”
+
+## Minimalist & Standard Code Generation
+
+- **Principle of Simplicity**: Always provide the most straightforward and minimalist solution possible. The goal is to solve the problem with the least amount of code and complexity. Avoid premature optimization or over-engineering.
+- **Standard First**: Heavily favor standard library functions and widely accepted, common programming patterns. Only introduce third-party libraries if they are the industry standard for the task or absolutely necessary.
+- **Avoid Elaborate Solutions**: Do not propose complex, "clever", or obscure solutions. Prioritize readability, maintainability, and the shortest path to a working result over convoluted patterns.
+- **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned.
+
+## Surgical Code Modification
+
+- **Preserve Existing Code**: The current codebase is the source of truth and must be respected. Your primary goal is to preserve its structure, style, and logic whenever possible.
+- **Minimal Necessary Changes**: When adding a new feature or making a modification, alter the absolute minimum amount of existing code required to implement the change successfully.
+- **Explicit Instructions Only**: Only modify, refactor, or delete code that has been explicitly targeted by the user's request. Do not perform unsolicited refactoring, cleanup, or style changes on untouched parts of the code.
+- **Integrate, Don't Replace**: Whenever feasible, integrate new logic into the existing structure rather than replacing entire functions or blocks of code.
+
+## Symbol-First Navigation (Serena MCP)
+
+When exploring code structure before making changes, prefer Serena MCP symbol tools over full-file reads:
+
+- **`get_symbols_overview`** - Fast summary of a file's structure (classes, functions, methods)
+- **`find_symbol`** - Locate specific code by name without reading entire files
+- **`find_referencing_symbols`** - Understand impact of changes by finding all call sites
+
+**Why symbol-first is minimalist:**
+- Reduces context pollution: see only the code you need
+- Identifies exact targets before editing: no guessing what to modify
+- Discovers existing patterns: find similar code to maintain consistency
+- Fast refactoring checks: verify changes won't break usages
+
+**When making edits, prefer symbol editing tools over file-based replacement:**
+- Use `insert_before_symbol` / `insert_after_symbol` for adding code
+- Use `replace_symbol_body` for rewriting function implementations
+- Use `replace_content` (file-based) only when editing small sections within a function
+
+See `serena-mcp-integration-guide.md` for detailed scenarios and examples.
+
+## Intelligent Tool Usage
+
+- **Use Tools When Necessary (via subagents)**: When a request requires external information or direct interaction with the environment, dispatch an appropriate subagent to use the necessary tools and return a cited Context Package. The orchestrator must not perform investigation/data-fetching I/O directly.
+- **Directly Edit Code When Requested (via subagents)**: If explicitly asked to modify/refactor/add code, dispatch an implementation subagent to apply the changes directly in the codebase. Avoid copy/paste snippets unless requested; default to a small, surgical diff implemented by the subagent.
+- **Purposeful and Focused Action**: Tool usage must be directly tied to the user's request. Do not perform unrelated searches or modifications. Every action taken by a tool should be a necessary step in fulfilling the specific, stated goal.
+- **Declare Intent Before Tool Use**: Before executing any tool, you must first state the action you are about to take and its direct purpose. This statement must be concise and immediately precede the tool call.
+
+## Quick checklist
+
+- Ensure a research subagent has read the relevant files (with citations) before any changes
+- Make the smallest diff that satisfies the requirement
+- Prefer existing utilities/abstractions over adding new ones
+- Avoid new dependencies unless clearly justified

package/template/.agent/skills/parallel-agents/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: parallel-agents
+description: Orchestrate concurrent analysis or implementation across independent domains. Use when a task can be decomposed into independent workstreams (e.g., via simultaneous tool calls or background processes) — spec writing, code review, security audit, feature implementation.
+---
+
+# Parallel Agents & Concurrent Tool Execution
+
+## Overview
+
+Some tasks are naturally parallelizable — they have independent domains that don't share state. As a highly-capable agent, you can drastically cut wall-clock time by leveraging **concurrent tool execution** (e.g., running multiple `view_file` calls, `grep_search` calls, or background terminal commands simultaneously) instead of investigating sequentially.
+
+**Core principle:** Parallelism is a scheduling optimization, not a quality shortcut. Every concurrent workstream follows the same quality standards as a sequential task.
+
+## When to Use
+
+- **Multi-surface implementation** — A slice has independent surfaces (DB, API, UI, admin) that don't share implementation logic
+- **Multi-domain analysis** — Security audit + performance review + accessibility audit on the same codebase
+- **Spec writing** — Multiple IA shards need specs written from the same architecture doc
+- **Code review** — Large PR touches independent subsystems
+- **Debugging** — Multiple independent failures (see `parallel-debugging` skill for the full protocol)
+
+## When NOT to Use
+
+- Tasks share mutable state or edit the same files
+- Later tasks depend on output of earlier tasks (use sequential pipeline instead)
+- You don't fully understand the task decomposition yet (investigate first)
+- Simple task that one agent handles in < 5 minutes
+
+## The Protocol
+
+### 1. Decompose
+
+Break the task into independent domains. Each domain must satisfy ALL of:
+
+| Requirement | Why |
+|-------------|-----|
+| **Independent files** — workstreams do not mutate the same file | Prevents race conditions and tool call hash mismatches |
+| **Independent state** — no shared mutable resources (DB tables, caches) | Prevents race conditions |
+| **Self-contained context** — stream can run without waiting on another's output | Prevents blocking |
+| **Clear deliverable** — you can verify the stream's work in isolation | Prevents integration surprises |
+
+If any requirement fails → that domain can't be parallelized. Run it sequentially.
+
+### 2. Define Workstream Profiles
+
+Instead of giving yourself a single massive objective, explicitly define the scope for each concurrent stream conceptually:
+
+```markdown
+## Workstream: [Domain Name]
+### Scope
+[Exactly what this stream owns — files, features, concerns]
+
+### Context
+[Everything needed — paste relevant code, specs, error messages]
+
+### Constraints
+- Do NOT mutate files outside the defined scope
+- Follow rule: boundary-not-placeholder for cross-stream dependencies
+```
+
+**Scope quality rules:**
+- ✅ **Focused** — one clear problem domain
+- ✅ **Constrained** — explicit file/scope boundaries
+- ❌ **Shared Mutable State** — running `replace_file_content` on the same file concurrently will fail or corrupt data.
+
+### 3. Concurrent Execution
+
+Launch the workstreams simultaneously using your concurrent tool execution capabilities.
+For example, if testing and formatting code, you might run `npm run test` in one background terminal and `npx prettier --write` in another, checking the statuses of both instead of waiting for one to finish before starting the other.
+When making file edits, batch disjoint `replace_file_content` tool calls in the same turn.
+
+### 4. Synthesize
+
+After ALL concurrent streams yield results, synthesize them into a single coherent picture before proceeding:
+
+```markdown
+## Concurrent Synthesis
+
+### Task Summary
+[What was accomplished across all workstreams]
+
+### Findings by Domain
+| Domain | Finding/Result |
+|--------|----------------|
+| Stream 1 | [what was found] |
+| Stream 2 | [what was found] |
+
+### Consolidated Actions
+1. **Critical**: [From Stream X]
+2. **Important**: [From Stream Y]
+
+### Integration Verification
+- [ ] No file conflicts during concurrent editing
+- [ ] Full test suite passes
+- [ ] Changes reviewed for consistency
+```
+
+### 5. Verify Integration
+
+**Non-negotiable:** After merging all agent outputs:
+1. Run the full validation suite (not just individual agent tests)
+2. Check for contradictions between agent recommendations
+3. Verify no files were modified by multiple agents
+4. Spot-check agent work — agents can make systematic errors
+
+## Task Decomposition Archetypes
+
+These are suggested ways to slice concurrent workstreams:
+
+| Archetype | Domain Focus | Typical Sub-Skills |
+|-----------|--------------|-------------------|
+| **Security Review** | Vulnerabilities, RBAC, input validation | security-scanning, code-review |
+| **Test Quality** | Test coverage, edge cases | tdd-workflow |
+| **Backend Implementation** | API design, data layer | rest-api-design, surrealdb-expert |
+| **Frontend Implementation** | UI components, accessibility | frontend-design, accessibility |
+| **Performance Audit** | Bottlenecks, bundle size | web-performance-optimization |
+| **Documentation** | API docs, architecture docs | — |
+| **ACH Debugging** | Root cause investigation | systematic-debugging, parallel-debugging |
+
+## Integration with Kit
+
+- **With `parallel-feature-development`:** When making concurrent file edits, use the strict file ownership protocol to prevent tool call conflicts (e.g. failing `replace_file_content` because the file hash changed).
+- **With `session-continuity` Protocol 9:** When you claim both a `BE` and `FE` task concurrently, the `files:` blocks are your guarantee that you can execute edits simultaneously safely.
+- **With `boundary-not-placeholder`:** If a concurrent stream hits a missing dependency, use `// BOUNDARY:` stubs. Don't block the stream indefinitely.
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Concurrent edits to same file | Overwrites, hash mismatches | One stream per file strictly |
+| No synthesis step | Contradictory logic | Always synthesize before committing changes |
+| Shared dependencies not frozen | Build breaks unexpectedly | Use interface contracts first |
+
+## TDD-Order Dispatch (Slice Implementation)
+
+### Triggering Condition
+
+Enter parallel mode when the slice's tasks contain surface tags (`BE`, `FE`, `QA`). Proceed sequentially when no tags are found.
+
+### Core Principle
+
+> **Tests are the rock. Code is malleable.** Tests encode the acceptance criteria and must be comprehensive. Code adapts to pass tests, never the reverse.
+
+### 5-Phase Dispatch Table
+
+| Phase | Agent | Responsibility | Depends On |
+|-------|-------|----------------|------------|
+| 0 | Orchestrator | Contracts/schemas (untagged tasks) | — |
+| 1 | QA (RED) | Write comprehensive failing tests | Phase 0 |
+| 2 | BE + FE (parallel) | Write code to make tests pass | Phase 1 |
+| 3 | QA (GREEN) | Verify all tests pass, anti-cheat audit | Phase 2 |
+| 4 | Orchestrator | Iterative correction loop if needed | Phase 3 |
+
+### Dispatch Instructions
+
+1. **Untagged tasks first** — Contract/schema work runs sequentially by orchestrator (Phase 0) before any tagged dispatch.
+2. **QA-RED** — QA agent writes comprehensive failing tests for ALL acceptance criteria. Tests MUST fail. Read `.agent/skills/session-continuity/protocols/09-parallel-claim.md`. Every contract field and error type covered.
+3. **BE + FE parallel** — Code against tests and contracts simultaneously. Annotate spec-gap decisions with `// DECISION: [what and why]`.
+4. **QA-GREEN** — Re-verify all tests pass, anti-cheat check, add integration tests.
+5. **Iterative loop rule** — If QA-GREEN fails → re-dispatch BE/FE → QA-GREEN again → repeat until all pass.
+6. **File independence check** — Verify no two tagged tasks touch the same files before dispatching (prevents tool call hash mismatches).
+
+### Progress Logging
+
+Log each dispatch phase to `.agent/progress/slices/phase-NN-slice-NN.md` under `## Dispatch Log`.