armadillo-maker

End-to-end pipeline for creating and updating armadillo artifacts — skills, packs, agents, rules, hooks, workflows, and reference docs — with recon, research, design, TDD implementation, registration, and full delivery

Model	Source	Category
opus	core	Meta

Tools: Skill, Task, Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, TaskGet

Context: fork

Overview

The end-to-end orchestrator for creating and updating ANY armadillo artifact. Skills, packs, agents, rules, hooks, reference docs, test baselines — all flow through this 10-phase pipeline.

What this skill does: Owns the full lifecycle from “I want to create X” to “X is merged to main, registered, routed, and the branch is cleaned up.”

What this skill wraps: writing-skills and writing-reference-skills are internal craft delegates. They handle the art of writing SKILL.md files. This

Full Reference

armadillo-maker

Mandatory Announcement — FIRST OUTPUT before anything else:

┏━ 🛡 armadillo-maker ━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ [one-line: what artifact + create/update]       ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

No exceptions. Box frame first, then work.

Overview

The end-to-end orchestrator for creating and updating ANY armadillo artifact. Skills, packs, agents, rules, hooks, reference docs, test baselines — all flow through this 10-phase pipeline.

What this skill does: Owns the full lifecycle from “I want to create X” to “X is merged to main, registered, routed, and the branch is cleaned up.”

What this skill wraps: writing-skills and writing-reference-skills are internal craft delegates. They handle the art of writing SKILL.md files. This skill handles everything else — the pipeline around them.

What this skill invokes: writing-plans, subagent-driven-development, worktree, verification-before-completion, finishing-a-development-branch, writing-prs

┌─────────────────────────────────────────────────────────────────┐
│                      armadillo-maker                            │
│                                                                 │
│  [1] CLASSIFY  →  what artifact type?                           │
│  [2] RECON     →  search for existing overlap                   │
│  [3] RESEARCH  →  WebSearch + WebFetch latest official docs     │
│  [4] DESIGN    →  design doc → user approval                    │
│  [5] PLAN      →  → writing-plans                               │
│  [6] BRANCH    →  → worktree (auto)                            │
│  [7] CRAFT     →  → writing-skills / writing-reference-skills   │
│                    → subagent-driven-development (TDD)           │
│  [8] REGISTER  →  armadillo.json, sync-all, shepherd, CLAUDE.md │
│  [9] VERIFY    →  → verification-before-completion              │
│  [10] SHIP     →  → finishing-a-development-branch              │
│                    → writing-prs → merge → cleanup               │
└─────────────────────────────────────────────────────────────────┘

NEVER skip Phase 2 (RECON) or Phase 8 (REGISTER). An unregistered artifact is an invisible artifact. 30 seconds of recon prevents hours of duplicate work.

Phase 1: CLASSIFY

Read the user’s request and classify the artifact type. Auto-detect create vs update intent.

Artifact Type	Detection Signal	Craft Delegate
Skill	”new skill”, “add skill to pack”, process/workflow documentation	→ writing-skills via Skill tool
Reference Skill	”API docs”, “library reference”, versioned external tool, SDK docs	→ writing-reference-skills via Skill tool
Pack	”new pack”, “group of skills for X”, “skill bundle”	→ writing-skills × N (one per skill)
Agent	”new agent”, “specialized subagent”, “expert for X”	Direct write — frontmatter + system prompt
Rule	”new rule”, “enforce X behavior”, “constraint”, “policy”	Direct write — constraint doc + integration table
Hook	”new hook”, “trigger on X event”, “block when Y”, “gate for Z”	Direct write — shell script + hooks.json entry
Test Baseline	”test baseline for skill X”, “pressure test patterns”	Direct write — test scenarios + success criteria
Workflow	”chain”, “workflow”, “pipeline”, “combine skills”, “wire up”	Direct write — shepherd entries + optional glue skill

Create vs Update

Intent	Signals	Pipeline
Create	”create”, “new”, “add”, “build”, “make”	All 10 phases
Update	”update”, “refresh”, “fix”, “improve”, “add to existing”	Skip Phase 4 (DESIGN) — artifact already has approved design

