ai-agentic-rules

Universal, tool-agnostic instruction packs for AI coding agents, plus tool-specific adapters.

CLI package: @aialchemy/ai-coding-rules (bin: ai-coding-rules)

What is this?

A modular system for defining how AI coding agents (and humans) should work in your codebase. Rules are organized into packs that can be combined via profiles, with explicit conflict resolution.

Philosophy

- Layered: Org-wide (~/.ai-coding-rules/) → Repo (AGENTS.md) → Domain/folder rules
- Tool-agnostic: Canonical rules live in packs; adapters are thin pointers
- Composable: Mix and match packs via profiles
- Explicit conflicts: Clear policy for resolving toolchain and rule conflicts
- Public-safe: No secrets, no internal URLs, no client names
- Human-owned: Your project context is never overwritten

Quick Start (Minimum Useful Setup)

Get started with a single command (npm v11+ requires an explicit binary):

``bash

`Option A (npx with explicit binary)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
Option B (npm exec)

npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init


That's it! This will:
1. Download the latest rules and adapters from GitHub
2. Prompt you to select a profile (bun-stack, node-stack, or mobile-stack)
3. Prompt you to select which AI tools you use (Cursor, VS Code Copilot, Kiro, Gemini)
4. Create a composed file structure that preserves your context
5. Configure your selected tools automatically
Outcome: Governance rules active, tool configured, human context preserved.
What This Tool Does (and Doesn't Do)
$3

- Governs how work happens (coding standards, conflict resolution, planning)
- Provides toolchain guidance (Bun vs Node, testing frameworks, etc.)
- Ensures consistency across your codebase
- Helps AI agents understand your project conventions
$3

- Replace developers
- Write business logic
- Make architectural decisions for you
- Run code or deploy applications
CLI Modes
The CLI supports three modes for different use cases:
$3

`bash ai-coding-rules init --mode=compose`

Behavior: - Creates or updatesAGENTS.rules.md(system-managed) - CreatesAGENTS.mdonly if missing (shared entry point) - CreatesAGENTS.local.mdonly if missing (human-managed, never overwritten) - Never deletes or overwrites human content

Use case: Default setup for new and existing projects.

`$3`

`bash ai-coding-rules init --mode=replace`

Behavior: - Fully regeneratesAGENTS.md- Requires explicit confirmation - Displays a warning before proceeding

Use case: When you want to start fresh with a completely new configuration.

`$3`

`bash ai-coding-rules init --mode=check`

Behavior: - Does not write files - Validates rule resolution - Returns non-zero exit code on conflicts - Validates pack availability and adapter configuration

Use case: CI/CD pipelines, validation before deployment.

`Plan Command`

Preview what would change without writing any files:

`bash ai-coding-rules plan`

Output includes: - Files to be created - Files to be modified - Files untouched - Rule packs applied - Conflict resolution decisions

Use case: High-trust feature for understanding impact before running.

`Non-interactive options (CI-friendly)`

You can skip prompts by providing explicit flags:

`bash ai-coding-rules init --mode=compose --profile=bun-stack --tools=cursor,vscode ai-coding-rules plan --profile=node-stack --tools=cursor,kiro,gemini ai-coding-rules check --profile=mobile-stack`

`File Ownership`

The CLI creates a composed file structure with clear ownership:

| File | Owner | Overwritten by CLI | | --------------- | ------ | ------------------ | | AGENTS.md | Shared | Only if missing | | AGENTS.rules.md | System | Yes | | AGENTS.local.md | Human | Never |

`$3`

`AGENTS.md # Entry point (human-readable, references other files) AGENTS.rules.md # System-managed (auto-generated, contains governance rules) AGENTS.local.md # Human-managed (never overwritten, your project context)`

`$3`

`markdown

`Agent Context`

This file is the canonical entry point for AI coding agents working in this repo.

`Governance Rules (Auto-generated)`

See: ./AGENTS.rules.md

`Project Context (Human-maintained)`

See: ./AGENTS.local.md`

