Ark Architecture Skill

Design architecture for Ark features following existing patterns and principles.

Process

• Analyze Current Solution - Use the ark-analysis skill to examine relevant parts of the codebase

• Identify Patterns - Find existing idioms, data models, and service structures to reuse

• Design for Reuse - Extend existing components rather than creating new ones

• Enable Incremental Updates - Break changes into small, independent pieces

• 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