If the intent is ambiguous, ask ONE clarifying question:

▸ Are you creating a new <type> or updating the existing <name>?

Output

Set two variables that flow through all subsequent phases:

• ARTIFACT_TYPE — one of: skill, reference-skill, pack, agent, rule, hook, test-baseline, workflow
• INTENT — one of: create, update

Phase 2: RECON

Search for existing overlap before creating anything. This takes 30 seconds and prevents duplicate artifacts.

Search Checklist

Run ALL of these — not just the first match:

1. Grep SKILL.md descriptions for the target topic:

   Grep: pattern="<topic>" across .claude/skills/*/SKILL.md and packs/*/skills/*/SKILL.md

2. Check armadillo.json skill lists for similar names:

   Grep: pattern="<topic>" in armadillo.json

3. Read shepherd routing table — scan the Routing Table section of .claude/skills/armadillo-shepherd/SKILL.md for existing routes that cover this domain

4. Check agent definitions (if creating an agent):

   Grep: pattern="<topic>" across .claude/agents/*.md

5. Check rules (if creating a rule):

   Grep: pattern="<topic>" across .claude/rules/*.md

6. Check hooks (if creating a hook):

   Grep: pattern="<topic>" across .claude/hooks/*.sh

Decision Matrix

Finding	Action
Exact match	Ask: “We already have <artifact>. Modify it instead, or create a variant?”
Partial overlap	Show the overlap, ask: “This overlaps with <artifact>. Absorb into it, or create separate?”
No match	Proceed to Phase 3
Coverage gap in shepherd	Note it — Phase 8 (REGISTER) will fill the gap

Update Path Recon

For updates, recon focuses on:

• Read the current artifact fully
• Identify what’s stale or missing
• Check if the artifact’s last_updated field is >90 days old
• Document what specifically needs to change

Workflow Recon

For workflow artifacts, recon includes four additional checks beyond the standard overlap scan:

1. Trigger overlap — do the proposed trigger patterns already route to an existing skill? Grep the shepherd routing table for each trigger phrase.
2. Chain redundancy — does an existing workflow already chain these same skills in the same order? Read the shepherd ## Workflows section and compare.
3. Circular chains — does the proposed chain create a loop (A → B → … → A)? Trace the full chain and verify no skill appears twice.
4. Skill existence — do all referenced skills actually exist in the ecosystem? Verify each skill name appears in armadillo.json or as a directory under .claude/skills/ or packs/*/skills/.

If conflicts found → present them to user with options: modify, extend existing, or proceed anyway.

Phase 3: RESEARCH

Date-aware web research. The current date matters for version-sensitive artifacts.

Research Depth by Artifact Type

Type	Depth	What to Research
Reference Skill	Deep	Official docs, changelogs, API versions, deprecations, breaking changes, auth flows
Skill	Medium	Best practices, common patterns, framework-specific conventions
Pack	Medium	Ecosystem survey — what tools/APIs belong together, naming conventions
Agent	Light	Verify the domain exists, check standard terminology
Rule	Light	Verify the constraint is technically accurate, check related standards
Hook	Light	Verify Claude Code hook event model, check hook API contract
Test Baseline	None	Based on existing skill — no external research needed
Workflow	Minimal	Verify referenced skills exist, read their SKILL.md for inputs/outputs — no external web research needed

Research Protocol (Medium/Deep)

1. WebSearch with current-year queries:

   • "<topic> API documentation 2026"
   • "<topic> changelog breaking changes 2025 2026"
   • "<topic> deprecated endpoints" (for APIs)
   • "<topic> best practices" (for frameworks)

2. WebFetch key pages:

   • Official getting-started guide
   • API reference / endpoint list
   • Changelog / migration guide
   • Authentication / setup guide

3. Save research notes to .claude/context/maker-research-<name>.md:

   • Version numbers pinned with dates
   • Key endpoints/patterns documented
   • Deprecation warnings flagged
   • Auth flows documented

