Outfitter Init

Initialize Outfitter Stack in any codebase — new or existing.

First: Detect the Scenario

Before doing anything, check what we're working with:

ls package.json 2>/dev/null

New Project Scaffolding

For new projects, use the CLI with agent-guided setup.

Step 1: Gather Context

Check for files that inform template choice:

ls CLAUDE.md SPEC.md PLAN.md README.md 2>/dev/null

If context files exist, read them and look for keywords:

• •"CLI", "command-line", "tool" → suggest cli template
• •"MCP", "server", "tools for AI" → suggest mcp template
• •"daemon", "background", "service" → suggest daemon template
• •Otherwise → suggest basic template

Step 2: Ask User Questions

Use AskUserQuestion to clarify before running commands. See references/new-project-scaffolding.md for the full decision flow.

Key questions:

1. •Template type (CLI, MCP, daemon, basic)
2. •Project name
3. •Whether to include tooling (scaffolding block)

Step 3: Run the CLI

outfitter init <template> . --name <name>

Options:

• •--no-tooling — Skip biome, lefthook, claude settings
• •--with <blocks> — Specific blocks: claude, biome, lefthook, bootstrap, scaffolding
• •--force — Overwrite existing files

Step 4: Report and Suggest Next Steps

After scaffolding:

1. •List key files created
2. •Suggest: bun install && bun run dev
3. •Recommend loading outfitter-fieldguide for pattern reference

Migration Workflow

For existing projects, generate a phased adoption plan.

Goal

Produce a structured adoption plan at .agents/plans/outfitter-init/ containing:

1. •Scan results showing what needs conversion (SCAN.md)
2. •Stage-by-stage task files tracking progress (stages/)
3. •Clear completion criteria for each stage

Constraints

DO:

• •Load fieldguide first — it has the patterns, this skill has the workflow
• •Run the setup script to generate the plan
• •Work through stages in dependency order
• •Mark progress in stages/overview.md

DON'T:

• •Skip the scan phase
• •Duplicate fieldguide content (reference it instead)
• •Work on blocked stages before dependencies complete

Steps

1. •Load kit:outfitter-fieldguide — you need it for conversion patterns
2. •Assess the codebase — run the setup script, review SCAN.md
3. •Configure the plan — adjust priorities in stages/overview.md
4. •Execute stage by stage — Foundation → Handlers → Errors → Adapters → Documents
5. •Verify compliance — run outfitter-check, confirm no violations
6. •Delete the plan directory when adoption is complete

Stage 1: Assess

Run the setup script to scan the codebase and generate the plan.

What to Run

# From the plugin directory (when installed):
./skills/outfitter-init/scripts/setup.sh [project-root]

# Or use the skill's scan functionality directly

The script will refuse to run if a plan already exists (won't override).

What Gets Generated

.agents/plans/outfitter-init/
├── PLAN.md       # Entry point with navigation
├── SCAN.md       # Scan results, effort estimates
└── stages/       # Task files for each stage

What to Review in SCAN.md

Decision Point

After reviewing SCAN.md:

• •Greenfield? → Load fieldguide, use its templates directly
• •Migration? → Continue to Stage 2

Stage 2: Configure

Adjust the plan based on your assessment.

What to Do

1. •Open stages/overview.md
2. •Review the status dashboard
3. •Adjust stage order if needed (Paths can run parallel with Handlers)
4. •Add notes about decisions or blockers

Stage Dependencies

Foundation (required first)
    │
    ├── Paths (can run parallel)
    │
    └── Handlers
            │
            ├── Errors
            │
            └── Adapters
                    │
                    └── Documents (last)

Unknowns: Review throughout, resolve before Documents

Stage 3: Execute

Work through stages in order, updating stages/overview.md as you go.

For Each Stage

1. •Open the stage file (e.g., stages/foundation.md)
2. •Work through the checklist items
3. •Reference fieldguide for conversion patterns:
   • •Throws → Result: patterns/conversion.md
   • •Error taxonomy: patterns/errors.md
   • •Logging: patterns/logging.md
   • •Templates: templates/
4. •Mark complete in stages/overview.md
5. •Move to next unblocked stage

Progress Markers

Update stages/overview.md as you work:

Quick Reference

For fast pattern lookup during execution: migration/patterns-quick-ref.md

Stage 4: Verify

Confirm the codebase follows Outfitter Stack patterns.

Verification Commands

Run these — all should return no results:

# No throws in application code
rg "throw new" --type ts -g "!*.test.ts"

# No console logging (except entry points)
rg "console\.(log|error|warn)" --type ts -g "!*.test.ts"

# No hardcoded home paths
rg "homedir\(\)" --type ts

Full Compliance Audit

Run the review skill for comprehensive checking:

/kit:outfitter-check

Completion Criteria

From stages/overview.md:

• • All handlers return Result<T, E>
• • No throw statements in application code
• • No console.log in production code
• • All paths use XDG conventions
• • CLI uses output() and exitWithError()
• • Documentation reflects new patterns
• • All unknowns resolved or documented
• • Tests updated and passing

When Complete

Delete the plan directory:

rm -rf .agents/plans/outfitter-init

Files

Related Skills

• •kit:outfitter-fieldguide — Patterns and templates (load first)
• •kit:outfitter-check — Compliance verification