@outfitter/agents

⚠️ DEPRECATED: This package is deprecated. Use npx outfitter add scaffolding instead.

The shadcn-style registry in outfitter CLI now provides the same functionality with better flexibility:

# Add all scaffolding files
npx outfitter add scaffolding

# Or add individual blocks
npx outfitter add claude      # Claude Code settings & hooks
npx outfitter add biome       # Biome configuration
npx outfitter add lefthook    # Git hooks
npx outfitter add bootstrap   # Bootstrap script

See the outfitter CLI documentation for more details.

Agent scaffolding and bootstrap utilities for AI-ready projects.

Installation

bun add @outfitter/agents

Quick Start

Initialize agent documentation in your project:

import { initAgentDocs } from "@outfitter/agents";

await initAgentDocs();

This creates:

• AGENTS.md — Guidelines for AI agents working in your project
• CLAUDE.md — Project-level instructions for Claude
• .claude/CLAUDE.md — Additional Claude-specific guidance
• .claude/settings.json — Claude Code settings
• .claude/hooks/bootstrap.sh — Bootstrap hook script

Features

• Agent Documentation — Scaffolds AGENTS.md and CLAUDE.md templates
• Bootstrap Tooling — Ensures core development tools are installed
• Settings Management — Merges Claude Code settings without overwriting
• CI-Friendly — Quiet mode for automated environments

API Reference

initAgentDocs(options)

Initialize agent documentation in a directory.

interface InitOptions {
  target?: string;   // Target directory (default: cwd)
  merge?: boolean;   // Merge with existing files (default: false)
  force?: boolean;   // Overwrite existing files (default: false)
  quiet?: boolean;   // Suppress output (default: false)
}

// Basic initialization
await initAgentDocs();

// Initialize in specific directory
await initAgentDocs({ target: "/path/to/project" });

// Merge settings.json with existing
await initAgentDocs({ merge: true });

// Force overwrite all files
await initAgentDocs({ force: true });

Behavior:

• Without force or merge, existing files are skipped
• With merge, only settings.json is merged; other files are skipped
• With force, all files are overwritten

bootstrap(options)

Run development environment bootstrap with optional extensions.

interface BootstrapOptions {
  tools?: string[];                  // Additional tools to install
  extend?: () => Promise<void>;      // Project-specific setup
  force?: boolean;                   // Skip checks, run full bootstrap
  quiet?: boolean;                   // Suppress output (for CI)
}

// Basic bootstrap
await bootstrap();

// With additional tools
await bootstrap({
  tools: ["ripgrep", "fd"],
});

// With project extensions
await bootstrap({
  extend: async () => {
    await setupDatabase();
    await seedTestData();
  },
});

// Quiet mode for CI
await bootstrap({ quiet: true });

Core tools installed:

• gh — GitHub CLI
• gt — Graphite CLI for stacked PRs
• markdownlint-cli2 — Markdown linting

Authentication checks:

• GitHub CLI (gh auth status or GH_TOKEN/GITHUB_TOKEN)
• Graphite CLI (gt auth status or GT_AUTH_TOKEN)

mergeSettings(existing, defaults)

Merge Claude Code settings without losing user customizations.

interface SettingsJson {
  mcpServers?: Record<string, unknown>;
  hooks?: Record<string, HookConfig>;
  allowedTools?: string[];
  customInstructions?: string;
  // ... other settings
}

interface HookConfig {
  command: string;
  event: string;
  // ... hook configuration
}

const merged = mergeSettings(existingSettings, defaultSettings);

Merge behavior:

• Arrays are concatenated and deduplicated
• Objects are recursively merged
• User values take precedence over defaults

Generated Files

AGENTS.md

Guidelines for AI agents working in your codebase:

# AGENTS.md

Guidelines for AI agents and developers working in this repository.

## Project Overview
[Project description and context]

## Project Structure
[Directory layout and conventions]

## Commands
[Build, test, lint commands]

## Architecture
[Key patterns and decisions]

CLAUDE.md

Project-level instructions for Claude:

# CLAUDE.md

This file provides AI agents with project-specific context.

@.claude/CLAUDE.md
@AGENTS.md

.claude/settings.json

Claude Code settings with hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "command": ".claude/hooks/bootstrap.sh",
        "event": "Bash",
        "matcher": "bun install"
      }
    ]
  }
}

.claude/hooks/bootstrap.sh

Bootstrap hook that runs after bun install:

#!/bin/bash
# Runs after bun install to ensure environment is ready
bun run bootstrap 2>/dev/null || true

Usage Patterns

CI/CD Bootstrap

// In CI, run quietly and skip interactive prompts
await bootstrap({ quiet: true, force: true });

Monorepo Setup

// Initialize docs at monorepo root
await initAgentDocs({ target: "/path/to/monorepo" });

// Individual packages can extend with their own AGENTS.md

Custom Tool Requirements

await bootstrap({
  tools: ["jq", "yq", "fzf"],
  extend: async () => {
    // Project-specific setup after core tools
    console.log("Running database migrations...");
    await runMigrations();
  },
});

Pre-commit Hook Integration

#!/bin/bash
# .husky/pre-commit or lefthook.yml
bun run -e "import { bootstrap } from '@outfitter/agents'; await bootstrap({ quiet: true })"

Environment Variables

| Variable | Description | |----------|-------------| | GH_TOKEN | GitHub CLI authentication token | | GITHUB_TOKEN | Alternative GitHub token (fallback) | | GT_AUTH_TOKEN | Graphite CLI authentication token |

Platform Support

• macOS: Uses Homebrew for gh and gt installation
• Linux/Windows: Falls back to npm/bun global installs

Related Packages

• @outfitter/cli — CLI framework for building tools
• @outfitter/config — XDG-compliant configuration