ai-rules 0.4.0

ai-rules 0.4.0

Summary

This release significantly expands the capabilities of the CLI, brings full
XDG Base Directory compliance, adds native Gemini support, and extends the
shared rule set with five new rule files.

New commands

• ai-rules remove: inverse of install — unlinks symlinks managed by
  ai-rules and restores the most recent backup (file or config patch).
• ai-rules verify: checks that flat files are in sync with current rules;
  exits 1 if stale — designed for CI use to catch forgotten ai-rules generate.
• ai-rules update (extended): now combines install + generate +
  legacy backup migration in one step — the canonical command after git pull.

New global CLI options

--verbose/-v, --quiet/-q, --debug, --no-color (respects NO_COLOR),
--no-log, --log-dir <path>.

File logging is now enabled by default:
$XDG_STATE_HOME/ai-rules/logs/ai-rules-YYYY-MM-DD.log

Gemini native imports

Gemini now uses native @./path imports instead of a generated flat file,
matching the Claude Code integration. The rules/ directory is symlinked into
~/.gemini/ at install time.

Codex config patch

The Codex installer now patches ~/.codex/config.toml in-place to set
project_doc_max_bytes = 131072, with automatic backup and restore on remove.
No repo-tracked config.toml is required.

XDG Base Directory compliance

All files written by ai-rules now follow XDG:

• Backups: $XDG_STATE_HOME/ai-rules/backups/<agent>/
• Logs: $XDG_STATE_HOME/ai-rules/logs/

Migration: users upgrading from 0.3.x should run ai-rules update once —
it will automatically move legacy backups from agent install dirs to the XDG
state directory.

New rule files (5)

• rules/quality.md: 11 project quality dimensions with definitions, implications, and red flags
• rules/testing.md: test pyramid, AAA pattern, naming conventions, coverage floor, per-language guidance
• rules/api.md: REST API conventions — URL structure, HTTP methods, status codes, pagination, auth, rate limiting
• rules/error-handling.md: exit code table, error message format, per-language patterns
• rules/logging.md: application-level logging — levels, structured JSON, XDG log path, aggregation

Rule updates

• rules/compatibility.md: XDG section clarified — scope condition, test isolation rule, Python example
• rules/docs.md: "Keep docs in sync with the code" — docs must be updated in the same commit as the code
• rules/review.md: TODO.md added to self-review checklist
• rules/naming.md: Python, JavaScript/TypeScript, Go conventions added
• rules/commits.md: prefer detailed commit messages
• rules/cli.md: shell completion required for every CLI tool

CI improvements

• ai-rules verify step added to test job
• Job timeouts enforced (lint: 5 min, test: 15 min)
• uv dependency cache keyed on uv.lock
• Coverage threshold: 80% enforced via --cov-fail-under=80

Open source documentation

CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md,
AUTHORS.md, GitHub issue templates, pull request template.

Breaking changes

None. Installation is backward-compatible. Backup paths have changed (XDG),
but ai-rules update handles migration automatically.

Stats

104 tests · 95% coverage · Python 3.11 and 3.12

0.3.1

Added

• .github/workflows/ci.yml: CI pipeline with lint (shellcheck + ruff) and
  test (pytest on Python 3.11 and 3.12) jobs, triggered on push and PR
• ruff>=0.4.0 added to dev dependencies
• CI badge added to README.md

Fixed

• CI workflow: replace uv pip install --system with uv sync + uv run
  to comply with PEP 668 (externally managed Python on Debian/Ubuntu runners)
• Unused imports removed in tests/test_agent.py (ruff F401)
• rules/git.md: document git branch -D requirement after GitHub squash/rebase merge
• README.md: fix dev installation command (uv pip install → uv sync --extra dev)

0.3.0

Added

• Python CLI (ai-rules) with install, update, status, and list commands
• src/ai_rules/ package: agent.py, config.py, installer.py, cli.py
• pyproject.toml: hatchling build backend, typer, pytest dev dependencies
• bin/ai-rules: development entry point (no installation required)
• agents.toml: agent registry with link declarations (Claude Code)
• agents/claude/CLAUDE.md: Claude Code entry point (moved from repo root)
• 20 tests covering agent loading, repo root resolution, and install logic
• tests/run-tests.sh: test runner wrapper
• Shell completion support via ai-rules --install-completion (bash/zsh/fish)

Changed

• Repository renamed from claude-config to ai-rules
• CLAUDE.md moved to agents/claude/CLAUDE.md
• README.md rewritten to reflect new scope and CLI usage
• .gitignore extended with Python artifact patterns

Removed

• install.sh replaced by the ai-rules install CLI command

0.2.0

Added

• rules/principles.md: general coding principles (analyze before coding,
  propose before implementing, propose options before deciding, clarify before
  starting, prefer minimal diffs, no refactoring without request, no speculative
  additions, no dead code, confirm before irreversible actions, explicit naming)
• scripts/extract-changelog.sh: extract release notes for a given version
  from CHANGELOG.md — robust against semver metadata and end-of-file edge cases
• TODO.md: deferred items tracker (naming conventions, CI advanced topics,
  logging, open source documentation)
• settings.json versioned in the repository with global Claude Code permissions
• install.sh now deploys a symlink for settings.json into ~/.claude/

Changed

• rules/git.md: full branch workflow (permanent and short-lived branches,
  rebase strategy, squash merge, workflows by case, merge conflict guidelines)
• rules/cli.md: add structured invocation format (namespace/command/subcommand)
• rules/commits.md: clarify commit message must cover all modified files
• rules/security.md: add .env.example pattern
• rules/review.md: restructure as full review guidelines with self-review
  checklist and code review sections (solo vs team projects)
• rules/release.md: detail platform release workflow for GitHub and Forgejo,
  replace inline sed with scripts/extract-changelog.sh
• CLAUDE.md: add rules/principles.md reference under new section

Fixed

• README structure now lists all 20 rule files including principles.md