Generates patterns, templates, and guides for @outfitter/* packages. Covers transport-agnostic handler systems, Result types, error taxonomy, and package APIs. Use when working with @outfitter/*, Result types, Handler contract, error taxonomy, or when Result, Handler, ValidationError, NotFoundError, OutfitterError, or package names like contracts, cli, mcp, schema, tui, daemon, config, logging are mentioned.
Instalar con Codex o Claude Copia este prompt, pรฉgalo en Codex, Claude u otro asistente, y deja que revise la pรกgina de la skill y la instale por ti.
Un comando directo omite el prompt de revisiรณn. Revisa el origen antes de ejecutarlo.
Generates patterns, templates, and guides for @outfitter/* packages. Covers transport-agnostic handler systems, Result types, error taxonomy, and package APIs. Use when working with @outfitter/*, Result types, Handler contract, error taxonomy, or when Result, Handler, ValidationError, NotFoundError, OutfitterError, or package names like contracts, cli, mcp, schema, tui, daemon, config, logging are mentioned.
Outfitter Atlas
Your trail map for building with @outfitter/* packages. This guide covers the patterns, the templates, andโjust as importantlyโthe *why* behind it all.
Why We Built This
We kept solving the same problems across projects: config loading, error handling, CLI output modes, MCP server boilerplate. Every tool needed the same foundation. So we extracted it.
Agents Are the New Users
The patterns assume you're building tools that agents will consumeโstructured output, typed errors, predictable behavior. Humans benefit too; agents just make the stakes clearer.
When an AI agent calls your CLI or MCP tool, it needs:
Structured output it can parse (JSON when explicitly requested)
Typed errors with categories it can reason about (retry? abort? ask user?)
Predictable exit codes for scripting and automation
Consistent behavior across transport surfaces
Outfitter enforces these properties by design, not discipline.
Errors Are Data, Not Exceptions
Traditional error handling (throw/catch) loses context, breaks type safety, and makes control flow unpredictable. We treat errors as first-class data:
Ten categories cover all failure modes. Each maps to exit codes (CLI) and HTTP status (API/MCP). Agents can make retry decisions without parsing error strings.
Tests First, Always
Tests define behavior; implementations follow. The workflow:
Red: Write a failing test that defines expected behavior
Green: Minimal code to pass
Refactor: Improve while staying green
The test proves the behavior exists. A failing test proves it doesn'tโyet.
One Definition, Many Derivations
Types, schemas, and contracts have exactly one source:
Concern
Source of Truth
Derives
Input validation
Zod schema
TypeScript types, JSON Schema
Error categories
ErrorCategory type
Exit codes, HTTP status
CLI flag names
Handler input types
MCP tool parameters
If two things must stay in sync, one derives from the other.
Bun-Native When Possible
Bun APIs before npm packagesโfaster, zero-dependency:
Need
Use
Hashing
Bun.hash()
Globbing
Bun.Glob
Semver
Bun.semver
Shell
Bun.$
SQLite
bun:sqlite
UUID v7
Bun.randomUUIDv7()
The Core Idea
Handlers are pure functions returning Result<T, E>. CLI and MCP are thin adapters over the same logic. Write the handler once, expose it everywhere.
# Foundation first
bun add @outfitter/contracts
# Then what you need
bun add @outfitter/cli # CLI apps
bun add @outfitter/mcp # MCP servers
bun add @outfitter/logging # Structured logging
bun add @outfitter/config # XDG-compliant config
bun add @outfitter/index # Full-text search# Dev dependencies
bun add -D @outfitter/testing @outfitter/tooling
