LaraSpec

Laravel-native specification engine — blueprint.yaml as the source of truth.

LaraSpec turns a single YAML file into a complete Laravel application: models, migrations, controllers, Filament resources, API routes, factories, and feature tests. It also generates AI coding assistant skills (Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Continue) that understand your Laravel project deeply.

Why LaraSpec?

AI coding assistants are powerful for Laravel work, but they guess at your schema. They don't know your Eloquent relationships, your Filament panel setup, whether you're using Sanctum or Passport, or how your routes are versioned. Every session starts from scratch.

LaraSpec fixes this by giving your AI a single file — laraspec/blueprint.yaml — that captures the entire system: models, auth, API, payments, roles, UI. Every generated file flows from it. When you change the blueprint, you regenerate. There's no drift between what your AI thinks your schema is and what your codebase actually has.

Key outcomes:

• One YAML file drives all code generation — models, migrations, controllers, Filament resources, routes, factories, tests.
• AI tools get deep Laravel context through generated skills that understand your blueprint.
• Structured change folders keep feature work explicit and auditable: proposals, tasks, and spec deltas live together.
• No API keys required. Works with the AI tools you already use.

How LaraSpec compares (at a glance)

| | LaraSpec | Describing schema in chat | jasonmccreary/blueprint | Writing by hand | |---|---|---|---|---| | Single source of truth | ✅ blueprint.yaml | ❌ lives in chat history | ✅ draft.yaml | ❌ scattered across files | | AI skill generation | ✅ all 6 major tools | ❌ manual context every session | ❌ | ❌ | | Filament resources | ✅ auto-generated | 🟡 hit or miss | ❌ | manual | | Spec-driven change tracking | ✅ proposals → tasks → archive | ❌ | ❌ | ❌ | | Brownfield support | ✅ extends existing code | 🟡 inconsistent | 🟡 | ✅ | | No build step / API keys | ✅ | ✅ | ✅ | ✅ |

• Compared to describing your schema in chat: no persistence — AI loses context between sessions and generates inconsistent output. LaraSpec's blueprint is always there.
• Compared to jasonmccreary/blueprint: that package focuses on code generation from YAML. LaraSpec wraps it with AI skill templates, spec-driven workflow, and Filament support. LaraSpec can also export a blueprint-compatible draft.yaml.
• Compared to writing models/migrations by hand: LaraSpec generates them from a single source of truth. Change one field in blueprint.yaml, regenerate, done.

Quick start

# Install globally
npm install -g laraspec

# Initialize in your Laravel project
cd my-laravel-app
laraspec init

# Edit the source of truth
nano laraspec/blueprint.yaml

# Generate all Laravel files
laraspec generate --all

# Run migrations and tests
php artisan migrate
php artisan test

How It Works

┌──────────────────────┐
│ Edit blueprint.yaml  │
│ (models, auth, UI)   │
└──────────┬───────────┘
           │ single source of truth
           ▼
┌──────────────────────┐
│ laraspec generate    │◀──── regenerate anytime ────┐
│ (models, migrations, │                             │
│  controllers, tests) │                             │
└──────────┬───────────┘                             │
           │ files written to disk                   │
           ▼                                         │
┌──────────────────────┐                             │
│ AI Implements Tasks  │─────────────────────────────┘
│ (reads blueprint +   │
│  generated files)    │
└──────────┬───────────┘
           │ feature complete
           ▼
┌──────────────────────┐
│ Archive Change       │
│ (specs updated)      │
└──────────────────────┘

1. Define your models, auth, UI, and API in blueprint.yaml.
2. Run laraspec generate to scaffold the Laravel files.
3. AI implements tasks referencing the generated scaffold and blueprint.
4. Archive the change to merge approved spec updates back into source-of-truth docs.

The blueprint

laraspec/blueprint.yaml drives everything:

project:
  name: "My CRM"
  type: CRM
  description: "Customer relationship management system"
  laravel_version: "11.x"

models:
  Lead:
    name: string
    email: string
    phone: string
    status: string
    user_id: foreignId       # auto-generates belongsTo(User)

  Customer:
    company_name: string
    lead_id: foreignId

ui:
  admin_panel: filament      # optional — omit for API-only projects
  frontend: none

auth:
  driver: sanctum
  social_login:
    - google

api:
  enabled: true
  versioned: true

payments:
  stripe: true

roles:
  enabled: true
  package: spatie

What gets generated

