@ardenthq/airc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArdentHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# 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):
+
+```bash
+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:
+
+```jsonc
+// 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 <security@ardenthq.com>. All reports will be promptly addressed.
+
+## Credits
+
+This project exists thanks to all the people who [contribute](../../contributors).
+
+## License
+
+[MIT](LICENSE) © [ArdentHQ](https://ardenthq.com)

package/guidelines/core.md

@@ -0,0 +1,65 @@
+<!-- airc v{{VERSION}} — managed file, do not edit -->
+<!-- Local override: CLAUDE.local.md. Per-repo override: below the @imports in CLAUDE.md. Permanent override: PR to https://github.com/ardenthq/airc -->
+
+# Baseline
+
+Shared rules for every repo. Apply to any stack.
+
+## Commits
+
+- Format: [Conventional Commits](https://www.conventionalcommits.org) — `feat:`, `fix:`, `chore:`, `style:`, `refactor:`, `test:`, `docs:`
+- Subject line only, ideally under 50 characters
+- Human, direct tone. Avoid formal or robotic voice ("this commit introduces…", "this change implements…")
+- **Never** add `Co-Authored-By` or any mention of Claude / AI / agents
+- **Never** add a description or body — subject only
+- Commit incrementally when a logical chunk lands — don't batch everything at the end
+- Examples: `feat: scaffold composer package`, `fix: stack detection for inertia`
+
+## Pull Requests
+
+- Always draft (`gh pr create --draft`)
+- Base branch: the repo's default
+- **Never** reference Claude / AI / agents in title, body, branch name, or comments
+
+## Pre-push checks
+
+Standard order before pushing:
+
+1. Formatter → 2. Linter → 3. Static analysis → 4. Tests
+
+Exact commands are repo-defined (see the repo's `CLAUDE.md` / `composer.json` / `package.json`). If the formatter modifies files, commit those changes before pushing so CI doesn't kick back automated `style:` cleanup commits.
+
+**Mid-task (recommendation):** for long tasks, run only affected/new checks during the work; defer the full suite to the end. For short tasks, skip intermediate runs. Don't run checks repeatedly mid-work — once at completion is usually enough.
+
+## Security
+
+- Never commit `.env`, credentials, tokens, or any secret
+- Flag any new dependency as suspect before adding it (typosquatting, unknown maintainer, etc.)
+- No destructive operations (`force-push`, branch deletion, history rewrite, `git reset --hard`, `rm -rf`) without explicit confirmation from the dev
+- For external tools (CI, pastebins, gists): consider whether uploaded content could be sensitive — it may be cached or indexed even if later deleted
+
+## Code style
+
+- Follow existing patterns before introducing new ones
+- Reuse existing components/helpers before writing new ones
+- No comments unless explaining a non-obvious **why** (a hidden constraint, a subtle invariant, a workaround for a specific bug)
+- Well-named identifiers > a comment explaining the "what"
+- **Don't document changes in comments.** Comments describe the code as it is, not how it got there:
+  - ❌ `// moved from backend to frontend`
+  - ❌ `// renamed from foo to bar`
+  - ❌ `// replaces the previous logic that used X`
+  - ❌ `// added for issue #123`
+  - ✅ omit the comment — git log / PR tells the story
+- Don't reference callers or temporal context: no `// used by X`, `// for the Y flow`, `// added in sprint Z`
+
+## Claude reply style
+
+- Concise. Skip the obvious.
+- End-of-turn summary: one or two sentences — what changed, what's next.
+- No long essays, no unnecessary disclaimers, no "sure, happy to help…"
+
+## Overrides
+
+- Personal override: create `CLAUDE.local.md` (gitignored)
+- Per-repo override: add rules below the `@imports` in this repo's `CLAUDE.md`
+- Permanent shared override: PR against the upstream guidelines repo

package/guidelines/js.md

@@ -0,0 +1,39 @@
+<!-- airc v{{VERSION}} — managed file, do not edit -->
+
+# JavaScript / TypeScript
+
+Code-writing rules for JS/TS files. Apply when writing or editing JS/TS code.
+
+## Types
+
+- TypeScript in strict mode. Don't disable strict checks per file.
+- Avoid `any` — use `unknown` and narrow, or a precise type.
+- Add explicit return types to exported functions.
+- Prefer `type` aliases; use `interface` only when you need declaration merging.
+- Keep shared/exported types in a dedicated `*.types.ts` file, not scattered across unrelated modules.
+
+## Syntax
+
+- Named exports over default exports (except where a framework requires default, e.g. a Next.js page).
+- Use curly braces for every control structure, even single-line bodies.
+
+## Comments
+
+- No comments unless explaining a non-obvious **why** (see `core.md`).
+- Well-named identifiers over a comment explaining the "what".
+
+## Package manager
+
+- Prefer **pnpm** over `npm` or `yarn`.
+
+## Scripts
+
+Use the standard scripts; don't invoke the underlying tool directly:
+
+- `pnpm format` — formatter (Prettier)
+- `pnpm lint` — linter (ESLint)
+- `pnpm test` / `pnpm test:coverage` — tests
+
+## Avoid
+
+- Mutating arguments or inputs — take them immutable, return new values.

package/guidelines/php.md

@@ -0,0 +1,75 @@
+<!-- airc v{{VERSION}} — managed file, do not edit -->
+
+# PHP
+
+Code-writing rules for PHP files. Apply when writing or editing PHP code. In Laravel apps these rules layer on top of whatever `laravel/boost` provides.
+
+## Types
+
+- Declare `strict_types=1` at the top of every PHP file.
+- Add explicit return type declarations to every method.
+- Add type hints to every parameter.
+- Use union and intersection types when they fit. Avoid `mixed` unless genuinely unbounded.
+- Use `readonly` properties when the value doesn't change after construction.
+
+## Syntax
+
+- Use PHP 8 constructor property promotion. Don't leave empty `__construct()` methods.
+- Use curly braces for every control structure, even single-line bodies.
+- Use `match` instead of `switch` when assigning a value or returning early.
+- Use first-class callable syntax (`Foo::bar(...)`) over closures wrapping a single call.
+- Use named arguments when a call has multiple booleans or optional params and clarity beats brevity.
+
+## Enums
+
+- Use enum classes for fixed sets of values; don't use string constants on a class.
+- TitleCase for enum case keys: `FavoritePerson`, `Monthly`.
+
+## Comments and PHPDoc
+
+- Prefer PHPDoc blocks over inline comments. Inline comments only for non-obvious WHY (see `core.md` rules on comments).
+- Use array shape definitions in PHPDoc for structured arrays:
+
+```php
+/** @return array{name: string, age: int} */
+```
+
+## PHP 8.4+ array helpers
+
+Prefer the built-in helpers over manual loops:
+
+- `array_find` over `foreach` + early return
+- `array_find_key` over manual key lookup
+- `array_any` / `array_all` over `foreach` + boolean accumulator
+
+## Method chaining on new instances (PHP 8.4+)
+
+Chain directly without wrapping in parentheses:
+
+```php
+// avoid: $d = (new DateTime('now'))->modify('+1 day');
+$d = new DateTime('now')->modify('+1 day');
+```
+
+## Composer scripts
+
+Use the standard scripts; don't invoke the underlying tool directly:
+
+- `composer format` — formatter (Pint)
+- `composer analyse` — static analysis (phpstan)
+- `composer test` / `composer test:coverage` — tests (Pest)
+
+If a script is missing, add it to `composer.json`:
+
+```json
+"scripts": {
+    "format": "vendor/bin/pint",
+    "analyse": "vendor/bin/phpstan analyse",
+    "test": "vendor/bin/pest"
+}
+```
+
+## Avoid
+
+- Mutating function arguments — take immutable inputs, return new values.
+- Static state (singletons, statics for caching). Prefer dependency injection.

package/guidelines/recommended.yaml

@@ -0,0 +1,44 @@
+# Optional recommendations the CLI prints after install.
+# Filters: `stacks` empty = any repo; populated = only those stacks.
+# Skip the recommendation if any `detect` rule resolves true.
+
+skills:
+  - name: caveman
+    description: Compresses Claude's output (~65% token savings)
+    install: curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
+    detect:
+      paths:
+        - ~/.claude/plugins/cache/caveman
+        - ~/.claude/skills/caveman
+    scope: user
+    stacks: []
+
+composer:
+  - name: laravel/boost
+    description: Laravel-aware AI guidelines and MCP server (covers Laravel patterns we intentionally don't duplicate)
+    install: composer require --dev laravel/boost && php artisan boost:install
+    detect:
+      composerJson: laravel/boost
+    stacks: [laravel]
+
+  - name: laravel/pint
+    description: Standalone code formatter (works without Laravel). Backs `composer format`.
+    install: composer require --dev laravel/pint
+    detect:
+      composerJson: laravel/pint
+    stacks: [php]
+
+npm:
+  - name: prettier
+    description: Code formatter. Backs `pnpm format`.
+    install: pnpm add -D prettier
+    detect:
+      npmJson: prettier
+    stacks: [js]
+
+  - name: eslint
+    description: Linter (pair with typescript-eslint on TS projects). Backs `pnpm lint`.
+    install: pnpm add -D eslint typescript-eslint
+    detect:
+      npmJson: eslint
+    stacks: [js]

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ardenthq/airc",
+  "version": "0.1.0",
+  "description": "Shared Claude conventions for Ark/ArdentHQ repos — writes guideline files into a consumer repo's .claude/ardenthq/ and wires up the CLAUDE.md imports.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "airc": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "guidelines"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.0.0",
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write \"**/*.{md,yaml,yml,json}\"",
+    "format:check": "prettier --check \"**/*.{md,yaml,yml,json}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "yaml": "^2.6.1"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1",
+    "vitest": "^3.2.4"
+  }
+}