AI Development Guidelines

Structured AI development guidelines for Laravel + React + Inertia projects. Works with Google Antigravity and Claude Code.

These guidelines transform AI assistants from general-purpose tools into specialized development partners with your coding style, standards, and workflow preferences.

What's Included

| Directory | Purpose | | ------------------- | ----------------------------------------------------------------------------- | | .agents/ | Skills, rules, and workflows for Google Antigravity | | .claude/ | Skills and settings for Claude Code (synced with .agents/) | | docs/engineering/ | Code standards, stack, testing, workflow, quality gates | | docs/ | Project docs generated by skills (PRD, architecture, design, tasks, progress) | | CLAUDE.md | Root guidelines file (read by both AI tools) |

Quick Start

1. Install

# Create your project (Laravel, Node, whatever)
laravel new my-project && cd my-project

# Install the guidelines
npx @juniorfontenele/ai-guidelines install

# Open your AI assistant and customize
/init-project

2. Update (without losing customizations)

npx @juniorfontenele/ai-guidelines update

The updater compares file hashes to detect what you changed. It only adds new files and updates untouched ones — your customizations are preserved.

# Preview what would change
npx @juniorfontenele/ai-guidelines update --dry-run

# Force overwrite (backs up your files first)
npx @juniorfontenele/ai-guidelines update --force

cp -r /path/to/ai-guidelines/.agents .
cp -r /path/to/ai-guidelines/.claude .
cp -r /path/to/ai-guidelines/docs .
cp /path/to/ai-guidelines/CLAUDE.md .

Note: manual installation does not support smart updates.

Development Pipeline

brainstorming → generate-prd → generate-architecture → generate-ui-design → generate-task-breakdown → implement-task
                                                                                                    ↗
                                                                         task-planner (standalone) ─┘

For the complete lifecycle, routing table, and quality gates, see docs/AGENT_FLOW.md.

Skills

| Skill | Purpose | Trigger | | --------------------------- | ---------------------------------- | ---------------------------- | | init-project | First-time setup, adapt guidelines | /init-project | | brainstorming | Ideation, spec refinement | /brainstorming | | generate-prd | Product requirements | /generate-prd | | generate-architecture | System architecture | /generate-architecture | | generate-ui-design | UI/UX design specs | /generate-ui-design | | generate-task-breakdown | Task breakdown from docs | /generate-task-breakdown | | task-planner | Plan features/refactors | /task-planner | | implement-task | Implement tasks with quality gates | /implement-task | | frontend-development | React + Inertia + Tailwind + Radix | When building UI | | generate-test | PestPHP tests | /generate-test | | bug-fixer | Root cause investigation | /bug-fixer | | security-analyst | OWASP Top 10 review | /security-analyst | | project-qa-auditor | QA audit before PR/deploy | /project-qa-auditor | | code-reviewer | Code health audit | /code-reviewer | | browser-qa-tester | Autonomous UX/UI QA | /browser-qa-tester | | i18n-manager | Translation audit & sync | /i18n-manager | | generate-persona | Persona profiles | /generate-persona | | generate-persona-feedback | Simulate persona feedback | /generate-persona-feedback | | developing-with-fortify | Auth reference (Fortify) | When implementing auth | | skill-creator | Create new skills | /skill-creator |

Default Stack

| Layer | Technology | Version | | ---------- | ------------------ | --------- | | Backend | PHP + Laravel | 8.4+ / 12 | | Database | MySQL | 9 | | Frontend | React + TypeScript | 19 / 5.7+ | | SPA Bridge | Inertia.js | 2 | | Styling | Tailwind CSS | 4 | | Bundler | Vite | 7 | | Auth | Laravel Fortify | 1 | | Routes | Laravel Wayfinder | 0.x | | Testing | PestPHP | 4 | | Analysis | Larastan | 3 |

Versions are reference defaults. The init-project skill updates them to match your actual project.

Keeping Fresh

The guidelines include a Version Freshness mechanism (CLAUDE.md §7):

• On first interaction, the AI verifies stack versions against docs/engineering/STACK.md
• If your project uses Laravel 13 but docs say 12, it updates automatically
• When the project specializes (adds multi-tenancy, changes auth), guidelines adapt

Coding Style

These guidelines enforce:

• SOLID principles, pragmatically applied
• Actions for single-purpose operations, Services for orchestration
• Form Requests for all validation
• Artisan commands for file generation (always prefer php artisan make:*)
• Semantic commits following conventional format
• i18n for all user-facing strings
• Quality gates: composer lint, npm run lint, composer test before commits

See docs/engineering/CODE_STANDARDS.md for complete standards.

Compatibility

| Tool | Directory | Notes | | ---------------------- | ---------- | ----------------------------------------- | | Google Antigravity | .agents/ | Skills, rules, workflows | | Claude Code | .claude/ | Skills, settings (synced from .agents/) |

Both tools read CLAUDE.md as the root guidelines file. Skills are identical across both directories.

License

MIT