spec-kit-contracts 1.0.0

Plugin interface contracts for Spec-Kit - Pure interfaces with zero dependencies

spec-kit-contracts

Pure interface contracts for the Spec-Kit plugin system.

Overview

This package contains only interfaces and contracts that define the communication between the Spec-Kit core and plugins. It has zero dependencies to ensure maximum portability.

Plugin developers should depend only on this package to create plugins that are compatible with the Spec-Kit ecosystem.

Installation

pip install spec-kit-contracts

Usage

Creating a Plugin

from spec_kit_contracts import (
    IPlugin,
    IPluginMetadata,
    PluginBase,
    PluginStatus,
    PluginCapability,
)

class MyPlugin(PluginBase):
    """Example plugin implementation."""

    def _create_metadata(self) -> IPluginMetadata:
        return IPluginMetadata(
            name="my-plugin",
            version="1.0.0",
            author="Your Name",
            description="My awesome plugin",
            capabilities=[PluginCapability.COMMAND, PluginCapability.HOOK],
        )

    def handle_message(self, message):
        """Handle incoming messages."""
        if hasattr(message, 'command_name'):
            if message.command_name == "my-plugin:hello":
                return {"message": "Hello from my plugin!"}
        return None

    def get_config_schema(self):
        """Return configuration schema."""
        return {
            "type": "object",
            "properties": {
                "enabled": {"type": "boolean", "default": True},
            },
        }

Using Service Interfaces

from spec_kit_contracts import (
    IServiceRegistry,
    IFileSystemService,
    IConfigService,
)

class MyPlugin(PluginBase):
    def register_services(self, registry: IServiceRegistry) -> None:
        """Register plugin services with the runtime."""
        registry.register_command("my-plugin:hello", self._handle_hello)
        registry.register_hook("post_save", self._on_file_saved, priority=50)

    def set_services(self, services: dict) -> None:
        """Receive injected services."""
        self.fs: IFileSystemService = services.get("filesystem")
        self.config: IConfigService = services.get("config")

Working with Messages

from spec_kit_contracts import (
    Message,
    Request,
    Response,
    Event,
    Command,
    MessageBuilder,
)

# Create a command message
command = MessageBuilder.command(
    name="design:generate",
    arguments=["my-feature"],
    options={"force": True},
)

# Create an event
event = MessageBuilder.event(
    name="file:saved",
    data={"path": "/path/to/file.py"},
)

# Create a request
request = MessageBuilder.request(
    method="get_config",
    params={"key": "max_lines"},
)

Available Contracts

Plugin Interfaces

Interface	Description
IPlugin	Core plugin protocol (duck typing)
IPluginMetadata	Plugin identity and capabilities
PluginBase	Convenience base class with defaults
PluginStatus	Lifecycle states (INACTIVE, ACTIVE, etc.)
PluginCapability	Declared capabilities (COMMAND, HOOK, etc.)

Service Interfaces

Interface	Description
IServiceRegistry	Register commands, hooks, services
IConfigService	Read/write configuration
IFileSystemService	File operations with safety
ITemplateService	Template rendering
ILoggingService	Structured logging
IEventService	Pub/sub events
IStateService	Persistent state

Message Types

Type	Description
Message	Base message class
Request	Method call expecting response
Response	Response to a request
Event	Notification/broadcast
Command	Direct execution
Query	Information request

Exceptions

Exception	Description
ContractError	Base contract error
PluginContractError	Plugin contract violation
MessageContractError	Message contract violation
ServiceContractError	Service contract violation

Design Principles

1. Zero Dependencies: This package has no external dependencies
2. Protocol-Based: Uses Python Protocols for duck typing
3. Type Safe: Full type annotations for IDE support
4. Minimal: Only interfaces, no implementations
5. Stable API: Semantic versioning for breaking changes

Version Compatibility

spec-kit-contracts	spec-kit-runtime	spec-kit-core
1.x	1.x	1.x

License

MIT License - see LICENSE file for details.