onboarding

Use when setting up armadillo in a new project, migrating an existing .claude/ setup to armadillo standard, or running armadillo for the first time in a project. Also use when the user says “onboard”, “init”, “setup”, or “install armadillo”.

Model	Source	Category
opus	core	Meta

Tools: Read, Glob, Grep, Bash, Write, Edit, Task, AskUserQuestion, WebFetch, Skill

Context: fork

Overview

Intelligent project onboarding that installs armadillo from a GitHub repository into any project. For fresh installs, scans the codebase to recommend custom skills, agents, and documentation tailored to the tech stack. For migrations, scans existing .claude/ content, classifies it semantically, handles conflicts intelligently, and installs armadillo as a git-native file copy. Leaves a clean slate with .armadillo-manifest.json for version tracking.

**Mandatory Announcement — FIRST OUTPUT bef

First time running armadillo in a project (no manifest)
Project has existing .claude/ directory without armadillo
Project has old armadillo installation that needs re-onboarding
User says “onboard”, “init”, “setup”, or “install armadillo”

Full Reference

Onboarding

Overview

Mandatory Announcement — FIRST OUTPUT before anything else:

┏━ 🛡 onboarding ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ [one-line description of what project/context] ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

No exceptions. Box frame first, then work.

Model requirement: This skill involves deep classification and thinking. Use Opus 4.6 (claude-opus-4-6) for any subagent dispatches.

Arguments

This skill accepts an optional GitHub repo URL:

install armadillo from https://github.com/Armadillo-Nation/armadillo-main-brains

If no URL is provided, default to https://github.com/Armadillo-Nation/armadillo-main-brains.

When to Use

First time running armadillo in a project (no manifest)
Project has existing .claude/ directory without armadillo
Project has old armadillo installation that needs re-onboarding
User says “onboard”, “init”, “setup”, or “install armadillo”

When NOT to Use

Project already has current armadillo installation → use updating-armadillo instead
Just need to check health → use updating-armadillo (includes doctor functionality)

Process Flow

Phase 0: Detect State
  ↳ has .claude/? → Migration path
  ↳ no .claude/ → Fresh install path

Phase 1: Scan & Classify (migrations only)
  ↳ Enumerate all files in .claude/
  ↳ Pass 1: path-based → Buckets A/C/D
  ↳ Pass 2: semantic → confirm B, promote to A

Phase 2: Auto-Upgrade
  ↳ Fetch armadillo repo from GitHub
  ↳ Copy core files: skills, agents, hooks, rules, lib
  ↳ Pack selection (auto from stack.json or interactive)
  ↳ Copy selected pack skills
  ↳ Merge settings.json

Phase 3: Walk Through Unknowns (migrations only)
  ↳ Bucket B: one item at a time — keep/rebuild/delete
  ↳ Handle dropped content from partial semantic matches

Phase 4: Rebuild Kept Customs
  ↳ writing-skills TDD for each item user chose to rebuild

Phase 5: Clean Slate
  ↳ Delete orphaned files
  ↳ Write .armadillo-manifest.json
  ↳ Generate CLAUDE.md
  ↳ Wire hooks.json

Phase 6: Project Analysis (fresh installs only)
  ↳ Scan codebase for frameworks, tools, patterns
  ↳ Recommend custom skills, agents, docs
  ↳ Create approved content via writing-skills TDD

Pre-flight Check

Before any GitHub API calls, verify gh CLI is installed and authenticated:

# 1. Check gh CLI is installed
command -v gh >/dev/null 2>&1 || { echo "gh CLI not found. Install from https://cli.github.com"; exit 1; }

# 2. Check keyring auth (not Claude Code's limited GITHUB_TOKEN)
env -u GITHUB_TOKEN gh auth status 2>&1

If command -v gh fails: Tell the user:

gh CLI not installed. Install it first:
  brew install gh        # macOS
  https://cli.github.com # other platforms
Then re-invoke this skill.

If gh auth status exits non-zero: Tell the user:

GitHub CLI not authenticated. Run:
  gh auth login
Then re-invoke this skill.

If both pass: Continue silently to Phase 0.

Phase 0: Detect State

Read the project’s current state:

