Agent skill

stack-architecture

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.

View SKILL.md on GitHub Repository
Stars 26
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/outfitter-dev/agents/tree/main/plugins/outfitter-stack/skills/stack-architecture

SKILL.md

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:

typescript
// 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

outfitter-dev/agents

stack-feedback

Creates GitHub issues for problems discovered while using @outfitter/* packages. Use when finding bugs, missing features, unclear documentation, or improvement opportunities.

26 0
Explore
outfitter-dev/agents

stack-templates

Templates for creating handlers, CLI commands, MCP tools, and daemon services following Outfitter Stack conventions. Use when scaffolding new components, creating handlers, adding commands, or when "create handler", "new command", "add tool", "scaffold", "template", or "daemon service" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-audit

Scan codebase for Outfitter Stack adoption candidates. Identifies throw statements, console usage, hardcoded paths, and custom errors. Use when assessing adoption scope or checking readiness.

26 0
Explore
outfitter-dev/agents

stack-review

Audits code for Outfitter Stack compliance including Result types, error handling, logging patterns, and path safety. Use for pre-commit reviews, code quality checks, migration validation, or when "audit", "check compliance", "review stack", or "stack patterns" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-patterns

Reference for Outfitter Stack patterns including Result types, Handler contract, Error taxonomy, and @outfitter/* package conventions. Use when learning the stack, looking up patterns, understanding packages, or when "Result", "Handler", "error taxonomy", "OutfitterError", "CLI output", "pagination", "MCP server", "MCP tool", "structured logging", "redaction", "test handler", "daemon", "IPC", or "@outfitter/*" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-debug

Troubleshoots Outfitter Stack issues including Result handling, MCP problems, CLI output, exit codes, and logging. Use when debugging stack-specific issues, unexpected errors, wrong output modes, or when "debug Result", "MCP not working", "wrong exit code", or "logging issue" are mentioned.

26 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results