Update Graft Inventory Skill

When to Activate

Activate this skill when:

• •Adding new feature flags via SQL migrations
• •Removing or deprecating grafts
• •The graft-inventory CI check fails
• •You want to verify inventory matches production D1
• •After applying migrations that add grafts

Files Involved

Inventory Structure

The inventory tracks grafts with full metadata:

{
  "grafts": {
    "total": 10,
    "breakdown": {
      "platform": 8,
      "greenhouse": 2
    },
    "byType": {
      "boolean": 9,
      "number": 1
    }
  },
  "flags": [
    {
      "id": "fireside_mode",
      "name": "Fireside Mode",
      "type": "boolean",
      "greenhouseOnly": true,
      "migration": "040_fireside_scribe_grafts.sql",
      "description": "AI-assisted writing prompts"
    }
  ]
}

Step-by-Step Process

1. List Grafts from Migrations

# Extract all flag IDs from migration INSERT statements
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" packages/engine/migrations/*.sql | sort -u

2. Query Production D1

# Get actual flags from production database
npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;"

3. Compare with Inventory

# Read current inventory
cat .github/graft-inventory.json | jq '.flags[].id' | sort

4. Identify Discrepancies

Look for:

• •New grafts: In migrations/D1 but not in inventory
• •Removed grafts: In inventory but not in D1
• •Changed metadata: Type, greenhouse_only, or description changed

5. Update Inventory JSON

Edit .github/graft-inventory.json:

1. •

   Update counts:

   json

   "grafts": {
     "total": <new count>,
     "breakdown": {
       "platform": <non-greenhouse count>,
       "greenhouse": <greenhouse_only count>
     }
   }
   

2. •

   Add/remove flag entries:

   json

   "flags": [
     {
       "id": "new_flag_id",
       "name": "Human Readable Name",
       "type": "boolean",
       "greenhouseOnly": false,
       "migration": "XXX_migration_name.sql",
       "description": "What this flag controls"
     }
   ]
   

3. •

   Update metadata:

   json

   "lastUpdated": "YYYY-MM-DD",
   "lastAuditedBy": "claude/<context>"
   

6. Update KnownGraftId Type

Edit packages/engine/src/lib/feature-flags/grafts.ts:

export type KnownGraftId =
  | "fireside_mode"
  | "scribe_mode"
  | "meadow_access"
  | "jxl_encoding"
  | "jxl_kill_switch"
  | "new_flag_id";  // Add new flag

7. Commit Changes

git add .github/graft-inventory.json packages/engine/src/lib/feature-flags/grafts.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownGraftId type"

Quick Reference Commands

# Count grafts in migrations
grep -c "INSERT OR IGNORE INTO feature_flags" packages/engine/migrations/*.sql | awk -F: '{sum+=$2} END {print sum}'

# List all flag IDs
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" packages/engine/migrations/*.sql | sort -u

# Count greenhouse-only grafts
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) FROM feature_flags WHERE greenhouse_only = 1;"

# Full flag details from production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT * FROM feature_flags ORDER BY id;"

# Check which migrations haven't been applied
# Compare migration file flag IDs vs production D1 flag IDs

Adding a New Graft (Full Checklist)

When adding a new graft:

• • Create migration file: packages/engine/migrations/XXX_name.sql
• • Apply migration: npx wrangler d1 execute grove-engine-db --remote --file=...
• • Add to KnownGraftId type in grafts.ts
• • Add entry to .github/graft-inventory.json flags array
• • Update inventory counts (total, breakdown.platform/greenhouse, byType)
• • Update lastUpdated and lastAuditedBy
• • Commit all changes together

Verifying Production Sync

After updating, verify production matches:

# Expected count
jq '.grafts.total' .github/graft-inventory.json

# Actual count in production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) as count FROM feature_flags;"

If they don't match, migrations may need to be applied:

# Apply a specific migration
npx wrangler d1 execute grove-engine-db --remote --file=packages/engine/migrations/XXX_name.sql

CI Integration

The .github/workflows/graft-inventory.yml workflow:

• •Runs on PRs touching packages/engine/migrations/*.sql
• •Runs on PRs touching packages/engine/src/lib/feature-flags/**
• •Parses migrations for INSERT statements
• •Compares count to inventory
• •Comments on PRs when there's a mismatch
• •Creates issues for drift on scheduled runs (Wednesdays)

When CI fails, run this skill to fix the mismatch.

Checklist

Before finishing:

• • Production D1 graft count matches inventory total
• • All flags in D1 have entries in inventory flags array
• • KnownGraftId type includes all flag IDs
• • lastUpdated date is today
• • Counts add up: total = platform + greenhouse
• • Type breakdown is accurate
• • Changes committed with descriptive message