@intentsolutionsio/jeremy-firestore 2.0.0 → 2.0.5

package/README.md

@@ -9,6 +9,7 @@ Build, manage, and optimize Firebase/Firestore databases with AI-powered agents
 ## Features
 
 ### Core Capabilities
+
 - **CRUD Operations** - Create, read, update, delete with batch support
 - **Security Rules** - Generate, validate, and deploy Firestore security rules
 - **Data Migration** - Migrate data between collections, projects, or environments
@@ -19,12 +20,14 @@ Build, manage, and optimize Firebase/Firestore databases with AI-powered agents
 - **Collection Management** - Schema validation, indexing, and organization
 
 ### AI Agents
+
 - **firebase-operations-agent** - CRUD, queries, batch operations
 - **firestore-security-agent** - Security rules generation and validation
 - **firestore-migration-agent** - Data migration and transformation
 - **firestore-optimizer-agent** - Performance and cost optimization
 
 ### Commands
+
 - `/firestore-setup` - Initialize Firebase SDK and credentials
 - `/firestore-query` - Interactive query builder
 - `/firestore-migrate` - Guided migration workflow
@@ -68,7 +71,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
 
 ### Example 1: CRUD Operations
 
-```javascript
+```text
 // Create documents
 "Create a new user document in the 'users' collection"
 
@@ -119,7 +122,8 @@ Agent:
 ```
 
 Agent generates:
-```javascript
+
+```text
 rules_version = '2';
 service cloud.firestore {
   match /databases/{database}/documents {
@@ -147,6 +151,7 @@ service cloud.firestore {
 ```
 
 Agent workflow:
+
 1. **Connects to staging** - Reads source collection
 2. **Transforms data** - Anonymizes PII fields
 3. **Validates** - Checks schema compatibility
@@ -162,6 +167,7 @@ Agent workflow:
 ```
 
 Agent executes:
+
 - Queries in batches of 500 documents
 - Uses batch writes for efficiency (reduces costs 10x)
 - Handles rate limits automatically
@@ -176,6 +182,7 @@ Agent executes:
 ```
 
 Agent analyzes:
+
 - **Missing indexes** - Identifies composite indexes needed
 - **Query patterns** - Finds inefficient queries
 - **Collection structure** - Suggests denormalization opportunities
@@ -191,18 +198,21 @@ Agent analyzes:
 **Purpose:** Handle all Firestore CRUD operations, queries, and batch processing
 
 **Use when:**
+
 - Creating, reading, updating, or deleting documents
 - Running complex queries with filters and ordering
 - Batch operations on multiple documents
 - Collection management
 
 **Trigger phrases:**
+
 - "create a document in..."
 - "query the users collection..."
 - "batch update all documents where..."
 - "delete documents matching..."
 
 **Example:**
+
 ```
 User: "Get the 10 most recent orders for user123"
 
@@ -218,18 +228,21 @@ Agent:
 **Purpose:** Generate, validate, and deploy Firestore security rules
 
 **Use when:**
+
 - Creating new security rules
 - Validating existing rules
 - Troubleshooting permission errors
 - Implementing authentication patterns
 
 **Trigger phrases:**
+
 - "create security rules for..."
 - "validate my firestore rules..."
 - "fix permission denied error..."
 - "implement role-based access..."
 
 **Example:**
+
 ```
 User: "Create rules for a chat app with public rooms and private messages"
 
@@ -248,18 +261,21 @@ Agent:
 **Purpose:** Migrate data between collections, projects, or environments
 
 **Use when:**
+
 - Moving data between environments (staging → production)
 - Restructuring collections
 - Backfilling data
 - Importing/exporting data
 
 **Trigger phrases:**
+
 - "migrate data from..."
 - "copy collection to..."
 - "restructure the users collection..."
 - "backfill missing fields..."
 
 **Example:**
+
 ```
 User: "Migrate users collection to a new structure with nested addresses"
 
@@ -276,18 +292,21 @@ Agent:
 **Purpose:** Optimize Firestore performance and reduce costs
 
 **Use when:**
+
 - Slow queries need optimization
 - Monthly costs are too high
 - Need index recommendations
 - Want to analyze usage patterns
 
 **Trigger phrases:**
+
 - "optimize my firestore performance..."
 - "reduce firebase costs..."
 - "why is this query slow..."
 - "analyze my firestore usage..."
 
 **Example:**
+
 ```
 User: "Why is my users query so slow?"
 
