sideline/.opencode/skills/mainline-architecture/SKILL.md

name, description, compatibility, metadata

name	description	compatibility	metadata
mainline-architecture	Pipeline stages, capability resolution, and core architecture patterns	opencode	audience source_type developers codebase

What This Skill Covers

This skill covers Mainline's pipeline architecture - the Stage-based system for dependency resolution, data flow, and component composition.

Key Concepts

Stage Class (engine/pipeline/core.py)

The Stage ABC is the foundation. All pipeline components inherit from it:

class Stage(ABC):
    name: str
    category: str  # "source", "effect", "overlay", "display", "camera"
    optional: bool = False
    
    @property
    def capabilities(self) -> set[str]:
        """What this stage provides (e.g., 'source.headlines')"""
        return set()
    
    @property
    def dependencies(self) -> set[str]:
        """What this stage needs (e.g., {'source'})"""
        return set()

Capability-Based Dependencies

The Pipeline resolves dependencies using prefix matching:

• "source" matches "source.headlines", "source.poetry", etc.
• "camera.state" matches the camera state capability
• This allows flexible composition without hardcoding specific stage names

Minimum Capabilities

The pipeline requires these minimum capabilities to function:

• "source" - Data source capability
• "render.output" - Rendered content capability
• "display.output" - Display output capability
• "camera.state" - Camera state for viewport filtering

These are automatically injected if missing (auto-injection).

DataType Enum

PureData-style data types for inlet/outlet validation:

• SOURCE_ITEMS: List[SourceItem] - raw items from sources
• ITEM_TUPLES: List[tuple] - (title, source, timestamp) tuples
• TEXT_BUFFER: List[str] - rendered ANSI buffer
• RAW_TEXT: str - raw text strings
• PIL_IMAGE: PIL Image object

Pipeline Execution

The Pipeline (engine/pipeline/controller.py):

1. Collects all stages from StageRegistry
2. Resolves dependencies using prefix matching
3. Executes stages in dependency order
4. Handles errors for non-optional stages

Canvas & Camera

• Canvas (engine/canvas.py): 2D rendering surface with dirty region tracking
• Camera (engine/camera.py): Viewport controller for scrolling content

Canvas tracks dirty regions automatically when content is written via put_region, put_text, fill, enabling partial buffer updates.

Adding New Stages

1. Create a class inheriting from Stage
2. Define capabilities and dependencies properties
3. Implement required abstract methods
4. Register in StageRegistry or use as adapter

Common Patterns

• Use adapters (engine/pipeline/adapters.py) to wrap existing components as stages
• Set optional=True for stages that can fail gracefully
• Use stage_type and render_order for execution ordering
• Clock stages update state independently of data flow

Sources

• engine/pipeline/core.py - Stage base class
• engine/pipeline/controller.py - Pipeline implementation
• engine/pipeline/adapters/ - Stage adapters
• docs/PIPELINE.md - Pipeline documentation