# System Commands Plugin Specification

## Overview

The System Commands Plugin provides a status view for core system commands. Note: The actual commands (/help, /config, /status, etc.) are registered by the core application in `_initialize_slash_commands()`. This plugin only provides the status bar display.

**Location:** `plugins/system_commands_plugin.py`

**Version:** 1.0.0

## Features

### Status View Display

- **Agnoster-style segment**: Displays "Commands Active" with agnoster styling
- **Quick reference**: Shows available system commands: /help /config /status
- **High priority display**: Priority 400 ensures visibility in status bar

## Architecture

### Plugin Structure

```python
class SystemCommandsPlugin:
    - initialize(event_bus, config, **kwargs) -> None
    - shutdown() -> None
    - _register_status_view() -> None
    - _get_status_content() -> List[str]
    - register_hooks() -> None
    - get_default_config() -> Dict[str, Any]
```

### Status View Configuration

```python
StatusViewConfig(
    name="System Commands",
    plugin_source="system_commands",
    priority=400,
    blocks=[
        BlockConfig(
            width_fraction=1.0,
            content_provider=self._get_status_content,
            title="System Commands",
            priority=100
        )
    ]
)
```

## Display Format

### Agnoster Segment

The status view renders as:

```
Commands Active /help /config /status
```

With agnoster color scheme:
- "Commands" - lime on dark
- "Active" - cyan on dark
- "/help /config /status" - neutral on mid

## Configuration

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable the plugin |

### Configuration File

Edit `~/.kollabor-cli/config.json`:

```json
{
  "plugins": {
    "system_commands": {
      "enabled": true
    }
  }
}
```

## Core System Commands

These commands are registered by the core application, not this plugin:

| Command | Description |
|---------|-------------|
| `/help` | Show help information and available commands |
| `/config` | Open configuration modal |
| `/status` | Show system status and plugin information |

## Implementation Details

### Registration Process

1. **Core initialization**: `_initialize_slash_commands()` in main app registers /help, /config, /status
2. **Plugin initialization**: `SystemCommandsPlugin.initialize()` registers status view
3. **Status bar**: Status renderer displays the agnoster segment

### Dependency Requirements

- `renderer.status_renderer.status_registry`: Required for status view registration
- `core.io.visual_effects.AgnosterSegment`: Used for rendering styled segments

## Error Handling

### Common Errors

| Error | Cause | Resolution |
|-------|-------|------------|
| Status view not registered | No renderer or status registry | Check renderer initialization |
| Segment render error | AgnosterSegment import failed | Check visual_effects module |

## Implementation Checklist

### Core Functionality
- [x] Status view registration
- [x] Agnoster segment rendering
- [x] System commands display
- [x] Error handling for missing dependencies

### Configuration
- [x] Default config
- [x] Enable/disable toggle

## Related Documentation

- /docs/reference/slash-commands-guide.md - Slash command system
- /docs/reference/status-bar.md - Status bar architecture
- /docs/core/system-commands.md - Core system commands

## Architecture Notes

### Separation of Concerns

The System Commands Plugin demonstrates proper separation of concerns:
- **Core application**: Registers actual slash commands
- **Plugin**: Provides visual feedback in status bar

This pattern allows the status display to be disabled or customized without affecting the underlying command functionality.

### Minimal Plugin

This plugin is intentionally minimal:
- No hook registration needed
- No slash commands (uses core commands)
- Single responsibility: status view display
- Good reference for simple status bar plugins
