slaminar

Intelligent project analyzer and setup tool for Claude Code.

Run slaminar init on any codebase and it will automatically analyze your project, generate a tailored CLAUDE.md, scaffold Claude Code plugins, and recommend the best ecosystem tools for your stack.

Korean Documentation (한국어)

Table of Contents

• Demo
• Features
• Installation
  • Claude Code Skill Auto-Deployment
• Usage
  • First-Run Setup (v0.6+)
  • Project Discovery & Batch Apply (v0.7+)
  • Environment Diagnostics (slaminar doctor)
  • Claude Code Skill Reference
• Project Analysis
• Generated Output
• Dynamic Catalog
  • Creating a Custom Catalog
  • Persistent Catalog Configuration
  • Catalog Federation (v0.8+)
• Verification
• Error Handling & Safety
• Tech Stack
• Architecture
• Development
• Implementation History
• Roadmap
• Project Stats
• FAQ
• Contributing
• License

$ slaminar init /path/to/your-project

━━━ slaminar init complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Profile:
  ┌──────────┬────────────┐
  │ Name     │ your-app   │
  │ Language │ typescript │
  │ Pattern  │ spa        │
  │ Maturity │ growing    │
  └──────────┴────────────┘

  Generated Files:
  ┌──────────────────────────────────────────────────┬────────┐
  │ File                                             │ Action │
  ├──────────────────────────────────────────────────┼────────┤
  │ CLAUDE.md                                        │ create │
  │ .claude/plugins/slaminar-generated/plugin.json   │ create │
  │ .claude/plugins/slaminar-generated/skills/dev.md │ create │
  └──────────────────────────────────────────────────┴────────┘

  Recommended Tools:
  ┌──────────────────────┬───────┬─────────────┐
  │ Tool                 │ Score │ Install      │
  ├──────────────────────┼───────┼─────────────┤
  │ impeccable           │ 65    │ marketplace  │
  │ everything-claude-code│ 55   │ git-clone    │
  │ planning-with-files  │ 45    │ npx          │
  └──────────────────────┴───────┴─────────────┘

  Verification: ✅ 9/9 checks pass

  Report saved: .slaminar/reports/2026-04-14-init.md

Features

7-Phase Pipeline

scan → analyze → recommend → plan → generate → place → verify

| Phase | What It Does | |-------|-------------| | Scan | Collects project structure, package manifests, Git history, AI context files, CI/CD config, and docs | | Analyze | Detects language/framework, architecture pattern, coding conventions, dependencies, and maturity level | | Recommend | Multi-dimensional scoring + conflict/synergy detection + maturity-based tool limits for smart recommendations | | Plan | Builds a generation plan (which files to create or merge) | | Generate | Produces CLAUDE.md (with ownership markers) + Claude Code plugin (plugin.json + skills) | | Place | Backs up existing files with obfuscated names, then merges via marker-based sections | | Verify | Validates CLAUDE.md commands, plugin.json schema, and generated file integrity |

Smart Tool Recommendations

The tool catalog contains 46 Claude Code ecosystem tools (with an online catalog that can be updated independently of releases). slaminar automatically selects the right ones for your project.

How it works:

• Multi-dimensional scoring (language/framework match, maturity fit, tag overlap)
• Conflict and overlap detection (e.g., caveman vs. everything-claude-code)
• Maturity-based limits (greenfield: 2, early: 3, growing: 5, mature: 7)
• Tools requiring external authentication are automatically excluded
• Custom catalog URL support via --catalog <url> for private/enterprise catalogs

Safe File Management

• Ownership markers: <!-- slaminar:begin:SECTION --> / <!-- slaminar:end:SECTION --> track generated sections. Content you wrote by hand is never touched.
• Obfuscated backups: .slaminar/.bk/{hex6}_{timestamp}.dat — stored in a format that IDEs and AI tools won't accidentally pick up.
• Incremental updates: slaminar update only regenerates changed sections.
• Full rollback: slaminar uninstall restores everything to its original state.

Claude Code Skill Integration

Since v0.5.0, installing slaminar globally also registers it as a Claude Code skill so it becomes invokable with /slaminar or by natural language ("set up this project", "slaminar ../other-repo 에 돌려줘").

• Auto-deployment via an npm postinstall hook — drops SKILL.md into ~/.claude/skills/slaminar/ without any manual step. Always graceful: never fails npm install, opts out in CI and for transitive installs, and can be disabled with SLAMINAR_SKIP_POSTINSTALL=1.
• Path parameterization — the skill accepts an optional <path>. If the user mentions a folder in their request, Claude forwards it to slaminar init <path>; otherwise the current working directory is used.
• Content-hash idempotence — reinstalling is a no-op when the bundled SKILL.md matches the installed copy. A modified SKILL.md is backed up to ~/.config/slaminar/skill-backups/ before being replaced, and slaminar skill uninstall restores the most recent backup.
• Explicit commands — slaminar skill install/uninstall/status mirror the auto-install flow when you need manual control.

See Claude Code Skill Reference under Usage for the full command surface, and Claude Code Skill Auto-Deployment under Installation for the postinstall contract.

Team Collaboration