Skip Conditions

• Test Baseline artifacts: skip entirely (based on existing skill, no external docs needed)
• Update path with minor changes: skip unless user says “refresh from latest docs”
• Light depth artifacts: one WebSearch max, skip WebFetch unless results are surprising
• Workflow artifacts: Minimal research only — verify referenced skills exist by reading their SKILL.md files. No WebSearch or WebFetch needed since workflows chain internal skills.

Phase 4: DESIGN

Write a design document and get user approval before any implementation.

Skipped for: Update path (artifact already exists, design was already done).

Design Doc Structure

Save to .claude/docs/plans/YYYY-MM-DD-<name>-design.md:

# <Artifact Name> — Design Document

**Date:** YYYY-MM-DD
**Artifact type:** <skill | reference skill | pack | agent | rule | hook | test baseline>
**Target location:** <exact file path(s)>

## What
<One paragraph: what this artifact does>

## Why
<One paragraph: why it's needed, what gap it fills — reference Phase 2 RECON findings>

## Research Findings
<Key facts from Phase 3 RESEARCH — versions, endpoints, patterns>
<For light-research artifacts: "N/A — light research, no significant findings">

## Scope
<What's in scope vs out of scope — YAGNI ruthlessly>

## Artifact-Specific Details
<For skills: sections, allowed-tools, model tier>
<For packs: skill list with one-line descriptions, pack name, category>
<For agents: model tier, tools, behavioral constraints, skills list>
<For rules: what it enforces, when active/inactive, integration table>
<For hooks: event type, matcher, blocking vs async, exit codes>

Complexity Scaling

Artifact Type	Design Doc Length
Rule	Short — 1 page max
Hook	Short — 1 page max
Test Baseline	Short — half page
Agent	Medium — 1-2 pages
Skill	Medium — 1-2 pages
Reference Skill	Medium-Long — 2-3 pages (research findings drive length)
Pack	Long — 1 page per skill in the pack

Approval Gate

Present the design doc to the user. Walk through sections, pausing for feedback.

Do NOT proceed to Phase 5 until user explicitly approves the design. No exceptions. No "this is simple enough to skip." Present it, get approval.

Commit

git add .claude/docs/plans/<design-doc>.md
git commit -m "docs: <artifact-name> design document"

Phase 5: PLAN

Invoke writing-plans to generate a TDD implementation plan from the approved design.

Skill: writing-plans

The plan MUST include these as explicit tasks:

• Craft tasks (Phase 7) — one per artifact file to create/modify
• Registration tasks (Phase 8) — armadillo.json, sync-all, shepherd routing
• Verification tasks (Phase 9) — test suite, sync-all —check, behavioral test

Each task follows RED-GREEN-COMMIT structure per writing-plans standards.

Plan is saved to .claude/docs/plans/YYYY-MM-DD-<name>-plan.md and committed.

Update Path Plans

For updates, the plan is lightweight:

• One task per file to modify
• Registration task to re-run sync-all.js
• Verification task

Phase 6: BRANCH

Invoke worktree to create an isolated worktree branch.

Skill: worktree

Branch naming: feat/maker-<artifact-name>

Examples:

• feat/maker-convex-skill
• feat/maker-error-formatting-rule
• feat/maker-tdd-gate-hook
• feat/maker-analytics-pack

All subsequent phases (7-10) execute inside the worktree. No work on main.

Phase 7: CRAFT

Execute the implementation plan via subagent-driven-development. The craft phase branches by artifact type — each type has a different creation process.

Skill: subagent-driven-development

Skill Craft

Delegate to writing-skills (invoked via Skill tool):

• TDD RED-GREEN-REFACTOR with subagent pressure testing
• Output: <skill-dir>/SKILL.md + optional test-baseline.md

For core skills: .claude/skills/<skill-name>/SKILL.md For pack skills: packs/<pack-name>/skills/<skill-name>/SKILL.md

Reference Skill Craft

Delegate to writing-reference-skills (invoked via Skill tool):

