CLI Plugin and Extension Reference Prompt

This prompt is designed for CLI platform engineers who own a plugin system and need to produce a complete, accurate developer reference from working code. The ideal user has direct access to the plugin loading source code, the interface or abstract base class that plugins must implement, and at least one reference plugin implementation that demonstrates the contract correctly. The job-to-be-done is turning these implementation artifacts into a structured document that plugin developers can rely on: installation paths, API contracts, lifecycle hooks, version compatibility constraints, and discovery mechanisms. If you are maintaining a CLI tool that supports extensions and you need to onboard third-party developers, this prompt converts your internal implementation knowledge into an external-facing reference.

You should use this prompt when you can provide concrete source artifacts. The prompt expects placeholders like [PLUGIN_LOADER_SOURCE] for the code that discovers and initializes plugins, [PLUGIN_INTERFACE_DEFINITION] for the abstract class or interface that plugins must satisfy, and [REFERENCE_PLUGIN_SOURCE] for a working example that validates the contract. The harness around this prompt should validate the generated reference against the actual plugin loading code to catch mismatches in method signatures, expected return types, or lifecycle hook ordering. For high-risk plugin systems where a bad plugin could crash the host CLI or corrupt user data, the output must include explicit error-handling contracts and require human review before publication.

Do not use this prompt when you lack source access or when the plugin system exists only as a design document without a working implementation to validate against. If you are speculating about a plugin architecture that has not been built, the generated reference will be untestable and likely incorrect. Similarly, avoid this prompt if you cannot provide a reference plugin implementation; without a concrete example, the model cannot verify that the documented contract matches what the loader actually expects. For purely conceptual plugin designs, start with an architecture decision record prompt instead, and return to this prompt only after you have working code and a reference plugin that loads successfully.

This template is designed to ingest your plugin interface source code, configuration schemas, and any existing developer documentation to produce a comprehensive plugin reference. It forces the model to document the contract—installation paths, API surfaces, lifecycle hooks, and discovery mechanisms—rather than just describing the plugin in prose. Replace every square-bracket placeholder with your specific code, schemas, and constraints before use.

textCopy
You are a technical writer for a CLI platform team. Your task is to produce a complete plugin and extension developer reference from the provided source code and plugin definitions.

## INPUT
- Plugin interface source code:
[PLUGIN_INTERFACE_SOURCE_CODE]

- Plugin manifest or configuration schema:
[PLUGIN_CONFIG_SCHEMA]

- Example plugin implementations (optional):
[EXAMPLE_PLUGIN_CODE]

- Existing developer docs (optional):
[EXISTING_DEV_DOCS]

## OUTPUT SCHEMA
Return a single JSON object with the following structure:
{
  "plugin_reference": {
    "overview": "string describing the plugin system's purpose and architecture",
    "installation_paths": [
      {
        "path": "string (e.g., ~/.cli/plugins, $CLI_PLUGIN_DIR)",
        "priority": "number (load order, lower = higher priority)",
        "description": "string"
      }
    ],
    "discovery_mechanism": {
      "method": "string (e.g., directory scan, manifest file, registry)",
      "description": "string",
      "configuration_required": "boolean"
    },
    "plugin_interface": {
      "required_exports": [
        {
          "name": "string (function, class, or variable name)",
          "type": "string (function, class, variable)",
          "signature": "string",
          "description": "string",
          "required": "boolean"
        }
      ],
      "optional_exports": [
        {
          "name": "string",
          "type": "string",
          "signature": "string",
          "description": "string"
        }
      ]
    },
    "lifecycle_hooks": [
      {
        "hook_name": "string",
        "trigger": "string (when the hook fires)",
        "arguments": "string (arguments passed to the hook)",
        "expected_return": "string",
        "description": "string"
      }
    ],
    "version_compatibility": {
      "plugin_api_version": "string",
      "minimum_cli_version": "string",
      "deprecated_versions": ["string"],
      "version_negotiation": "string (how plugins declare and check compatibility)"
    },
    "error_handling": {
      "plugin_load_failures": "string (what the CLI does when a plugin fails to load)",
      "runtime_errors": "string (how plugin errors are surfaced to users)",
      "isolation_guarantees": "string (process isolation, memory, crash boundaries)"
    },
    "example_plugin": {
      "code": "string (a minimal but complete working plugin)",
      "explanation": "string (walkthrough of the example)"
    }
  }
}

