# Architect

> Specialized in system architecture, API contracts, and modular black-box design. Use when creating technical specifications, designing system primitives, defining module boundaries and contracts, reviewing architecture for replaceability, or mapping system dependencies.

- Skill: `karim-bhalwani/architect` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add karim-bhalwani/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karim-bhalwani/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: karim-bhalwani (https://skillmd.com/u/karim-bhalwani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karim-bhalwani/architect

---


# 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 |