| Command | Files created | |---------|---------------| | laraspec generate --models | app/Models/*.php with relationships | | laraspec generate --migrations | database/migrations/*.php | | laraspec generate --controllers | app/Http/Controllers/Api/*.php + Resources | | laraspec generate --routes | routes/api.php | | laraspec generate --filament | app/Filament/Resources/*.php + Pages | | laraspec generate --factories | database/factories/*.php | | laraspec generate --tests | tests/Feature/*.php (Pest) | | laraspec generate --export-blueprint | draft.yaml (for jasonmccreary/blueprint) | | laraspec generate --all | All of the above |

Example: How AI Creates LaraSpec Files

When you ask your AI assistant to "add a subscription system", it:

1. Edits laraspec/blueprint.yaml to add the new models and configuration
2. Runs laraspec generate --models --migrations to scaffold the files
3. Implements the business logic on top of the generated scaffold

The blueprint change looks like this:

# laraspec/blueprint.yaml — AI adds these entries

models:
  Subscription:
    user_id: foreignId
    plan: string
    status: string
    trial_ends_at: timestamp
    ends_at: timestamp

  Plan:
    name: string
    slug: string
    price: decimal
    interval: string         # monthly | yearly

payments:
  stripe: true

The generated files created by laraspec generate --all:

app/Models/Subscription.php          ← Eloquent model with belongsTo(User), belongsTo(Plan)
app/Models/Plan.php                  ← Model with hasMany(Subscription)
database/migrations/
  ..._create_subscriptions_table.php
  ..._create_plans_table.php
app/Http/Controllers/Api/V1/
  SubscriptionController.php
  PlanController.php
app/Http/Resources/
  SubscriptionResource.php
  PlanResource.php
app/Filament/Resources/
  SubscriptionResource.php           ← full admin panel resource
  SubscriptionResource/Pages/
    ListSubscriptions.php
    CreateSubscription.php
    EditSubscription.php
  PlanResource.php
database/factories/
  SubscriptionFactory.php
  PlanFactory.php
tests/Feature/
  SubscriptionTest.php
  PlanTest.php

AI-generated Eloquent model (Subscription.php):

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Factories\HasFactory;

class Subscription extends Model
{
    use HasFactory;

    protected $fillable = [
        'user_id',
        'plan_id',
        'status',
        'trial_ends_at',
        'ends_at',
    ];

    public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function plan(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(Plan::class);
    }
}

AI-generated change proposal (created in laraspec/changes/add-subscription/):

laraspec/
└── changes/
    └── add-subscription/
        ├── proposal.md       # Why subscriptions, business requirements
        ├── tasks.md          # Implementation checklist
        └── specs/
            └── billing/
                └── spec.md   # Delta: ADDED subscription requirements

Important: You don't create these files manually. Your AI assistant generates them based on your requirements, edits the blueprint, and runs the generator.

Specification documents

LaraSpec also generates a full spec artifact chain from your blueprint:

laraspec/
├── blueprint.yaml        ← source of truth (you edit this)
├── requirements.md       ← what the system must do
├── architecture.md       ← how it's designed
├── ui-wireframes.md      ← admin panel + API response shapes
├── tasks.md              ← implementation checklist
├── validation.md         ← Pest test scenarios
├── config.yaml           ← LaraSpec configuration
└── changes/              ← change proposals (like git commits for specs)

Generate spec documents:

laraspec new change "add-subscription-system"
laraspec status --change "add-subscription-system"

AI tool integration

laraspec init sets up skills for your AI coding tools:

| Tool | Skills directory | |------|-----------------| | Claude Code | .claude/skills/laraspec-*/ | | Cursor | .cursor/skills/laraspec-*/ | | GitHub Copilot | .github/skills/laraspec-*/ | | Windsurf | .windsurf/skills/laraspec-*/ | | Cline | .cline/skills/laraspec-*/ | | Continue | .continue/skills/laraspec-*/ |

Skills include: laraspec-init, laraspec-generate, laraspec-model, laraspec-api, laraspec-filament, laraspec-test.

CLI reference

laraspec init               Initialize LaraSpec in a Laravel project
laraspec generate           Generate Laravel files from blueprint.yaml
laraspec validate           Validate changes, specs, or blueprint.yaml
laraspec validate --blueprint  Validate blueprint.yaml syntax and types
laraspec list               List changes or specs
laraspec view               Interactive dashboard
laraspec new change <name>  Create a new spec change
laraspec status             Show artifact completion for a change
laraspec archive <name>     Archive a completed change
laraspec update             Refresh AI tool skills

Column types

Valid field types in blueprint.yaml models section:

string · integer · bigInteger · boolean · text · longText · json · timestamp · date · decimal · float · foreignId · uuid · enum · tinyInteger · unsignedBigInteger

foreignId fields automatically generate belongsTo relationships in the model class.

Filament is optional

The ui section is entirely optional. Projects without ui.admin_panel: filament will not generate any Filament files. A pure REST API project simply omits the ui block entirely.

Experimental Features

Why this exists:

• Standard workflow is linear — you can't jump back to tweak a spec after generation starts
• When AI output is off, you can't improve the prompts yourself without rebuilding
• OPSX makes the workflow hackable: edit templates and schemas directly, test immediately, no rebuild

What's different:

• Hackable — edit templates and schemas yourself, test immediately
• Granular — each artifact has its own instructions, tweak individually
• Fluid — no phase gates, update any artifact at any time

You can always go back:

  proposal ──→ specs ──→ design ──→ tasks ──→ implement
     ▲           ▲          ▲                    │
     └───────────┴──────────┴────────────────────┘

| Command | What it does | |---------|--------------| | /opsx:new | Start a new change | | /opsx:continue | Create the next artifact (based on what's ready) | | /opsx:ff | Fast-forward (all planning artifacts at once) | | /opsx:apply | Implement tasks, updating artifacts as needed | | /opsx:archive | Archive when done |

We collect only command names and version to understand usage patterns. No arguments, paths, file content, or PII. Automatically disabled in CI.

Opt-out: export LARASPEC_TELEMETRY=0 or export DO_NOT_TRACK=1

Requirements

• Node.js >= 20.19.0
• A Laravel project (composer.json with laravel/framework)

Contributing

See CONTRIBUTING.md.

• Install dependencies: npm install
• Build: npm run build
• Test: npm test

License

MIT — see LICENSE.

LaraSpec is an independent Laravel-focused fork of OpenSpec, scoped and extended exclusively for Laravel projects.