## CONSTRAINTS
- Document every required and optional export found in the plugin interface source code.
- If the source code defines a version constant or compatibility check, include it in version_compatibility.
- The example_plugin.code must be syntactically correct and runnable given the documented interface.
- If any field cannot be determined from the provided source, set its value to null and add a note in the description.
- Do not invent plugin hooks, exports, or behaviors not present in the source code.
- Use the exact function signatures and type names from the source code.

## RISK_LEVEL
Medium. Plugin documentation errors can cause integration failures for downstream developers. A human reviewer must verify the documented interface against the actual source code before publication.

After pasting this template, replace each placeholder with your actual source code and schemas. The [PLUGIN_INTERFACE_SOURCE_CODE] placeholder should contain the exact interface file that plugin authors must implement—typically a base class, a set of function signatures, or a protocol definition. The [PLUGIN_CONFIG_SCHEMA] should include your manifest format, whether it's a JSON schema, a YAML structure, or a Python setup.cfg entry point definition. If you have working example plugins, include them in [EXAMPLE_PLUGIN_CODE] to ground the model's output in real patterns. Run the output through a JSON schema validator before accepting it, and always diff the documented exports against the source interface to catch omissions.

The CLI Plugin and Extension Reference Prompt is designed to be embedded in a documentation generation pipeline, not used as a one-off chat interaction. The harness must supply structured inputs—plugin interface definitions, lifecycle hook signatures, installation paths, and version compatibility matrices—and validate the generated reference against the actual plugin loading code. This section covers the integration points, validation gates, and retry logic needed to make the prompt reliable in production.

Wire the prompt into a pipeline that first extracts the plugin contract from source code. For a Go CLI using a plugin interface, parse the interface definition, exported methods, and any registration or discovery mechanism. Feed these into the prompt as [INPUT] along with a [CONTEXT] block containing the CLI version, supported plugin API versions, and known compatibility constraints. The prompt should produce a structured reference document with sections for interface specs, lifecycle hooks, installation paths, and example plugins. After generation, run a schema validator that checks the output against a defined [OUTPUT_SCHEMA]—verify that every documented method signature matches the parsed source interface, that all lifecycle hooks (init, execute, cleanup, shutdown) are present, and that installation paths reference real filesystem conventions. If validation fails, log the specific missing or mismatched fields and trigger a retry with the validation errors appended to the [CONSTRAINTS] block.

For retry logic, implement a two-pass approach. On the first pass, use a capable model (Claude 3.5 Sonnet or GPT-4o) with the full prompt template. If the schema validator returns errors, construct a repair prompt that includes the original output, the validation error list, and an instruction to fix only the flagged issues while preserving the rest of the document. Limit retries to two attempts; if the output still fails validation, route it to a human review queue with the validation report attached. Log every generation attempt—model used, token counts, validation pass/fail status, and retry count—so you can track prompt drift over time. For CLI tools with multiple plugins, batch the generation per plugin interface and run validations in parallel to keep the pipeline fast.

When the prompt output passes validation, inject it into your documentation site build. Add a drift detection step that runs weekly: re-parse the plugin source code, regenerate the reference, and diff it against the published version. Flag any new methods, changed signatures, or deprecated hooks for review. This keeps the plugin reference synchronized with the actual codebase without requiring manual audits. Avoid using this prompt for plugins with unstable or undocumented internal APIs—if the source code lacks clear interface boundaries, the generated reference will be speculative and should be marked as draft with a human-review gate before publication.