# Outfitter Start

> Start with Outfitter — scaffold new projects or adopt patterns in existing codebases. Detects context, scans for adoption candidates, and orchestrates phased conversion.

- Skill: `outfitter-dev/outfitter-start` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add outfitter-dev/outfitter-start`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/outfitter-start/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outfitter-dev/outfitter-start

---


# Outfitter Start

Start with Outfitter — new projects or existing codebase adoption.

## Steps

1. **Detect scenario** — Check for `package.json`:
   - No package.json → **New project** (continue to [New Project Scaffolding](#new-project-scaffolding))
   - Has package.json → **Existing project** (continue to step 2)
2. **Load skills** — Load `outfitter-atlas` (patterns) and `context-management` (task persistence).
3. **Scan** — Run the setup script to generate `.agents/plans/outfitter-start/` with scan results and staged plan.
4. **Review** — Present SCAN.md findings to user. Use AskUserQuestion for scope and priority decisions.
5. **Execute stages** — Work through stages in dependency order:
   - **Foundation** — Scaffold Result types, logger, dependencies (outfitter-atlas)
   - **Handlers** — TDD handler conversions (tdd-fieldguide + outfitter-atlas)
   - **Errors** — Map custom errors to taxonomy
   - **Adapters** — Wire CLI/MCP transport layers
   - **Documents** — Update docs to reflect new patterns
6. **Verify** — Load `outfitter-check` for compliance audit.
7. **Feedback** — If issues discovered, load `outfitter-issue` to report.
8. **Persist** — Update Tasks throughout with progress and decisions.

---

## New Project Scaffolding

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

### Step 1: Gather Context

Check for files that inform preset choice:

```bash
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` preset
- "MCP", "server", "tools for AI" → suggest `mcp` preset
- "daemon", "background", "service" → suggest `daemon` preset
- Otherwise → suggest `minimal` preset

### Step 2: Ask User Questions

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

**Key questions:**

1. Preset type (CLI, MCP, daemon, minimal)
2. Project name
3. Whether to include tooling (scaffolding block)

### Step 3: Run the CLI

```bash
outfitter init <cli|mcp|daemon> . --name <name>
# Or: outfitter init . --preset <preset> --name <name>
```

**Options:**

- `--no-tooling` — Skip linter, lefthook, claude settings
- `--with <blocks>` — Specific blocks: `claude`, `linter`, `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-atlas` for pattern reference

---

## Migration Workflow

For existing projects, generate a phased adoption plan.

### Goal

Produce a structured adoption plan at `.agents/plans/outfitter-start/` 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 `outfitter-atlas` — you need it for conversion patterns
2. [Assess the codebase](#stage-1-assess) — run the setup script, review SCAN.md
3. [Configure the plan](#stage-2-configure) — adjust priorities in `stages/overview.md`
4. [Execute stage by stage](#stage-3-execute) — Foundation → Handlers → Errors → Adapters → Documents
5. [Verify compliance](#stage-4-verify) — 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

```bash
# From the plugin directory (when installed):
./skills/outfitter-start/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-start/
├── PLAN.md       # Entry point with navigation
├── SCAN.md       # Scan results, effort estimates
└── stages/       # Task files for each stage
```

### What to Review in SCAN.md

| Finding                    | Meaning                                                 |
| -------------------------- | ------------------------------------------------------- |
| 0 throws, 0 custom errors  | Greenfield — skip to Foundation, use fieldguide presets |
| 1-5 throws                 | Low effort — straightforward conversions                |
| 6-15 throws                | Medium effort — plan your approach                      |
| 16+ throws                 | High effort — work through stages methodically          |
| Custom error classes       | Map each to taxonomy (see `stages/errors.md`)           |
| High console count         | Lots of logging to convert (see `stages/handlers.md`)   |
| Package Discovery table    | Review all `@outfitter/*` options before installing     |
| High blast radius handlers | Split into caller-focused sub-phases before converting  |

`@outfitter/types` should be treated as **optional** unless the target project
has clear branded-type or utility adoption points.

### Decision Point

After reviewing SCAN.md:

- **Greenfield?** → Load fieldguide, use its presets 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](${CLAUDE_PLUGIN_ROOT}/shared/patterns/conversion.md)
   - **Error taxonomy**: [patterns/errors.md](${CLAUDE_PLUGIN_ROOT}/shared/patterns/errors.md)
   - **Logging**: [patterns/logging.md](${CLAUDE_PLUGIN_ROOT}/shared/patterns/logging.md)
   - **Templates**: [templates/](${CLAUDE_PLUGIN_ROOT}/shared/templates/)
4. Mark complete in `stages/overview.md`
5. Move to next unblocked stage

### Progress Markers

Update `stages/overview.md` as you work:

| Status         | When to Use                         |
| -------------- | ----------------------------------- |
| ⬜ Not Started | Haven't begun this stage            |
| 🟡 In Progress | Currently working on it             |
| ✅ Complete    | All checklist items done            |
| 🔴 Blocked     | Waiting on another stage            |
| ⏭️ Skipped     | Not applicable (e.g., no MCP tools) |

### Quick Reference

For fast pattern lookup during execution: [migration/patterns-quick-ref.md](migration/patterns-quick-ref.md)

## Stage 4: Verify

Confirm the codebase follows Outfitter patterns.

### Verification Commands

Run these — all should return no results:

```bash
# 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:

```
/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:

```bash
rm -rf .agents/plans/outfitter-start
```

## Files

| File                                                                           | Purpose                                |
| ------------------------------------------------------------------------------ | -------------------------------------- |
| [references/new-project-scaffolding.md](references/new-project-scaffolding.md) | Full guide for new project setup       |
| [scripts/setup.sh](scripts/setup.sh)                                           | Entry point — generates migration plan |
| [migration/assessment.md](migration/assessment.md)                             | Decision tree for scope evaluation     |
| [migration/patterns-quick-ref.md](migration/patterns-quick-ref.md)             | Quick lookup → links to fieldguide     |
| [references/manual-scan.md](references/manual-scan.md)                         | Manual ripgrep commands                |

## Related Skills

- `outfitter-atlas` — Patterns and templates (load first)
- `outfitter-check` — Compliance verification