ag-cortex 0.1.0

package/.agent/skills/compound-docs/schema.yaml

@@ -0,0 +1,176 @@
+# CORA Documentation Schema
+# This schema MUST be validated before writing any documentation file
+
+required_fields:
+  module:
+    type: string
+    description: "Module/area of CORA (e.g., 'Email Processing', 'Brief System', 'Authentication')"
+    examples:
+      - "Email Processing"
+      - "Brief System"
+      - "Assistant"
+      - "Authentication"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date when this problem was solved (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error          # Rails, bundle, compilation errors
+      - test_failure         # Test failures, flaky tests
+      - runtime_error        # Exceptions, crashes during execution
+      - performance_issue    # Slow queries, memory issues, N+1 queries
+      - database_issue       # Migration, query, schema problems
+      - security_issue       # Authentication, authorization, XSS, SQL injection
+      - ui_bug               # Frontend, Stimulus, Turbo issues
+      - integration_issue    # External service, API integration problems
+      - logic_error          # Business logic bugs
+      - developer_experience # DX issues: workflow, tooling, seed data, dev setup
+      - workflow_issue       # Development process, missing steps, unclear practices
+      - best_practice        # Documenting patterns and practices to follow
+      - documentation_gap    # Missing or inadequate documentation
+    description: "Primary category of the problem"
+
+  component:
+    type: enum
+    values:
+      - rails_model          # ActiveRecord models
+      - rails_controller     # ActionController
+      - rails_view           # ERB templates, ViewComponent
+      - service_object       # Custom service classes
+      - background_job       # Sidekiq, Active Job
+      - database             # PostgreSQL, migrations, schema
+      - frontend_stimulus    # Stimulus JS controllers
+      - hotwire_turbo        # Turbo Streams, Turbo Drive
+      - email_processing     # Email handling, mailers
+      - brief_system         # Brief generation, summarization
+      - assistant            # AI assistant, prompts
+      - authentication       # Devise, user auth
+      - payments             # Stripe, billing
+      - development_workflow # Dev process, seed data, tooling
+      - testing_framework    # Test setup, fixtures, VCR
+      - documentation        # README, guides, inline docs
+      - tooling              # Scripts, generators, CLI tools
+    description: "CORA component involved"
+
+  symptoms:
+    type: array[string]
+    min_items: 1
+    max_items: 5
+    description: "Observable symptoms (error messages, visual issues, crashes)"
+    examples:
+      - "N+1 query detected in brief generation"
+      - "Brief emails not appearing in summary"
+      - "Turbo Stream response returns 404"
+
+  root_cause:
+    type: enum
+    values:
+      - missing_association  # Incorrect Rails associations
+      - missing_include      # Missing eager loading (N+1)
+      - missing_index        # Database performance issue
+      - wrong_api            # Using deprecated/incorrect Rails API
+      - scope_issue          # Incorrect query scope or filtering
+      - thread_violation     # Real-time unsafe operation
+      - async_timing         # Async/background job timing
+      - memory_leak          # Memory leak or excessive allocation
+      - config_error         # Configuration or environment issue
+      - logic_error          # Algorithm/business logic bug
+      - test_isolation       # Test isolation or fixture issue
+      - missing_validation   # Missing model validation
+      - missing_permission   # Authorization check missing
+      - missing_workflow_step # Skipped or undocumented workflow step
+      - inadequate_documentation # Missing or unclear documentation
+      - missing_tooling      # Lacking helper scripts or automation
+      - incomplete_setup     # Missing seed data, fixtures, or config
+    description: "Fundamental cause of the problem"
+
+  resolution_type:
+    type: enum
+    values:
+      - code_fix             # Fixed by changing source code
+      - migration            # Fixed by database migration
+      - config_change        # Fixed by changing configuration
+      - test_fix             # Fixed by correcting tests
+      - dependency_update    # Fixed by updating gem/dependency
+      - environment_setup    # Fixed by environment configuration
+      - workflow_improvement # Improved development workflow or process
+      - documentation_update # Added or updated documentation
+      - tooling_addition     # Added helper script or automation
+      - seed_data_update     # Updated db/seeds.rb or fixtures
+    description: "Type of fix applied"
+
+  severity:
+    type: enum
+    values:
+      - critical             # Blocks production or development (build fails, data loss)
+      - high                 # Impairs core functionality (feature broken, security issue)
+      - medium               # Affects specific feature (UI broken, performance impact)
+      - low                  # Minor issue or edge case
+    description: "Impact severity"
+
+optional_fields:
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version where this was encountered (e.g., '7.1.0')"
+
+  related_components:
+    type: array[string]
+    description: "Other components that interact with this issue"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Searchable keywords (lowercase, hyphen-separated)"
+    examples:
+      - "n-plus-one"
+      - "eager-loading"
+      - "test-isolation"
+      - "turbo-stream"
+
+validation_rules:
+  - "module must be a valid CORA module name"
+  - "date must be in YYYY-MM-DD format"
+  - "problem_type must match one of the enum values"
+  - "component must match one of the enum values"
+  - "symptoms must be specific and observable (not vague)"
+  - "root_cause must be the ACTUAL cause, not a symptom"
+  - "resolution_type must match one of the enum values"
+  - "severity must match one of the enum values"
+  - "tags should be lowercase, hyphen-separated"
+
+# Example valid front matter:
+# ---
+# module: Email Processing
+# date: 2025-11-12
+# problem_type: performance_issue
+# component: rails_model
+# symptoms:
+#   - N+1 query when loading email threads
+#   - Brief generation taking >5 seconds
+# root_cause: missing_include
+# rails_version: 7.1.2
+# resolution_type: code_fix
+# severity: high
+# tags: [n-plus-one, eager-loading, performance]
+# ---
+#
+# Example DX issue front matter:
+# ---
+# module: Development Workflow
+# date: 2025-11-13
+# problem_type: developer_experience
+# component: development_workflow
+# symptoms:
+#   - No example data for new feature in development
+#   - Rails db:seed doesn't demonstrate new capabilities
+# root_cause: incomplete_setup
+# rails_version: 7.1.2
+# resolution_type: seed_data_update
+# severity: low
+# tags: [seed-data, dx, workflow]
+# ---

package/.agent/skills/create-agent-skills/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: creating-agent-skills
+description: Expert guidance for creating, writing, and refining Antigravity Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+---
+
+# Creating Agent Skills
+
+This skill teaches how to create effective Antigravity Skills following Antigravity's official specification.
+
+## Core Principles
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct. Assume Antigravity is smart - only add context Antigravity doesn't have.
+
+### 2. Standard Markdown Format
+
+Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
+
+```markdown
+---
+name: my-skill-name
+description: What it does and when to use it
+---
+
+# My Skill Name
+
+## Quick Start
+Immediate actionable guidance...
+
+## Instructions
+Step-by-step procedures...
+
+## Examples
+Concrete usage examples...
+```
+
+### 3. Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
+
+```
+my-skill/
+├── SKILL.md              # Entry point (required)
+├── reference.md          # Detailed docs (loaded when needed)
+├── examples.md           # Usage examples
+└── scripts/              # Utility scripts (executed, not loaded)
+```
+
+### 4. Effective Descriptions
+
+The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
+
+**Good:**
+```yaml
+description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Bad:**
+```yaml
+description: Helps with documents
+```
+
+## Skill Structure
+
+### Required Frontmatter
+
+| Field | Required | Max Length | Description |
+|-------|----------|------------|-------------|
+| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
+| `description` | Yes | 1024 chars | What it does AND when to use it |
+| `allowed-tools` | No | - | Tools Antigravity can use without asking |
+| `model` | No | - | Specific model to use |
+
+### Naming Conventions
+
+Use **gerund form** (verb + -ing) for skill names:
+
+- `processing-pdfs`
+- `analyzing-spreadsheets`
+- `generating-commit-messages`
+- `reviewing-code`
+
+Avoid: `helper`, `utils`, `tools`, `antigravity-*`, `agent-*`
+
+### Body Structure
+
+Use standard markdown headings:
+
+```markdown
+# Skill Name
+
+## Quick Start
+Fastest path to value...
+
+## Instructions
+Core guidance Antigravity follows...
+
+## Examples
+Input/output pairs showing expected behavior...
+
+## Advanced Features
+Additional capabilities (link to reference files)...
+
+## Guidelines
+Rules and constraints...
+```
+
+## What Would You Like To Do?
+
+1. **Create new skill** - Build from scratch
+2. **Audit existing skill** - Check against best practices
+3. **Add component** - Add workflow/reference/example
+4. **Get guidance** - Understand skill design
+
+## Creating a New Skill
+
+### Step 1: Choose Type
+
+**Simple skill (single file):**
+- Under 500 lines
+- Self-contained guidance
+- No complex workflows
+
+**Progressive disclosure skill (multiple files):**
+- SKILL.md as overview
+- Reference files for detailed docs
+- Scripts for utilities
+
+### Step 2: Create SKILL.md
+
+```markdown
+---
+name: your-skill-name
+description: [What it does]. Use when [trigger conditions].
+---
+
+# Your Skill Name
+
+## Quick Start
+
+[Immediate actionable example]
+
+```[language]
+[Code example]
+```
+
+## Instructions
+
+[Core guidance]
+
+## Examples
+
+**Example 1:**
+Input: [description]
+Output:
+```
+[result]
+```
+
+## Guidelines
+
+- [Constraint 1]
+- [Constraint 2]
+```
+
+### Step 3: Add Reference Files (If Needed)
+
+Link from SKILL.md to detailed content:
+
+```markdown
+For API reference, see [REFERENCE.md](REFERENCE.md).
+For form filling guide, see [FORMS.md](FORMS.md).
+```
+
+Keep references **one level deep** from SKILL.md.
+
+### Step 4: Add Scripts (If Needed)
+
+Scripts execute without loading into context:
+
+```markdown
+## Utility Scripts
+
+Extract fields:
+```bash
+python scripts/analyze.py input.pdf > fields.json
+```
+```
+
+### Step 5: Test With Real Usage
+
+1. Test with actual tasks, not test scenarios
+2. Observe where Antigravity struggles
+3. Refine based on real behavior
+4. Test with Haiku, Sonnet, and Opus
+
+## Auditing Existing Skills
+
+Check against this rubric:
+
+- [ ] Valid YAML frontmatter (name + description)
+- [ ] Description includes trigger keywords
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] SKILL.md under 500 lines
+- [ ] References one level deep
+- [ ] Examples are concrete, not abstract
+- [ ] Consistent terminology
+- [ ] No time-sensitive information
+- [ ] Scripts handle errors explicitly
+
+## Common Patterns
+
+### Template Pattern
+
+Provide output templates for consistent results:
+
+```markdown
+## Report Template
+
+```markdown
+# [Analysis Title]
+
+## Executive Summary
+[One paragraph overview]
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Recommendations
+1. [Action item]
+2. [Action item]
+```
+```
+
+### Workflow Pattern
+
+For complex multi-step tasks:
+
+```markdown
+## Migration Workflow
+
+Copy this checklist:
+
+```
+- [ ] Step 1: Backup database
+- [ ] Step 2: Run migration script
+- [ ] Step 3: Validate output
+- [ ] Step 4: Update configuration
+```
+
+**Step 1: Backup database**
+Run: `./scripts/backup.sh`
+...
+```
+
+### Conditional Pattern
+
+Guide through decision points:
+
+```markdown
+## Choose Your Approach
+
+**Creating new content?** Follow "Creation workflow" below.
+**Editing existing?** Follow "Editing workflow" below.
+```
+
+## Anti-Patterns to Avoid
+
+- **XML tags in body** - Use markdown headings instead
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Too many options** - Provide a default with escape hatch
+- **Windows paths** - Always use forward slashes
+- **Punting to Antigravity** - Scripts should handle errors
+- **Time-sensitive info** - Use "old patterns" section instead
+
+## Reference Files
+
+For detailed guidance, see:
+
+- [official-spec.md](references/official-spec.md) - Antigravity's official skill specification
+- [best-practices.md](references/best-practices.md) - Skill authoring best practices
+
+## Success Criteria
+
+A well-structured skill:
+- Has valid YAML frontmatter with descriptive name and description
+- Uses standard markdown headings (not XML tags)
+- Keeps SKILL.md under 500 lines
+- Links to reference files for detailed content
+- Includes concrete examples with input/output pairs
+- Has been tested with real usage
+
+Sources:
+- [Agent Skills - Antigravity Docs](https://code.agent.com/docs/en/skills)
+- [Skill authoring best practices](https://platform.agent.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [GitHub - anthropics/skills](https://github.com/anthropics/skills)

package/.agent/skills/create-agent-skills/references/api-security.md

@@ -0,0 +1,226 @@
+<overview>
+When building skills that make API calls requiring credentials (API keys, tokens, secrets), follow this protocol to prevent credentials from appearing in chat.
+</overview>
+
+<the_problem>
+Raw curl commands with environment variables expose credentials:
+
+```bash
+# ❌ BAD - API key visible in chat
+curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data
+```
+
+When Antigravity executes this, the full command with expanded `$API_KEY` appears in the conversation.
+</the_problem>
+
+<the_solution>
+Use `~/.antigravity/scripts/secure-api.sh` - a wrapper that loads credentials internally.
+
+<for_supported_services>
+```bash
+# ✅ GOOD - No credentials visible
+~/.antigravity/scripts/secure-api.sh <service> <operation> [args]
+
+# Examples:
+~/.antigravity/scripts/secure-api.sh facebook list-campaigns
+~/.antigravity/scripts/secure-api.sh ghl search-contact "email@example.com"
+```
+</for_supported_services>
+
+<adding_new_services>
+When building a new skill that requires API calls:
+
+1. **Add operations to the wrapper** (`~/.antigravity/scripts/secure-api.sh`):
+
+```bash
+case "$SERVICE" in
+    yourservice)
+        case "$OPERATION" in
+            list-items)
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items"
+                ;;
+            get-item)
+                ITEM_ID=$1
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items/$ITEM_ID"
+                ;;
+            *)
+                echo "Unknown operation: $OPERATION" >&2
+                exit 1
+                ;;
+        esac
+        ;;
+esac
+```
+
+2. **Add profile support to the wrapper** (if service needs multiple accounts):
+
+```bash
+# In secure-api.sh, add to profile remapping section:
+yourservice)
+    SERVICE_UPPER="YOURSERVICE"
+    YOURSERVICE_API_KEY=$(eval echo \$${SERVICE_UPPER}_${PROFILE_UPPER}_API_KEY)
+    YOURSERVICE_ACCOUNT_ID=$(eval echo \$${SERVICE_UPPER}_${PROFILE_UPPER}_ACCOUNT_ID)
+    ;;
+```
+
+3. **Add credential placeholders to `~/.antigravity/.env`** using profile naming:
+
+```bash
+# Check if entries already exist
+grep -q "YOURSERVICE_MAIN_API_KEY=" ~/.antigravity/.env 2>/dev/null || \
+  echo -e "\n# Your Service - Main profile\nYOURSERVICE_MAIN_API_KEY=\nYOURSERVICE_MAIN_ACCOUNT_ID=" >> ~/.antigravity/.env
+
+echo "Added credential placeholders to ~/.antigravity/.env - user needs to fill them in"
+```
+
+4. **Document profile workflow in your SKILL.md**:
+
+```markdown
+## Profile Selection Workflow
+
+**CRITICAL:** Always use profile selection to prevent using wrong account credentials.
+
+### When user requests YourService operation:
+
+1. **Check for saved profile:**
+   ```bash
+   ~/.antigravity/scripts/profile-state get yourservice
+   ```
+
+2. **If no profile saved, discover available profiles:**
+   ```bash
+   ~/.antigravity/scripts/list-profiles yourservice
+   ```
+
+3. **If only ONE profile:** Use it automatically and announce:
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+4. **If MULTIPLE profiles:** Ask user which one:
+   ```
+   "Which YourService profile: main, clienta, or clientb?"
+   ```
+
+5. **Save user's selection:**
+   ```bash
+   ~/.antigravity/scripts/profile-state set yourservice <selected_profile>
+   ```
+
+6. **Always announce which profile before calling API:**
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+7. **Make API call with profile:**
+   ```bash
+   ~/.antigravity/scripts/secure-api.sh yourservice:<profile> list-items
+   ```
+
+## Secure API Calls
+
+All API calls use profile syntax:
+
+```bash
+~/.antigravity/scripts/secure-api.sh yourservice:<profile> <operation> [args]
+
+# Examples:
+~/.antigravity/scripts/secure-api.sh yourservice:main list-items
+~/.antigravity/scripts/secure-api.sh yourservice:main get-item <ITEM_ID>
+```
+
+**Profile persists for session:** Once selected, use same profile for subsequent operations unless user explicitly changes it.
+```
+</adding_new_services>
+</the_solution>
+
+<pattern_guidelines>
+<simple_get_requests>
+```bash
+curl -s -G \
+    -H "Authorization: Bearer $API_KEY" \
+    "https://api.example.com/endpoint"
+```
+</simple_get_requests>
+
+<post_with_json_body>
+```bash
+ITEM_ID=$1
+curl -s -X POST \
+    -H "Authorization: Bearer $API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @- \
+    "https://api.example.com/items/$ITEM_ID"
+```
+
+Usage:
+```bash
+echo '{"name":"value"}' | ~/.antigravity/scripts/secure-api.sh service create-item
+```
+</post_with_json_body>
+
+<post_with_form_data>
+```bash
+curl -s -X POST \
+    -F "field1=value1" \
+    -F "field2=value2" \
+    -F "access_token=$API_TOKEN" \
+    "https://api.example.com/endpoint"
+```
+</post_with_form_data>
+</pattern_guidelines>
+
+<credential_storage>
+**Location:** `~/.antigravity/.env` (global for all skills, accessible from any directory)
+
+**Format:**
+```bash
+# Service credentials
+SERVICE_API_KEY=your-key-here
+SERVICE_ACCOUNT_ID=account-id-here
+
+# Another service
+OTHER_API_TOKEN=token-here
+OTHER_BASE_URL=https://api.other.com
+```
+
+**Loading in script:**
+```bash
+set -a
+source ~/.antigravity/.env 2>/dev/null || { echo "Error: ~/.antigravity/.env not found" >&2; exit 1; }
+set +a
+```
+</credential_storage>
+
+<best_practices>
+1. **Never use raw curl with `$VARIABLE` in skill examples** - always use the wrapper
+2. **Add all operations to the wrapper** - don't make users figure out curl syntax
+3. **Auto-create credential placeholders** - add empty fields to `~/.antigravity/.env` immediately when creating the skill
+4. **Keep credentials in `~/.antigravity/.env`** - one central location, works everywhere
+5. **Document each operation** - show examples in SKILL.md
+6. **Handle errors gracefully** - check for missing env vars, show helpful error messages
+</best_practices>
+
+<testing>
+Test the wrapper without exposing credentials:
+
+```bash
+# This command appears in chat
+~/.antigravity/scripts/secure-api.sh facebook list-campaigns
+
+# But API keys never appear - they're loaded inside the script
+```
+
+Verify credentials are loaded:
+```bash
+# Check .env exists
+ls -la ~/.antigravity/.env
+
+# Check specific variables (without showing values)
+grep -q "YOUR_API_KEY=" ~/.antigravity/.env && echo "API key configured" || echo "API key missing"
+```
+</testing>