From product idea to reviewed Laravel code

Your editor connects to two MCP servers: Laravel Boost (docs, schema, Tinker) and Larapilot (backlog and workflow). Skills orchestrate the conversation; the CLI guarantees consistency; artifacts survive between sessions.

The discovery interview

Everything starts with /larapilot-inception. You bring a rough idea — one sentence is enough. Mark (PM), Jennifer (Strategist), and John (Architect) run a guided conversation, not a form to fill in one shot.

What they explore:

• Market positioning, competitive context, and product risks (Jennifer)
• Market research and enterprise business perspective (Benjamin)
• Competitive challenger: integrations and competitor data porting — import paths for users switching from rival products, lock-in-free export (Sebastian)
• Product scope, personas, and delivery-target trade-offs (Mark)
• SOLID, scalable, performant architecture within budget (John + Aurora) — Budget Sensitivity can be set to Relaxed to exclude budget evaluation; business validation is loosened, never removed
• For public websites: SEO, Analytics, tracking, Lighthouse (Emma) and social strategy (Lauren)
• When personal data is involved: GDPR and privacy (Violet)

How the interview behaves:

• Agents speak in character (💎 Mark:, 🧭 Jennifer:, 📐 John:) so you see which lens is asking
• Questions appear only when critical — at most 3 per round, grouped in one message; you can skip any of them
• The agent infers what it can from your codebase and existing artifacts before asking
• The conversation follows your language; the PRD is written in the same language

When there is enough context, the team drafts a PRD (Elevator Pitch, Vision, Personas, Functional Requirements, MVP Scope, Technical Architecture), saves it via larapilot:prd-write, and validates it with larapilot:validate-prd. Inception does not create the backlog — that is /larapilot-spec.

From PRD to shipped code

After the PRD, each user story follows the same loop:

1. /larapilot-spec — MVP broken into backlog entries (backlog.yaml + specs/US-XXX.yaml)
2. /larapilot-plan US-XXX — technical plan with tasks → PLANNED
3. /larapilot-implement US-XXX — code and tests → REVIEW
4. /larapilot-review US-XXX — you approve (DONE) or send back (TODO)

The CLI blocks invalid jumps (implement before plan, approve before review). Optional /larapilot-design adds UI mockups before planning.

Requirements

• PHP ^8.3
• Laravel ^12 or ^13
• Laravel Boost ^1.0 or ^2.0 (installed automatically with Larapilot)
• An AI editor with MCP support (Cursor, etc.)

1. Install

Three commands, run from your Laravel project root. Laravel Boost is installed automatically as a Larapilot dependency — no separate composer require needed.

1a — Add the package:

composer require andreapollastri/larapilot --dev

1b — Initialize Larapilot. Creates the .larapilot/ workspace in your repo:

php artisan larapilot:install

INFO  Larapilot installed successfully.

  - .larapilot/config.yaml
  - .larapilot/shared-runtime.md

Next: run php artisan boost:install (or boost:update --discover) to publish AI skills and guidelines.

1c — Publish skills via Laravel Boost. Makes the eight /larapilot-* skills and the coding guidelines available to your AI editor:

php artisan boost:install

Boost's installer asks which editors and agents you use, then publishes guidelines and skills for them. Already running Boost in the project? Use php artisan boost:update --discover instead to pick up the Larapilot skills.

2. Enable MCP servers

Your editor needs both servers: Boost for Laravel context (docs, schema, Tinker) and Larapilot for workflow state.

Concrete example for editors with a JSON MCP config (Cursor: .cursor/mcp.json, Claude Code: .mcp.json):

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    },
    "larapilot": {
      "command": "php",
      "args": ["artisan", "mcp:start", "larapilot"]
    }
  }
}

3. Use skills in your AI agent

4. Example: from idea to done

Start with a fresh Laravel app and this prompt in your AI editor:

I want a simple team task board: user registration, projects, and assignable tasks.

After step 6, your repo might look like this:

.larapilot/
├── docs/
│   └── PRD.md
├── backlog.yaml
├── specs/
│   ├── US-001.yaml
│   └── US-002.yaml
├── plans/
│   └── US-001-plan.yaml
└── mockups/
    └── US-001/
        └── index.html

Use /larapilot-autopilot to batch-plan and implement multiple specs when the backlog is stable.

php artisan larapilot:metrics  # backlog progress

5. Verify installation

php artisan larapilot:doctor

{
  "schema": "larapilot/v1",
  "kind": "doctor",
  "data": {
    "healthy": true,
    "checks": {
      "config": true,
      "shared_runtime": true,
      "backlog": false,
      "prd": false,
      "boost": true
    },
    "project_root": "/path/to/your-app"
  }
}