Check for .claude/ directory — does it exist?
Check for manifest — .claude/.armadillo-manifest.json
Resume detection — If .claude/.armadillo-manifest.json exists but the completed field is absent or false, this is an interrupted onboarding. Read the saved phase field and resume from there. Inform user: “Found interrupted onboarding at Phase [N]. Resuming.”
Check if user provided a GitHub repo URL (e.g., https://github.com/Armadillo-Nation/armadillo-main-brains) → Extract repo owner/name, proceed. If no repo URL is provided and no manifest exists, fall back to Armadillo-Nation/armadillo-main-brains.
Determine path:
- No .claude/ → Fresh install (skip to Phase 2 pack selection, then Phase 6 project analysis)
- .claude/ with manifest AND completed: true → Existing armadillo (warn: use updating-armadillo skill instead, unless user wants full re-onboard)
- .claude/ without manifest → Migration (proceed to Phase 1)

Phase 1: Scan & Classify

Use Glob (**/{*,.*} in .claude/) to enumerate all files (including dotfiles like .armadillo-manifest.json), then Read each file to classify it.

Scan every file in .claude/ and classify each into one of four buckets:

Classification Rules

Classification runs in two passes.

Pass 1 — Path-Based (Fast)

Bucket A — “Armadillo covers this” (auto-upgrade, no questions asked):

Any skill directory matching an armadillo skill name (e.g., skills/brainstorming/, skills/writing-plans/, skills/executing-plans/, skills/test-driven-development/, skills/systematic-debugging/, skills/verification-before-completion/, skills/requesting-code-review/, skills/receiving-code-review/, skills/subagent-driven-development/, skills/dispatching-parallel-agents/, skills/using-git-worktrees/, skills/finishing-a-development-branch/, skills/writing-prs/, skills/onboarding/, skills/updating-armadillo/, skills/writing-skills/, skills/writing-reference-skills/, skills/armadillo-shepherd/)
Any agent file matching an armadillo agent name (e.g., agents/code-reviewer.md, agents/brand-strategist.md)
hooks/hooks.json → armadillo’s hook config
hooks/session-start.sh → armadillo’s session start
hooks/reinject-after-compact.sh → armadillo’s compact hook
hooks/run-hook.cmd → armadillo’s Windows hook runner
hooks/task-completed.sh → armadillo’s task completion hook
lib/skills-core.js → armadillo’s shared lib
settings.json → armadillo’s settings template
CLAUDE.md content between  and  markers

Bucket B — “Pass 2 candidate” (path didn’t match — send to semantic analysis):

Custom skills not in the armadillo skill list (e.g., skills/cleanup/, skills/commit-helper/)
Custom agents not in the armadillo agent list (e.g., agents/api-reviewer.md, agents/planner.md)
Custom hooks not in armadillo’s hook list (e.g., hooks/block-destructive.sh)
rules/ directory contents, docs/ contents, filled-in knowledge/ files
CLAUDE.md content OUTSIDE armadillo markers
Any .claude/ files/dirs not matching armadillo paths

Bucket D — “Sacred: preserve exactly as-is” (never touch, never classify, never overwrite):

agent-memory/*/MEMORY.md — accumulated agent knowledge (rankings, API gotchas, baselines, bug fixes)
docs/ with real content (brand guides, education docs, architecture references, research)
context/ directory — runtime state written by hooks (SWARM-STATE.md, logs, audit snapshots)
progress/ directory — handoffs, plans, designs, optimization logs
Any file with owner: "user" in the manifest

Bucket C — “Safe to delete” (empty/obsolete):

Empty template files (knowledge base templates with only placeholder text)
.gitkeep files
Empty directories
Old manifest files (will be replaced with new format)

Pass 2 — Semantic Analysis

For each Bucket B candidate from Pass 1, read its full content and compare it against armadillo’s skill and agent descriptions. Ask: “Does this file’s core purpose overlap with any armadillo skill or agent?”

Full semantic match (core function 100% covered by an armadillo equivalent):

Promote to Bucket A
Label with the armadillo equivalent: e.g., skills/commit-helper/ → finishing-a-development-branch
No unique content to extract

Partial semantic match (core function covered, but file has additional behavior not in the armadillo equivalent):

Promote to Bucket A
Label with the armadillo equivalent
Extract the unique portions (not covered by the armadillo skill) into the dropped content buffer — a list of snippets with their source file, to be processed in Phase 2’s Dropped Content Processing step

No match (does something armadillo has no equivalent for):

Remains Bucket B (confirmed) — will surface in Phase 3

Classification Output

Present a summary table to the user:

## Scan Results

### Auto-Upgrade (Armadillo covers these — will be replaced):
- skills/brainstorming/SKILL.md (armadillo skill — path match)
- skills/test-driven-development/SKILL.md (armadillo skill — path match)
- agents/code-reviewer.md (armadillo agent — path match)
- hooks/hooks.json (armadillo hooks config — path match)
- ... [N files total]

### Semantic Match → Auto-Upgrade (different name, same function):
- skills/commit-helper/SKILL.md → finishing-a-development-branch
  (unique content extracted: Heroku deploy commands, Slack step)
- agents/reviewer.md → code-reviewer (armadillo agent)
  (identical function — nothing unique)
- ... [N files total]

### Needs Your Decision (Custom content — no armadillo equivalent):
- skills/cleanup/SKILL.md (custom skill — no armadillo equivalent)
- hooks/block-destructive.sh (custom hook — no armadillo equivalent)
- rules/code-style.md (custom rules — armadillo has no rules concept)
- docs/data-structure.md (project documentation)
- ... [N files total]

### Safe to Delete:
- knowledge/client/audience-profiles.md (empty template)
- docs/archive/.gitkeep
- ... [N files total]

Ask user: “This is what I found. Ready to proceed? Path matches and semantic matches will all be replaced with armadillo’s latest versions — this is non-negotiable. Unique content from partial matches will be handled automatically. I’ll walk you through the remaining truly custom items next.”

Git health check: After classification, check if the project has .githooks/ or .claude/rules/git-workflow.md. If neither exists, note it for Phase 2 — git-setup will be invoked after the migration completes.

Checkpoint: Write partial manifest with classification results to .claude/.armadillo-manifest.json (include phase: 1 field).

Phase 2: Install Armadillo

Armadillo is THE standard. Anything it covers gets replaced. No negotiation.

Fetching from GitHub

All armadillo files are fetched from the GitHub repository. The repo URL must be known — either provided by the user at first install, or read from repoUrl in an existing manifest. Default: https://github.com/Armadillo-Nation/armadillo-main-brains.

Method 1 — GitHub CLI (preferred if gh is available):

env -u GITHUB_TOKEN gh api repos/Armadillo-Nation/armadillo-main-brains/contents/.claude/skills/brainstorming/SKILL.md --jq '.content' | base64 -d

Method 2 — WebFetch (fallback if gh is unavailable): Use WebFetch on raw GitHub URLs: https://raw.githubusercontent.com/Armadillo-Nation/armadillo-main-brains/main/.claude/skills/brainstorming/SKILL.md

Use the Write tool to write fetched content to the matching local .claude/ path.

Core Files to Install

Fetch and write these core files from the armadillo repo:

Skills (always install these — core skill set):

.claude/skills/brainstorming/SKILL.md
.claude/skills/writing-plans/SKILL.md
.claude/skills/executing-plans/SKILL.md
.claude/skills/test-driven-development/SKILL.md
.claude/skills/systematic-debugging/SKILL.md
.claude/skills/verification-before-completion/SKILL.md
.claude/skills/requesting-code-review/SKILL.md
.claude/skills/receiving-code-review/SKILL.md
.claude/skills/subagent-driven-development/SKILL.md
.claude/skills/dispatching-parallel-agents/SKILL.md
.claude/skills/using-git-worktrees/SKILL.md
.claude/skills/finishing-a-development-branch/SKILL.md
.claude/skills/writing-prs/SKILL.md
.claude/skills/onboarding/SKILL.md
.claude/skills/updating-armadillo/SKILL.md
.claude/skills/writing-skills/SKILL.md
.claude/skills/writing-reference-skills/SKILL.md
.claude/skills/armadillo-shepherd/SKILL.md
.claude/skills/git-setup/SKILL.md

Agents:

.claude/agents/code-reviewer.md
(fetch the full agents directory listing via gh api repos/Armadillo-Nation/armadillo-main-brains/contents/.claude/agents to discover all agents)

Hooks:

.claude/hooks/hooks.json
.claude/hooks/session-start.sh
.claude/hooks/reinject-after-compact.sh
.claude/hooks/run-hook.cmd
.claude/hooks/task-completed.sh

Lib:

.claude/lib/skills-core.js

Rules:

.claude/rules/coding-standards.md
.claude/rules/git-workflow.md
.claude/rules/output-style.md
.claude/rules/pr-format.md
.claude/rules/project-context.md

Create runtime directories:

mkdir -p .claude/context

Then create .claude/context/.gitkeep with a comment explaining it’s for runtime state.

Store the repo URL in the manifest (repoUrl field) so updating-armadillo can use it later without asking.

Pack Installation

Install ALL packs unconditionally. Every Armadilloer gets the complete skill library. Skills that don’t match their stack sit dormant with zero overhead.

No interactive selection. No prompting. Full install.

Fetch all packs from the armadillo repo:

For each pack directory in packs/:

Read pack’s skill files from packs/<pack-name>/skills/<skill-name>/SKILL.md
Write to .claude/skills/<skill-name>/SKILL.md
Copy any additional files (prompt templates, test files, etc.)

Log what was installed:

Installed skill packs:
  ✓ core (29 skills)
  ✓ frontend (16 skills)
  ✓ google-apis (8 skills)
  ✓ backend (4 skills)
  ...
  ✓ dns (7 skills)

Total: <N> skills across <N> packs

Settings Merge

Fetch armadillo’s settings.json template from the repo. Merge with any existing .claude/settings.json:

Preserve all user customizations
Add armadillo defaults for any missing keys
Write the merged result to .claude/settings.json

Permission Mode Selection

armadillo works best with bypassPermissions. Ask the user:

Use AskUserQuestion with these options:

armadillo works best with bypassPermissions mode.

What this means:
▪ Claude auto-approves all tool calls except the deny-list
▪ Faster iteration — no permission prompts for safe commands
▪ Deny-list still blocks catastrophic commands (rm -rf /, force push, etc.)

▸ Enable bypassPermissions?

“Yes, enable it” (Recommended) — set defaultMode to "bypassPermissions" in settings.json
“No, keep acceptEdits” — leave as-is; session-start will nudge each session

If yes → use Edit tool to change "defaultMode": "acceptEdits" to "defaultMode": "bypassPermissions" in the project’s .claude/settings.json.

Git Workflow Setup

Invoke the git-setup skill to detect and configure the project’s git strategy:

Invoke Skill tool with skill="git-setup"

This checks for branch protection, git-workflow rule, conventional commits, and version-bump automation. The user walks through each component — nothing is forced.

If .githooks/ already exists or .claude/rules/git-workflow.md already exists, git-setup detects them and skips those steps.

For Fresh Installs:

Install core files (above)
Pack selection (auto-detect or interactive)
Settings merge
Permission mode selection
Git workflow setup
Knowledge base — ask if they want brand knowledge base templates (agency/client/both/skip)

For Migrations:

Delete all Bucket A files — they’re being replaced (both path-matched and semantic-matched); for semantic matches, their original directory may differ from any armadillo path — step 6 handles those deletions
Delete all Bucket C files — they’re empty/obsolete
Install armadillo files — core files + selected pack skills
Preserve Bucket B files — don’t touch content yet (Phase 3); step 6 will relocate any that live at non-standard paths
Pack selection — for migrations, auto-select packs that cover existing skills, then offer additional optional packs
Structural normalization:
- Delete misplaced originals — for every file promoted to Bucket A via semantic match, delete it from its original location (step 1 handled path-matched deletions; this covers the remainder). If skills/commit-helper/ was semantically matched to finishing-a-development-branch, delete the entire skills/commit-helper/ directory — don’t leave it alongside the new armadillo version.
- Fix non-standard directories — scan .claude/ for directories that don’t match armadillo’s expected layout (skills/, agents/, hooks/, lib/, rules/, docs/). Bucket B files living in wrong locations (e.g., a custom skill at .claude/my-skill.md) get moved to the correct path (.claude/skills/my-skill/SKILL.md) before Phase 3 walkthrough.
- Prune empty directories — after all moves and deletes, remove any empty directories under .claude/.

Hook Merging (Critical)

A common problem with manual setup is overwriting hooks.json and orphaning custom hooks. The onboarding skill must:

Write armadillo’s hooks.json — the standard SessionStart configuration
Detect custom hooks from Bucket B (e.g., block-destructive.sh, protect-main-branch.sh)
These go to Phase 3 for user decision — if kept, they get integrated into hooks.json properly in Phase 5

Dropped Content Processing

For each unique snippet in the dropped content buffer (extracted during Pass 2 of Phase 1 from partial semantic matches), determine the right home and handle it immediately — no passive summaries, no “you may want to keep this”:

Unique content type	Action
Project-specific workflow or multi-step process	Write a custom skill via `armadillo:writing-skills` TDD process
One-liner command, alias, or project convention	Add to project-specific section of `CLAUDE.md`
Protection, enforcement, or blocking behavior	Write a hook script and wire it into `hooks.json` immediately (these are new scripts, not pre-existing Bucket B hooks — no Phase 3 deferral)
Reference information (endpoints, env vars, API key formats)	Write to `.claude/docs/<name>.md`
Trivial or redundant (armadillo already handles it)	Discard silently
Ambiguous (cannot confidently categorize)	Surface as a Bucket B item for the Phase 3 walkthrough — don’t guess

All custom artifacts created here (skills, CLAUDE.md additions, hooks, docs) are tracked in the manifest as owner: "user" with SHA-256 hash immediately after writing.

Checkpoint: Update manifest with installed files and phase: 2.

Phase 3: Walk Through Custom Unknowns

For each Bucket B item, one at a time: