Ailloy

The package manager for AI instructions.

Find, create, and share reusable AI workflow packages — the way Helm manages Kubernetes applications.

Quick Start · Documentation · Official Mold · Contributing

---

Why Ailloy

• Reproducible — Versioned, configurable mold packages with Helm-style value precedence. Same mold, same flux values, same output every time.
• Tool-agnostic — Works with any AI coding tool that reads file-based instructions: Claude Code, Cursor, Windsurf, GitHub Copilot, and more. The output: mapping in flux.yaml decides where blanks land.
• Helm-style ergonomics — cast, forge, smelt, temper. If you know helm install and helm template, you already know the shape.

What is Ailloy?

Ailloy compiles, packages, and distributes AI-assisted development workflows. Molds are to Ailloy what charts are to Helm: versioned, configurable packages that can be installed into any project.

Like in metallurgy — combining elements yields a stronger alloy — Ailloy fuses human development practices with AI assistance.

Helm	Ailloy	What it does
helm template	ailloy forge	Dry-run render of blanks with flux values
helm install	ailloy cast	Compile and install blanks into a project
helm package	ailloy smelt	Bundle a mold into a tarball or binary
helm lint	ailloy temper	Validate mold structure and templates
—	ailloy anneal	Interactive wizard to set flux variables
—	ailloy assay	Lint rendered AI instruction files

How It Works

The Ailloy pipeline is a small set of composable steps. Author once, configure per project, render and install anywhere.

Step	Command	Description
Author	—	Write instruction templates (blanks) with Go text/template syntax
Configure	ailloy anneal	Interactive wizard to set flux variables
Preview	ailloy forge	Dry-run render of blanks with flux values
Install	ailloy cast	Compile and install blanks into a project
Package	ailloy smelt	Bundle a mold into a tarball or binary
Validate	ailloy temper	Validate mold structure, manifests, and templates
Lint	ailloy assay	Lint rendered AI instruction files against best practices

Quick Start

1. Install

Homebrew (macOS, Linux)

brew install nimble-giant/tap/ailloy

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/nimble-giant/ailloy/main/install.sh | bash

Go install

go install github.com/nimble-giant/ailloy/cmd/ailloy@latest

Build from source

git clone https://github.com/nimble-giant/ailloy
cd ailloy
make build   # binary at ./bin/ailloy

Already installed? ailloy evolve (alias: reinstall) upgrades the CLI in place to the latest release — Homebrew installs should still use brew upgrade nimble-giant/tap/ailloy.

2. Cast a mold

Molds resolve directly from git — no clone required:

# Install blanks from the official mold (latest tag)
ailloy cast github.com/nimble-giant/nimble-mold

# Pin to a version, or use a semver range
ailloy cast github.com/nimble-giant/nimble-mold@v0.1.10
ailloy cast github.com/nimble-giant/nimble-mold@^0.1.0

# Include GitHub Actions workflow blanks
ailloy cast github.com/nimble-giant/nimble-mold --with-workflows

# Override flux at install time
ailloy cast github.com/nimble-giant/nimble-mold --set project.organization=mycompany

# Install as a Claude Code plugin (writes to .claude/plugins/<slug>/)
ailloy cast github.com/nimble-giant/nimble-mold --claude-plugin

3. Configure flux variables

# Interactive wizard
ailloy anneal github.com/nimble-giant/nimble-mold -o flux-overrides.yaml

# Use the overrides
ailloy cast github.com/nimble-giant/nimble-mold -f flux-overrides.yaml

Commands

cast · forge — install and preview molds

