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

File Purpose

.github/graft-inventory.json

Source of truth for graft counts and metadata

libs/engine/migrations/*.sql

Migration files that define grafts

libs/engine/src/lib/feature-flags/grafts.ts

Type definitions (KnownGraftId )

docs/guides/adding-grafts-and-flags.md

Developer guide

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_]+" libs/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 :

Update counts:

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

Add/remove flag entries:

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

Update metadata:

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

6. Update KnownGraftId Type

Edit libs/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 libs/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" libs/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_]+" libs/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: libs/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=libs/engine/migrations/XXX_name.sql

CI Integration

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

• Runs on PRs touching libs/engine/migrations/*.sql

• Runs on PRs touching libs/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