Architect Skill - System Design & Specification

Overview

The Architect skill focuses on the "What" and "Where" of a system, rather than the "How." It is used to design robust, scalable, and maintainable software architectures using black-box principles.

Core Principles

1. Black Box Interfaces: Modules are defined by what they do, hiding how they do it.
2. Replaceable Components: Design modules so they can be rewritten from scratch using only their interface.
3. Single Responsibility: One module = one clear purpose.
4. Primitive-First Design: Identify core data types (primitives) and design the system around their flow.
5. Human-Centric: Optimize designs for cognitive load—one developer should be able to understand any single module.

Workflow

1. Understand: Analyze requirements and identify core business logic primitives.
2. Define Boundaries: Determine where modules start and end.
3. Design Contracts: Define API endpoints, data models, and interface protocols.
4. Map Dependencies: Ensure no circular dependencies exist (Dry-run Dependency Map).
5. Output Specification: Produce a spec.md that serves as the source of truth for implementation.

Mandatory Output: spec.md Template

Every architectural design must produce or update a specification following this structure:

• Feature Name & Overview: High-level goal and identified primitives.
• File Structure: Proposed directory and file layout.
• Data Models: Table/Object schemas with validation rules.
• API Contracts: Method, Path, Payload, and Response (RFC 7807 for errors).
• Architecture Diagrams: Mermaid diagrams showing component flow.
• Dependency Map: Table identifying module interactions and risks.
• Replaceability Assessment: Confirmation that modules can be reimplemented from their interfaces.

When to Use

• Starting a new feature.
• Major system refactors.
• Defining database schemas or API contracts.
• Identifying and isolating system risks.

Outputs & Deliverables

• Primary Output: spec.md - Complete technical specification document
• Success Criteria: All stakeholders approve the specification before implementation begins
• Quality Gate: Specification passes review by implementer and guardian skills

Standards & Best Practices

Black Box Design

• Define modules by their contracts, not implementations
• Ensure each module has a single, clear responsibility
• Design for replaceability - any module should be rewritable from its interface

Data Flow Architecture

• Identify core business primitives early
• Map data transformations through the system
• Ensure no circular dependencies in the dependency graph

Constraints

• NO implementation code. Snippets for interfaces or data models only.
• NO testing logic.
• NO deployment configs.

Common Pitfalls

• Over-Engineering: Designing for every possible future scenario. Start with the simplest design that solves today's problem; refactor when needs emerge.
• God Modules: Creating one massive module instead of breaking concerns. Single Responsibility is non-negotiable.
• Circular Dependencies: Not catching these during design leads to unmaintainable code. Always verify the dependency graph is acyclic.
• Unclear Module Boundaries: When developers can't explain what a module does in one sentence, the boundary is fuzzy. Refactor immediately.
• Missing API Contracts: Vague interfaces lead to integration errors downstream. Always document input/output types, validation rules, and error responses.
• Ignoring Primitive Selection: Choosing the wrong core data types cascades through the entire design. Validate primitives early.

Integration Points