`$3`

Edit this file to add: - Project overview and goals - Architecture decisions - Team-specific guidelines - Domain-specific rules - Any other project context

Important: This file is never overwritten by AI Agentic Rules.

`Installation Options`

`$3`

`bash

`Option A (npx with explicit binary)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
Option B (npm exec)

npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init

If you install the CLI globally, you can run ai-coding-rules init directly.

`$3`

`bash curl -fsSL https://raw.githubusercontent.com/aialchemylabs/ai-agentic-rules/main/install/install-from-remote.sh | bash`

Then run one of the commands above in your repo to configure it.

`$3`

1. Clone and install packs:`bash git clone https://github.com/aialchemylabs/ai-agentic-rules.git cd ai-agentic-rules ./install/install-to-home.sh`

2. Choose a profile: -bun-stack: Bun-first tooling + TypeScript + coding standards -node-stack: Node/pnpm/Vite/Jest + TypeScript + coding standards -mobile-stack: Android + iOS + coding standards

3. Create AGENTS.mdin your repo root:`markdown # Agent Rules for This Repository Profile: bun-stack # Repo-specific overrides - Use Next.js App Router - Prefer shadcn/ui components`Seeexamples/sample-repo/AGENTS.md for a complete example.

4. Configure your tool adapter: - Cursor: Copyadapters/cursor/rules/*.mdc to .cursor/rules/(create the folder if needed) - VS Code Copilot: Seeadapters/vscode-copilot/copilot-instructions.md- Kiro: Seeadapters/kiro/project.md- Gemini/Antigravity: Seeadapters/antigravity-gemini/GEMINI.md

`Structure`

`ai-agentic-rules/ ├── packs/ # Canonical rule packs │ ├── core/ # Universal agent behavior │ ├── bun-first/ # Bun toolchain defaults │ ├── typescript/ # TypeScript standards │ ├── java/ # Java standards │ ├── android/ # Android/Kotlin standards │ ├── ios/ # iOS/Swift standards │ ├── ai-coding-standards/ # Coding standards │ └── profiles/ # Profile definitions │ ├── bun-stack.md │ ├── node-stack.md │ └── mobile-stack.md ├── adapters/ # Tool-specific adapters │ ├── cursor/ │ ├── vscode-copilot/ │ ├── kiro/ │ └── antigravity-gemini/ ├── install/ # Installation scripts │ ├── install-to-home.sh │ ├── install-from-remote.sh │ └── update.sh └── examples/ # Example usage └── sample-repo/ └── AGENTS.md`

`Layering`

Rules are applied in this order (highest to lowest priority):

1. Enforcement: CI checks, linters, typecheck, tests, build pipelines 2. Org-wide rules:~/.ai-coding-rules/packs/(if installed) 3. Repo rules:.ai-coding-rules/directory in the repo 4. Domain/folder rules: Directory-specific overrides (if present) 5. Local context:AGENTS.local.md6. Profile defaults: Pack combinations defined in profiles

See packs/core/RULES.md for the full conflict resolution policy.

`Conflict Resolution`

When multiple rule sources apply:

1. Enforcement wins: CI/lint/tests override written guidance 2. Specific beats general: Folder rules > repo rules 3. Explicit precedence:org > repo > folder > local4. Profile decides toolchain:bun-stack → Bun, node-stack→ Node/pnpm/Vite 5. Match the repo: If repo already chose a toolchain, follow it

`Pack Editing Guidance`

- Core packs: canonical, do not edit directly. - Org packs: fork and own for your company’s rules. - Local overrides: useAGENTS.local.md or repo-level packs for project-specific context.

Precedence rule: org > repo > folder > local

`Rule Pack Maturity`

Each pack declares a maturity level in its metadata.json:

`$3`

- core — Canonical, rarely changed (e.g., core, typescript, ai-coding-standards) -opinionated — Stack-specific (e.g., bun-first, android, ios) -org— Company-owned (for org-specific packs) -experimental — Evolving (for experimental features)

`$3`

- Core packs should not be edited directly - Org packs are expected to be forked - Local overrides are supported and encouraged (viaAGENTS.local.md)

`Profiles`

`$3`

- packs/core— Universal agent behavior -packs/bun-first— Bun toolchain (bun install/test/build/serve) -packs/typescript— TypeScript strictness -packs/ai-coding-standards — Coding standards

Toolchain: Bun, bun:sqlite, Bun.redis, Bun.sql, Bun.serve(), HTML imports

`$3`

- packs/core— Universal agent behavior -packs/typescript— TypeScript strictness -packs/ai-coding-standards — Coding standards

Toolchain: Node.js, pnpm (preferred), Vite, Jest/Vitest, Express

`$3`

- packs/core— Universal agent behavior -packs/android— Android/Kotlin standards -packs/ios— iOS/Swift standards -packs/ai-coding-standards — Coding standards

Toolchain: Kotlin, Gradle, Android SDK / Swift, Xcode, SPM/CocoaPods

`Tool Adapters`

`$3`

From your consuming repo, copy adapter files from your ai-agentic-rules clone:

`bash mkdir -p .cursor/rules cp /path/to/ai-agentic-rules/adapters/cursor/rules/*.mdc .cursor/rules/`

The adapters point to AGENTS.md and installed packs.

CLI output: ✔ Cursor adapter applied → .cursor/rules/

`$3`

See adapters/vscode-copilot/copilot-instructions.md for setup instructions.

CLI output: ✔ VS Code Copilot adapter applied → .vscode/settings.json

`$3`

See adapters/kiro/project.md for configuration.

CLI output: ✔ Kiro adapter applied → .kiro/steering/project.md

`$3`

See adapters/antigravity-gemini/GEMINI.md for @include usage.

CLI output: ✔ Gemini adapter applied → GEMINI.md

`Local Validation`

`$3`

`bash

`Dry run (check what would be installed)`


./install/install-to-home.sh --dry-run
Install packs

./install/install-to-home.sh
Verify packs are installed

ls -la ~/.ai-coding-rules/packs/

$3

`bash

`Check all required files exist`


find packs adapters install examples -type f | sort
Verify scripts are executable

test -x install/install-to-home.sh && echo "✓ install script is executable"
test -x install/update.sh && echo "✓ update script is executable"


How a Consuming Repo Uses This
$3

`bash

`In your repo root (choose one)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init
Or with explicit mode

npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=compose
npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=replace
npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=check
Plan what would change

npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules plan

This automatically: - Downloads the latest rules and adapters from GitHub - Creates a composed file structure that preserves your context - CreatesAGENTS.md, AGENTS.rules.md, and AGENTS.local.md- Configures your selected IDE tools

`$3`

1. Install packs (optional, for org-wide use):`bash # Option A: Remote installer curl -fsSL https://raw.githubusercontent.com/aialchemylabs/ai-agentic-rules/main/install/install-from-remote.sh | bash # Option B: Clone and install git clone https://github.com/aialchemylabs/ai-agentic-rules.git cd ai-agentic-rules ./install/install-to-home.sh`

2. Create AGENTS.mdin your repo:`markdown # Agent Rules Profile: bun-stack # Repo-specific rules - Use Next.js App Router - Prefer shadcn/ui`

3. Configure your tool (e.g., Cursor):`bash mkdir -p .cursor/rules cp /path/to/ai-agentic-rules/adapters/cursor/rules/*.mdc .cursor/rules/`

4. Agents will: - ReadAGENTS.mdfirst - Load profile packs from~/.ai-coding-rules/packs/ or repo's .ai-coding-rules/- Apply repo-specific overrides fromAGENTS.local.md- Follow conflict resolution policy

`Non-Functional Requirements`

- Deterministic: All file writes are deterministic - Idempotent: CLI can be run multiple times safely - No silent destruction: Clear logs for every action - Safe defaults: Safety over power - Transparent: Every action is logged and explained

`Support`

If this project saved you time or helped improve your development workflow, consider supporting our work:

Sponsor us on GitHub — Buy us a coffee and help us continue building open-source tools for the AI coding community.

`License`

MIT License — see LICENSE file.

`Contributing`

This repository provides public-safe, tool-agnostic rule packs. Contributions should:

- Be explicit, testable, and short - Avoid tool lock-in - Include conflict resolution notes when introducing new packs - Keep eachRULES.mdunder ~200-300 lines - Includemetadata.json` for new packs with appropriate maturity level

Guiding Principle

> AI Agentic Rules should feel like guardrails, not handcuffs.

Speed with safety. Governance with respect.

ai-agentic-rules

Universal, tool-agnostic instruction packs for AI coding agents, plus tool-specific adapters.

CLI package: @aialchemy/ai-coding-rules (bin: ai-coding-rules)

What is this?

Philosophy

Quick Start (Minimum Useful Setup)

Get started with a single command (npm v11+ requires an explicit binary):

``bash

`Option A (npx with explicit binary)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
Option B (npm exec)

npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init


That's it! This will:
1. Download the latest rules and adapters from GitHub
2. Prompt you to select a profile (bun-stack, node-stack, or mobile-stack)
3. Prompt you to select which AI tools you use (Cursor, VS Code Copilot, Kiro, Gemini)
4. Create a composed file structure that preserves your context
5. Configure your selected tools automatically
Outcome: Governance rules active, tool configured, human context preserved.
What This Tool Does (and Doesn't Do)
$3

- Governs how work happens (coding standards, conflict resolution, planning)
- Provides toolchain guidance (Bun vs Node, testing frameworks, etc.)
- Ensures consistency across your codebase
- Helps AI agents understand your project conventions
$3

- Replace developers
- Write business logic
- Make architectural decisions for you
- Run code or deploy applications
CLI Modes
The CLI supports three modes for different use cases:
$3

`bash ai-coding-rules init --mode=compose`

Use case: Default setup for new and existing projects.

`$3`

`bash ai-coding-rules init --mode=replace`

Behavior: - Fully regeneratesAGENTS.md- Requires explicit confirmation - Displays a warning before proceeding

Use case: When you want to start fresh with a completely new configuration.

`$3`

`bash ai-coding-rules init --mode=check`

Behavior: - Does not write files - Validates rule resolution - Returns non-zero exit code on conflicts - Validates pack availability and adapter configuration

Use case: CI/CD pipelines, validation before deployment.

`Plan Command`

Preview what would change without writing any files:

`bash ai-coding-rules plan`

Output includes: - Files to be created - Files to be modified - Files untouched - Rule packs applied - Conflict resolution decisions

Use case: High-trust feature for understanding impact before running.

`Non-interactive options (CI-friendly)`

You can skip prompts by providing explicit flags:

`File Ownership`

The CLI creates a composed file structure with clear ownership:

`$3`

`markdown

`Agent Context`

This file is the canonical entry point for AI coding agents working in this repo.

`Governance Rules (Auto-generated)`

See: ./AGENTS.rules.md

`Project Context (Human-maintained)`

See: ./AGENTS.local.md`

`$3`

Edit this file to add: - Project overview and goals - Architecture decisions - Team-specific guidelines - Domain-specific rules - Any other project context

Important: This file is never overwritten by AI Agentic Rules.

`Installation Options`

`$3`

`bash

`Option A (npx with explicit binary)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
Option B (npm exec)

npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init

If you install the CLI globally, you can run ai-coding-rules init directly.

`$3`

`bash curl -fsSL https://raw.githubusercontent.com/aialchemylabs/ai-agentic-rules/main/install/install-from-remote.sh | bash`

Then run one of the commands above in your repo to configure it.

`$3`

1. Clone and install packs:`bash git clone https://github.com/aialchemylabs/ai-agentic-rules.git cd ai-agentic-rules ./install/install-to-home.sh`

`Structure`

`Layering`

Rules are applied in this order (highest to lowest priority):

See packs/core/RULES.md for the full conflict resolution policy.

`Conflict Resolution`

When multiple rule sources apply:

`Pack Editing Guidance`

- Core packs: canonical, do not edit directly. - Org packs: fork and own for your company’s rules. - Local overrides: useAGENTS.local.md or repo-level packs for project-specific context.

Precedence rule: org > repo > folder > local

`Rule Pack Maturity`

Each pack declares a maturity level in its metadata.json:

`$3`

- Core packs should not be edited directly - Org packs are expected to be forked - Local overrides are supported and encouraged (viaAGENTS.local.md)

`Profiles`

`$3`

Toolchain: Bun, bun:sqlite, Bun.redis, Bun.sql, Bun.serve(), HTML imports

`$3`

- packs/core— Universal agent behavior -packs/typescript— TypeScript strictness -packs/ai-coding-standards — Coding standards

Toolchain: Node.js, pnpm (preferred), Vite, Jest/Vitest, Express

`$3`

- packs/core— Universal agent behavior -packs/android— Android/Kotlin standards -packs/ios— iOS/Swift standards -packs/ai-coding-standards — Coding standards

Toolchain: Kotlin, Gradle, Android SDK / Swift, Xcode, SPM/CocoaPods

`Tool Adapters`

`$3`

From your consuming repo, copy adapter files from your ai-agentic-rules clone:

`bash mkdir -p .cursor/rules cp /path/to/ai-agentic-rules/adapters/cursor/rules/*.mdc .cursor/rules/`

The adapters point to AGENTS.md and installed packs.

CLI output: ✔ Cursor adapter applied → .cursor/rules/

`$3`

See adapters/vscode-copilot/copilot-instructions.md for setup instructions.

CLI output: ✔ VS Code Copilot adapter applied → .vscode/settings.json

`$3`

See adapters/kiro/project.md for configuration.

CLI output: ✔ Kiro adapter applied → .kiro/steering/project.md

`$3`

See adapters/antigravity-gemini/GEMINI.md for @include usage.

CLI output: ✔ Gemini adapter applied → GEMINI.md

`Local Validation`

`$3`

`bash

`Dry run (check what would be installed)`


./install/install-to-home.sh --dry-run
Install packs

./install/install-to-home.sh
Verify packs are installed

ls -la ~/.ai-coding-rules/packs/

$3

`bash

`Check all required files exist`


find packs adapters install examples -type f | sort
Verify scripts are executable

test -x install/install-to-home.sh && echo "✓ install script is executable"
test -x install/update.sh && echo "✓ update script is executable"


How a Consuming Repo Uses This
$3

`bash

`In your repo root (choose one)`


npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init
npm exec --yes --package=@aialchemy/ai-coding-rules -- ai-coding-rules init
Or with explicit mode

npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=compose
npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=replace
npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules init --mode=check
Plan what would change

npx --yes --package=@aialchemy/ai-coding-rules ai-coding-rules plan

`$3`

2. Create AGENTS.mdin your repo:`markdown # Agent Rules Profile: bun-stack # Repo-specific rules - Use Next.js App Router - Prefer shadcn/ui`

3. Configure your tool (e.g., Cursor):`bash mkdir -p .cursor/rules cp /path/to/ai-agentic-rules/adapters/cursor/rules/*.mdc .cursor/rules/`

`Non-Functional Requirements`

`Support`

If this project saved you time or helped improve your development workflow, consider supporting our work:

Sponsor us on GitHub — Buy us a coffee and help us continue building open-source tools for the AI coding community.

`License`

MIT License — see LICENSE file.

`Contributing`

This repository provides public-safe, tool-agnostic rule packs. Contributions should:

Guiding Principle

> AI Agentic Rules should feel like guardrails, not handcuffs.

Speed with safety. Governance with respect.