From d2152517a87f1d533f51a524ce225b23e41465a1 Mon Sep 17 00:00:00 2001 From: Alfonso Bribiesca Date: Mon, 1 Jun 2026 12:16:21 -0600 Subject: [PATCH] chore: install ardenthq/ai conventions --- .claude/ardenthq/core.md | 72 ++++++++++++++++++++++++++++++++++++++ .claude/ardenthq/php.md | 75 ++++++++++++++++++++++++++++++++++++++++ .gitignore | 3 ++ CLAUDE.md | 4 +++ composer.json | 3 ++ 5 files changed, 157 insertions(+) create mode 100644 .claude/ardenthq/core.md create mode 100644 .claude/ardenthq/php.md create mode 100644 CLAUDE.md diff --git a/.claude/ardenthq/core.md b/.claude/ardenthq/core.md new file mode 100644 index 0000000..403ab37 --- /dev/null +++ b/.claude/ardenthq/core.md @@ -0,0 +1,72 @@ + + + +# 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…" + +## Recommended dev setup (one-time per dev) + +Not required, but recommended to improve the Claude experience. The CLI detects whether they're already installed and prints recommendations only for missing ones. + +- **caveman** — compresses Claude's output (~65% token savings): + `curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash` + +## 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 diff --git a/.claude/ardenthq/php.md b/.claude/ardenthq/php.md new file mode 100644 index 0000000..759fe2d --- /dev/null +++ b/.claude/ardenthq/php.md @@ -0,0 +1,75 @@ + + +# 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. diff --git a/.gitignore b/.gitignore index 2ac24a9..f6c34e2 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ coverage.xml .php-cs-fixer.cache # Used for the schnorr signature hack, remove once a php version is implemented scripts/node_modules + +# airc +CLAUDE.local.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5f5a12c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ +@.claude/ardenthq/core.md +@.claude/ardenthq/php.md + + diff --git a/composer.json b/composer.json index 5b30300..8f552f4 100755 --- a/composer.json +++ b/composer.json @@ -59,6 +59,9 @@ } ], "scripts": { + "post-update-cmd": [ + "npx @ardenthq/airc update" + ], "format": [ "vendor/bin/php-cs-fixer fix" ],