Component Architecture Skill

This skill defines how the component architect designs the internal structure of a component at a logical level. The component architect is the leaf architecture agent - there is no further delegation to another architecture agent. Developers (human or automated) implement the specifications.

Core Principle

Define WHAT, not HOW. No code snippets. Keep it concise.

Container-Architect assigns responsibilities
              ↓
     [Component Architect]
              ↓
    Logical Design (interfaces, schemas, responsibilities)
              ↓
         Developer implements

Success Factors

1. Clarity

2. Conciseness

3. Completeness

Input: What You Receive

From Architecture Registry

.arch-registry/components/{container}/{component}.md

Contains:

• •Responsibilities (R1, R2, ...) with sources
• •Required interfaces to implement
• •Dependencies on other components

.arch-registry/interfaces/{container}/{interface-name}.md

Contains:

• •Cross-Container Interfaces published by your container and exposed by others

From Container Specifications

{container}/.specs/
├── components.md       # Your context in the container
├── technology.md       # Technology decisions
├── interfaces/         # Container Internal Contracts you must implement
└── data-models/        # Entities you work with

From Constraints

.constraints/TECHNOLOGY.md    # Global tech stack context

Output: What You Create

Concise Specifications ({component}/.specs/)

{component}/.specs/
├── design.md           # Logical structure overview
├── interfaces.md       # All component internal interface definitions not covered by cross-container and container level.
├── schemas.md          # All data schemas
├── test-scenarios.md   # High-level test cases
└── decisions/
    └── ADR-{n}.md      # Significant decisions

Note: You do NOT create code directories or code snippets. Developers do implementation.

Naming Conventions

Directory and Module Names: Use Underscores, Not Hyphens

CRITICAL: All component, module, and directory names MUST use underscores (_), NOT hyphens (-).

Rationale: Python (and many other languages) cannot import modules with hyphens. import document-parser is a syntax error.

This convention ensures component directories can be imported as packages/modules in any language.

Design Process

Step 1: Understand Your Assignment

Read and understand:

1. •Responsibilities from registry entry
2. •Interfaces you must implement
3. •Data models you work with

Step 2: Define Logical Structure

Create a module breakdown:

Step 3: Define Component internal Interfaces

For each module, specify its contract:

Step 4: Define Data Schemas

For each data structure:

Step 5: Define Test Scenarios

High-level test cases (no test code):

Templates

Design Document (design.md)

# {Component Name} - Design

## Overview
{One sentence: what this component does}

## Registry Reference
[{component}.md](path/to/registry/entry.md)

## Modules

| Module | Responsibility | Dependencies |
|--------|---------------|--------------|
| {Name} | {Purpose} | {Dependencies} |

## Module Details

### {ModuleName}

**Responsibility**: {Single sentence}

**Depends on**: {List}

**Provides**: {What it exposes}

## Error Handling

| Error | Condition | Behavior |
|-------|-----------|----------|
| {ErrorName} | {When} | {What happens} |

## Implementation Order

1. {First module}
2. {Second module}

Component Interfaces (interfaces.md)

# {Component Name} - Interfaces

## {ModuleName}

### {methodName}

| Aspect | Definition |
|--------|------------|
| **Purpose** | {What it does} |
| **Parameters** | {name}: {type} - {description} |
| **Returns** | {type} - {description} |
| **Errors** | {ErrorType} - {when thrown} |
| **Preconditions** | {What must be true} |
| **Postconditions** | {What will be true} |

Schemas (schemas.md)

# {Component Name} - Data Schemas

## {EntityName}

**Purpose**: {What this entity represents}

| Field | Type | Required | Constraints |
|-------|------|----------|-------------|
| id | string | Yes | UUID format |
| {field} | {type} | {Yes/No} | {rules} |

Test Scenarios (test-scenarios.md)

# {Component Name} - Test Scenarios

## {ModuleName}

| Scenario | Given | When | Then |
|----------|-------|------|------|
| Happy path | {setup} | {action} | {expected} |
| Error case | {setup} | {action} | {error expected} |
| Edge case | {setup} | {action} | {expected} |

Workflow: Greenfield (New Component)

1. •Read registry entry for responsibilities
2. •Read container interfaces and data models
3. •Create .specs/ directory
4. •Write design.md with module breakdown
5. •Write interfaces.md with all component contracts
6. •Write schemas.md with all data structures
7. •Write test-scenarios.md with test cases
8. •Verify NO code snippets in any spec

Workflow: Brownfield (Feature Request)

When container-architect adds ## Proposed Changes:

1. •Read the proposed changes
2. •Analyze impact on existing modules
3. •Update design.md, interfaces.md, schemas.md
4. •Document new test scenarios
5. •Create ADR if significant decision required

Quality Checklists

Specification Checklist

• • Every module has clear, single responsibility
• • Every interface method is fully specified
• • Every data schema has all fields defined
• • All error conditions documented
• • No code snippets anywhere
• • Specs are concise and table-based

Completeness Checklist

• • All responsibilities from registry mapped to modules
• • All component interfaces implemented
• • All data models accounted for
• • Implementation order specified
• • Test scenarios cover happy path and errors

Anti-Patterns to Avoid

Best Practices

DO:

1. •Use tables - More scannable than prose
2. •Be specific - Exact types, exact constraints
3. •Define all errors - Every failure scenario
4. •Stay logical - No implementation details
5. •Keep concise - Essential information only

DON'T:

1. •Write code - Not even pseudocode
2. •Suggest patterns - Developer's choice
3. •Over-document - Avoid redundancy
4. •Be vague - Ambiguity causes bugs
5. •Exceed scope - Only assigned responsibilities