# Core Plugins Specifications

This directory contains comprehensive specifications for Kollabor CLI core plugins.

## Purpose

Core plugin specs provide complete architectural documentation for recreating,
understanding, and extending Kollabor's plugin system. Each spec includes:

- Architecture overview and design patterns
- Complete API documentation with method signatures
- Data models and type definitions
- UI workflows and interaction patterns
- Event system integration
- Error handling strategies
- Testing strategies with mock dependencies
- Implementation checklists

## Available Specs

### tmux_plugin_spec.md

Comprehensive specification for the Tmux Plugin.

features:
  - tmux session management (new, view, list, kill)
  - live streaming view with keyboard passthrough
  - isolated tmux server (configurable)
  - session cycling with keyboard navigation
  - configurable capture lines from history

slash commands:
  - /terminal new &lt;name&gt; [cmd]   create session
  - /terminal view [name]        live view (cycles if no name)
  - /terminal list               list all sessions
  - /terminal kill &lt;name&gt;        kill session
  - /t                           alias for /terminal

architecture:
  - isolated tmux server with configurable socket
  - live modal integration with input callback
  - status bar integration

### resume_conversation_plugin_spec.md

Comprehensive specification for the Resume Conversation Plugin.

features:
  - session management (resume, browse, search, filter)
  - conversation branching from any message point
  - modal-based interactive session selection
  - search with relevance scoring
  - current conversation branching

slash commands:
  - /resume [id] [--force]      resume or browse sessions
  - /sessions [search query]    browse or search
  - /branch [id] [index]        three-step branching workflow

architecture:
  - event-driven with MODAL_COMMAND_SELECTED hook
  - dependency injection (6 services)
  - modal UI with keyboard navigation
  - message coordinator integration

### background_tasks_plugin_spec.md

Comprehensive specification for the Background Tasks Plugin.

features:
  - async command execution without blocking
  - output buffering with circular buffer
  - process groups with auto-cleanup
  - LLM integration with XML tool calls
  - task lifecycle management (start, status, output, kill, wait)

slash commands:
  - /bg [list|kill|output|clear]    manage background tasks

architecture:
  - asyncio subprocess management
  - task registry with status tracking
  - XML command parsing
  - display filter integration

### agent_orchestrator_plugin_spec.md

Comprehensive specification for the Agent Orchestrator Plugin.

features:
  - parallel agent spawning via XML commands
  - tmux-based agent isolation
  - activity monitoring with MD5 hashing
  - result injection to conversation
  - team spawning and broadcast messaging

slash commands:
  - CLI args: --session, --capture, --list-agents

architecture:
  - XMLCommandParser for command parsing
  - AgentOrchestrator for tmux management
  - ActivityMonitor for idle detection
  - MessageInjector for result injection

### system_commands_plugin_spec.md

Specification for the System Commands Plugin.

features:
  - status view for core system commands
  - agnoster-style segment display

architecture:
  - status bar integration
  - minimal plugin (commands registered by core)

### hook_monitoring_plugin_spec.md

[SHOWCASE] Comprehensive specification demonstrating ALL plugin ecosystem features.

features:
  - hook monitoring and performance tracking
  - plugin discovery via PluginFactory
  - cross-plugin service registration via SDK
  - direct plugin-to-plugin communication
  - interactive dashboard with stats, errors, health, services

architecture:
  - Hook execution counting and metrics
  - performance baseline and degradation detection
  - SDK and factory integration examples
  - plugin health monitoring

### save_conversation_plugin_spec.md

Specification for the Save Conversation Plugin.

features:
  - export to transcript, markdown, jsonl formats
  - clipboard support (macOS)
  - auto-generated filenames with timestamps
  - status bar integration

slash commands:
  - /save [format] [file]    save conversation

architecture:
  - command registration and handling
  - format-specific renderers
  - file and clipboard output

### workflow_enforcement_plugin_spec.md

Comprehensive specification for the Workflow Enforcement Plugin.

features:
  - todo list detection in LLM responses
  - sequential step enforcement
  - tool call verification
  - user confirmation and bypass support
  - state machine workflow management

architecture:
  - pattern-based todo detection
  - WorkflowContext state tracking
  - step verification with TOOL_CALL_POST hook
  - multi-state workflow enforcement

### setup_wizard_plugin_spec.md

