npm package: @juniorfontenele/ai-guidelines
Description: Structured AI development guidelines for Laravel + React + Inertia projects. Works with Google Antigravity and Claude Code.
Latest version: 1.3.0

# 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

```bash
# 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)

```bash
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.

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

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

<details>
<summary>Manual installation (without npx)</summary>

```bash
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.

</details>

---

## 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