data.healthy is true when config, shared runtime, and Boost are all in place. On a fresh install backlog and prd are still false — that's expected: they turn true after /larapilot-inception (PRD) and /larapilot-spec (backlog).

6. Keep it updated

Boost publishes guidelines and skills as copies into your editor directories, so after upgrading the package one command brings everything current — the shared runtime doc, the Larapilot guidelines, and the /larapilot-* skills:

composer update andreapollastri/larapilot
php artisan larapilot:update

larapilot:update never touches .larapilot/config.yaml — your project customizations survive — and re-runs boost:update with the editor and agent choices you already made during boost:install (no questions asked). Pass --skip-boost to refresh only the shared runtime and manage Boost publishing yourself.

To keep the project aligned automatically, hook it into Composer in your app's composer.json:

"scripts": {
    "post-update-cmd": [
        "@php artisan larapilot:update --ansi"
    ]
}

From then on every composer update republishes runtime, guidelines, and skills — nothing goes stale silently. Run php artisan larapilot:doctor anytime to confirm the install is healthy.

Workflow states

Transition guards

Invalid transitions fail with E_PRECONDITION and exit code 4:

• spec-plan — refuses specs in REVIEW or DONE
• spec-start — requires PLANNED
• spec-review — requires IN PROGRESS
• spec-approve / spec-request-changes — require REVIEW

Setup & diagnostics

PRD

Backlog & specs

Planning & implementation

Review & approval

Success envelope

{
  "schema": "larapilot/v1",
  "kind": "spec_show",
  "data": {
    "code": "US-001",
    "status": "PLANNED",
    "workdir": "/absolute/path/to/project",
    "tasks": [...]
  }
}

Error envelope

{
  "schema": "larapilot/v1",
  "kind": "error",
  "error": {
    "code": "E_PRECONDITION",
    "message": "Spec US-001 is TODO, expected PLANNED",
    "hint": "Run larapilot:spec-plan US-001 first"
  }
}

Error codes

connector: file

paths:
  prd: .larapilot/docs/PRD.md
  mockups: .larapilot/mockups/
  test_results: .larapilot/docs/test-results/

workflow:
  statuses:
    todo: TODO
    planned: PLANNED
    in_progress: IN PROGRESS
    review: REVIEW
    done: DONE

file:
  backlog: .larapilot/backlog.yaml
  specs: .larapilot/specs/
  planning: .larapilot/plans/

Environment variables

Worktree support

spec-show and spec-next return data.workdir for per-spec codebase work. Connector commands run from data.project_root.

Cursor configuration

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    },
    "larapilot": {
      "command": "php",
      "args": ["artisan", "mcp:start", "larapilot"]
    }
  }
}

.larapilot/
├── config.yaml
├── shared-runtime.md
├── backlog.yaml
├── docs/
│   ├── PRD.md
│   └── test-results/
├── specs/
│   ├── US-001.yaml
│   └── US-002.yaml
├── plans/
│   ├── US-001-plan.yaml
│   └── US-002-plan.yaml
└── mockups/
    └── US-001/
        └── index.html

Spec format

#### US-001: User Registration

**Epic:** EP-001 | **Priority:** HIGH | **Points:** 5 | **Status:** TODO

**User Story**
As a new visitor,
I want to create an account,
So that I can access protected features.

**Acceptance Criteria**
- [ ] AC-001: Email validation enforced
- [ ] AC-002: Password minimum 8 characters

Language & validation

Artifacts can be in any language. The structure is fixed — only labels and content are translated.

Every section must use a markdown heading (## Title or **Title**). Plain prose that mentions “User Story” without a heading does not count.

The validator first looks for known translations of these section names. If a heading is in another language, validation still passes when there are enough marked headings:

• PRD — 6 headings with ## …
• Spec body — 3 headings with ## … or **…**
• Plan task — 1 heading with ## … per task

Mockups live in .larapilot/mockups/{spec}/. The {spec} segment must match the folder name — typically a backlog code like US-001.

Examples: .larapilot/mockups/US-001/index.html → /mockups/US-001 (default file). Nested assets: /mockups/US-001/css/app.css.

Disable with LARAPILOT_MOCKUPS_ROUTE=false in .env.

Run the doctor

php artisan larapilot:doctor

Common issues

• Missing config — Run php artisan larapilot:install
• Skills not found — Run php artisan boost:install
• Invalid transition — Check status with larapilot:spec-show {code}
• Validation failures — Fix data.findings from validate-*
• MCP not connecting — Register both servers from project root
• Mockups 404 — Check environment and LARAPILOT_MOCKUPS_ROUTE

Disabled mode

When LARAPILOT_ENABLED=false, MCP and mockup route are gated off. Artisan commands and doctor remain available.