ailloy cast [mold-ref] (alias: install) — Render and install blanks. Accepts a local path or host/owner/repo[@version][//subpath].

• -g, --global — Install into ~/ instead of the current project
• --with-workflows — Include GitHub Actions workflow blanks
• --set key=value — Override flux variables (repeatable)
• -f, --values file — Layer flux value files (repeatable)
• --claude-plugin — Package the rendered mold as a Claude Code plugin under .claude/plugins/<slug>/ (see docs/cast-claude-plugin.md)
• --plugin-name, --plugin-version — Override plugin metadata (require --claude-plugin)

ailloy forge [mold-ref] (aliases: blank, template) — Dry-run render of mold blanks.

• -o, --output dir — Write to a directory instead of stdout
• --set, -f — Same as cast

mold · ingot — manage blanks and template components

ailloy mold — Manage AI command blanks.

• list — Show all available blanks
• show <blank-name> — Display blank content
• get <reference> — Download a mold to local cache without installing

ailloy ingot — Reusable template components.

• get <reference> — Download to local cache
• add <reference> — Install into the project's .ailloy/ingots/

anneal — configure flux variables

ailloy anneal [mold-ref] (alias: configure) — Mold-aware wizard. Reads flux.schema.yaml to generate type-driven prompts with optional discovery commands.

• -s, --set key=value — Set in scripted mode (repeatable)
• -o, --output file — Write flux YAML to file (default: stdout)

smelt — package molds for distribution

ailloy smelt [mold-dir] (alias: package) — Package a mold into a distributable format.

• -o, --output-format — tar (default) or binary
• --output dir — Output directory

assay · temper — lint and validate

ailloy assay [path] (alias: lint) — Lint rendered AI instruction files.

• Auto-detects CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions, and more
• --format json|markdown for CI · --fail-on warning|suggestion for exit control
• Configure via .ailloyrc.yaml (--init for a starter)

ailloy temper [path] (alias: validate) — Validate a mold or ingot package.

• Checks structural integrity, manifests, file references, template syntax, flux schema
• --lint — Render and run assay on output before casting
• --set, -f, --format, --fail-on, --max-lines

foundry — discover and manage mold registries

See the Remote Molds guide.

The official nimble-giant foundry (github.com/nimble-giant/foundry) is a verified built-in default — it appears in list and is searched by search without any registration step.

• search <query> — Search registered indexes and GitHub Topics
• add <url> — Register a foundry index (git repo or static YAML URL)
• list — List registered indexes and their status
• remove <name|url> — Remove a registered index
• update — Refresh all cached indexes
• install <name|url> (alias: cast-all) — Cast every mold the foundry indexes (skips already-installed; -g, --with-workflows, --dry-run, --force, --claude-plugin)

foundries — interactive TUI

ailloy foundries opens a four-tab terminal UI (Discover / Installed / Foundries / Health) for browsing the catalog, multi-installing molds, managing your casted ailloys, and surfacing drift + assay findings. Requires a TTY. See the TUI section in the foundry guide.

cache clear — clear the on-disk cache

ailloy cache clear (also: ailloy clear cache) wipes the global caches under ~/.ailloy/cache/ — both mold artifacts and foundry indexes. Prints a preview (counts + size) and prompts for confirmation. In a non-interactive shell it refuses to run without --yes. See docs/cache.md for the full guide.

• --molds — clear only the mold artifact cache (preserve indexes/)
• --indexes — clear only the foundry index cache
• --dry-run — preview what would be cleared without deleting
• -y/--yes — skip the confirmation prompt

uninstall — remove a casted mold

ailloy uninstall <source> removes the files a previous cast wrote. Uses the install manifest (files: + fileHashes: in ailloy.lock) so user-modified files are retained unless --force is passed; files claimed by another casted mold are retained automatically.

• -g/--global — operate on ~/ailloy.lock instead of ./ailloy.lock
• --dry-run — print what would be removed without touching disk
• --force — delete files even if modified since cast

evolve — self-upgrade the CLI

ailloy evolve (alias: reinstall) — Download the latest release, verify its SHA256 against the release's checksums.txt, and atomically swap the running binary in place. On success, plays a retro RPG-style evolution animation; falls back to a plain success line outside a TTY.

• --check — Print current and latest version without installing
• --version vX.Y.Z — Install or downgrade to a specific release tag
• --force — Upgrade even if installed via Homebrew (default behavior is to refuse and point at brew upgrade nimble-giant/tap/ailloy)
• --no-animate — Skip the evolution animation

Windows is not supported (the running .exe can't be replaced in place); download a release manually instead.

plugin — Claude Code plugin generation

Currently Claude Code specific; the core pipeline is tool-agnostic.

• generate — Generate plugin from blanks (--mold, --output, --watch, --force)
• update [path] — Update existing plugin
• validate [path] — Validate plugin structure

Looking to install a mold as a Claude Code plugin (rather than author one)? Use ailloy cast --claude-plugin instead.

Bidirectional commands — noun-verb or verb-noun

ailloy foundry search blueprint    # noun-verb
ailloy search foundry blueprint    # verb-noun

ailloy mold get github.com/org/repo
ailloy get mold github.com/org/repo

ailloy ingot add github.com/org/repo
ailloy add ingot github.com/org/repo

Blanks

Blanks are Markdown instruction templates — commands, skills, or workflows — that compile with flux variables when you cast or forge a mold.

• Commands (commands/) — Invoked explicitly (e.g., /brainstorm, /create-issue)
• Skills (skills/) — Proactive workflows the AI tool uses based on context
• Workflows (workflows/) — GitHub Actions YAML, installed with --with-workflows

# Deploy Checklist

Generate a deployment checklist for {{ project.organization }}.

1. Use `{{ scm.cli }}` to check for open PRs targeting the release branch
2. Verify all CI checks are passing

{{if .ore.status.enabled}}
Update the status field ({{ .ore.status.field_id }}) after each step.
{{end}}

The official mold ships pre-built blanks for SDLC tasks (issue management, PR workflows, code review) and is a good reference. For the full guide, see docs/blanks.md. For packaging, see docs/smelt.md.

Configuration

Ailloy uses flux — YAML variable files that configure how blanks render.

Precedence (lowest → highest):

1. mold.yaml flux: schema defaults
2. flux.yaml defaults shipped with the mold
3. -f value files (left to right)
4. --set flags

For the full guide, see docs/flux.md. For the wizard, see docs/anneal.md.

Status

Alpha — Ailloy is an early-stage package manager for AI instructions. The core toolchain is functional and used in production by the maintainers, but APIs and on-disk formats may change before 1.0.

What's shipped

• Mold casting and forging with flux variable rendering
• Blank management and viewing
• Flux-based configuration with Helm-style value precedence
• Reusable flux partials via ore — opt-in data structures for business logic (e.g. GitHub Project status, priority, iteration)
• Mold packaging (tarball and self-contained binary)
• Mold/ingot validation and linting
• Claude Code plugin generation from blanks
• Workflow blanks for GitHub Actions
• Automatic GitHub Project field discovery via GraphQL
• Interactive wizard with charmbracelet/huh for guided configuration
• SCM-native mold resolution from git repos with semver constraints and local caching
• Foundry search and discovery via GitHub Topics and SCM-agnostic foundry indexes
• Ingot package management with bidirectional CLI commands

What's planned

• Additional AI provider support
• Advanced workflow automation

Project structure

/cmd/ailloy          # CLI tool entry point
/internal            # Private Go packages
  /commands          # CLI command implementations (cast, forge, smelt, etc.)
/pkg
  /blanks            # MoldReader abstraction (reads mold directories)
  /foundry           # SCM-native mold resolution, caching, version management
  /github            # GitHub ProjectV2 discovery via gh API GraphQL
  /mold              # Template engine, flux loading, ingot resolution
  /plugin            # Plugin generation pipeline
  /safepath          # Safe path utilities
  /smelt             # Mold packaging (tarball/binary)
  /styles            # Terminal UI styles (lipgloss)
/docs                # Documentation

Contributing

Community input welcome. As AI development practices mature, Ailloy aims to be the standard package manager for AI instructions — the way Helm became the standard for Kubernetes.

Prerequisites

Recommended: Flox provides a reproducible dev environment with all dependencies.

curl -fsSL https://flox.dev/install | bash    # one-time
flox activate
make check-deps

Manual installation

Dependency	Purpose	Install
Go 1.24+	Build the CLI	brew install go
golangci-lint	Linting	brew install golangci-lint
lefthook	Git hooks	brew install lefthook
Docker	Local CI	Docker Desktop
act	Run GitHub Actions locally	brew install act
gh	GitHub CLI	brew install gh

Development setup

git clone https://github.com/nimble-giant/ailloy
cd ailloy
flox activate          # or install deps manually
make hooks             # install git hooks
make build
make test
make lint
make ci                # full CI run locally (requires Docker)

Submitting changes

1. Fork the repository
2. Create a feature branch
3. Add blanks or improve CLI functionality
4. Ensure make test and make lint pass
5. Submit a pull request

Contributors

License

Apache License 2.0 — see LICENSE.md.