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

Phase	Input From	Output To	Context
Discovery	brainstorming, thinker	This spec	Understand requirements and constraints
Specification	Core business logic	implementer, data-modeler	Implement according to spec
Validation	N/A	guardian	Review for security and patterns
Operations	Deployment requirements	ops-manager	Infrastructure needs based on architecture