Update Graft Inventory Skill Skill

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/platform/feature-flags/flags.ts | Type definitions (KnownFlagId) | | docs/guides/adding-grafts-and-flags.md | Developer guide (grafts = Grove term for feature flags) |

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 KnownFlagId Type

Edit libs/engine/src/lib/platform/feature-flags/flags.ts:

export type KnownFlagId =
	| "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/platform/feature-flags/flags.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownFlagId 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 KnownFlagId type in flags.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
[ ] KnownFlagId type includes all flag IDs
[ ] lastUpdated date is today
[ ] Counts add up: total = platform + greenhouse
[ ] Type breakdown is accurate
[ ] Changes committed with descriptive message

Agent Skills: Update Graft Inventory Skill

Install this agent skill to your local

Skill Files