@@ -349,24 +368,28 @@ module.exports = {
 ## Best Practices
 
 ### Security Rules
+
 - **Never allow open access** - Always require authentication
 - **Validate all writes** - Check field types and values
 - **Limit read scope** - Only allow reading necessary data
 - **Test rules thoroughly** - Use Firebase Emulator Suite
 
 ### Performance
+
 - **Use indexes** - Create composite indexes for complex queries
 - **Batch operations** - Use batch writes for multiple documents
 - **Denormalize data** - Duplicate data to avoid joins
 - **Paginate results** - Use cursor-based pagination for large datasets
 
 ### Cost Optimization
+
 - **Cache frequently read data** - Use in-memory caching
 - **Minimize document reads** - Use `select()` to read specific fields
 - **Archive old data** - Move historical data to Cloud Storage
 - **Monitor usage** - Set up billing alerts
 
 ### Data Modeling
+
 - **Keep documents small** - Max 1MB per document
 - **Use subcollections** - For nested data hierarchies
 - **Plan for scale** - Design for millions of documents
@@ -378,7 +401,7 @@ module.exports = {
 
 ### Pattern 1: User Profiles with Privacy
 
-```javascript
+```text
 // Collection structure
 users/{userId}
   - public: { name, avatar, bio }        // Anyone can read
@@ -388,7 +411,7 @@ users/{userId}
 
 ### Pattern 2: Real-time Chat
 
-```javascript
+```text
 // Collection structure
 rooms/{roomId}
   - metadata: { name, createdAt, memberCount }
@@ -404,7 +427,7 @@ messages/{messageId}
 
 ### Pattern 3: E-commerce Orders
 
-```javascript
+```text
 // Collection structure
 orders/{orderId}
   - userId, status, total, createdAt
@@ -475,7 +498,7 @@ firebase projects:list
 
 ### Cloud Functions Integration
 
-```javascript
+```text
 // Trigger Cloud Functions from Firestore
 "Create a function that sends an email when a new user signs up"
 
@@ -587,16 +610,19 @@ exports.onUserCreate = functions.firestore
 ## Resources
 
 ### Firebase Documentation
+
 - [Firestore Documentation](https://firebase.google.com/docs/firestore)
 - [Security Rules](https://firebase.google.com/docs/firestore/security/get-started)
 - [Best Practices](https://firebase.google.com/docs/firestore/best-practices)
 
 ### Plugin Resources
+
 - [GitHub Repository](https://github.com/jeremylongshore/claude-code-plugins)
 - [Issue Tracker](https://github.com/jeremylongshore/claude-code-plugins/issues)
 - [Marketplace](https://claudecodeplugins.io/)
 
 ### Community
+
 - [Discord](https://discord.com/invite/6PPFFzqPDZ) (#claude-code channel)
 - [GitHub Discussions](https://github.com/jeremylongshore/claude-code-plugins/discussions)
 

package/agents/firebase-operations-agent.md

@@ -1,15 +1,42 @@
 ---
 name: firebase-operations-agent
-description: >
-  Expert Firestore operations agent for CRUD, queries, batch processing,
-  and...
+description: Expert Firestore operations agent for CRUD, queries, batch processing, and...
+tools:
+- Read
+- Write
+- Edit
+- Bash
+- Glob
+- Grep
+- WebFetch
+- WebSearch
+- Task
+- TodoWrite
 model: sonnet
+color: cyan
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- community
+- firebase
+- operations
+disallowedTools: []
+skills: []
+background: false
+# ── upgrade levers — uncomment + set when tuning this agent ──
+# effort: high            # reasoning depth: low/medium/high/xhigh/max (omit = inherit session)
+# maxTurns: 50            # cap the agentic loop (omit = engine default)
+# memory: project         # persistent scope: user/project/local (omit = ephemeral)
+# isolation: worktree     # run in an isolated git worktree
+# initialPrompt: "…"      # seed the agent's first turn
+# hooks / mcpServers / permissionMode → set at the PLUGIN level, not on a plugin agent
 ---
 You are a Firebase/Firestore operations expert specializing in production-ready database operations for Google Cloud.
 
 ## Your Expertise
 
 You are a master of:
+
 - **Firestore CRUD operations** - Create, read, update, delete with proper error handling
 - **Complex queries** - Where clauses, ordering, pagination, filtering
 - **Batch operations** - Efficient bulk reads/writes with rate limit handling
@@ -22,6 +49,7 @@ You are a master of:
 ## Your Mission
 
 Help users perform Firestore operations safely, efficiently, and cost-effectively. Always:
+
 1. **Validate before executing** - Check credentials, collections exist, queries are safe
 2. **Handle errors gracefully** - Catch exceptions, provide helpful messages
 3. **Optimize for cost** - Use batch operations, limit reads, suggest indexes
@@ -33,6 +61,7 @@ Help users perform Firestore operations safely, efficiently, and cost-effectivel
 ### 1. Create Documents
 
 When creating documents:
+
 - Validate all required fields are present
 - Check data types match schema
 - Use server timestamps for createdAt/updatedAt
@@ -40,6 +69,7 @@ When creating documents:
 - Handle duplicates gracefully
 
 Example:
+
 ```javascript
 const admin = require('firebase-admin');
 const db = admin.firestore();
@@ -58,6 +88,7 @@ console.log(`Created user with ID: ${docRef.id}`);
 ### 2. Read Documents
 
 When reading documents:
+
 - Use get() for single documents
 - Use where() for filtered queries
 - Add orderBy() for sorting
@@ -65,6 +96,7 @@ When reading documents:
 - Implement pagination for large datasets
 
 Example:
+
 ```javascript
 // Get single document
 const userDoc = await db.collection('users').doc('user123').get();
@@ -89,6 +121,7 @@ activeUsers.forEach(doc => {
 ### 3. Update Documents
 
 When updating documents:
+
 - Use update() for partial updates
 - Use set({ merge: true }) for upserts
 - Always update timestamps
@@ -96,6 +129,7 @@ When updating documents:
 - Handle missing documents
 
 Example:
+
 ```javascript
 // Partial update
 await db.collection('users').doc('user123').update({
@@ -119,6 +153,7 @@ await db.collection('stats').doc('page_views').update({
 ### 4. Delete Documents
 
 When deleting documents:
+
 - **Always confirm dangerous operations**
 - Check for related data (cascading deletes)
 - Use batch deletes for multiple documents
@@ -126,6 +161,7 @@ When deleting documents:
 - Log deletions for audit trail
 
 Example:
+
 ```javascript
 // Single delete
 await db.collection('users').doc('user123').delete();
@@ -150,6 +186,7 @@ console.log(`Deleted ${docsToDelete.size} documents`);
 ### Batch Operations
 
 For operations on multiple documents:
+
 1. **Use batched writes** - Up to 500 operations per batch
 2. **Chunk large operations** - Process in batches of 500
 3. **Handle failures** - Implement retry logic
@@ -157,6 +194,7 @@ For operations on multiple documents:
 5. **Validate first** - Dry run before executing
 
 Example:
+
 ```javascript
 async function batchUpdate(collection, query, updates) {
   const snapshot = await query.get();
@@ -187,6 +225,7 @@ async function batchUpdate(collection, query, updates) {
 ### Complex Queries
 
 For advanced queries:
+
 - **Use composite indexes** - Required for multiple filters
 - **Avoid array-contains with other filters** - Limited support
 - **Use orderBy strategically** - Affects which filters work
@@ -194,6 +233,7 @@ For advanced queries:
 - **Consider denormalization** - For complex joins
 
 Example:
+
 ```javascript
 // Composite query (requires index)
 const results = await db.collection('orders')
@@ -225,12 +265,14 @@ async function getNextPage() {
 ### Transactions
 
 For atomic operations:
+
 - **Use transactions** - For reads and writes that must be consistent
 - **Keep transactions small** - Max 500 writes
 - **Handle contention** - Implement retry logic
 - **Read before write** - Transactions validate reads haven't changed
 
 Example:
+
 ```javascript
 await db.runTransaction(async (transaction) => {
   // Read current balance
@@ -304,11 +346,13 @@ try {
 ## Cost Optimization
 
 Firestore charges per operation:
+
 - **Document reads**: $0.06 per 100k
 - **Document writes**: $0.18 per 100k
 - **Document deletes**: $0.02 per 100k
 
 Optimize costs by:
+
 - Using batch operations (1 write vs 500 writes)
 - Caching frequently read data
 - Using Cloud Functions for background tasks

package/agents/firestore-security-agent.md

@@ -1,15 +1,42 @@
 ---
 name: firestore-security-agent
-description: >
-  Expert Firestore security rules generation, validation, and A2A agent
-  access...
+description: Expert Firestore security rules generation, validation, and A2A agent access...
+tools:
+- Read
+- Write
+- Edit
+- Bash
+- Glob
+- Grep
+- WebFetch
+- WebSearch
+- Task
+- TodoWrite
 model: sonnet
+color: purple
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- community
+- firestore
+- security
+disallowedTools: []
+skills: []
+background: false
+# ── upgrade levers — uncomment + set when tuning this agent ──
+# effort: high            # reasoning depth: low/medium/high/xhigh/max (omit = inherit session)
+# maxTurns: 50            # cap the agentic loop (omit = engine default)
+# memory: project         # persistent scope: user/project/local (omit = ephemeral)
+# isolation: worktree     # run in an isolated git worktree
+# initialPrompt: "…"      # seed the agent's first turn
+# hooks / mcpServers / permissionMode → set at the PLUGIN level, not on a plugin agent
 ---
 You are a Firestore security rules expert specializing in production-ready security for web apps, mobile apps, and AI agent-to-agent (A2A) communication.
 
 ## Your Expertise
 
 You are a master of:
+
 - **Firestore Security Rules** - rules_version 2 syntax, patterns, validation
 - **Authentication patterns** - Firebase Auth, custom claims, role-based access
 - **A2A security** - Agent-to-agent authentication and authorization
@@ -22,6 +49,7 @@ You are a master of:
 ## Your Mission
 
 Generate secure, performant Firestore security rules for both human users and AI agents. Always:
+
 1. **Default deny** - Start with denying all access, then explicitly allow
 2. **Validate authentication** - Require auth for all sensitive operations
 3. **Validate data** - Check types, formats, required fields
@@ -465,6 +493,7 @@ When generating security rules:
 ## Security Checklist
 
 Before deploying rules:
+
 - [ ] All sensitive collections require authentication
 - [ ] Service accounts are whitelisted (not open to all)
 - [ ] Data validation checks all required fields

package/commands/firestore-setup.md

@@ -6,6 +6,7 @@ model: sonnet
 # Firestore Setup Command
 
 Initialize Firebase Admin SDK in your project with support for:
+
 - Basic Firestore operations (CRUD, queries)
 - A2A (Agent-to-Agent) framework integration
 - MCP server communication patterns
@@ -58,6 +59,7 @@ npm install dotenv  # For environment variables
 Ask the user:
 
 **Option A: Download from Firebase Console**
+
 ```
 1. Go to https://console.firebase.google.com
 2. Select your project
@@ -67,12 +69,14 @@ Ask the user:
 ```
 
 **Option B: Use existing GCP credentials**
+
 ```bash
 # If using Google Cloud SDK
 gcloud auth application-default login
 ```
 
 **Option C: Environment variable (production)**
+
 ```bash
 # Set environment variable
 export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
@@ -109,6 +113,7 @@ module.exports = { admin, db };
 ```
 
 For TypeScript:
+
 ```typescript
 import * as admin from 'firebase-admin';
 
@@ -161,6 +166,7 @@ testFirestore();
 ```
 
 Run the test:
+
 ```bash
 node test-firestore.js
 ```
@@ -368,6 +374,7 @@ CLOUD_RUN_SERVICE_URL=https://your-service-abc123-uc.a.run.app
 ```
 
 Add to `.gitignore`:
+
 ```
 serviceAccountKey.json
 .env
@@ -514,19 +521,23 @@ Tell the user:
 ## Common Issues
 
 ### Issue 1: "Permission denied" errors
+
 - Check service account has Firestore permissions
 - Verify security rules allow the operation
 - Ensure GOOGLE_APPLICATION_CREDENTIALS is set correctly
 
 ### Issue 2: "Firebase app already initialized"
+
 - This is normal - only initialize once
 - Check if Firebase is initialized in multiple files
 
 ### Issue 3: "Cannot find module 'firebase-admin'"
+
 - Run `npm install firebase-admin`
 - Check package.json includes firebase-admin
 
 ### Issue 4: A2A collections not accessible
+
 - Verify service account email is whitelisted in security rules
 - Check firestore.rules includes A2A patterns
 - Test with Firebase Emulator first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/jeremy-firestore",
-  "version": "2.0.0",
+  "version": "2.0.5",
   "description": "Firestore database specialist for schema design, queries, and real-time sync",
   "keywords": [
     "firebase",

package/skills/firestore-operations-manager/ARD.md

@@ -112,6 +112,7 @@ for (let i = 0; i < docs.length; i += BATCH_SIZE) {
 **Rationale**: A migration processing 100,000 documents takes 200 batch commits. If the script crashes at batch 150, without checkpoints it must restart from document 0 (re-reading 75,000 already-processed documents). With checkpoints, it reads the last checkpoint and resumes from document 75,001.
 
 **Checkpoint document schema**:
+
 ```typescript
 interface MigrationCheckpoint {
   migrationId: string;
@@ -193,6 +194,7 @@ IndexManager
 ### Migration Logging
 
 Every batch commit logs:
+
 ```
 [migration:backfill-status-field] Batch 150/200 committed. Processed: 75000, Skipped: 12, Failed: 0. Elapsed: 4m32s.
 ```
@@ -200,6 +202,7 @@ Every batch commit logs:
 ### Cost Estimation
 
 Before executing large operations, estimate cost:
+
 ```
 Operation: backfill 100,000 documents
   Reads:   100,000 × $0.06/100k = $0.06

package/skills/firestore-operations-manager/PRD.md

@@ -49,33 +49,42 @@ These problems share a root cause: Firestore's document model and operational co
 ## Functional Requirements
 
 ### FR-1: Schema-Aware CRUD
+
 The skill must detect the existing collection schema (by reading sample documents) before proposing writes. New fields added via `update()` must not overwrite existing data unless explicitly requested.
 
 ### FR-2: Batch Write Management
+
 Batch writes must:
+
 - Chunk operations into groups of 500 (Firestore limit per `batch.commit()`)
 - Log progress every N documents (configurable, default 1,000)
 - Write a checkpoint document after each successful batch so the operation can resume
 - Retry failed batches with exponential backoff (3 attempts, 1s/2s/4s delays)
 
 ### FR-3: Composite Index Generation
+
 When the skill generates a query with multiple `where()` clauses or a `where()` + `orderBy()` combination, it must also produce the corresponding composite index entry for `firestore.indexes.json`.
 
 ### FR-4: Security Rules
+
 Generated rules must:
+
 - Deny all access by default (no `match /{document=**} { allow read, write: if true }`)
 - Use helper functions for authentication and ownership checks
 - Include field-level validation for create and update operations
 - Be testable with `@firebase/rules-unit-testing`
 
 ### FR-5: Migration Operations
+
 Migrations must:
+
 - Support backfill (add field to existing documents) and transform (modify field values)
 - Write a checkpoint after each batch to a `_migrations/{migrationId}` document
 - Support dry-run mode that reads but does not write
 - Produce a summary (documents processed, skipped, failed)
 
 ### FR-6: Pagination
+
 Queries that may return more than 100 documents must use `startAfter()` cursor-based pagination. The skill must produce both the query code and the pagination cursor management logic.
 
 ## Non-Functional Requirements

package/skills/firestore-operations-manager/SKILL.md

@@ -1,15 +1,24 @@
 ---
 name: firestore-operations-manager
-description: |
-  Manage Firebase/Firestore operations including CRUD, queries, batch processing, and index/rule guidance.
-  Use when you need to create/update/query Firestore documents, run batch writes, troubleshoot missing indexes, or plan migrations.
-  Trigger with phrases like "firestore operations", "create firestore document", "batch write", "missing index", or "fix firestore query".
+description: 'Manage Firebase/Firestore operations including CRUD, queries, batch
+  processing, and index/rule guidance.
+
+  Use when you need to create/update/query Firestore documents, run batch writes,
+  troubleshoot missing indexes, or plan migrations.
+
+  Trigger with phrases like "firestore operations", "create firestore document", "batch
+  write", "missing index", or "fix firestore query".
+
+  '
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash(cmd:*)
 version: 1.0.0
 author: Jeremy Longshore <jeremy@intentsolutions.io>
 license: MIT
-compatible-with: claude-code, codex, openclaw
-tags: [community, migration, firestore-operations]
+tags:
+- community
+- migration
+- firestore-operations
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Firestore Operations Manager
 
@@ -53,10 +62,12 @@ Use this skill to design Firestore data access patterns and implement changes wi
 ## Examples
 
 **Example: Fix a failing query**
+
 - Request: “This query needs a composite index—what do I add?”
 - Result: the exact index definition and a safer query pattern if needed.
 
 **Example: Batch migration**
+
 - Request: “Backfill a new field across 100k docs.”
 - Result: batched write strategy, checkpoints, and rollback guidance.
 
@@ -64,4 +75,4 @@ Use this skill to design Firestore data access patterns and implement changes wi
 
 - Full detailed guide (kept for reference): `${CLAUDE_SKILL_DIR}/references/SKILL.full.md`
 - Firestore docs: https://firebase.google.com/docs/firestore
-- Firestore indexes: https://firebase.google.com/docs/firestore/query-data/indexing
+- Firestore indexes: https://firebase.google.com/docs/firestore/query-data/indexing