System Operations Manager CLI Assistant

Expert assistant for working with the System Operations Manager - a Python-based CLI framework for managing distributed systems, deployments, monitoring, and infrastructure operations.

What This Skill Does

Provides comprehensive guidance for developing, testing, and maintaining the System Operations Manager CLI. Covers architecture patterns, plugin development, testing strategies, and best practices specific to this codebase.

Instructions

When working with this repository, follow these guidelines:

1. Understand the Architecture

The system uses a layered architecture:

```

User Interface (CLI/REPL/REST API)

↓

Command Processing (Router, Validation, Error Handling)

↓

Core Engine (Plugin Manager, Config Manager, State Management)

↓

Service Layer (Deployment, Monitoring, System Control)

↓

Integration Layer (External APIs, File System, SSH)

```

**Key architectural patterns:**

- Plugins inherit from `Plugin` base class

- Must implement: `initialize()`, `register_commands()`, `cleanup()`

- Entry points defined in `pyproject.toml` under `[tool.poetry.plugins."system_operations_manager.plugins"]`

1. Default → 2. System → 3. User → 4. Project → 5. Environment vars → 6. CLI args

2. Source Structure

```

src/system_operations_manager/

├── cli/ # CLI command definitions (Typer)

├── core/ # Core engine and plugin system

├── logging/ # Structured logging with structlog

├── services/ # Business logic services

├── integrations/ # External tool integrations

├── plugins/ # Built-in plugins

└── utils/ # Utility functions

```

3. Development Workflow

**Setup and dependencies:**

```bash

Install core dependencies

poetry install

Install all optional dependencies

poetry install --all-extras

Install pre-commit hooks

pre-commit install

```

**Optional dependency groups:**

**Code quality checks:**

```bash

Lint code

ruff check src tests

Format code

ruff format src tests

Type check

mypy src

Run all pre-commit checks

pre-commit run --all-files

```

4. Testing Strategy

**Running tests:**

```bash

Run all tests

pytest

Run specific file

pytest tests/unit/test_version.py

Pattern match

pytest -k "test_status"

Verbose output

pytest -v

With coverage

pytest --cov=system_operations_manager

```

**Test markers available:**

**Coverage target:** 80%+

5. CLI Usage

```bash

Show version

poetry run ops --version

Show system status

poetry run ops status

Initialize project config

poetry run ops init

```

The CLI entry point is `ops` command via `system_operations_manager.cli.main:main`.

6. Commit Conventions

Uses conventional commits with commitlint validation:

**Format:** `type(scope): description`

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`

**Scopes:** `adr`, `config`, `docs`, `examples`, `features`, `integrations`, `plugins`, `commands`, `deps`, `release`, `setup`

**Rules:**

**Example:** `feat(plugins): add hot-reload support for custom plugins`

7. Plugin Development Best Practices

When creating or modifying plugins:

1. Inherit from the `Plugin` base class

2. Implement all required methods: `initialize()`, `register_commands()`, `cleanup()`

3. Register plugin entry points in `pyproject.toml`

4. Add appropriate test coverage with relevant markers

5. Document configuration options and CLI commands

6. Handle errors gracefully with proper logging

8. Configuration Management

When working with configuration:

1. Respect the configuration hierarchy (default → system → user → project → env → CLI)

2. Use profile inheritance for shared configurations

3. Validate configuration values before use

4. Document all configuration options

5. Provide sensible defaults

Important Notes

Example Usage

**Scenario:** Adding a new monitoring plugin

1. Create plugin class inheriting from `Plugin` in `src/system_operations_manager/plugins/`

2. Implement required methods with monitoring logic

3. Register entry point in `pyproject.toml`

4. Add unit tests with `@pytest.mark.unit` and integration tests with `@pytest.mark.monitoring`

5. Update documentation

6. Run quality checks: `ruff check && mypy src && pytest --cov`

7. Commit: `feat(plugins): add Datadog monitoring integration`

**Scenario:** Debugging test failures

1. Run specific test: `pytest tests/unit/test_plugin.py -v`

2. Check logs in test output

3. Use markers to isolate: `pytest -k "test_plugin_init"`

4. Run with coverage to identify gaps: `pytest --cov=system_operations_manager.plugins`