{
  "feature": "plugin-development",
  "version": "1.0.0",
  "description": "Create and register plugins to extend CSS framework with custom utilities, variants, and theme values",
  "category": "integration",
  "tags": [
    "extensibility",
    "plugins",
    "custom-utilities",
    "theme-extension"
  ],
  "actors": [
    {
      "id": "plugin_developer",
      "name": "Plugin Developer",
      "type": "human",
      "description": "Creates custom utilities or theme extensions"
    },
    {
      "id": "framework_engine",
      "name": "Framework Engine",
      "type": "system",
      "description": "CSS framework that processes and applies plugins"
    },
    {
      "id": "consumer_project",
      "name": "Consumer Project",
      "type": "system",
      "description": "Project that installs and uses the plugin"
    }
  ],
  "fields": [
    {
      "name": "plugin_name",
      "type": "text",
      "required": true,
      "label": "Plugin Name"
    },
    {
      "name": "plugin_type",
      "type": "select",
      "required": true,
      "label": "Plugin Type",
      "options": [
        {
          "value": "utility",
          "label": "utility"
        },
        {
          "value": "variant",
          "label": "variant"
        },
        {
          "value": "base-styles",
          "label": "base-styles"
        },
        {
          "value": "theme-extension",
          "label": "theme-extension"
        }
      ]
    },
    {
      "name": "utility_name",
      "type": "text",
      "required": false,
      "label": "Utility Name"
    },
    {
      "name": "utility_values",
      "type": "json",
      "required": false,
      "label": "Utility Values"
    },
    {
      "name": "variant_name",
      "type": "text",
      "required": false,
      "label": "Variant Name"
    },
    {
      "name": "variant_selector",
      "type": "text",
      "required": false,
      "label": "Variant Selector"
    },
    {
      "name": "plugin_config",
      "type": "json",
      "required": false,
      "label": "Plugin Configuration"
    },
    {
      "name": "plugin_options",
      "type": "json",
      "required": false,
      "label": "Plugin Options"
    },
    {
      "name": "theme_namespace",
      "type": "text",
      "required": false,
      "label": "Theme Namespace"
    }
  ],
  "states": {
    "field": "plugin_status",
    "values": [
      {
        "value": "created",
        "description": "Plugin function defined but not yet loaded"
      },
      {
        "value": "registered",
        "description": "Plugin registered in project config",
        "initial": true
      },
      {
        "value": "loaded",
        "description": "Plugin module loaded and instantiated"
      },
      {
        "value": "applied",
        "description": "Plugin utilities and variants available in CSS generation"
      },
      {
        "value": "disabled",
        "description": "Plugin disabled in config (not used)"
      }
    ]
  },
  "rules": {
    "plugin_format": [
      "Plugin must export a function that receives plugin API utilities (addBase, addUtility, addVariant)",
      "Plugin can optionally return a config object to extend theme"
    ],
    "registration": [
      "Plugin must be registered in project config under plugins array",
      "Plugins are applied in order; later plugins can override earlier ones"
    ],
    "naming_conventions": [
      "Custom utility names use kebab-case (e.g., 'prose-sm', 'card-outlined')",
      "Custom variant names use kebab-case (e.g., 'group-hover', 'supports-grid')",
      "Theme extension keys must match framework namespace format (--namespace-value)"
    ],
    "config_merge": [
      "Plugin config extends theme; conflicting keys in user config take precedence",
      "Theme.extend in plugin is recursively merged with user theme.extend"
    ],
    "scope": [
      "Plugin utilities and variants are global; they apply to all compiled CSS",
      "Plugin theme values are available via theme() function in arbitrary values"
    ]
  },
  "outcomes": {
    "create_simple_utility": {
      "priority": 1,
      "given": [
        "Plugin developer creates a utility for card layout",
        "Utility should have responsive values (sm: small-size, md: medium-size)"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "utility",
          "fields": [
            "utility_name",
            "utility_values"
          ]
        },
        {
          "action": "emit_event",
          "event": "plugin.utility_created",
          "payload": [
            "utility_name",
            "utility_values"
          ]
        }
      ],
      "result": "Custom utility registered; available in compiled CSS (e.g., 'card', 'sm:card')"
    },
    "extend_theme_with_colors": {
      "priority": 2,
      "given": [
        "Plugin provides custom color palette (brand-primary: #FF6B35, brand-secondary: #004E89)",
        "Plugin returns config object with colors"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "theme_value",
          "fields": [
            "theme_namespace",
            "color_values"
          ]
        },
        {
          "action": "emit_event",
          "event": "plugin.theme_extended",
          "payload": [
            "theme_namespace",
            "new_values"
          ]
        }
      ],
      "result": "Colors available in utilities (text-brand-primary, bg-brand-secondary) and theme() function"
    },
    "create_custom_variant": {
      "priority": 3,
      "given": [
        "Plugin developer creates variant for 'even-child' pseudo-selector",
        "Selector provided: '&:nth-child(even)'"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "variant",
          "fields": [
            "variant_name",
            "variant_selector"
          ]
        },
        {
          "action": "emit_event",
          "event": "plugin.variant_created",
          "payload": [
            "variant_name",
            "variant_selector"
          ]
        }
      ],
      "result": "Custom variant available (even-child:flex, md:even-child:bg-gray-100)"
    },
    "plugin_with_options": {
      "priority": 4,
      "given": [
        "Plugin created with plugin.withOptions to accept configuration",
        "Consumer passes options when registering plugin"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "plugin_options",
          "value": "{prefix: 'tw-', customColor: '#FF0000'}"
        },
        {
          "action": "emit_event",
          "event": "plugin.instantiated_with_options",
          "payload": [
            "plugin_name",
            "plugin_options"
          ]
        }
      ],
      "result": "Plugin instance created with custom options; utilities and theme generated based on options"
    },
    "plugin_adds_base_styles": {
      "priority": 5,
      "given": [
        "Plugin provides reset or base styles for typography",
        "Plugin calls addBase({ h1: { fontSize: '2.5rem', fontWeight: 'bold' } })"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "plugin.base_styles_added",
          "payload": [
            "base_rules"
          ]
        }
      ],
      "result": "Base styles injected at @layer base; applied to matched selectors without class needed"
    },
    "multiple_utilities_single_plugin": {
      "priority": 6,
      "given": [
        "Plugin provides multiple utilities (prose-sm, prose-base, prose-lg)"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "utility",
          "fields": [
            "utility_name",
            "utility_values"
          ],
          "count": 3
        }
      ],
      "result": "All utilities registered; each available with responsive variants (md:prose-base, lg:prose-lg)"
    },
    "config_override_by_user": {
      "priority": 7,
      "given": [
        "Plugin extends theme with color (brand: '#FF6B35')",
        "User config also defines brand color (brand: '#FF0000')"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "theme_namespace",
          "value": "{brand: '#FF0000'}"
        }
      ],
      "result": "User-defined color takes precedence; utilities use user's color, not plugin's"
    },
    "plugin_load_failure": {
      "priority": 10,
      "error": "PLUGIN_LOAD_FAILED",
      "given": [
        "Plugin module fails to load or export invalid structure",
        "Plugin does not export a function"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "plugin.load_error",
          "payload": [
            "plugin_name",
            "error_message"
          ]
        }
      ],
      "result": "Build fails; error message indicates which plugin caused failure"
    },
    "plugin_type_mismatch": {
      "priority": 11,
      "error": "INVALID_PLUGIN_API_USAGE",
      "given": [
        "Plugin calls addUtility with invalid value structure",
        "Or addVariant with invalid selector syntax"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "plugin.validation_error",
          "payload": [
            "plugin_name",
            "api_method",
            "error_details"
          ]
        }
      ],
      "result": "Build fails; error indicates which API call was invalid"
    }
  },
  "errors": [
    {
      "code": "PLUGIN_LOAD_FAILED",
      "status": 400,
      "message": "Failed to load plugin module. Check that the plugin is properly exported and accessible."
    },
    {
      "code": "INVALID_PLUGIN_API_USAGE",
      "status": 400,
      "message": "Plugin API call is invalid. Verify utility/variant definition matches expected format."
    },
    {
      "code": "PLUGIN_THEME_CONFLICT",
      "status": 400,
      "message": "Plugin theme values conflict with framework reserved keys. Use a custom namespace."
    }
  ],
  "events": [
    {
      "name": "plugin.utility_created",
      "payload": [
        "utility_name",
        "utility_values"
      ]
    },
    {
      "name": "plugin.variant_created",
      "payload": [
        "variant_name",
        "variant_selector"
      ]
    },
    {
      "name": "plugin.theme_extended",
      "payload": [
        "theme_namespace",
        "new_values"
      ]
    },
    {
      "name": "plugin.instantiated_with_options",
      "payload": [
        "plugin_name",
        "options"
      ]
    },
    {
      "name": "plugin.base_styles_added",
      "payload": [
        "base_rules"
      ]
    },
    {
      "name": "plugin.load_error",
      "payload": [
        "plugin_name",
        "error_message"
      ]
    }
  ],
  "related": [
    {
      "feature": "theme-configuration",
      "type": "recommended",
      "reason": "Plugins can extend theme with custom values"
    },
    {
      "feature": "utility-composition",
      "type": "recommended",
      "reason": "Custom utilities composed with variants like built-in utilities"
    },
    {
      "feature": "build-integration",
      "type": "optional",
      "reason": "Plugins loaded and applied during build process"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_plugin_development",
        "description": "Create and register plugins to extend CSS framework with custom utilities, variants, and theme values",
        "success_metrics": [
          {
            "metric": "success_rate",
            "target": ">= 99.5%",
            "measurement": "Successful operations divided by total attempts"
          },
          {
            "metric": "error_recovery_rate",
            "target": ">= 95%",
            "measurement": "Errors that auto-recover without manual intervention"
          }
        ],
        "constraints": [
          {
            "type": "availability",
            "description": "Must degrade gracefully when dependencies are unavailable",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "create_simple_utility",
          "permission": "supervised"
        },
        {
          "action": "extend_theme_with_colors",
          "permission": "autonomous"
        },
        {
          "action": "create_custom_variant",
          "permission": "supervised"
        },
        {
          "action": "plugin_with_options",
          "permission": "autonomous"
        },
        {
          "action": "plugin_adds_base_styles",
          "permission": "autonomous"
        },
        {
          "action": "multiple_utilities_single_plugin",
          "permission": "autonomous"
        },
        {
          "action": "config_override_by_user",
          "permission": "supervised"
        },
        {
          "action": "plugin_load_failure",
          "permission": "autonomous"
        },
        {
          "action": "plugin_type_mismatch",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "throughput",
        "reason": "integration failures can cascade across systems"
      }
    ]
  },
  "extensions": {
    "tech_stack": {
      "language": "TypeScript / JavaScript",
      "api_style": "Functional (builder pattern)",
      "pattern": "Factory pattern (plugin.withOptions for configurable plugins)"
    },
    "source_location": "packages/tailwindcss/src",
    "plugin_patterns": [
      "Simple: plugin(({ addBase, addUtility, addVariant }) => { ... })",
      "Configurable: plugin.withOptions((options) => (api) => { ... })"
    ]
  }
}