npm package: @filenamedotexe/armadillo
Description: A skill system for Claude Code — installs into .claude/ directory. No CLI to install, no daemon to run.
Latest version: 0.22.0

# Armadillo

A skill system for [Claude Code](https://code.claude.com). Installs into your project's `.claude/` directory — not a standalone app. No CLI to install, no daemon to run.

───

## Install

Armadillo uses a **multi-plugin architecture** — install the core plugin first, then add skill packs for the tools you actually use.

### Step 1 — Add the marketplace (required)

Open Claude Code in your project directory and paste this:

```
Install armadillo from https://github.com/filenamedotexe/armadillo
```

Claude will add the armadillo marketplace to your `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "armadillo": {
      "source": { "source": "github", "repo": "filenamedotexe/armadillo" }
    }
  },
  "enabledPlugins": {
    "armadillo-core@armadillo": true
  }
}
```

Core ships 22 workflow skills — TDD, debugging, planning, code review, git, and testing. That's all most projects need.

### Step 2 — Add skill packs (optional)

Skill packs extend armadillo with domain-specific reference skills. Enable them in `enabledPlugins` — all come from the same marketplace:

```json
{
  "enabledPlugins": {
    "armadillo-core@armadillo": true,
    "armadillo-frontend@armadillo": true,
    "armadillo-database@armadillo": true
  }
}
```

Skills from each pack load automatically — no files copied, no restarts. See [Plugin Ecosystem](#plugin-ecosystem) for the full list.

See [What Happens During Onboarding](#what-happens-during-onboarding) for the full picture.

───

## Update

Once installed, tell Claude:

```
Update armadillo
```

Claude checks for new versions, auto-updates unmodified files, walks you through conflicts for anything you've changed, audits your custom skills for quality and armadillo overlap, and runs a full health check. See [What Happens During Update](#what-happens-during-update) for details.

───

## What You Get

### Core (always installed)

<!-- BEGIN:core-skills-count -->23<!-- END:core-skills-count --> skills covering the full development lifecycle:

<!-- BEGIN:core-skills-table -->
| Skill | What it does |
|-------|-------------|
| **brainstorming** | Collaborative design sessions before implementation |
| **dispatching-parallel-agents** | Run 2+ independent tasks concurrently with subagents |
| **executing-plans** | Execute implementation plans task-by-task with review checkpoints |
| **finishing-a-development-branch** | Guides completion — merge, PR, or cleanup options |
| **receiving-code-review** | Process review feedback with technical rigor |
| **requesting-code-review** | Request and manage code review after completing work |
| **subagent-driven-development** | Dispatch fresh subagent per task with code review between |
| **systematic-debugging** | Root cause analysis — trace, reproduce, fix, verify |
| **test-driven-development** | RED/GREEN/REFACTOR cycle for all code changes |
| **using-git-worktrees** | Isolated feature branches with smart directory selection |
| **armadillo-shepherd** | Active router — classifies requests and routes to the correct skill |
| **verification-before-completion** | Run verification commands before claiming work is done |
| **writing-plans** | Create detailed implementation plans from designs |
| **writing-reference-skills** | Create API/tool reference skills with mandatory web research |
| **writing-skills** | Create and test new skills using the TDD cycle |
| **onboarding** | Intelligent project setup — scans existing .claude/, auto-upgrades armadillo-covered items, walks through custom unknowns, rebuilds to armadillo quality |
| **updating-armadillo** | Check for updates, upgrade versions, resolve conflicts, health check |
| **playwright** | E2E testing, cross-browser automation, visual comparison, test generation |
| **puppeteer** | Browser automation, Chrome DevTools Protocol, headless Chrome, PDF generation |
| **cypress** | E2E and component testing with real-time runner and time-travel debugging |
| **vitest** | Vite-native unit and component testing with Jest-compatible API |
| **writing-prs** | Conventional commits PR titles + hybrid description template with conditional sections |
| **claude-code-plugins** | Claude Code plugin system — marketplace.json, plugin.json, sources, distribution, multi-plugin repos |
<!-- END:core-skills-table -->

<!-- BEGIN:rules-count -->5<!-- END:rules-count --> rules ship with every install:

<!-- BEGIN:rules-table -->
| Rule | What it enforces |
|------|-----------------|
| **coding-standards** | DRY, YAGNI, TDD, smart backgrounding, skill-first workflow |
| **git-workflow** | `env -u GITHUB_TOKEN` auth, conventional commits, atomic changes |
| **output-style** | Consistent formatting, status markers, Armadilloer voice |
| **pr-format** | Conventional commits PR titles, hybrid template, anti-patterns |
| **project-context** | Stack-aware behavior — reads stack.json, PROJECT.md, fresh-project.json |
<!-- END:rules-table -->

## Plugin Ecosystem

23 plugins across every domain. Core is always required — skill packs are optional.

<!-- BEGIN:plugin-ecosystem-table -->
| Plugin | Skills | Description |
|--------|--------|-------------|
| **armadillo-core** | 23 | Workflow, testing, git, debugging, and meta skills — always required |
| **armadillo-frontend** | 10 | React, Tailwind, Astro, accessibility, and animation skills |
| **armadillo-google-apis** | 7 | GA4, Google Ads, Search Console, YouTube, Places, and Lighthouse APIs |
| **armadillo-backend** | 4 | Hono, Express, tRPC, and REST API patterns |
| **armadillo-database** | 4 | Supabase, MongoDB, Neon, and Redis/Upstash |
| **armadillo-orm** | 2 | Drizzle and Prisma ORM skills |
| **armadillo-auth** | 3 | Auth.js, Clerk, and Supabase Auth |
| **armadillo-deploy** | 4 | Vercel, Cloudflare, Docker, and GitHub Actions |
| **armadillo-forms** | 2 | Zod schema validation and React Hook Form |
| **armadillo-state** | 2 | Zustand and TanStack Query state management |
| **armadillo-monitoring** | 2 | Sentry error tracking and PostHog analytics |
| **armadillo-cms** | 2 | Sanity and Payload CMS skills |
| **armadillo-email** | 2 | Resend transactional email and React Email templates |
| **armadillo-storage** | 2 | Uploadthing file uploads and S3/Cloudflare R2 object storage |
| **armadillo-ai** | 2 | Vercel AI SDK and Anthropic API integration skills |
| **armadillo-tooling** | 2 | ESLint/Prettier linting and Turborepo monorepo skills |
| **armadillo-fresh-project** | 3 | Greenfield project setup, scaffolding, and stack recommendation |
| **armadillo-mobile** | 1 | Expo and React Native mobile development |
| **armadillo-payments** | 1 | Stripe payments and billing integration |
| **armadillo-video** | 1 | Remotion programmatic video creation |
| **armadillo-brand** | 2 | Brand knowledge building and Deepgram transcription |
| **armadillo-web-migration** | 1 | Duda to Astro website migration |
| **armadillo-creative** | 1 | ASCII art and creative CLI output |
<!-- END:plugin-ecosystem-table -->

Each plugin lives in its own GitHub repo and installs independently. Add only what your project uses.

───

## What Happens During Onboarding

The `onboarding` skill handles everything. It runs in phases:

### Fresh Project (no existing `.claude/`)

```
▸ Plugin registration    Adds armadillo marketplace to settings.json with enabledPlugins
▸ Directory structure    Creates context/ for runtime state (logs, version checks)
▸ Settings               acceptEdits + allow-list + deny-list (toggle in settings.json)
▸ CLAUDE.md              Armadillo-managed block + space for your project instructions
▸ Manifest               .armadillo-manifest.json tracking version and user-owned files
▸ Project analysis       Codebase scanned → custom skills, agents, docs recommended
```

Skills, agents, hooks, and rules load from the plugin automatically — no files copied to `.claude/`.

### Existing `.claude/` (migration from manual setup)

The onboarding skill scans every file and classifies each into four buckets:

| Bucket | What it contains | Action |
|--------|-----------------|--------|
| **A — Armadillo covers this** | Files whose purpose matches an armadillo skill (path or semantic match) | Auto-replaced. No questions asked. |
| **B — Truly custom** | Skills, agents, hooks, rules with no armadillo equivalent | Walk through one at a time: keep, rebuild, or delete |
| **C — Safe to delete** | Empty templates, `.gitkeep`, stale placeholders | Deleted silently |
| **D — Sacred** | `agent-memory/*/MEMORY.md`, `docs/` with real content, `context/`, `progress/` | Never touched. Never reclassified. Never overwritten. |

**Semantic matching** — if a file's name doesn't match armadillo but its content does the same job (e.g. `commit-helper` → `finishing-a-development-branch`), it gets promoted to Bucket A automatically. Unique content from partial matches is extracted and processed — written to a custom skill, added to `CLAUDE.md`, turned into a hook, or stored in `docs/`. Nothing is silently discarded.

**Bucket D (sacred files)** are never touched regardless of name or location:

```
▪ agent-memory/*/MEMORY.md    Domain knowledge built over real sessions
▪ docs/ with real content      Brand guides, architecture docs, research
▪ context/                     Runtime state (SWARM-STATE.md, logs, snapshots)
▪ progress/                    Handoffs, plans, designs, optimization logs
```

After migration, these are registered in `skills.json` `sharedFiles` so all skills can discover and reference them.

**Custom skills** chosen for "Keep & rebuild" go through the full `writing-skills` TDD process — proper frontmatter, CSO-optimized description, process flowchart, quick reference table, common mistakes section.

**Reference skills** — if your project uses version-sensitive external APIs, the `writing-reference-skills` skill creates proper reference docs with current endpoint versions, auth flows, and rate limits.

───

## What Happens During Update

The `updating-armadillo` skill runs 8 steps. In the multi-plugin architecture, each registered plugin is checked individually — core and every skill pack get their own version check, update, and conflict resolution pass.

```
1  Read manifest         Current version, install type (plugin vs legacy file-copy)
2  Fetch latest          Check GitHub releases for new version — per plugin
2.5  What's New          Changelog grouped by breaking / added / improved / fixed
2.6  Plugin Migration    (Legacy users only) Mandatory migration to plugin system with backups
3  Classify changes      (File-copy only) Auto-update, conflict, new file, deleted upstream
4  Apply updates         (File-copy only) Auto-update unmodified; walk conflicts one at a time
5  User-Owned Audit      Overlap check, quality review, hook audit, orphan processing
6  Health check          Manifest integrity, context directory, CLAUDE.md markers
7  Update manifest       Version, install type, user-owned files
8  Summary               Migration status, audit results, health status
```

**Step 2.6 (Plugin Migration)** — All pre-plugin installations (file-copy) get a mandatory, safe migration:
```
▪ Backs up skills/, agents/, hooks/ directories to .claude/*-backup-YYYYMMDD/
▪ Registers armadillo plugin in settings.json
▪ Removes hooks from settings.json (plugin hooks.json takes over)
▪ Creates context/ runtime directory
▪ Updates .gitignore for runtime state files
▪ Updates manifest to installType: "plugin"
▪ Runs health check
```

After migration, the plugin handles all armadillo content automatically.

**Step 5 (User-Owned Audit) runs every update cycle**, even without a version change:

```
▪ Overlap check      Semantic comparison of your skills against all armadillo skills
▪ Quality review     8-signal scoring — scores below standard get targeted fix offer
▪ Hook audit         Wired in hooks.json, executable, has error handling
▪ Orphan processing  Any .claude/ file not in manifest gets classified and tracked
```

───

## Runtime Intelligence

Hooks fire at lifecycle events. No manual intervention needed.

| Event | Hook | What it does |
|-------|------|-------------|
| **SessionStart** | `session-start.sh` | Injects skill awareness, SWARM-STATE, error log, agent memory list; version check once per day; bypass mode warning |
| **UserPromptSubmit** | `inject-skill-awareness.sh` | Hard constraint — skill invocation required before any response (fires **every prompt**) |
| **PreToolUse** | `enforce-skills.sh` | Blocks Plan and Explore agents (use skills instead) |
| **SubagentStart** | `subagent-start.sh` | Injects coding standards + output style into subagent context |
| **PostToolUse** | `async-lint.sh` | Async typecheck after Write/Edit (non-blocking) |
| **PostToolUse** | `post-push-pr-check.sh` | Reminds to create PR after push to feature branch |
| **PreCompact** | `pre-compact.sh` | Snapshots SWARM-STATE, error log, progress, git log before compaction |
| **TaskCompleted** | `task-completed.sh` | Blocks task completion if tests fail |
| **Stop** | `stop-verify.sh` | Verification reminder on session end |

All hooks share `hooks/lib/json-escape.sh` — no duplicated utility code.

Agent coordination state, domain knowledge, and recent errors survive compaction and session boundaries automatically.

───

## Permissions

Default mode: `acceptEdits` — Claude can read, search, and edit files without prompting. Bash commands use an allow-list.

| Mode | Behavior | Risk |
|------|----------|------|
| `acceptEdits` | Auto-approves reads + edits, prompts for unknown Bash | Low — you see Bash prompts |
| `bypassPermissions` | Auto-approves everything except deny-list | High — faster but less control |
| `plan` | Read-only, no writes | Zero — exploration only |

Toggle in `.claude/settings.json` → `permissions.defaultMode`.

**Deny-list (always active):**

```
✗  rm -rf / ~ /* ~/*       sudo rm -rf       mkfs
✗  dd if=/dev/zero          dd if=/dev/random  chmod -R 777 /
✗  git push --force         git reset --hard
```

───

## Tuning

Armadillo works with Claude Code defaults. For Armadilloers who want to optimize:

| Variable | Default | Recommendation | Effect |
|----------|---------|----------------|--------|
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | ~95% | `80` | Earlier compaction → better summaries, pairs well with PreCompact hooks |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 32,000 | `64000` | Longer responses, useful for big refactors. Reduces input context space. |
| `MAX_THINKING_TOKENS` | 31,999 | Leave default | Reducing hurts reasoning quality on complex tasks |

Set in your shell profile or `.claude/settings.json` `env` block.

───

## How It Works

Each plugin lives in its own GitHub repo and follows the same structure. Claude Code loads plugins directly from their repos — no cloning, no file copying.

```
Plugin Repo Structure (per plugin):
├── plugin.json                  Plugin metadata (name, version, description)
├── marketplace.json             Marketplace registration
├── skills/                      Skill SKILL.md + reference.md files
├── agents/                      Agent system prompts (core only)
├── hooks/                       Hook scripts (core only)
│   ├── lib/json-escape.sh       Shared JSON escaping utility
│   ├── session-start.sh         Injects skills + runtime context
│   ├── pre-compact.sh           Snapshots state before compaction
│   ├── stop-verify.sh           Verification reminder on stop
│   ├── enforce-skills.sh        Blocks Plan agents (use skills instead)
│   ├── inject-skill-awareness.sh  Skill constraint (fires every prompt)
│   ├── subagent-start.sh        Injects standards into subagents
│   ├── async-lint.sh            Async typecheck after Write/Edit
│   ├── post-push-pr-check.sh    PR reminder after push
│   └── task-completed.sh        Test gate — blocks completion if tests fail
└── rules/                       coding-standards, git-workflow, output-style, pr-format (core only)

User Project .claude/ Directory (Auto-created on install):
.claude/
├── settings.json                Plugin registration — add plugins here to activate them
│                                  "enabledPlugins": { "armadillo-core@armadillo-marketplace": true,
│                                                      "armadillo-frontend@armadillo-marketplace": true }
├── CLAUDE.md                    Project-specific instructions + skill list (auto-updated per plugin)
├── .armadillo-manifest.json     Tracks versions and user-owned files per plugin
├── context/                     Runtime state (hooks write, agents read)
│   ├── .gitkeep                 Directory tracked, files ignored
│   ├── SWARM-STATE.md           Live agent coordination state
│   ├── error-log.txt            Accumulated errors across sessions
│   └── armadillo-version-check.txt  Daily version check cache
├── agent-memory/                Accumulated domain knowledge per agent
│   └── <agent-name>/MEMORY.md   Domain-specific learnings
├── docs/                        Project knowledge base
│   └── <topic>.md               Architecture, brand guides, research
└── progress/                    Handoffs, plans, snapshots
```

Each plugin registered in `enabledPlugins` loads automatically at session start — skills, agents, hooks, and rules from every active plugin are available immediately. The manifest tracks installed versions and user-owned files per plugin. User-owned files are handled exclusively through the Step 5.5 audit — with consent, one at a time.

───

## Skill Features

Skills use Claude Code frontmatter for fine-grained control:

| Field | Effect | Example |
|-------|--------|---------|
| `allowed-tools` | Restricts which tools the skill can use | `Read, Glob, Grep, Bash` |
| `disable-model-invocation` | Prevents Claude from auto-triggering the skill | onboarding, updating-armadillo |
| `context: fork` | Runs in forked context (protects main session) | onboarding, writing-skills |
| `depends` | Declares skill prerequisite chain (in `skills.json`) | executing-plans → writing-plans → brainstorming |

Rules use `paths:` frontmatter to scope activation — coding-standards only fires when working with source code files, not markdown or JSON.

───

## Health Check

Run without AI tokens:

```bash
node .claude/lib/doctor.js
```

Checks: manifest integrity, tracked files, hooks config, executable permissions, CLAUDE.md markers, settings validity, orphaned files, version match.

───

## Model Selection

Agents and skills specify their own `model:` field. Never override via Task tool `model` parameter.

| Tier | Model ID | Use Cases |
|------|----------|-----------|
| **Opus 4.6** | `claude-opus-4-6` | Onboarding, updating-armadillo, writing-plans, executing-plans, subagent-driven-development, systematic-debugging, writing-skills, dispatching-parallel-agents, receiving-code-review, code-reviewer, brand-strategist |
| **Sonnet 4.6** | `claude-sonnet-4-6` | Implementation, content creation, API work, domain experts (ascii-art-creator, duda-migration-agent, remotion-creator, frontend-testing-guide, frontend-dev-guide) |
| **Haiku 4.5** | `claude-haiku-4-5-20251001` | Mechanical tasks, batch scanning, rendering |
| **Inherit** | — | Reference/knowledge agents follow invoking agent's model |

───

## For AI Assistants

**Do NOT clone this repository.** Armadillo installs by fetching individual files into the user's existing project.

### Installing armadillo in a user's project

```bash
# 1. Fetch skills.json
env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/skills.json --jq '.content' | base64 -d

# 2. Fetch the onboarding skill
env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/.claude/skills/onboarding/SKILL.md --jq '.content' | base64 -d

# 3. Execute the onboarding workflow. It handles everything.
```

### Fetching any file from the repo

```bash
env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/PATH --jq '.content' | base64 -d
```

Replace `PATH` with the file path relative to repo root (e.g. `.claude/skills/brainstorming/SKILL.md`).

### What the onboarding skill handles

```
▪ Bundle selection (reads bundles from skills.json dynamically)
▪ Fetching and writing all skill files, agent files, shared files to .claude/
▪ Migration classification (Bucket A/B/C/D) for existing .claude/ setups
▪ Semantic matching of custom files against armadillo skill descriptions
▪ Dropped content processing (unique logic extracted from partial matches)
▪ Custom skill rebuilds via writing-skills TDD
▪ Reference skill creation via writing-reference-skills for external APIs
▪ Manifest creation with SHA-256 hashes
▪ CLAUDE.md generation with armadillo markers
▪ hooks.json configuration
```

### Do NOT

```
✗  git clone this repo into the user's project
✗  Copy the entire repo contents
✗  Manually recreate files without fetching from GitHub
✗  Hardcode bundle names — always read from skills.json
✗  Touch Bucket D files (agent-memory, context, progress, docs with real content)
```

───

## Requirements

```
▪ Claude Code        https://code.claude.com
▪ gh CLI             Authenticated (for fetching from GitHub)
                     — or internet access for WebFetch fallback
```