Specification for the Setup Wizard Plugin.

features:
  - interactive first-time user onboarding
  - single-screen configuration form
  - profile management integration
  - keyboard shortcuts and slash commands reference
  - full-screen modal with animations

architecture:
  - FullScreenPlugin base class
  - form navigation with Tab/Arrows
  - configuration validation
  - manager injection (config, profile_manager)

### fullscreen_framework_plugin_spec.md

Comprehensive specification for the Full-Screen Framework.

features:
  - FullScreenPlugin base class
  - FullScreenRenderer for terminal management
  - drawing primitives (boxes, progress bars, spinners)
  - animation framework with easing functions
  - keyboard handling with modifier support
  - color system with gradient rendering

architecture:
  - plugin lifecycle (initialize, on_start, render_frame, handle_key, on_end)
  - component system (drawing, animation, input, color)
  - render loop with FPS control

### matrix_plugin_spec.md

Specification for the Matrix Rain Plugin.

features:
  - iconic digital rain effect
  - column-based animation with varying speeds
  - multiple character sets (katakana, binary, mixed)
  - customizable colors and speed

architecture:
  - MatrixRenderer component
  - column state management
  - trail effect rendering
  - keyboard controls for speed, color, characters

### space_shooter_plugin_spec.md

Comprehensive specification for the Space Shooter Plugin.

features:
  - retro 80s arcade-style gameplay
  - starfield with parallax
  - player ship with banking
  - enemy spawning and AI
  - laser shooting and collision detection
  - particle explosion effects
  - score and lives system

architecture:
  - SpaceShooterRenderer component
  - game objects (Star, Player, Enemy, Laser, Particle)
  - collision detection system
  - particle system for explosions

Comprehensive specification for the Tmux Plugin.

features:
  - tmux session management (new, view, list, kill)
  - live streaming view with keyboard passthrough
  - isolated tmux server (configurable)
  - session cycling with keyboard navigation
  - configurable capture lines from history

slash commands:
  - /terminal new <name> [cmd]   create session
  - /terminal view [name]        live view (cycles if no name)
  - /terminal list               list all sessions
  - /terminal kill <name>        kill session
  - /t                           alias for /terminal

architecture:
  - isolated tmux server with configurable socket
  - live modal integration with input callback
  - status bar integration

### resume_conversation_plugin_spec.md

Comprehensive specification for the Resume Conversation Plugin.

features:
  - session management (resume, browse, search, filter)
  - conversation branching from any message point
  - modal-based interactive session selection
  - search with relevance scoring
  - current conversation branching

slash commands:
  - /resume [id] [--force]      resume or browse sessions
  - /sessions [search query]    browse or search
  - /branch [id] [index]        three-step branching workflow

architecture:
  - event-driven with MODAL_COMMAND_SELECTED hook
  - dependency injection (6 services)
  - modal UI with keyboard navigation
  - message coordinator integration

## Usage

These specs are intended for:

1. recreating plugins from scratch
2. understanding plugin architecture patterns
3. extending existing plugins
4. training new developers on plugin system
5. documenting plugin capabilities

## Directory Structure

```
docs/plugins/
├── core/                        # Core plugin specifications
│   ├── README.md               # This file
│   ├── tmux_plugin_spec.md     # Tmux session management
│   └── resume_conversation_plugin_spec.md
└── community/                   # Community plugin specs (future)
```

## Related Documentation

- /docs/reference/hook-system-sdk.md      # Hook system development guide
- /docs/reference/slash-commands-guide.md # Slash command system
- /docs/features/RESUME_COMMAND_SPEC.md   # Resume feature requirements
- /CLAUDE.md                              # Plugin development guidelines

## Contributing

When adding new plugin specs, ensure they include:

- [x] complete architecture overview
- [x] all method signatures with docstrings
- [x] data model definitions
- [x] workflow diagrams
- [x] event system integration details
- [x] error handling patterns
- [x] testing strategy
- [x] implementation checklist
- [x] configuration examples
- [x] dependency requirements

## Maintenance

Plugin specs should be updated when:

- plugin architecture changes significantly
- new features are added to plugins
- event system integration changes
- data models are modified
- breaking changes are introduced

Keep specs synchronized with actual plugin implementations to ensure
they remain useful as reference documentation.
