npm package: @fr-nan-ai/anvil
Description: Agent-first CLI — make any project AI-agent compatible
Latest version: 0.6.2

<p align="center">
  <img src="docs/anvil.png" alt="Anvil" width="250">
</p>

<h1 align="center">@fr-nan-ai/anvil</h1>

**Agent-first CLI — make any project AI-agent compatible.**

Anvil installs, projects, and maintains AI agent components (skills, recipes, hooks, agents) in each agent's native format. Write once, deploy to Copilot, Claude, or Cursor — then promote recipes to autonomous GitHub Agentic Workflows.

Components are loaded from the [official marketplace](https://github.com/FR-NAN-AI/anvil-marketplace) (synced on first use) and optional external marketplaces.

## How to use anvil — the human story

If you have never used anvil before, **read this first**. The detailed command reference comes later.

Anvil works in **two simple steps**, and you only need to remember one CLI command. The rest happens in your AI agent (Copilot, Claude, or Cursor) in plain natural language.

### Step 1 — Initialize the project with the CLI

In your terminal, at the root of any project (legacy or new):

```bash
anvil init --agent copilot
```

Replace `copilot` by `claude` or `cursor` if you use one of those instead. That's it for the CLI — anvil prepares the project (creates `.anvil/`, syncs the marketplace, installs the bootstrap skills) and stops.

### Step 2 — Open your IDE and ask the AI agent to take over

Open your project in VSCode (Copilot), Claude Code, or Cursor, and simply tell your AI agent:

> **« Initialize the project »**
> *(or in French: « Initialise le projet »)*

That's it. The agent will:
- Detect your stack (Java? Node? Python? Spring Boot? React?)
- Check that the tools you need are installed
- Suggest which AI components fit your project
- **Build a complete project wiki in `.anvil/wiki/`** — architecture, stack, conventions, known issues, and a "clone-install-run" README — by analyzing your codebase and validating each page with you
- Configure everything specific to your team (Jira? Linear? GitHub Issues?)

You stay in control the whole time. The agent explains what it does before doing it, asks before installing things, and you can stop at any moment.

### What you get when it's done

A `.anvil/` directory at the root of your project, ready to be committed and shared with your team:

```
.anvil/
  config.json        ← project configuration
  wiki/              ← navigable project knowledge base (architecture, stack, features, ...)
  state/             ← installed AI components
```

Your teammates clone the repo, open their AI agent, and **the wiki + the installed skills give the agent everything it needs** to be useful immediately on a project they have never seen before. No more "the AI hallucinates because it doesn't know our codebase".

### Day-to-day usage

After the initial setup, you keep talking to the agent in natural language:
- *« Is the wiki up to date? »* → the agent checks what changed and offers to refresh
- *« Implement this ticket: PROJ-123 »* → the agent uses the installed recipes
- *« Review my code »* → the agent uses the installed code-reviewer agent
- *« What does the orders module do? »* → the agent reads the wiki first and answers from grounded context

**You almost never need to touch the anvil CLI again** after `anvil init`. The agent uses anvil for you.

### Special case — onboard a legacy app

If you are **parachuted on a legacy app** that nobody documents anymore, use the dedicated bundle when initializing:

```bash
anvil init --agent copilot --preset legacy-archaeology
```

Then ask the agent to *« Initialize the project »* as above. The agent will run a deep cartography of the codebase (dependency graph, entry points, patterns, tech debt) and produce a full validated wiki — typically 30 to 90 minutes of dialogue, after which your team can actually understand the app.

---

## Quick Start (command reference)

The detailed list below is for advanced users and CI scripts. For day-to-day work, follow the "human story" above.

```bash
npm install -g @fr-nan-ai/anvil

# Initialize a project for GitHub Copilot
anvil init --agent copilot

# Or with a bundle (installs a curated set of components)
anvil init --agent copilot --preset full-stack

# Install components from the catalog
anvil install skill coding-principles
anvil install skill test-driven-development
anvil install hook pre-commit-check

# Customize a component for your team
anvil customize skill coding-principles
# Edit .anvil/state/local/skills/coding-principles/index.md
anvil generate

# Create a brand new local component
anvil create skill my-team-guidelines

# Promote a recipe to an autonomous GitHub workflow
anvil promote recipe my-workflow --target gh-aw

# Validate project integrity
anvil validate

# Check what's installed
anvil status
```

## Supported Targets

| Target | Surface |
|--------|---------|
| **copilot** | `.github/copilot-instructions.md`, `.github/instructions/`, `.github/prompts/` |
| **claude** | `AGENTS.md`, `.claude/skills/` |
| **cursor** | `.cursor/rules/*.mdc` |
| **gh-aw** *(promotion)* | `.github/workflows/*.md` + `.github/workflows/*.lock.yml` |

## How It Works

Anvil follows a **state-then-project** architecture with a **copy-on-customize** model:

```
catalog (official + external marketplaces)
    │
    ▼  anvil install
    │
.anvil/state/framework/     ← installed components (read-only)
    │
    ├── anvil customize ──► .anvil/state/local/  ← editable copies
    │
    ▼  anvil generate
    │
.github/instructions/        ← Copilot surface
.claude/skills/              ← Claude surface
.cursor/rules/               ← Cursor surface
```

1. `anvil install` copies a component from the catalog into `.anvil/state/framework/`
2. `anvil customize` copies it to `.anvil/state/local/` for editing
3. `anvil generate` projects state into the agent's native surface (auto-selects local or framework)
4. `anvil update` merges upstream changes into customized components (3-way merge with backup)
5. `anvil promote` compiles a recipe into a GitHub Agentic Workflow (`.md` + `.lock.yml`)
6. Components are tracked with SHA-256 hashes for version detection

## Commands

| Command | Description |
|---------|-------------|
| `anvil init --agent <target>` | Initialize a project for an AI agent |
| `anvil install <type> <name>` | Install a component from the catalog |
| `anvil remove <type> <name>` | Remove an installed component |
| `anvil customize <type> <name>` | Copy a component to local for editing |
| `anvil uncustomize <type> <name>` | Restore the framework version |
| `anvil create <type> <name>` | Scaffold a new local component |
| `anvil status` | Show installed components and their state |
| `anvil generate` | Re-project state to agent surface files |
| `anvil catalog` | Browse available components |
| `anvil inspect <type> <name>` | Show component details before installing |
| `anvil diff` | Compare installed components with source |
| `anvil update <type> <name>` | Update a component from source |
| `anvil update <type> <name> --preview` | Preview changes without applying |
| `anvil update <type> <name> --restore` | Restore from backup after a bad merge |
| `anvil marketplace list` | List configured marketplace sources |
| `anvil marketplace add <name>` | Add an external marketplace |
| `anvil marketplace remove <name>` | Remove a marketplace source |
| `anvil marketplace sync` | Sync marketplace catalogs |
| `anvil marketplace enable <name>` | Enable a marketplace |
| `anvil marketplace disable <name>` | Disable a marketplace |
| `anvil marketplace init <path>` | Scaffold a new marketplace repository |
| `anvil promote recipe <name> --target gh-aw` | Promote a recipe to a GitHub Agentic Workflow |
| `anvil promote --recompile <name>` | Recompile a promoted workflow after recipe update |
| `anvil validate` | Validate project integrity (config, state, promotions) |
| `anvil doctor` | Diagnose installation health |
| `anvil onboard complete` | Mark project as onboarded |

## Global Flags

| Flag | Description |
|------|-------------|
| `--json` | Output as structured JSON |
| `--yes` | Skip confirmation prompts (also `ANVIL_YES=1`) |
| `--verbose` | Verbose output |
| `--quiet` | Suppress non-essential output |
| `--force` | Force operation (skip guards) |
| `--from <marketplace>` | Specify source marketplace |
| `--all` | Apply to all components |
| `--preset <name>` | Use a preset during init |
| `--preview` | Dry-run for update (show diff without writing) |
| `--restore` | Restore last backup after update |
| `--target <target>` | Promotion target (currently `gh-aw`) |
| `--trigger <event>` | Trigger event for promoted workflow |
| `--recompile` | Recompile a promoted workflow |
| `--dry-run` | Simulate promotion without writing files |
| `--help` | Show help |
| `--version` | Show version |

## Customization

Anvil uses a **copy-on-customize** model: framework components are read-only, and customization creates an editable local copy.

```bash
# Customize a framework component
anvil customize skill coding-principles

# Edit the local copy
# .anvil/state/local/skills/coding-principles/index.md

# Re-project to surface
anvil generate

# When upstream updates are available
anvil update skill coding-principles --preview   # preview the diff
anvil update skill coding-principles             # merge with auto-backup
anvil update skill coding-principles --restore   # undo if merge was bad

# Revert to the framework version
anvil uncustomize skill coding-principles
```

### Creating Local Components

```bash
# Create a brand new skill (not from catalog)
anvil create skill my-guidelines

# Create a recipe
anvil create recipe my-workflow

# Local components are stored in .anvil/state/local/
# and projected to the active surface automatically
```

## Promotion (GitHub Agentic Workflows)

Recipes with `interactions` and `providers` can be **promoted** to autonomous GitHub Agentic Workflows. Promotion compiles a recipe (with its dependent skills inlined) into a `.md` workflow and a `.lock.yml` lockfile.

```bash
# Promote a recipe to GitHub Agentic Workflow
anvil promote recipe us-to-pr --target gh-aw

# Preview what would be generated (dry-run)
anvil promote recipe us-to-pr --target gh-aw --dry-run

# Specify a custom trigger event
anvil promote recipe us-to-pr --target gh-aw --trigger "issues:labeled:ready"

# After updating a promoted recipe, recompile the workflow
anvil update recipe us-to-pr
# ⚠ Warning: promoted workflow is stale
anvil promote --recompile us-to-pr
```

Generated files:
- `.github/workflows/<name>.md` — workflow with frontmatter (trigger, tools, permissions) + recipe content + inlined skills
- `.github/workflows/<name>.lock.yml` — lockfile with recipe hash, compiled timestamp, interaction mappings

### Interactions & Providers

Recipes can declare `interactions` (human-in-the-loop points) and `providers` (external integrations) in `component.yaml`:

```yaml
interactions:
  - id: validate-approach
    phase: analysis
    mode: interactive
    fallback: comment
providers:
  - type: ticket
    name: ticket-source
    required: true
```

These are visible via `anvil inspect recipe <name>` and compiled into the workflow during promotion.

## Hooks Runtime

Hooks with a `script` field in `component.yaml` execute shell scripts in response to events:

```yaml
name: post-install-check
type: hook
event: post.install
script: scripts/check.sh
timeout: 5000
```

Supported events: `session.start`, `session.end`, `prompt.submitted`, `tool.pre`, `tool.post.success`, `tool.post.failure`, `post.install`, `post.remove`, `post.generate`.

Scripts run sandboxed via `execFile` (not shell) with environment variables: `ANVIL_EVENT`, `ANVIL_PROJECT_ROOT`, `ANVIL_COMPONENT_NAME`.

## Validation

```bash
# Full project integrity check
anvil validate
```

Validates: catalog schema, config consistency, component state, hash integrity, surface projections, promotion consistency (workflow + lockfile exist, stale detection), and orphan components.

## Marketplaces

Anvil supports multiple component sources. The `official` marketplace is fetched from [GitHub](https://github.com/FR-NAN-AI/anvil-marketplace) and cached locally. You can add external sources via git or local path.

```bash
# Add a team marketplace from a git repo
anvil marketplace add myteam --git https://github.com/org/anvil-components.git

# Add a local marketplace (useful for development)
anvil marketplace add local-dev --local /path/to/components

# Sync all marketplaces
anvil marketplace sync

# Browse the unified catalog (all sources)
anvil catalog

# Install from a specific marketplace
anvil install skill my-skill --from myteam

# Scaffold a new marketplace repository
anvil marketplace init ./my-marketplace
```

When a component name exists in multiple marketplaces, anvil requires `--from` to disambiguate.

## Bundles (Presets)

Bundles are curated sets of components for common use cases, hosted in the marketplace:

```bash
anvil init --agent copilot --preset full-stack
```

Available bundles: `full-stack`, `tech-lead`. Browse them with `anvil catalog --type bundle`.

## Component Lifecycle

```bash
# Inspect before installing
anvil inspect skill coding-principles

# Install
anvil install skill coding-principles

# Customize for your team
anvil customize skill coding-principles

# Check for updates
anvil diff

# Update with 3-way merge (auto-backup)
anvil update skill coding-principles

# Preview update without writing
anvil update skill coding-principles --preview

# Restore backup if merge was bad
anvil update skill coding-principles --restore

# Update all non-customized components
anvil update --all

# Revert customization
anvil uncustomize skill coding-principles

# Remove (with dependency guard)
anvil remove skill coding-principles
```

## Project Structure

After `anvil init --agent copilot`, your project will have:

```
.anvil/
  config.json          ← project config (v2 schema)
  state/
    framework/
      official/        ← official catalog components
      external/        ← external marketplace components
    local/             ← customized + created components
  backups/             ← automatic backups before merges
  cache/
    marketplaces/      ← synced marketplace catalogs
  docs/                ← project documentation for agents
  .gitignore
```

## Component Types

| Type | Description | Copilot | Claude | Cursor |
|------|-------------|---------|--------|--------|
| **skill** | Reusable guidance | `.github/instructions/*.instructions.md` | `.claude/skills/*.md` | `.cursor/rules/*.mdc` |
| **hook** | Event-driven instructions | `.github/instructions/*-hook.instructions.md` | `.claude/skills/*-hook.md` | `.cursor/rules/*-hook.mdc` |
| **agent** | Specialized AI agents | `.github/instructions/*.instructions.md` | `.claude/skills/*.md` | `.cursor/rules/*.mdc` |
| **recipe** | Multi-step workflows | `.github/prompts/*.prompt.md` | `.claude/skills/*.md` | `.cursor/rules/*.mdc` |

## Component Format

Each component lives in its own directory with:

```
skills/coding-principles/
  component.yaml       ← metadata (type, name, version, targets, depends)
  index.md             ← content
```

## Configuration

`.anvil/config.json` uses a v2 schema:

```json
{
  "version": 2,
  "agent": "copilot",
  "marketplaces": {
    "official": { "kind": "git", "enabled": true, "priority": 0, "remote": "https://github.com/FR-NAN-AI/anvil-marketplace.git", "ref": "main" },
    "myteam": { "kind": "git", "enabled": true, "priority": 10, "remote": "..." }
  },
  "components": {
    "skills": {
      "coding-principles": {
        "marketplace": "official",
        "hash": "...",
        "customized": false,
        "frameworkHash": null
      }
    }
  },
  "promotions": {
    "us-to-pr": {
      "target": "gh-aw",
      "recipeHash": "...",
      "promotedAt": "...",
      "trigger": "issues:labeled:agent-ready",
      "workflowPath": ".github/workflows/us-to-pr.md",
      "lockfilePath": ".github/workflows/us-to-pr.lock.yml",
      "stale": false
    }
  },
  "onboarded": false
}
```

## Doctor

`anvil doctor` runs comprehensive health checks:

- Node.js version (>= 18)
- `.anvil/` structure integrity
- Component state consistency (config ↔ state ↔ surface)
- SHA-256 hash integrity (detects manual edits)
- Orphan components (state without config entry)
- Orphan projections (surface files without matching component)
- Customized components with outdated upstream
- Stale backups (> 30 days)
- Marketplace cache status

## Versioning

- **0.1.x**: Copilot target, official catalog
- **0.2.x**: Multi-target (Claude, Cursor), external marketplaces, presets
- **0.3.x**: Customization (copy-on-customize), create, 3-way merge, backups
- **0.4.x**: Promotion (gh-aw), validate, hooks runtime, interactions/providers
- **0.5.x**: Remote official marketplace, educational onboarding, improved adapters
- **v1.0.0**: Stable API, production ready

## Development

```bash
# Run E2E tests
node test/e2e-phase1.js    # 42 tests — core commands
node test/e2e-phase2.js    # 57 tests — marketplaces, adapters, lifecycle
node test/e2e-phase3.js    # 62 tests — customization, create, merge, backups
node test/e2e-phase4.js    # 49 tests — promotion, validate, hooks runtime

# Test manually
node bin/anvil --help
node bin/anvil --version
```

## Architecture

```
bin/anvil                    ← entry point
lib/
  cli/
    parse-args.js            ← argument parser (Node 18+ util.parseArgs)
    output.js                ← structured output (JSON/text)
  core/
    config.js                ← .anvil/config.json v2
    state-store.js           ← .anvil/state/ management
    hash.js                  ← SHA-256 component tracking
    catalog.js               ← catalog reader + multi-source merge
    marketplace.js           ← marketplace registry (add/remove/enable)
    marketplace-sync.js      ← git clone + cache management
    marketplace-cmd.js       ← anvil marketplace CLI handler (+ init)
    preset.js                ← preset loading + apply
    dependencies.js          ← dependency graph + remove guard
    init.js                  ← anvil init (+ preset support)
    install.js               ← anvil install (multi-source)
    remove.js                ← anvil remove (with dependency check)
    customize.js             ← anvil customize + uncustomize
    create.js                ← anvil create (scaffold local component)
    backup.js                ← automatic backups before merge
    merge.js                 ← 3-way merge engine
    status.js                ← anvil status
    generate.js              ← anvil generate
    inspect.js               ← anvil inspect
    diff.js                  ← anvil diff
    update.js                ← anvil update (+ merge, --preview, --restore)
    promote.js               ← anvil promote (recipe → gh-aw workflow)
    validate.js              ← anvil validate (project integrity)
    hooks-runtime.js         ← hooks script execution (sandboxed)
    doctor.js                ← anvil doctor (hash integrity, orphans)
    onboard.js               ← anvil onboard
  adapters/
    shared.js                ← adapter interface contract
    index.js                 ← adapter registry
    copilot/transform.js     ← Copilot adapter (.github/)
    claude/transform.js      ← Claude adapter (AGENTS.md, .claude/)
    cursor/transform.js      ← Cursor adapter (.cursor/rules/)
    gh-aw/transform.js       ← GitHub Agentic Workflow adapter (promotion)
skills/
  onboarding/                ← embedded fallback (auto-installed on init)
  anvil-cli-reference/       ← embedded fallback (auto-installed on init)
  catalog-browser/           ← embedded fallback (auto-installed on init)
```

## License

MIT — see [LICENSE](LICENSE)