airc

Shared CLAUDE.md conventions for Ark/ArdentHQ repos, delivered by a single CLI.

Single source of truth for AI/agent conventions across the Ark/ArdentHQ ecosystem. One CLI works in any repo, whatever the stack - PHP, JS, Rust, and more.

Philosophy

The goal is a small, shared baseline of AI instructions that every repo can pull in and that ages well - not a style guide.

What belongs here

• Preferences and conventions that aren't obvious: how commits, PRs, and overrides should work, and the few code habits a model wouldn't already follow.
• Rules that are universal and stable - true across stacks, and likely still true in six months.
• A clean separation: guidelines/ holds rules for the AI; recommended.yaml holds tools to suggest installing. Never "install X" inside a guideline.

What doesn't

• Anything the linter, formatter, type system, or the model already enforces. If a tool can catch it, let the tool catch it.
• Project-specific detail (paths, scripts, gotchas) - that lives in each repo's own CLAUDE.md, below the imports.
• Personal preference - that goes in a gitignored CLAUDE.local.md.
• Volume. Fewer rules age better; when in doubt, leave it out. A stale rule the model follows literally is worse than no rule.

How it behaves

• Non-invasive and layered: the CLI only writes .claude/ardenthq/* and the @import lines - everything else in your CLAUDE.md is yours. Overrides go weakest to strongest: the managed baseline, then your repo's CLAUDE.md, then CLAUDE.local.md.
• Universal by default: rules read so that anyone could adopt them, not just this org.

Usage

Run the installer once in a repo (needs Node ≥18):

npx @ardenthq/airc install

It writes the guideline files to .claude/ardenthq/, adds the matching @import lines to your CLAUDE.md (creating it if missing), ignores CLAUDE.local.md, and prints recommended tools that aren't installed yet. Set AIRC_QUIET=1 to hide the recommendations.

Flags: --path <dir> to target another directory, --no-gitignore to skip the .gitignore edit.

Keep it in sync

update re-syncs the managed .claude/ardenthq/ files only - it never touches your CLAUDE.md or .gitignore. Wire it into the repo's native hook so it refreshes automatically:

// composer.json (PHP)
"scripts": { "post-update-cmd": ["npx @ardenthq/airc update"] }

// package.json (JS/TS)
"scripts": { "postinstall": "npx @ardenthq/airc update" }

For other stacks, run npx @ardenthq/airc update from a git hook or CI step.

npx caches by version - use npx @ardenthq/airc@latest … to be sure you're on the current release. In CI, airc check exits non-zero when the managed files drift or fall behind, so a stale or hand-edited baseline fails the build.

Security

If you discover a security vulnerability, please email [email protected]. All reports will be promptly addressed.

Credits

This project exists thanks to all the people who contribute.

License

MIT © ArdentHQ