stack-architecture

name	stack-architecture
version	0.1.0
description	Design stack-based systems using @outfitter/* packages. Use when planning new projects, choosing packages, designing handler architecture, or when "architecture", "design", "structure", "plan handlers", or "error taxonomy" are mentioned.
context	fork
agent	stacker
allowed-tools	Read Grep Glob

Stack Architecture Design

Design transport-agnostic handler systems with proper Result types and error taxonomy.

Process

Step 1: Understand Requirements

Gather information about:

• Transport surfaces — CLI, MCP, HTTP, or all?
• Domain operations — What actions does the system perform?
• Failure modes — What can go wrong? (maps to error taxonomy)
• External dependencies — APIs, databases, file system?

Step 2: Design Handler Layer

For each domain operation:

1. Define input type (Zod schema)
2. Define output type
3. Identify possible error types (from taxonomy)
4. Write handler signature: Handler<Input, Output, Error1 | Error2>

Example:

// Input schema
const CreateUserInputSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

// Output type
interface User {
  id: string;
  email: string;
  name: string;
}

// Handler signature
const createUser: Handler<unknown, User, ValidationError | ConflictError>;

Step 3: Map Errors to Taxonomy

Map domain errors to the 10 categories:

Domain Error	Stack Category	Error Class
Not found	not_found	NotFoundError
Invalid input	validation	ValidationError
Already exists	conflict	ConflictError
No permission	permission	PermissionError
Auth required	auth	AuthError
Timed out	timeout	TimeoutError
Connection failed	network	NetworkError
Limit exceeded	rate_limit	RateLimitError
Bug/unexpected	internal	InternalError
User cancelled	cancelled	CancelledError

Step 4: Choose Packages

Packages are organized into three tiers:

Package Tiers

┌─────────────────────────────────────────────────────────────────┐
│                        TOOLING TIER                              │
│  Build-time, dev-time, test-time packages                       │
│  @outfitter/testing                                             │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ depends on
┌─────────────────────────────────────────────────────────────────┐
│                        RUNTIME TIER                              │
│  Application-specific packages for different deployment targets  │
│  @outfitter/cli    @outfitter/mcp    @outfitter/daemon          │
│  @outfitter/config @outfitter/logging @outfitter/file-ops       │
│  @outfitter/state                                               │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ depends on
┌─────────────────────────────────────────────────────────────────┐
│                       FOUNDATION TIER                            │
│  Zero-runtime-dependency core packages                          │
│  @outfitter/contracts    @outfitter/types                       │
└─────────────────────────────────────────────────────────────────┘

Tier	Packages	Dependency Rule
Foundation	contracts, types	No @outfitter/* deps
Runtime	cli, mcp, daemon, config, logging, file-ops, state	May depend on Foundation
Tooling	testing	May depend on Foundation + Runtime

Package Selection

Package	Purpose	When to Use
@outfitter/contracts	Result types, errors, Handler contract	Always (foundation)
@outfitter/types	Type utilities, collection helpers	Type manipulation
@outfitter/cli	CLI commands, output modes, formatting	CLI applications
@outfitter/mcp	MCP server, tool registration	AI agent tools
@outfitter/config	XDG paths, config loading	Configuration needed
@outfitter/logging	Structured logging, redaction	Logging needed
@outfitter/daemon	Background services, IPC	Long-running services
@outfitter/file-ops	Secure paths, atomic writes, locking	File operations
@outfitter/state	Pagination, cursor state	Paginated data
@outfitter/testing	Test harnesses, fixtures	Testing

Selection criteria:

• All projects need @outfitter/contracts (foundation)
• CLI applications add @outfitter/cli (includes UI components)
• MCP servers add @outfitter/mcp
• File operations need both @outfitter/config (paths) and @outfitter/file-ops (safety)

Step 5: Design Context Flow

Determine:

• Entry points — Where is context created? (CLI main, MCP server, HTTP handler)
• Context contents — Logger, config, signal, workspaceRoot
• Tracing — How requestId flows through operations

Output Templates

Architecture Overview

Project: {PROJECT_NAME}
Transport Surfaces: {CLI | MCP | HTTP | ...}

Directory Structure:
├── src/
│   ├── handlers/           # Transport-agnostic business logic
│   │   ├── {handler-1}.ts
│   │   └── {handler-2}.ts
│   ├── commands/           # CLI adapter (if CLI)
│   ├── tools/              # MCP adapter (if MCP)
│   └── index.ts            # Entry point
└── tests/
    └── handlers/           # Handler tests

Dependencies:
├── @outfitter/contracts    # Foundation (always)
├── @outfitter/{package-2}  # {reason}
└── @outfitter/{package-3}  # {reason}

Handler Inventory

Handler	Input	Output	Errors	Description
getUser	GetUserInput	User	NotFoundError	Fetch user by ID
createUser	CreateUserInput	User	ValidationError, ConflictError	Create new user
deleteUser	DeleteUserInput	void	NotFoundError, PermissionError	Remove user

Error Strategy

Domain Errors → Stack Taxonomy:

{domain-error-1} → {stack-category} ({ErrorClass})
  - When: {condition}
  - Exit code: {code}

{domain-error-2} → {stack-category} ({ErrorClass})
  - When: {condition}
  - Exit code: {code}

Implementation Order

1. Foundation — Install packages, create types
2. Core handlers — Implement business logic with tests
3. Transport adapters — Wire up CLI/MCP/HTTP
4. Testing — Integration tests across transports

Constraints

Always:

• Recommend Result types over exceptions
• Map domain errors to taxonomy categories
• Design handlers as pure functions (input, context) → Result
• Consider all transport surfaces upfront
• Include error types in handler signatures

Never:

• Suggest throwing exceptions
• Design transport-specific logic in handlers
• Recommend hardcoded paths
• Skip error type planning
• Couple handlers to specific transports

Related Skills

• outfitter-stack:stack-patterns — Reference for all patterns
• outfitter:tdd — TDD implementation methodology
• outfitter-stack:stack-templates — Templates for components