| File | Git Committed | Purpose | |------|:---:|------| | .slaminar/config.json | Yes | Team settings (approved tools, catalog version) | | .slaminar/config.local.json | No | Personal settings (AI mode, personal tools) | | .slaminar/reports/*.md | Yes | Setup reports (useful for PR reviews) | | .slaminar/.bk/ | No | Backup files |

Config schema and defaults:

.slaminar/config.json (team, committed):

{
  "slaminarVersion": "0.1.0",
  "excludeAuthTools": true,
  "fileCountCap": 10000,
  "approvedTools": [],
  "catalogVersion": "",
  "catalogUrl": "",
  "catalogMode": "replace"
}

| Field | Description | |-------|-------------| | slaminarVersion | Version of slaminar that generated this config | | excludeAuthTools | Auto-exclude tools requiring external authentication | | fileCountCap | Max files scanned in file-tree analysis | | approvedTools | Team-approved tool names (empty = accept all recommendations) | | catalogVersion | Catalog version used at setup time (reserved for future version-pinning) | | catalogUrl | Custom catalog URL (empty = official catalog). Set via slaminar catalog config --url | | catalogMode | replace (default) or extend. Set via slaminar catalog config --mode |

.slaminar/config.local.json (personal, gitignored):

{
  "aiMode": "auto",
  "personalTools": []
}

| Field | Description | |-------|-------------| | aiMode | auto (detect provider), ai (require AI), or local (no AI) | | personalTools | Reserved for future per-user tool additions (not yet active) |

Installation

npm install -g slaminar

Or run directly with npx:

npx slaminar init .

Requirements

• Node.js >= 18
• Git (optional — used for history analysis)

Claude Code Skill Auto-Deployment

When you install slaminar globally, it also registers itself as a Claude Code skill so you can invoke it with /slaminar (or by asking naturally: "set up Claude Code for this project"). The skill is placed at:

~/.claude/skills/slaminar/SKILL.md

Path parameterization — the skill accepts an optional target path. If you mention a folder in your request ("slaminar ~/work/other-repo 에 돌려줘"), Claude forwards it to slaminar init <path>. Otherwise the current directory is used.

Managing the skill:

slaminar skill status      # Show whether the skill is installed and matches the bundled version
slaminar skill install     # Reinstall (creates a backup if content differs)
slaminar skill install --force
slaminar skill uninstall   # Remove (restores your previous SKILL.md if one was backed up)

Opting out of the auto-install during npm install -g:

SLAMINAR_SKIP_POSTINSTALL=1 npm install -g slaminar

The postinstall hook is also skipped automatically in CI (CI=true) and during local/transitive installs, and can never cause npm install itself to fail — any error is logged as a warning and exits 0.

Usage

Basic Setup

# Preview without writing files
slaminar init --dry-run .

# Run the full pipeline
slaminar init .

# Verbose output with detailed analysis
slaminar init --verbose .

# Disable AI enhancement (use local rules only)
slaminar init --no-ai .

# Use a custom/private tool catalog
slaminar init --catalog https://company.com/catalog.json .

First-Run Setup (v0.6+)

A single command walks you through every global preference slaminar needs. Re-runs on demand to reconfigure just one section.

slaminar setup                          # Interactive 6-step wizard (first run)
slaminar setup --reconfigure auth       # Re-run just the AI provider step
slaminar setup --reconfigure catalog    # Re-run just the catalog step
slaminar setup --reconfigure defaults   # aiMode / excludeAuthTools / fileCountCap / versionCheck
slaminar setup --reconfigure skill      # Claude Code skill auto-install preference
slaminar setup --yes                    # Non-interactive (CI) — reads SLAMINAR_* env vars
slaminar setup --no-discovery           # Skip the optional Step 6 project scan
slaminar setup --yes --apply-to-discovered   # CI: scan + apply init/update to every find

Non-interactive --yes mode reads environment variables for every decision:

| Env var | Purpose | |---|---| | SLAMINAR_AI_PROVIDER | cloudflare or anthropic — selects provider | | SLAMINAR_CF_TOKEN, SLAMINAR_CF_ACCOUNT_ID, SLAMINAR_CF_MODEL | Cloudflare credentials | | SLAMINAR_ANTHROPIC_KEY, SLAMINAR_ANTHROPIC_MODEL | Anthropic credentials | | SLAMINAR_CATALOG_URL, SLAMINAR_CATALOG_MODE | Custom catalog source | | SLAMINAR_DEFAULT_AI_MODE | auto / ai / local | | SLAMINAR_EXCLUDE_AUTH_TOOLS | true / false | | SLAMINAR_FILE_COUNT_CAP | Integer | | SLAMINAR_VERSION_CHECK | true / false — weekly npm version check | | SLAMINAR_DISCOVER_ROOTS | Comma/space-separated roots for Step 6 discovery | | SLAMINAR_BATCH_APPROVED | Explicit list of discovered project roots to apply | | SLAMINAR_BATCH_DRY_RUN | true to force dry-run during batch apply | | SLAMINAR_ONLY_NEW | true to restrict batch apply to status === 'new' projects | | SLAMINAR_IMPORT_TEAM_CATALOG | true to auto-import team catalogUrl into user defaults |

Project Discovery & Batch Apply (v0.7+)

Scan user-specified roots for Claude Code projects and optionally run init / update across all of them at once.

slaminar discover ~/work ~/projects              # One-shot scan with ASCII table
slaminar discover                                # Re-uses the last roots from defaults.json
slaminar discover ~/work --json                  # Machine-readable output
slaminar discover ~/work --apply --dry-run       # Scan + preview every init/update
slaminar discover ~/work --apply --only-new      # Only operate on projects classified "new"
slaminar discover ~/work --no-cache              # Force a fresh scan (ignore 24h cache)

Classification:

| Status | Meaning | Suggested action | |---|---|---| | new | Has .claude/ but no CLAUDE.md | init | | configured | Has .slaminar/config.json | update | | existing | Has CLAUDE.md but no .claude/ | init-merge (preserves content) | | unsupported | No detectable language or signature | skip |

Safety notes:

• The walker stops descending as soon as it confirms a project, so $HOME-wide scans stay fast.
• node_modules, .git, .venv, .cache, .turbo, macOS Library/, Applications/, etc. are excluded by default.
• Symlinks are not followed; cycles are caught via realpath inode tracking.
• Every batch run writes a markdown audit log to ~/.config/slaminar/setup-logs/batch-<timestamp>.md.
• The scan result is cached at ~/.config/slaminar/discovery-cache.json (24 h TTL) — pass --no-cache to force refresh.

Environment Diagnostics (slaminar doctor)

Read-only health check. Exits 0 (all pass), 1 (warnings), or 2 (failures).

slaminar doctor            # Human-readable report
slaminar doctor --json     # Machine-readable for CI

Checks include:

• Node.js and git versions
• slaminar version and skill installation status
• AI provider availability (auth.json + env vars)
• Catalog cache freshness
• Write permissions for ~/.config/slaminar/ and ~/.claude/skills/slaminar/
• defaults.json validity

AI Enhancement (Optional)

AI-powered CLAUDE.md enhancement is set up during slaminar setup and applied across all your projects.

Providers

Cloudflare Workers AI (recommended):

• Free tier: 10,000 Neurons/day (more than enough for typical usage)
• Minimum permission: Workers AI: Read
• Default model: @cf/meta/llama-3.3-70b-instruct-fp8-fast (24K context)
• Also supports: Llama 3.1 8B, Mistral Small 3.1, Gemma 3, Qwen 2.5 Coder

Anthropic Claude:

• Highest quality, paid
• Model: claude-sonnet-4
• Requires: npm install @anthropic-ai/sdk

Configuration Priority

| Source | Priority | Use Case | |--------|:---:|------| | CLI flag (--no-ai) | 1 (highest) | One-off disable | | Environment variables (CLOUDFLARE_*, ANTHROPIC_API_KEY) | 2 | CI / ephemeral | | ~/.config/slaminar/auth.json (mode 0600) | 3 | Saved via slaminar setup | | (none) | 4 | Local rules only |

Individual Commands

# Project scan (JSON output)
slaminar scan .

# Project analysis (JSON output)
slaminar analyze .

# Tool recommendation (JSON output)
slaminar recommend .
slaminar recommend --catalog https://example.com/catalog.json .

# Health check
slaminar status .

# Incremental update (changed sections only)
slaminar update .

# Remove a specific tool from team config
slaminar remove caveman

# Full uninstall + restore
slaminar uninstall .

# CI validation (non-interactive, exit codes)
slaminar check .
slaminar check --json .

Catalog Management

The tool catalog can be updated without upgrading slaminar itself:

slaminar catalog update                    # Fetch latest catalog + show diff
slaminar catalog update --catalog <url>    # Fetch from custom URL
slaminar catalog list                      # Table view of all tools
slaminar catalog search <query>            # Search by name, tags, or description
slaminar catalog check                     # Detect deprecated tools + show replacements
slaminar catalog info <name>               # Detailed tool info
slaminar catalog status                    # Cache status (age, validity, source)
slaminar catalog rollback                  # Restore previous catalog version
slaminar catalog config                    # View/set persistent catalog URL + mode

Deprecation detection: Tools in the catalog can be marked deprecated: true with an optional deprecatedReason and replacedBy field. Running slaminar catalog check scans your recommended tools against the catalog and warns about deprecated ones, showing the reason and suggested replacement.

Claude Code Skill Reference

After npm install -g slaminar (or a manual slaminar skill install), the skill file lives at ~/.claude/skills/slaminar/SKILL.md and Claude Code discovers it automatically.

Invocation patterns Claude recognizes:

| User phrasing | Claude runs | |---|---| | /slaminar | slaminar init --dry-run . → asks for approval → slaminar init . | | "set up Claude Code for this project" | same as above, current CWD | | "slaminar 돌려줘" | same as above, current CWD | | "slaminar ../legacy-app 에 돌려줘" | slaminar init --dry-run ../legacy-app → approval → slaminar init ../legacy-app | | "analyze ~/work/other-repo with slaminar" | same, with the resolved absolute path | | "slaminar update this repo" | slaminar update <path> | | "slaminar status" | slaminar status <path> |

The SKILL.md template instructs Claude to extract <path> from the user's request (absolute, relative, or ~-prefixed) and fall back to . when no path is mentioned.

Skill subcommands (for managing the skill itself):

slaminar skill status                # Report install state + content match with bundled version
slaminar skill install               # Install / update at ~/.claude/skills/slaminar/SKILL.md
slaminar skill install --force       # Overwrite even when content is identical (still backs up)
slaminar skill uninstall             # Remove and restore the most recent backup (if any)

Example — first-time install on a fresh machine:

$ slaminar skill status

Claude Code Skill Status
  Path:      /Users/me/.claude/skills/slaminar/SKILL.md
  Installed: no
  Bundled:   available

$ slaminar skill install

✓ Skill installed at /Users/me/.claude/skills/slaminar/SKILL.md

Example — reinstall over a hand-edited SKILL.md:

$ slaminar skill install

✓ Skill updated at /Users/me/.claude/skills/slaminar/SKILL.md
  Previous version backed up to /Users/me/.config/slaminar/skill-backups/SKILL_a1b2c3_1713412800.md

Example — uninstall with backup restore:

$ slaminar skill uninstall

✓ Uninstalled and restored previous SKILL.md from /Users/me/.config/slaminar/skill-backups/SKILL_a1b2c3_1713412800.md

Opt-out during npm install -g:

SLAMINAR_SKIP_POSTINSTALL=1 npm install -g slaminar   # explicit opt-out
CI=true npm install -g slaminar                       # auto-skipped

The postinstall hook additionally skips itself for non-global (local/transitive) installs so installing slaminar as a library dependency of another project will not touch your home directory.

Safety guarantees:

• postinstall wraps everything in try/catch and redirects errors to a warning line, exiting with code 0 — npm install is never blocked.
• Content comparison uses SHA-256 so a byte-identical SKILL.md is skipped silently (idempotent re-install).
• Any pre-existing SKILL.md is copied into ~/.config/slaminar/skill-backups/ before being overwritten.
• slaminar skill uninstall removes the skill file and, if a backup exists, writes the most recent one back as SKILL.md — so the previous custom skill is restored without manual intervention.

Flags

| Flag | Description | Available On | |------|-------------|-------------| | --dry-run | Preview only, no files written | init, update | | --verbose | Detailed analysis output | init, recommend, status | | --json | Machine-readable JSON output | check | | --no-ai | Skip AI enhancement | init | | --catalog <url> | Use a custom catalog URL | init, recommend, catalog update | | --catalog-mode <mode> | Catalog mode: extend or replace | init, recommend, catalog update |

Project Analysis

Supported Languages & Frameworks

| Language | Framework Detection | Package Manager | |----------|-------------------|-----------------| | TypeScript/JavaScript | React, Vue, Svelte, Angular, Next, Nuxt, Express, Fastify, Koa, Hono, NestJS | npm (package.json) | | Python | Django, Flask, FastAPI | pip (pyproject.toml) | | Rust | Actix, Axum | cargo (Cargo.toml) | | Go | Gin, Echo | go (go.mod) | | Java/Kotlin/Scala | Spring | maven (pom.xml) | | Elixir | Phoenix | — |

Architecture Pattern Detection

| Pattern | Detection Criteria | |---------|-------------------| | CLI | commander, yargs, meow, or similar CLI framework dependencies | | SPA | React/Vue/Svelte + Vite/Webpack | | API | Express/Fastify/Koa or similar server frameworks | | Fullstack | SPA + API detected simultaneously | | Library | Package manager present but no framework detected | | Monorepo | Multiple package manager files |

Maturity Assessment

| Maturity | Criteria | Max Tools | |----------|----------|:---------:| | greenfield | No git, no packages, no source files | 2 | | early | < 10 commits | 3 | | growing | 10–200 commits | 5 | | mature | 200+ commits or 5+ contributors + CI | 7 |

Convention Detection

• Naming: camelCase, kebab-case, snake_case (from source filenames)
• Test framework: vitest, jest, pytest, etc.
• Linter/formatter: ESLint, Prettier
• Commit style: conventional, emoji, freeform
• Doc language: ko, en, ja, zh (from filename patterns)

Generated Output

CLAUDE.md

Sections are managed via ownership markers:

# CLAUDE.md

This file provides guidance to Claude Code...

<!-- slaminar:begin:overview -->
## Overview
Project description, language, framework, pattern, maturity
<!-- slaminar:end:overview -->

<!-- slaminar:begin:commands -->
## Build & Development Commands
Auto-extracted from package.json scripts
<!-- slaminar:end:commands -->

## My Custom Section       ← slaminar will never touch this
Custom content...

<!-- slaminar:begin:architecture -->
## Architecture
Architecture pattern, layout, entry points, test patterns
<!-- slaminar:end:architecture -->

When a CLAUDE.md already exists:

1. The original is backed up with an obfuscated filename (.slaminar/.bk/a7f3c2_1713081600.dat)
2. Only sections within markers are updated
3. All user-authored content outside markers is fully preserved

Claude Code Plugin

.claude/plugins/slaminar-generated/
├── plugin.json          # Plugin manifest
└── skills/
    └── dev.md           # Development workflow (build/test/lint commands)

Reports

.slaminar/reports/YYYY-MM-DD-init.md — automatically generated Markdown reports containing:

• Project profile
• List of generated files
• Recommended/excluded tools with reasons
• Verification results

These can be included in PRs for team review.

Dynamic Catalog

slaminar's tool catalog is designed to evolve independently of CLI releases:

• Online catalog: 46 tools fetched from GitHub (catalog/catalog.json in this repo), updated without upgrading slaminar
• Local cache: ~/.config/slaminar/catalog-cache.json with 24-hour TTL and file permission 0600
• Fallback chain: valid cache → remote fetch → stale cache → bundled fallback (always works offline)
• ETag support: conditional HTTP requests — if the remote catalog hasn't changed, the server responds 304 Not Modified and no data is transferred
• Catalog diff: slaminar catalog update shows added, removed, deprecated, and updated tools in colored terminal output
• Custom catalog URL: point to your own catalog with --catalog <url> for enterprise or private tool registries
• Rollback: slaminar catalog rollback restores the previous catalog version from catalog-cache.prev.json

How the fallback chain works:

slaminar catalog update (or init/recommend)
  │
  ├─ 1. Is there a valid cache? (< 24 hours old)
  │     YES → use cached catalog
  │     NO  ↓
  ├─ 2. Fetch from remote URL (with ETag if available)
  │     200 OK    → save to cache, use new catalog
  │     304       → mark cache as fresh, use cached
  │     FAIL      ↓
  ├─ 3. Is there a stale cache? (expired but exists)
  │     YES → use stale cache (with warning)
  │     NO  ↓
  └─ 4. Use bundled catalog (14 tools, always available)

Catalog Tools (46)

| Category | Tools | |----------|-------| | Token/Performance | caveman, everything-claude-code, moyu | | Planning/Spec | planning-with-files, get-shit-done, spec-kit | | Frontend | impeccable, senior-frontend | | Testing/QA | playwright-skill, tdd-guard, test-kitchen | | Memory/Context | claude-mem, reporecall, knowledge-graph | | Code Analysis | graphify, cartographer | | Security | trailofbits/skills, awesome-claude-skills-security | | Quality Gate | vibeguard, review-squad, obey | | Team/Workflow | oh-my-claudecode, vibe-kanban, ccpm | | Multi-Agent | wshobson/agents, claude-code-subagents | | DevOps/IaC | terraform-skill, hashicorp/agent-skills, devops-claude-skills, container-use | | Database | supabase/agent-skills, pg-aiguide | | Framework | laravel/agent-skills, claude-on-rails, apollographql/skills, developer-kit, rafaelkamimura/claude-tools, claude-elixir-phoenix | | Onboarding/Utility | claude-code-templates, cc-safe-setup, preflight | | Monitoring/LSP | claude-hud, claude-code-lsps, homunculus |

Full list: slaminar catalog list

Creating a Custom Catalog

You can host your own catalog and use it with --catalog <url>. The catalog must follow the RemoteCatalog JSON schema.

Deep dive (v0.8.5+): see docs/catalog-authoring-guide.md for a step-by-step authoring guide (5-minute tutorial, full schema tables, local-file examples, extend/replace patterns, and troubleshooting). For a curated "what is this tool and when to use it" index of every entry in the bundled catalog — including the new presentation category — see docs/catalog-tools-reference.md.

Minimum format (only tools is required):

{
  "tools": [
    {
      "name": "my-internal-tool",
      "repo": "company/internal-tool",
      "category": "skill",
      "description": "Internal code review tool",
      "authRequired": false,
      "networkRequired": "none",
      "installMethod": "git-clone",
      "installCommands": ["git clone https://git.company.com/tool.git ~/.claude/skills/tool"],
      "prerequisites": [],
      "tags": ["code-review", "internal"],
      "maturityFit": ["growing", "mature"]
    }
  ]
}

Full format (all optional fields included):

{
  "version": "1.0.0",
  "minSlaminarVersion": "0.2.0",
  "updatedAt": "2026-04-16T00:00:00Z",
  "tools": [],
  "suggestions": [],
  "relations": []
}

CatalogTool fields:

| Field | Type | Required | Description | |-------|------|:--------:|-------------| | name | string | Yes | Unique tool name | | repo | string | Yes | GitHub owner/repo | | category | string | Yes | plugin, skill, hook, agent, or workflow | | description | string | Yes | Short description | | authRequired | boolean | Yes | Requires external auth (excluded from recommendations if true) | | networkRequired | string | Yes | none, partial, or full | | installMethod | string | Yes | marketplace, npx, git-clone, or pip | | installCommands | string[] | Yes | Shell commands to install | | prerequisites | string[] | Yes | Runtime requirements (e.g., ["python>=3.10"]) | | tags | string[] | Yes | Scoring tags (e.g., ["typescript", "testing"]) | | maturityFit | string[] | Yes | greenfield, early, growing, mature | | deprecated | boolean | No | Mark as deprecated | | deprecatedReason | string | No | Why deprecated | | replacedBy | string | No | Successor tool name |

Usage:

# One-off via CLI flag
slaminar init --catalog https://company.com/catalog.json .
slaminar recommend --catalog https://company.com/catalog.json .
slaminar catalog update --catalog https://company.com/catalog.json

# Or host it on any static server / internal registry

When version, suggestions, or relations are omitted, slaminar uses sensible defaults (empty arrays, version "0.0.0").

Persistent Catalog Configuration

Instead of passing --catalog <url> every time, you can save the custom catalog URL and mode in your project config:

# Set custom catalog in extend mode (merge with official)
slaminar catalog config --url https://company.com/catalog.json --mode extend

# Set custom catalog in replace mode (custom only)
slaminar catalog config --url https://company.com/catalog.json --mode replace

# View current configuration
slaminar catalog config

# Clear configuration (revert to official catalog)
slaminar catalog config --clear

Extend vs. Replace modes:

| Mode | Behavior | |------|----------| | extend | Custom tools are merged with the official catalog. If both catalogs have a tool with the same name, the custom version wins. | | replace | Only the custom catalog is used. The official catalog is ignored (bundled catalog remains as offline fallback). |

Precedence (highest to lowest):

| Source | Priority | |--------|:--------:| | CLI flags (--catalog, --catalog-mode) | 1 (highest) | | Project config (.slaminar/config.json) | 2 | | Default (official catalog, replace mode) | 3 |

Note: --catalog <url> without --catalog-mode defaults to replace mode for backward compatibility.

Team scenarios:

# Enterprise: extend official catalog with company tools
slaminar catalog config --url https://tools.company.com/catalog.json --mode extend
# → Team members get official + company tools after git pull

# Security team: only allow approved tools
slaminar catalog config --url https://security.company.com/approved.json --mode replace
# → Only security-approved tools are recommended

Extend mode diagram:

slaminar recommend (with extend mode)
  │
  ├─ 1. Resolve official catalog (fallback chain)
  │     → 46 official tools
  │
  ├─ 2. Fetch custom catalog
  │     → N custom tools
  │     (if fetch fails → use official only + warning)
  │
  └─ 3. Merge: official + custom
        → Same-name tools: custom wins
        → Relations: deduplicated union
        → Suggestions: official only

Catalog Federation (v0.8+)

v0.8 promotes catalogUrl to an array of layered sources with explicit priority so teams can mix a company catalog, a personal catalog, and a security-approved allowlist without losing the official one. The legacy single-URL config still works — it's surfaced as a single *-legacy source on load.

Priority layers (ascending, higher wins):

| Priority | Scope | Where it lives | |---:|---|---| | -1 | bundled | Built into the binary — always available | | 0 | official | Default GitHub-hosted catalog | | 100+ | user | ~/.config/slaminar/defaults.json → catalog.sources[] | | 200+ | project | .slaminar/config.json → catalogSources[] (git-committed) | | 500 | env | SLAMINAR_CATALOG_SOURCES environment variable | | 999 | cli | --catalog <url> CLI flag (adhoc) |

A replace-mode layer drops every lower-priority layer entirely. Multiple extend layers stack; name collisions award the higher layer.

Manage sources via slaminar catalog source:

# Add a company catalog at the project scope (git-committed)
slaminar catalog source add https://tools.company.com/catalog.json \
  --scope project --mode extend --name company

# Add a personal catalog at the user scope (gitignored by design)
slaminar catalog source add ~/my-catalog.json --scope user --name personal

# Security team overrides everything below them
slaminar catalog source add https://sec.company.com/approved.json \
  --scope project --mode replace --priority 300 --name security-allowlist

# Inspect every active layer in priority order
slaminar catalog source list

# Validate a URL without persisting it
slaminar catalog source test https://example.com/catalog.json

# Disable (keep in config) or remove
slaminar catalog source disable company
slaminar catalog source remove company

Env-var escape hatch (CI friendly):

SLAMINAR_CATALOG_SOURCES="extend:https://a.example/c.json,replace:/etc/slaminar/approved.json" \
  slaminar recommend .

Backward compatibility:

• v0.7 users upgrade with zero file edits. Any existing catalogUrl / catalogMode is synthesized into a *-legacy source at the matching scope every time the resolver runs.
• slaminar catalog config still works but prints a deprecation notice pointing at catalog source.
• --catalog <url> on init / recommend still works and becomes a cli-adhoc layer at priority 999.

Verification

After slaminar init completes, an automatic verification pass runs:

| Check | Description | |-------|-------------| | file-exists | CLAUDE.md exists | | has-headings | Contains ## headings | | markers-well-formed | Ownership marker pairs match | | commands-valid | npm run commands exist in package.json | | plugin.json exists | Plugin file present | | Valid JSON | plugin.json is parseable | | Required fields | name, description, version fields exist | | Skills directory | Skills directory exists | | Skill files | .md skill files present |

# Use in CI
slaminar check --ci .
# Exit codes: 0 = pass, 1 = warnings, 2 = errors

Error Handling & Safety

Error Handling

• Every CLI command is wrapped in try/catch — user-friendly messages instead of stack traces
• Path validation — detects non-existent paths, files passed where directories are expected
• Defensive JSON parsing — graceful handling of corrupted manifest/config files
• Partial write handling — reports which files succeeded and which failed

Rollback Strategy

• On init failure: previously backed-up files are automatically restored
• Manifest safety: recorded in a finally block — backup tracking survives partial failures
• Session isolation: only the current session's backups are rolled back (previous sessions are untouched)

Fallback Strategy

• AI provider chain: env vars → auth.json → local rules. Nothing ever blocks.
• AI call failure: HTTP, network, and token errors all gracefully fall back to the local draft
• Anthropic SDK not installed: if only the API key is set but the SDK isn't installed, local mode kicks in automatically
• Cloudflare account auto-detection failure: /accounts → /memberships → manual input — three-stage fallback
• Python not installed: recommends cartographer instead of graphify (same purpose, different runtime)
• All tool scores zero: returns an empty recommendation (CLAUDE.md + plugin are still generated)
• Git not installed: skips git-related analysis, sets maturity to greenfield
• Catalog remote fetch failure: falls back to stale cache, then bundled catalog

Security

• All shell execution uses execFileSync (execSync / exec are forbidden) — prevents command injection
• Arguments are passed as arrays, never concatenated into shell strings
• Git commands have a 10-second timeout to prevent indefinite blocking
• Auth tokens stored with file permission 0600 (owner read/write only)

Tech Stack

| Component | Technology | |-----------|-----------| | Language | TypeScript (ESM) | | Runtime | Node.js >= 18 | | CLI framework | commander | | Terminal output | chalk + cli-table3 | | Testing | vitest (TDD) | | Build | tsc | | Development | tsx |

Architecture

src/
├── cli.ts                        # CLI entry point (22 commands + global flags)
├── version.ts                    # Single source of truth for runtime version string
├── types/index.ts                # All shared types
│
├── core/                         # Pipeline core
│   ├── scanner.ts                # Scan coordinator (calls all scanners)
│   ├── pipeline.ts               # analyze() + init() (with rollback)
│   ├── verifier.ts               # Verification coordinator
│   └── updater.ts                # Incremental update (change detection)
│
├── scanner/                      # Phase 1: Data collection
│   ├── file-tree.ts              # Directory structure (.gitignore-aware, file count cap)
│   ├── git-info.ts               # Git metadata (timeout, contributor limit)
│   ├── ai-files.ts               # CLAUDE.md, .claude/ detection
│   └── package-info.ts           # npm, cargo, pip, go, maven manifests
│
├── analyzer/                     # Phase 2: Profiling
│   ├── language-detector.ts      # Language / framework / build tool / runtime
│   ├── structure-mapper.ts       # CLI / SPA / API / library / monorepo patterns
│   ├── convention-extractor.ts   # Naming, test, linter, commit style, doc language
│   ├── dependency-analyzer.ts    # Notable dependency classification (AI, DB, server, etc.)
│   └── maturity-detector.ts      # greenfield / early / growing / mature
│
├── recommender/                  # Phase 3: Smart recommendations
│   ├── catalog.ts                # Bundled tool catalog (offline fallback)
│   ├── catalog-resolver.ts       # Resolve catalog (cache → remote → stale → bundled)
│   ├── catalog-cache.ts          # Local cache with 24h TTL + rollback
│   ├── catalog-remote.ts         # Remote fetch with ETag conditional requests
│   ├── catalog-diff.ts           # Diff engine (added/removed/deprecated/updated)
│   ├── catalog-merger.ts         # Merge official + custom catalogs (extend mode)
│   ├── scorer.ts                 # Multi-dimensional scoring (tags, maturity, versatility)
│   ├── conflict-detector.ts      # Conflict / synergy detection
│   ├── recommender.ts            # Coordinator (filter → score → conflicts → limit)
│   └── installer.ts              # Tool installer (marketplace / npx / git-clone / pip)
│
├── planner/                      # Phase 4: Planning
│   └── planner.ts                # GenerationPlan assembly
│
├── generator/                    # Phase 5: Generation
│   ├── claude-md.ts              # CLAUDE.md (with ownership markers)
│   ├── claude-plugin.ts          # plugin.json + skills/dev.md
│   ├── ai-provider.ts            # AI routing (Cloudflare / Anthropic / local)
│   └── cloudflare-ai.ts          # Cloudflare Workers AI adapter (native fetch)
│
├── auth/                         # AI provider authentication (internal; invoked via `setup`)
│   ├── config.ts                 # ~/.config/slaminar/auth.json (0600)
│   ├── models.ts                 # Cloudflare / Anthropic model catalog
│   ├── diagnostics.ts            # Token validation, /user, /memberships, inference test
│   └── wizard.ts                 # Interactive login flow (called from setup Step 2)
│
├── setup/                        # Global first-run experience (v0.6)
│   ├── wizard.ts                 # `slaminar setup` — 5-step progressive wizard
│   ├── defaults.ts               # ~/.config/slaminar/defaults.json I/O
│   ├── doctor.ts                 # `slaminar doctor` — read-only diagnostics
│   └── update-check.ts           # Weekly npm registry version check (privacy-safe)
│
├── placer/                       # Phase 6: Placement
│   ├── backup.ts                 # Obfuscated backup (.dat) + manifest
│   ├── markers.ts                # Ownership marker extraction & merge
│   └── writer.ts                 # File writer (merge / create modes)
│
├── validator/                    # Phase 7: Verification
│   ├── claude-md.ts              # CLAUDE.md validity (commands, markers, structure)
│   └── plugin-schema.ts          # plugin.json schema validation
│
├── reporter/                     # Output
│   ├── terminal.ts               # Color tables (chalk + cli-table3)
│   ├── markdown.ts               # Markdown report generation
│   └── progress.ts               # PhaseTimer (for --verbose)
│
├── team/                         # Team collaboration
│   └── config.ts                 # Team / local config split + .gitignore
│
├── rollback/                     # Rollback
│   └── uninstaller.ts            # Full uninstall + individual tool removal
│
├── ci/                           # CI/CD
│   └── check.ts                  # Non-interactive validation (exit codes)
│
├── runtime/                      # Runtime management
│   ├── prerequisite.ts           # Version checks (Node / Python / Git / uv / volta)
│   └── detector.ts               # Runtime detection (uv / volta manager identification)
│
└── skill/                        # Claude Code integration
    ├── SKILL.md                  # /slaminar skill definition (path-parameterized)
    ├── installer.ts              # install/uninstall/status for ~/.claude/skills/slaminar/
    └── post-install.ts           # npm postinstall entry (fail-safe, opt-out aware)

scripts/copy-assets.mjs runs after tsc to copy src/skill/SKILL.md into dist/skill/ so the compiled installer.js can resolve it as a sibling via import.meta.url. The compiled dist/skill/post-install.js is the target of the postinstall script in package.json.

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev -- init .

# Tests
npm test              # Run all tests
npm run test:watch    # Watch mode

# Single test file
npx vitest run tests/scanner/file-tree.test.ts

Implementation History

Phase 1: Core Foundation

Project scaffolding, type system, 4 scanners (file-tree, git-info, ai-files, package-info), and 5 analyzers (language, structure, convention, dependency, maturity). slaminar scan and slaminar analyze became operational.

Phase 2: Recommendation Engine

14-tool catalog, multi-dimensional scoring, conflict/synergy detection, and the recommendation coordinator. slaminar recommend became operational.

Phase 3: Generation & Placement

CLAUDE.md generator with ownership markers, Claude Code plugin generator, obfuscated backup system, marker-based merge, and file placement. The full slaminar init pipeline was completed.

Phase 4: Verification & Reporting

CLAUDE.md validity checks, plugin.json schema validation, colored terminal table reporter, and Markdown report generation. The 7-phase pipeline was fully operational.

Phase 5–6: Team, CI, Rollback

Team/local config split, incremental updates, uninstall/remove rollback, CI validation, and the remaining CLI commands.

Phase 7: Cloudflare Workers AI + Unified Auth

Significant UX improvement: added Cloudflare Workers AI as a free-tier AI provider, and unified all AI configuration under login/whoami/logout commands (modeled after gh, wrangler, and vercel CLIs).

Phase 8: Dynamic Catalog System (v0.2.0)

Decoupled the tool catalog from the release cycle. Online catalog (24 tools) with local caching (24h TTL), ETag conditional requests, fallback chain, diff on update, and 7 new slaminar catalog subcommands.

Phase 9: Custom Catalog URL Support (v0.3.0)

Added --catalog <url> flag to init, recommend, and catalog update commands, enabling enterprise and private catalog hosting. Fixed CLI version mismatch and stabilized catalog resolver tests with deterministic failure URLs.

Phase 10: Persistent Catalog Config + Catalog Expansion (v0.4.0)

Added catalog config command for persisting custom catalog URL and mode (extend/replace) in project settings. Extend mode merges custom tools with official catalog; replace mode uses custom only. Expanded online catalog from 24 to 46 tools covering DevOps, team workflow, quality gates, databases, testing, frontend, and framework-specific domains. Added 14 new relation rules for synergy/overlap detection.

Phase 11: Claude Code Skill Auto-Deployment + Path Parameterization (v0.5.0)

Motivation. Pre-v0.5, users had to manually copy SKILL.md into ~/.claude/skills/slaminar/ after npm install. The distribution gap made the /slaminar skill essentially invisible to new users.

Shipped.

• Auto-install via npm postinstall hook — package.json:postinstall, src/skill/post-install.ts
• src/skill/installer.ts — idempotent install with SHA-256 content check
• slaminar skill {install,uninstall,status} command group — src/cli.ts
• scripts/copy-assets.mjs — copies SKILL.md into dist/ at build time
• SKILL.md path parameterization (<path> argument) — src/skill/SKILL.md

Decisions.

• D11.1 — Triple-safe postinstall guard. Alternatives: (a) single try/catch, (b) shell || true, (c) defensive process.exit(0). Chosen: all three combined plus opt-outs (SLAMINAR_SKIP_POSTINSTALL=1, CI=true, transitive install detection). Rationale: a postinstall failure must NEVER break npm install — losing user trust is worse than a silently-skipped skill install. Evidence: src/skill/post-install.ts, tests/skill/installer.test.ts.
• D11.2 — SHA-256 content-hash idempotence. Alternative: unconditional overwrite. Rationale: users customize SKILL.md; forcing overwrite would erase their work. Hash-equal → no-op; hash-differs → backup first, then replace. Evidence: src/skill/installer.ts:installSkill.
• D11.3 — Assets copied via separate build script. Alternative: include .md in tsconfig.json. Rationale: tsc doesn't emit non-JS; a tiny copy-assets.mjs is transparent and runs at predictable build time. Evidence: scripts/copy-assets.mjs, package.json:build.
• D11.4 — Backup only on diverging overwrite. Alternative: backup every install. Rationale: most reinstalls are hash-equal no-ops; indiscriminate backup would churn ~/.config/slaminar/skill-backups/ with duplicates. Evidence: src/skill/installer.ts:installSkill backup branch.
• D11.5 — Path-parameterized SKILL.md. Alternative: the skill detects cwd internally. Rationale: Claude Code routing works better when the skill accepts explicit arguments — phrasings like "slaminar ../other-repo에 돌려줘" now route to slaminar init ../other-repo instead of slaminar init .. Evidence: src/skill/SKILL.md frontmatter description.

Cross-refs. CHANGELOG v0.5.0 · no dedicated spec (designed inline) · tests: tests/skill/.

Phase 12: Global Setup Wizard + Doctor + Defaults (v0.6.0)

Motivation. Post-v0.5, setup was scattered across four commands (login/whoami/logout/auth), and many TeamConfig/LocalConfig fields had no CLI setter — users edited JSON manually. No diagnostic existed to answer "is my install healthy?". First-run felt fragmented.

Shipped.

• slaminar setup — 5-step interactive wizard (Environment → AI → Catalog → Defaults → Skill) — src/setup/wizard.ts
• slaminar doctor — read-only health report, exit codes 0/1/2 — src/setup/doctor.ts
• ~/.config/slaminar/defaults.json — single user-global preferences file — src/setup/defaults.ts
• Weekly npm registry version check (privacy-safe) via commander preAction hook — src/setup/update-check.ts
• Removed login/whoami/logout/auth (breaking)
• --yes non-interactive mode driven by SLAMINAR_* env vars

Decisions.

• D12.1 — Single setup entry point, not four separate commands. Alternative: keep login/whoami/etc. and add setup alongside. Rationale: four surfaces for one concern was the original fragmentation; aggregating preserves discoverability. Breaking change accepted for the simpler mental model. Evidence: src/setup/wizard.ts:runSetupWizard, CHANGELOG "Breaking" table.
• D12.2 — defaults.json under ~/.config/slaminar/, not ~/.slaminar/. Alternative: a dotfile in $HOME. Rationale: XDG Base Directory compliance; co-locates with auth.json so users have a single directory to inspect or delete. Evidence: src/setup/defaults.ts:getDefaultsPath, src/auth/config.ts:getConfigDir.
• D12.3 — Weekly version check, not per-command. Alternative: check every run (fresh data). Rationale: npm registry rate limits; users dislike chatty CLIs. One check per 7 days is balanced; privacy-safe (no identifier). Opt-out via --no-update-check or telemetry.versionCheck=false. Evidence: src/setup/update-check.ts, tests/setup/update-check.test.ts.
• D12.4 — --yes + env vars for CI, not a separate config file. Alternative: --config-file <path> flag. Rationale: env vars are idiomatic for CI (GitHub Actions, CircleCI secrets flow natively). Minimal flag surface; CI-specific complexity stays in the env namespace. Evidence: src/setup/wizard.ts:authFromEnv, Steps 2–5 all check SLAMINAR_* env first in yes mode.
• D12.5 — Doctor is strictly read-only. Alternative: auto-fix mode (doctor --fix). Rationale: mixing diagnosis with action creates ambiguity about what happened; setup --reconfigure <section> is the explicit fix path. Exit codes 0/1/2 mirror slaminar check for CI consistency. Evidence: src/setup/doctor.ts, tests/setup/doctor.test.ts.
• D12.6 — Malformed defaults.json falls back, doesn't crash. Alternative: error out with "fix your config". Rationale: defaults are non-sensitive; losing them to a parse error shouldn't block work. A partial file still merges its valid sections with built-in defaults. Evidence: src/setup/defaults.ts:loadDefaults, mergeWithBuiltIn.

Cross-refs. CHANGELOG v0.6.0 · spec: 2026-04-17-global-setup-plan.md · tests: tests/setup/{wizard,doctor,defaults,update-check}.test.ts.

Phase 13: Project Discovery & Batch Apply (v0.7.0)

Motivation. Solo developers with many repos had no way to bulk-configure slaminar; the wizard only set up one project at a time. Team members joining a project with existing .slaminar/config.json had no auto-import path. Setup was still per-directory toil.

Shipped.

• slaminar discover [roots...] — scan user-specified roots for Claude Code projects — src/discover/scanner.ts
• slaminar setup --apply-to-discovered — optional Step 6 of the wizard — src/setup/wizard.ts:stepDiscovery
• Project classifier (new/configured/existing/unsupported) — src/discover/detector.ts
• Batch apply with markdown audit log — src/discover/batch.ts
• Team catalog auto-import — src/discover/team-import.ts
• ASCII table reporter — src/reporter/discovery-table.ts

Decisions.

• D13.1 — User-specified roots, no guessed defaults. Alternative: auto-pick ~/work, ~/projects, ~/src. Rationale: false positives waste time and raise privacy concerns ("who told slaminar to walk my home dir?"). Explicit roots only; remembered in defaults.json.discovery.lastRoots for next-run convenience. Evidence: src/discover/scanner.ts:parseRootsInput, tests/discover/scanner.test.ts.
• D13.2 — Stop descending once a project signature is found. Alternative: full depth-4 walk even inside confirmed projects. Rationale: a monorepo's root and every sub-package would both match — noisy and wasteful. First hit wins; nested projects inside a confirmed project are intentionally ignored. Evidence: src/discover/scanner.ts:walk, tests/discover/scanner.test.ts "does not descend into a confirmed project".
• D13.3 — Dry-run default, apply is opt-in. Alternative: immediate apply with --dry-run escape. Rationale: writing files across many projects is irreversible without backups. Interactive: menu includes "Dry-run all (recommended)" as default. CI: requires explicit --apply-to-discovered or SLAMINAR_BATCH_APPROVED. Evidence: src/setup/wizard.ts:stepDiscovery, src/discover/batch.ts.
• D13.4 — Batch audit log in ~/.config/slaminar/setup-logs/. Alternative: no log (stdout only). Rationale: running setup --apply-to-discovered across 20 repos needs proof — which projects init'd, which updated, which failed. Markdown file per batch with succeeded/failed/skipped breakdown. Evidence: src/discover/batch.ts:writeSummary.
• D13.5 — "CLAUDE.md but no .claude/" → existing + init-merge, not skip. Alternative: treat pre-existing CLAUDE.md as a reason to skip. Rationale: pre-v0.5 users wrote CLAUDE.md by hand; slaminar's ownership-marker system merges cleanly around that content. Auto-skipping would orphan those projects from the ecosystem. Evidence: src/discover/detector.ts:classifyStatus, tests/discover/detector.test.ts.
• D13.6 — Realpath inode dedup as secondary symlink guard. Alternative: just "don't follow symlinks" by default. Rationale: bind mounts and case-insensitive filesystems can produce cycles without symlinks; realpath is the belt-and-suspenders guard. Evidence: src/discover/scanner.ts:walk (visitedInodes + realKey).

Cross-refs. CHANGELOG v0.7.0 · spec §v0.7 · tests: tests/discover/*.test.ts, tests/reporter/discovery-table.test.ts.

Phase 14: Catalog Federation (v0.8.0)

Motivation. v0.3–v0.7 supported exactly one custom catalog URL. Three-layer scenarios (security allowlist + company catalog + personal tools) forced users to manually merge JSON. Teams wanted enforced allowlists expressed as "replace mode" separately from company extend-mode additions.

Shipped.

• 6-layer priority model (bundled:-1 → official:0 → user:100 → project:200 → env:500 → cli:999) — src/recommender/catalog-sources.ts
• CatalogSource type with persistent trust field — src/types/index.ts
• slaminar catalog source {add,list,remove,enable,disable,test} CLI — src/cli.ts
• Per-source cache at ~/.config/slaminar/cache/<id>.json — src/recommender/catalog-cache.ts
• N-way merge with replace-floor semantics — src/recommender/catalog-merger.ts:mergeCatalogStack
• SLAMINAR_CATALOG_SOURCES env var (mode:uri,mode:uri)
• Auto-migration from v0.7 legacy catalogUrl

Decisions.

• D14.1 — Scope Phase 1–3 only; defer Phase 4 (trust/security) to v0.9. Alternative: full spec in one release (6–7 days). Rationale: shipping smaller gets faster feedback, and enforcement UX has independent complexity (confirm prompts, HTTPS policy, signed catalogs). The trust field is persisted now to avoid a later data migration. Evidence: CHANGELOG v0.8.0 "Deferred to v0.9", design spec Phase table.
• D14.2 — Read-path-only migration (no file rewrite). Alternative: auto-migrate on first load by rewriting the config file. Rationale: a v0.7 user who pilots v0.8, dislikes it, and downgrades would find their config file mysteriously changed. Read-time migration synthesizes *-legacy sources in memory; files are only rewritten when the user edits via catalog source add or setup --reconfigure catalog. Evidence: src/recommender/catalog-sources.ts:loadEffectiveSources legacy-URL branch, tests/recommender/catalog-sources.test.ts "synthesizes a user-scope source from legacy catalog.url".
• D14.3 — Per-source cache files, not a composite file. Alternative: one catalog-cache.json with sources: { [id]: entry }. Rationale: (a) rollback of a single source doesn't touch other sources' prev-files; (b) concurrent fetches (future) can write without lock contention; (c) easier to inspect by hand. Official source still writes to the legacy catalog-cache.json path (id='official') for v0.7 rollback compat. Evidence: src/recommender/catalog-cache.ts:getSourceCachePath, tests/recommender/catalog-cache.test.ts.
• D14.4 — Wizard keeps single-URL prompt; add CLI hint. Alternative: expand wizard into a multi-source array builder (inquirer loop). Rationale: 80% of users want one custom catalog; a loop is annoying for them. Power users go to slaminar catalog source add which is better for iteration. Evidence: src/setup/wizard.ts:stepCatalog, "Tip: layer additional sources" print.
• D14.5 — Bundled is exempt from replace-floor filtering. Alternative: replace drops every lower-priority layer including bundled. Rationale: if the user's custom replace source goes offline (stale + unreachable), they'd lose everything. Bundled is the last-resort guaranteed source — a floor, not a participant. Evidence: src/recommender/catalog-merger.ts:mergeCatalogStack, applyReplaceFloor.
• D14.6 — trust field now, enforcement in v0.9. Alternative: omit trust until enforcement exists. Rationale: adding it later forces a config-file migration. Persisting now with no behavioral effect is a zero-cost forward investment. Default trust: 'untrusted' for newly added sources is intentional — v0.9 will flag these at install time. Evidence: src/types/index.ts:CatalogSource, CHANGELOG v0.8.0 "persisted but not enforced".
• D14.7 — CLI --catalog becomes a cli-adhoc source, not a side channel. Alternative: keep pre-v0.8 behavior where --catalog bypassed stacking. Rationale: uniformity — every source flows through the same priority/fetch pipeline. CLI adhoc at priority 999 naturally wins collisions with lower layers (the expected semantics for a one-shot override). Evidence: src/recommender/catalog-sources.ts:makeCliAdhocSource, backward-compat test in catalog-resolver.test.ts.
• D14.8 — Env source IDs hashed from URI; cli-adhoc stable. Alternative: all IDs auto-generated via random. Rationale: env sources can coexist (comma-separated); hashing disambiguates them. CLI adhoc is one-at-a-time, so a stable cli-adhoc ID lets its cache file be reused across invocations. Evidence: src/recommender/catalog-sources.ts:generateSourceId, makeCliAdhocSource.

Cross-refs. CHANGELOG v0.8.0 · spec: 2026-04-16-custom-catalog-plan.md + spec §v0.8 · tests: tests/recommender/{catalog-sources,catalog-source-persistence,catalog-merger,catalog-resolver}.test.ts.

Phase 15: Claude Code Passthrough (v0.8.2)

Motivation. Up to v0.8.1, invoking /slaminar inside Claude Code forced users to configure a separate AI provider (Cloudflare or Anthropic) even though an outer Claude agent was already running. This duplicated AI calls and demanded an API key that users with a Max/Pro Claude subscription should never have needed.

Shipped.

• src/skill/SKILL.md — 7-step workflow rewrite that forces --no-ai in Steps 2 and 4 and adds Step 5 (outer Claude enhances in place) and Step 6 (verify with slaminar check)
• docs/getting-started-walkthrough.md — new §1.5 explaining the two execution contexts
• Core TypeScript code unchanged — this release reuses the existing --no-ai flag and ownership marker system

Decisions.

• D15.1 — Force --no-ai inside Claude Code; slaminar never calls an external provider from the skill path. Alternative: let the outer agent decide per-invocation. Rationale: an outer Claude is already the best available model and already running; nested AI calls add latency, cost, and configuration friction for zero marginal quality. Evidence: src/skill/SKILL.md Steps 2 & 4 both pass --no-ai; src/cli.ts --no-ai flag handling.
• D15.2 — Enhancement boundary is slaminar's existing ownership markers. Alternative: introduce a new "agent-editable region" primitive. Rationale: markers are already load-bearing for slaminar update incremental merges and already enforce the "slaminar region vs user region" split. Adding another layer would risk contract drift. Evidence: src/placer/markers.ts, src/core/updater.ts.
• D15.3 — SKILL.md is the sole "Claude Code context" carrier; no env-var auto-detection. Alternative: read SLAMINAR_AGENT_MODE=1 or inspect parent process to force the passthrough mode. Rationale: SKILL.md already defines "this was invoked via Claude Code" precisely — being inside a Claude Code skill call is exactly the signal we need, no extra channel required. Env-var detection would add false-positive risk without new capability. Evidence: src/skill/SKILL.md frontmatter + workflow.

Cross-refs. CHANGELOG v0.8.2 · spec: 2026-04-17-claude-code-passthrough-design.md · no new tests (existing 338 continue to pass).

Phase 16: Init-First Mini-Setup (v0.8.4)

Motivation. Up to v0.8.3, a user running slaminar init <path> for the first time saw only a passive nudge — "Run slaminar setup once" — then got local rules whether they wanted AI or not. The 15-decision slaminar setup wizard felt like a gate before doing the actual thing (init). Simulation data made the gap concrete: path A (Claude Code /slaminar) needed 2 decisions, path B (terminal wizard + init) needed 15. We want init itself to handle first-run gracefully so most users never need to type setup.

Shipped.

• src/setup/inline-prompt.ts — new runInlineAuthPrompt() asks a single select question and branches into Skip / Cloudflare / Anthropic
• src/auth/wizard.ts — new runLoginWizardForProvider() export that skips provider selection (already chosen) and delegates to the existing setupCloudflare() / setupAnthropic() flows
• src/cli.ts init action — passive nudge replaced with the active mini-setup; auth failure aborts init with three recovery paths; successful Skip or auth persists defaults.json so future runs stay silent
• tests/setup/inline-prompt.test.ts — 5 new unit tests (338 → 343)

Decisions.

• D16.1 — First-run gate is presence/absence of ~/.config/slaminar/defaults.json. Alternative: combine multiple signals (defaults + auth + env vars). Rationale: both slaminar setup and the new mini-setup write defaults.json when they finish. A single file-exists check is deterministic and false-positive-free. Evidence: src/setup/defaults.ts:defaultsExist, src/cli.ts init-action gate.
• D16.2 — Mini-setup asks exactly one question (AI provider). Alternative: ask 2–3 questions (tool install, catalog, etc.). Rationale: simulation showed 14 of the setup wizard's 15 decisions had reasonable silent defaults. Forcing the first-run user to navigate more than one question re-creates the friction we wanted to remove. Catalog / tool install / weekly version check all stay at their built-in defaults until the user explicitly reconfigures. Evidence: src/setup/inline-prompt.ts:runInlineAuthPrompt, src/setup/defaults.ts:builtInDefaults.
• D16.3 — Auth failure aborts init with three recovery paths (no graceful fallback). Alternative: fall back to local rules silently. Rationale: a user who actively picked Cloudflare or Anthropic is expressing intent to use AI. Silently demoting to local rules would produce an output different from what they asked for, with no obvious way to recover. Aborting with a clear "what to do" list respects the intent and is easier to debug. Skip is its own success path; this decision only covers explicit-provider + auth-fail. Evidence: src/cli.ts init-action auth-failure branch.
• D16.4 — slaminar setup is untouched — mini-setup is an independent code path. Alternative: rework setup to delegate to mini-setup, or rename setup → setup --advanced. Rationale: backward compatibility is a hard constraint for existing users and CI scripts. The only shared primitive is runLoginWizardForProvider(), which both paths call. Evidence: src/setup/wizard.ts unchanged, src/auth/wizard.ts diff limited to one new exported function.
• D16.5 — No claude CLI detection in v0.8.4 — reserved for v0.9.0. Alternative: detect claude now and offer a 4th "Use Claude Code subscription" option. Rationale: YAGNI. The choices array is structured so a future release can prepend the passthrough option with a single line change. Shipping passthrough separately keeps v0.8.4 reviewable and lets v0.9.0 focus on the detection + subprocess design unknowns. Evidence: structure of choices in inline-prompt.ts.

Cross-refs. CHANGELOG v0.8.4 · spec: 2026-04-17-v0-8-4-init-first-design.md · test file: tests/setup/inline-prompt.test.ts.

Phase 17: Catalog Ecosystem (v0.8.5)

Motivation. v0.8.0 shipped federated catalog sources — the bundled / official / user / project / env / CLI stack — with a CatalogSource.type: 'file' | 'url' | 'github' | 'official' schema and the merge/cache plumbing to back it. In practice one branch was declared-only: source.type === 'file' went through fetchRemoteCatalog(), which delegates to Node's native fetch() — and Node's fetch refuses file: URIs without an experimental flag. So local-file catalog sources, the escape hatch for teams that wanted a shared catalog over a network drive or inside a monorepo, silently didn't work. Separately, users building presentation-generation workflows had no starting point — the catalog didn't seed that ecosystem at all — and catalog authors writing their own JSON had no reference beyond source code.

Shipped.

• src/recommender/catalog-remote.ts — new fetchLocalCatalog(uri) reads file://, ~/, ./, and absolute paths via node:fs. New fetchCatalogBySource(source, etag?) dispatcher routes by source.type: file → local, url/official → HTTP, github:owner/repo/path → expanded to `raw