• WebSearch/WebFetch + RED-GREEN accuracy testing
• Output: <skill-dir>/SKILL.md (lean router) + reference/*.md (version-pinned docs)

Pack Craft

Invoke writing-skills sequentially for each skill in the pack:

• One SKILL.md per skill, created in order
• For 5+ skills with no file overlap: use dispatching-parallel-agents
• Output: packs/<pack-name>/skills/<skill-N>/SKILL.md for each

Agent Craft

Direct write following the standard agent template:

---
name: <agent-name>
description: |
  Use this agent when <trigger conditions>.
  Also use when <secondary triggers>.
model: <tier from design doc — see CLAUDE.md Model Selection table>
memory: project
maxTurns: 20
skills:
  - <relevant-skill-1>
  - <relevant-skill-2>
last_updated: 2026-03-05
---

Below the frontmatter: system prompt with role definition, behavioral instructions, process steps, and tool usage patterns.

Reference existing agents in .claude/agents/ for style. Match the voice and structure of verifier.md, debugger.md, code-reviewer.md.

Rule Craft

Direct write following the standard rule structure:

# <Rule Name>

## What This Enforces
<Clear statement of the constraint — what behavior is required>

## When Active
<Conditions under which this rule applies>

## When Inactive
<Conditions where this rule does NOT apply — test fixtures, documentation, etc.>

## Details
<Specific guidelines, examples, do/don't tables>

## Integration

| Skill | How it uses this rule |
|-------|----------------------|
| `<skill-name>` | <how this skill references or enforces this rule> |

Hook Craft

Two files required:

1. Shell script (.claude/hooks/<hook-name>.sh):

#!/usr/bin/env bash
# <hook-name>.sh — <one-line description>
set -euo pipefail

# Read hook input from stdin (JSON)
INPUT=$(cat)

# Extract relevant fields
# TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')

# Your logic here

# Exit codes:
# 0 = allow (hook passes)
# 2 = block with message (send message to stderr)
# Other = error

Must be executable: chmod +x .claude/hooks/<hook-name>.sh

2. hooks.json registration — add entry to the appropriate event section in .claude/hooks/hooks.json:

{
  "matcher": "<tool-or-event-pattern>",
  "hooks": [{
    "type": "command",
    "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/<hook-name>.sh"
  }]
}

Event types: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, PreCompact, Stop, SubagentStart, SubagentStop, TaskCompleted, PostToolUseFailure

Test Baseline Craft

Direct write to <skill-dir>/test-baseline.md:

• Pressure test scenarios (RED phase prompts)
• Expected baseline failures without the skill
• GREEN criteria (what the skill must fix)
• Subagent test instructions

Workflow Craft

Direct write — same pattern as rules and hooks. No separate craft delegate needed.

Primary output: Edit .claude/skills/armadillo-shepherd/SKILL.md:

1. Add a new chain entry to the ## Workflows section with chain name, trigger conditions, and step sequence
2. Add trigger pattern rows to the relevant routing table sections

Optional output: Create a thin glue skill when chain logic is non-trivial:

Scenario	Output
Simple linear chain (A → B → C)	Shepherd route only — no glue skill
Conditional branching (if X → A else → B → C)	Thin pimp-style glue skill
State passing between steps	Glue skill with state management
Parallel steps in the chain	Glue skill using dispatching-parallel-agents

Glue skills follow standard SKILL.md structure and go in .claude/skills/<workflow-name>/SKILL.md.

Phase 8: REGISTER

Every artifact must be registered or it’s invisible. Run ALL applicable registration steps for the artifact type.

Registration Matrix

Step	Skill	Ref Skill	Pack	Agent	Rule	Hook	Test Baseline	Workflow
Add to armadillo.json	✓	✓	✓	✓	✗	✗	✗	✗
Run node scripts/sync-all.js	✓	✓	✓	✓	✗	✗	✗	✓
Add shepherd route	✓	✓	✓	✓	✗	✗	✗	✓
Update hooks.json	✗	✗	✗	✗	✗	✓	✗	✗
Rebuild settings.json hooks	✗	✗	✗	✗	✗	✓	✗	✗
Add to CLAUDE.md rules table	✗	✗	✗	✗	✓	✗	✗	✗
Verify sync-all.js --check	✓	✓	✓	✓	✗	✗	✗	✓
Add to shepherd ## Workflows	✗	✗	✗	✗	✗	✗	✗	✓

armadillo.json Registration

For core skills: Add skill name string to core.skills[] array in armadillo.json.

For pack skills: Add to packs.<pack-name>.skills[] array. If creating a new pack, add the entire pack entry:

"<pack-name>": {
  "description": "<one-line pack description>",
  "skills": ["<skill-1>", "<skill-2>"]
}

For agents: Add filename (e.g., "my-agent.md") to core.agents[] array.

sync-all.js

After editing armadillo.json:

node scripts/sync-all.js          # regenerate CLAUDE.md + README.md
node scripts/sync-all.js --check  # verify everything is in sync

If --check fails → fix the discrepancy and re-run until clean.

Shepherd Routing

Edit .claude/skills/armadillo-shepherd/SKILL.md:

1. Find the correct category section in the ## Routing Table
2. Add a row: | <request pattern> | \` |`
3. If no category fits, add to the closest match

For agents that route to skills, also check the Task tool agent descriptions in .claude/settings.json or the agent file itself.

Rules Registration

For new rules, add a row to the rules table in .claude/CLAUDE.md (in the ## Rules section):

| **<rule-name>** | <one-line description> |

Also add the rule to .claude/rules/ table in the release-checklist.md if armadillo-repo-specific.

Hook Registration

For hooks, the hooks.json edit IS the registration. Also verify the settings.json hooks section reflects the hooks.json content (sync-all handles this for skills, but hooks need manual verification).

Workflow Registration

For workflows, registration edits the shepherd directly:

1. Add the workflow chain to ## Workflows section of .claude/skills/armadillo-shepherd/SKILL.md
2. Add trigger pattern rows to the routing table sections
3. Run node scripts/sync-all.js to regenerate CLAUDE.md
4. Verify with node scripts/sync-all.js --check

If a glue skill was created, also register it in armadillo.json like any other core skill.

Commit Registration

git add armadillo.json .claude/skills/armadillo-shepherd/SKILL.md
git add .claude/CLAUDE.md README.md  # generated by sync-all
git commit -m "chore(maker): register <artifact-name> in armadillo ecosystem"

Phase 9: VERIFY

Invoke verification-before-completion (via Skill tool).

Skill: verification-before-completion

Verification Checklist

1. Test suite — run full test suite, all must pass:

   node --test tests/

   Known pre-existing failures (like hook-session-end.test.js) are documented — don’t block on those.

2. sync-all validation — registry and generated files in sync:

   node scripts/sync-all.js --check

3. Behavioral test — invoke the new artifact via subagent to verify it works:

   • For skills: can a subagent load and follow the skill correctly?
   • For agents: does the agent respond correctly to a test prompt?
   • For hooks: does the hook fire on the correct event and produce expected output?
   • For rules: does the rule constrain behavior as intended?

4. Registration verification — confirm the artifact is reachable:

   • Skill: grep shepherd routing table for the route
   • Agent: check armadillo.json agents list
   • Hook: check hooks.json has the entry
   • Rule: check CLAUDE.md rules table

Phase 10: SHIP

Invoke finishing-a-development-branch (via Skill tool).

Skill: finishing-a-development-branch

This automatically chains through:

1. finishing-a-development-branch — presents options (PR, Draft PR, Keep, Discard)
2. writing-prs — writes PR with conventional commit title + hybrid body
3. Squash merge via REST API (env -u GITHUB_TOKEN gh api)
4. Post-merge cleanup — delete branch, prune remotes, clean worktree

The maker’s job ends when the artifact is merged to main and the worktree is cleaned up.

Hard Gates

These gates are non-negotiable. No exceptions. No “this is too simple.”

Gate	Rule	Why
No skip recon	Phase 2 always runs	30-second overlap scan prevents hours of duplicate work
No skip design	Phase 4 required for create path	Design doc + approval = aligned expectations before code
No skip registration	Phase 8 always runs	Unregistered artifact = invisible artifact
No skip TDD	All code artifacts through RED-GREEN	writing-skills enforces its own TDD, hooks need test coverage
No manual branch	Phase 6 auto-creates worktree	Isolation prevents cross-contamination of work
No skip verification	Phase 9 always runs	Evidence before assertions, always

Anti-Rationalization Table

If you catch yourself thinking any of these, STOP — you’re rationalizing skipping the pipeline.

Thought	Reality
”This agent is too simple for the full pipeline”	Agents need shepherd routing + CLAUDE.md registration. Skip = invisible.
”I’ll register it later”	Later never comes. Registration is Phase 8, not optional.
”The user just wants a quick rule”	Rules need integration tables showing which skills use them. Design phase catches that.
”I know what this API does, skip research”	Training data is stale. WebSearch takes 30 seconds and catches breaking changes.
”This pack only has one skill, no need for pack structure”	One skill today, three tomorrow. Pack structure is cheap.
”I’ll update the shepherd routing after”	Unrouted skill = dead skill. Registration is atomic with creation.
”Tests aren’t needed for a markdown skill file”	Behavioral testing via subagent IS the test. writing-skills RED-GREEN is non-negotiable.
”I can do this faster without the pipeline”	Fast + wrong > slow + right? No. The pipeline exists because shortcuts fail.
”The user didn’t ask for a design doc”	The user asked for an artifact. The pipeline delivers it correctly. Users don’t ask for seatbelts either.
”This is just a small update, skip most phases”	Use the Update Path (below) — it’s shorter but still runs recon, research, register, verify, ship.

Error Recovery

Failure Point	Recovery Action
Recon finds exact duplicate	Ask user: modify existing or create variant? Don’t silently create duplicate.
Research finds API deprecated	Flag in design doc, propose alternative technology
sync-all.js --check fails	Fix discrepancy inline (usually missing armadillo.json entry), re-run
TDD RED phase finds no baseline failures	Skill already handles the case — recon may have missed overlap, re-evaluate scope
Merge conflict on armadillo.json	Rebase worktree onto main, re-run registration, re-verify
Pre-existing unrelated test failure	Document as known issue, don’t block on it (e.g., session-end hook test)
Subagent refuses to follow the skill	Skill content issue — iterate on SKILL.md, re-run GREEN test
User rejects design doc	Revise based on feedback, re-present. Don’t skip the gate.

Update Path

When update intent is detected in Phase 1, the pipeline shortens:

CLASSIFY → RECON (read current artifact) → RESEARCH (what changed) →
PLAN (lightweight — targeted edits only) → BRANCH → CRAFT (edits, not full rewrite) →
REGISTER (re-sync) → VERIFY → SHIP

Phase 4 (DESIGN) is skipped — the artifact already has an approved design.

Update Triggers

• User says “update”, “refresh”, “fix”, “improve”, “add to existing”
• Stale last_updated field detected (>90 days old)
• User explicitly requests a refresh of reference docs

Update Plan Characteristics

• One task per file to modify (not per feature)
• Registration task to re-run sync-all.js (catches frontmatter changes)
• Verification task (same as create path)
• Typically 3-5 tasks instead of 8-13

Batch Mode

When creating a pack with 5+ skills:

1. Single design doc covers the whole pack (one approval gate, not N)
2. Single plan with one task group per skill
3. Parallelized craft via dispatching-parallel-agents when skills touch separate directories (which they always do in a pack)
4. Single registration pass at the end — one armadillo.json update, one sync-all.js run
5. Single PR for the whole pack

When to Use Batch Mode

• Creating a pack with 3+ skills
• User explicitly says “batch” or “all at once”
• Multiple related artifacts that should ship together

Batch Limitations

• All skills must be in the same pack
• Design doc must cover all skills (don’t split approval across multiple docs)
• Registration is still one pass at the end — don’t register piecemeal