stack-architecture_skill

Overview

This skill designs transport-agnostic, stack-based systems using @outfitter/* packages. It helps you plan handler architecture, choose appropriate packages, and define a clear error taxonomy so handlers return Results instead of throwing. Use it to align domain operations, error mapping, and package tiers for robust, testable services.

How this skill works

It walks through requirements, designs handlers as pure functions with Zod input schemas and explicit Result/error types, and maps domain failures to a 10-category taxonomy. It then recommends package selection across Foundation, Runtime, and Tooling tiers and shows how to structure context flow and transport adapters. Output templates include architecture overviews, handler inventories, and an error strategy to guide implementation order.

When to use it

• Planning a new project and choosing package dependencies
• Designing handler signatures, input/output schemas, and error types
• When architecture, design, structure, or handler plans are discussed
• Defining an error taxonomy or exit-code strategy
• Preparing to support multiple transport surfaces (CLI, MCP, HTTP)

Best practices

• Always use Result types over exceptions and include error types in handler signatures
• Keep handlers transport-agnostic and pure (input, context) → Result
• Map every domain error to the 10-category stack taxonomy (validation, not_found, etc.)
• Start with Foundation packages (@outfitter/contracts) then add Runtime/Tooling as needed
• Design context creation at entry points with logger, config, signal, and requestId tracing

Example use cases

• Define a createUser handler: Zod input, User output, ValidationError | ConflictError in signature
• Plan a CLI + MCP service: include @outfitter/cli and @outfitter/mcp on top of contracts and config
• Map domain errors from an external API to stack categories for consistent exit codes
• Create a handler inventory and tests directory before wiring transport adapters
• Design context propagation so requestId and logger flow through all handlers