Gaia Forge — Installer CLI for .axetrules/ and tools/

Gaia Forge is a Node.js CLI that installs and configures a standard workspace layout in the folder where it is executed.

When you run gaia-forge, it copies the following directories (bundled inside the npm package) into your current working directory (cwd):

• .axetrules/ — rules, automation assets and history structure used by Axet/agents
• tools/ — shared tools shipped with this repository (e.g. doc generation workflows)

This repository intentionally behaves as an installer/configurator (it does not scaffold applications).

Table of contents

• What it does
• Requirements
• Install
• Quick start
• CLI reference
• Files installed
• Safety & overwrite policy
• Development
• Publishing

What it does

✅ Install assets into the current folder

Running the CLI will create (or update) these directories in cwd:

• ./.axetrules/
• ./tools/

✅ Idempotent by default

If the target directories already exist, Gaia Forge will:

• ask for confirmation before overwriting, or
• overwrite automatically when you pass --force

✅ Works with npm, npx, or npm link

Requirements

• Node.js: 18+ (LTS recommended)

Install

Global install (recommended)

npm install -g gaia-forge

Verify:

gaia-forge --help

One-off usage (no global install)

npx gaia-forge --help

Quick start

From the folder where you want the assets installed:

cd my-project
gaia-forge

This runs the default behavior: install into the current working directory.

To force overwrite without prompts:

gaia-forge install --force

CLI reference

gaia-forge (no args)

Alias for:

gaia-forge install

gaia-forge install

Copies .axetrules/ and tools/ into the current directory.

Usage

gaia-forge install [options]

Options

• -f, --force
  Overwrite existing .axetrules/ and tools/ directories without prompting.

Exit codes

• 0 success
• 1 unexpected error (a message will be printed to stderr)

Files installed

.axetrules/

Contains rules and supporting resources. Example structure:

• .axetrules/sonar/ (Sonar rules & snapshots, if bundled)
• .axetrules/history/ (local execution evidence and reports)

Note: .axetrules/history/ tends to be generated/grown over time (it can be ignored in git).

tools/

Contains reusable workflows and scripts shipped with Gaia Forge. Example:

• tools/docgen/workflow_crearReadme/ (readme generators, templates, prompts)

Safety & overwrite policy

By default, if ./.axetrules/ or ./tools/ already exist:

• Gaia Forge does not overwrite automatically
• It will prompt:
  • “¿Quieres sobrescribir … ?”
• If you answer “no”, that directory will be skipped and the command continues with the next one.

To overwrite both directories without prompting:

gaia-forge install --force

Development

Local setup

npm install
npm link

Run locally

gaia-forge --help
gaia-forge install

Publishing

Validate packaged content

npm run prepack
npm pack

Publish

npm login
npm version patch
npm publish