README

Engineering conventions and AI skills for Laravel projects.

Installs best practices as a single source of truth (.ai/upstream/) referenced by Cursor, GitHub Copilot, and Claude Code — so every tool reads the same rules.

What's Included

Category	Content
Backend	Controller → Action → Resource architecture, N+1 prevention, eager loading, cache, jobs, security, PHPStan level 5
Frontend	shadcn-vue components, design system, TypeScript typing, all UI states, forms with vee-validate + zod
Database	Migrations with constraints, cascade rules, index strategy, data types for Brazilian documents
Exceptions	Domain exceptions, centralized HTTP translation
Testing	Pest strategy — unit for Actions, feature for endpoints
PHPDocs	Documentation conventions for AI-assisted development
RPI Workflow	Brainstorm → Research → Plan → Iterate → Implement → Investigate

Installation

Via Packagist (após publicar)

composer require podtech/skill

Via repositório local (desenvolvimento / antes de publicar)

No composer.json do seu projeto Laravel:

{
    "repositories": [
        {
            "type": "path",
            "url": "../podtech-skill",
            "options": { "symlink": true }
        }
    ],
    "require": {
        "podtech/skill": "^1.0"
    }
}

composer require podtech/skill:^1.0

Via repositório Git (antes do Packagist)

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/podtech/skill"
        }
    ],
    "minimum-stability": "dev",
    "prefer-stable": true,
    "require": {
        "podtech/skill": "dev-main"
    }
}

composer require podtech/skill:dev-main

1. Publish convention files

API project (PHP only):

php artisan vendor:publish --tag=podtech-api

Inertia + shadcn-vue project:

php artisan vendor:publish --tag=podtech-inertia

This creates:

.ai/
  upstream/          ← package conventions (do not edit)
    conventions.md
    database.md
    exceptions.md
    phpdocs.md
    static-analysis.md
    testing.md
    crud.md            (api only)
    resources.md       (api only)
    components.md      (inertia only)
    forms.md           (inertia only)
    pages.md           (inertia only)
    props.md           (inertia only)
  local/
    overrides.md       ← your project-specific rules (edit freely)
AGENTS.md              ← global agent instructions

2. Install IDE rules

Cursor:

# Interactive
php artisan podtech:cursor

# API project
php artisan podtech:cursor --api

# Inertia + shadcn-vue
php artisan podtech:cursor --inertia

# With RPI workflow
php artisan podtech:cursor --inertia --rpi

GitHub Copilot:

php artisan podtech:copilot --api
php artisan podtech:copilot --inertia

Claude Code CLI:

# All skills (project-scoped)
php artisan podtech:claude

# Specific skills
php artisan podtech:claude --backend
php artisan podtech:claude --frontend
php artisan podtech:claude --database
php artisan podtech:claude --rpi

# Install globally (all projects)
cp -r .claude/skills/* ~/.claude/skills/

Project Structure After Setup

project/
├── .ai/
│   ├── upstream/          ← DO NOT EDIT (managed by package)
│   │   ├── conventions.md
│   │   ├── database.md
│   │   ├── exceptions.md
│   │   └── ...
│   └── local/
│       └── overrides.md   ← EDIT HERE (your project rules)
├── .claude/
│   ├── skills/            ← Claude Code skills
│   │   ├── backend-laravel/
│   │   ├── frontend-shadcn/
│   │   ├── database-modeling/
│   │   ├── brainstorm/
│   │   ├── research/
│   │   ├── plan/
│   │   ├── iterate/
│   │   ├── implement/
│   │   └── investigate/
│   └── agents/
├── .cursor/
│   ├── rules/
│   │   ├── podtech.mdc    ← convention rules
│   │   └── rpi.mdc        ← RPI workflow rule
│   └── skills/            ← RPI skills for Cursor
├── .github/
│   └── copilot-instructions.md
└── AGENTS.md

Project-Specific Rules

Edit .ai/local/overrides.md to override any upstream convention:

# Project Overrides

## This project uses Livewire instead of Inertia
- Ignore all upstream Inertia conventions
- Forms follow Livewire patterns (see app/Livewire/)

## Custom exception base class
- Use App\Exceptions\AppException instead of DomainException

Local rules always have higher priority than upstream.

RPI Workflow

For complex features, use the Research → Plan → Implement flow:

Skill	Cursor	Claude Code	When
Brainstorm	`/brainstorm`	`/brainstorm`	Explore ideas before research
Research	`/research`	`/research`	Deep technical investigation
Plan	`/plan`	`/plan`	Atomic tasks before coding
Iterate	`/iterate`	`/iterate`	Adjust an existing plan
Implement	`/implement`	`/implement`	Execute the plan mechanically
Investigate	`/investigate`	`/investigate`	Diagnose bugs

Artifacts are saved in docs/rpi/.

Updating

composer update podtech/skill
php artisan vendor:publish --tag=podtech-api --force     # or --tag=podtech-inertia
php artisan podtech:claude --all --force
php artisan podtech:cursor --inertia --rpi --force

Package Structure

podtech/skill/
├── composer.json
├── AGENTS.md
├── src/
│   ├── SkillServiceProvider.php
│   └── Commands/
│       ├── CursorSetupCommand.php
│       ├── CopilotSetupCommand.php
│       └── ClaudeCodeSetupCommand.php
└── resources/
    ├── ai/
    │   ├── shared/       conventions, database, exceptions, phpdocs, static-analysis, testing
    │   ├── api/          crud, resources
    │   ├── inertia/      components (shadcn-vue), forms, pages, props
    │   └── local/        overrides template
    ├── cursor/
    │   ├── podtech-api.mdc
    │   ├── podtech-inertia.mdc
    │   ├── rpi.mdc
    │   └── skills/       brainstorm, research, plan, iterate, implement, investigate
    ├── claude/
    │   ├── skills/       backend-laravel, frontend-shadcn, database-modeling + RPI
    │   └── agents/       detective, developer, world-detective, writer
    └── copilot/
        ├── podtech-api.md
        └── podtech-inertia.md

podtech / skill

Maintainers

Package info

Statistics

Security