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