---
name: ark-architecture
description: Design architecture for Ark features following existing patterns and principles. Use when planning new features, extending components, or evaluating technical approaches.
---

# Ark Architecture Skill

Design architecture for Ark features following existing patterns and principles.

## Process

1. **Analyze Current Solution** - Use the ark-analysis skill to examine relevant parts of the codebase
2. **Identify Patterns** - Find existing idioms, data models, and service structures to reuse
3. **Design for Reuse** - Extend existing components rather than creating new ones
4. **Enable Incremental Updates** - Break changes into small, independent pieces
5. **Flag One-Way Decisions** - Raise questions on choices that are hard to reverse

## Principles

- **Reuse over creation** - Extend existing services, models, and patterns
- **Follow existing idioms** - Match current code style, naming, and structure
- **Incremental delivery** - Design so features can be shipped in stages
- **Reversibility** - Identify and question decisions that lock in future options

## Conventions

- **Watch endpoints**: Use `?watch=true` query param for SSE streaming (Kubernetes-style)
- **Service ports**: Use named ports (e.g., `port: mcp`) rather than port numbers

## Output

Architecture documents should include:
- Component diagram showing how new pieces fit with existing ones
- Data model extending current schemas
- API design following existing conventions
- List of one-way decisions requiring team input
- Implementation phases for incremental delivery