Download the PHP package andreapollastri/larapilot without Composer

Larapilot

From product idea to reviewed Laravel code — with an AI product team that follows a real process.

Larapilot is a spec-driven workflow for Laravel projects, integrated with Laravel Boost. Install the package, run /larapilot-* skills in your AI editor, and ship backlog artifacts, plans, and reviewed code from .larapilot/.

The agent proposes. You approve what ships. Human-in-the-loop, always.

📖 Documentation: larapilot.web.ap.it · Walkthrough · API

Why Larapilot

AI agents are fast, but isolated prompts are not a product process. Larapilot gives your assistant a disciplined squad — discovery → backlog → plan → implement → review → ship — with 30 personas (Mark, John, Mike, Lucille, Sarah for CLI/Git/Linux, Alex, Anne, …) as review lenses, not costumes. Packages (PHP/Laravel Composer) are a first-class Project Kind beside apps and sites.

Each skill orchestrates the conversation. Artisan commands persist state; Boost skills drive the workflow in chat; MCP exposes Laravel context and workflow tools to your editor.

Core loop

Greenfield — repeat steps 3–5 per user story:

Optional: /larapilot-design before plan · /larapilot-ship when MVP stories are DONE · /larapilot-autopilot to batch plan + implement · /larapilot-settings for project effort / backlog granularity / git / testing modes · /larapilot-backstage to publish the repo into a Backstage developer portal.

Git discipline follows settings.git_mode (default Gitflow without auto-push): one feature/US-XXX-* branch per story, atomic commits per plan task; push + remote PR only when mode is GITFLOW_PUSH. Optional forge toggles github / gitlab / bitbucket (default OFF) add PR/MR URLs via gh, glab, or Bitbucket Cloud API; optional Slack/Discord/Telegram notifications (default OFF) cover task/spec/PR/schedule/ship events — see .larapilot/integrations.md. Configure with /larapilot-settings. Details on the docs site.

What lands in .larapilot/

Skills write artifacts; the workflow engine blocks invalid state transitions (e.g. implement before plan, approve before review, approve with open [blocks-merge] feedback or unfinished tasks — override with --force).

Two configuration layers

The YAML wins for workflow settings; Laravel config only provides their defaults on first install.

Skills

Published via Laravel Boost after php artisan boost:install:

During inception, John + Joe ask Frontend Topology: Laravel-coupled, SPA-in-Laravel, or API + external frontend. For split-repo: larapilot:frontend-set --path=…, then frontend-scan — all from Laravel. Details: Frontend companion.

Dashboard & API (dev/staging)

When the dashboard is browsable (never in production):

• /larapilot — Kanban board, PRD reader, Settings (options + inception choices), Usage (Lucille metrics + Gantt + report download), spec detail with mockup preview and internal feedback
• /larapilot/api — JSON over the same artifacts (board, specs, PRD, OpenAPI at /larapilot/api/docs)
• GET /larapilot/api/backstage — Backstage catalog entities + delivery snapshot (see Developer portal)
• POST /larapilot/api/specs/{code}/comments — append internal feedback from scripts or tooling

API auth: set LARAPILOT_API_TOKEN to require a bearer token (or X-Larapilot-Token header) on every /larapilot/api/* request — strongly recommended on shared staging hosts. Without a token, reads stay open in the allowed environments, but writes are refused outside local/development/testing.

Diagnostics (bug triage)

Read-only runtime snapshot for /larapilot-bug and local debugging — never mutates workflow state.

Query params (API): ?lines=100 (default from config, capped by max_log_lines) · ?no_logs=1 to omit the log tail.

Payload: app (name, env, Laravel/PHP versions, …), checks (storage_writable, cache, database, queue, log_file), healthy (critical checks), optional logs with secrets redacted ([REDACTED]).

Config (config/larapilot.php / env): LARAPILOT_DIAGNOSTICS_ENABLED (default true), LARAPILOT_DIAGNOSTICS_LOG_LINES (default 100), LARAPILOT_DIAGNOSTICS_MAX_LOG_LINES (default 500).

Workflow state still changes only via skills or Artisan — not from the dashboard or API.

Frontend companion — split repo

When Frontend Topology is API + external frontend, Laravel is the only Larapilot cockpit. PRD, backlog, plans, and all /larapilot-* commands run in the backend workspace. The FE repo is a linked write target configured with an absolute path.

How it works

1. Inception records topology and asks for the FE absolute path → larapilot:frontend-set.
2. Scan (larapilot:frontend-scan) reads existing FE structure before planning evolutive work.
3. Spec → plan → implement run on Laravel. UI tasks use repo: frontend and write under data.frontend.repo_path.

Setup commands

Or /larapilot-frontend-companion in the Laravel editor.

Details: Frontend companion.

Developer portal — Backstage

Larapilot is repo-level; Backstage is org-level. The integration publishes .larapilot/ into the portal — one way. The workspace stays the source of truth and workflow state never changes from Backstage.

Or run /larapilot-backstage, which asks for owner/system/lifecycle first and persists them to .env.

catalog-info.yaml and mkdocs.yml are never overwritten without --force — a project may already own them. Everything under .larapilot/techdocs/ is regenerated, and pages for deleted specs are pruned. --no-techdocs generates the catalog entity only.

Catalog identity lives in Laravel config / .env (not .larapilot/config.yaml — it describes the org catalog, not the delivery workflow):

Live delivery data

For a Backstage plugin or entity provider, two endpoints share the dashboard gate (dev/staging only):

• GET /larapilot/api/backstage — catalog entities, rendered YAML, TechDocs metadata, and a lean snapshot (metrics, per-status counts, blocking feedback, story list without bodies) built for polling many repos
• GET /larapilot/api/backstage/catalog-info.yaml — the same entities as a Backstage url location

Call them through the Backstage backend proxy so LARAPILOT_API_TOKEN stays server-side. The API returns 404 in production by design — if the portal cannot reach a dev/staging host, ship the committed catalog-info.yaml and TechDocs instead.

Keep the catalog fresh with a CI step on the default branch (--write --force) or by re-running /larapilot-backstage after PRD and backlog milestones. php artisan larapilot:config-show reports the current mapping under data.backstage.

Project trackers — Linear, Asana, Jira, Trello, ClickUp, Monday

Optional, API-key based. Mirrors the backlog into the tool the rest of the organisation already uses, so a PM or a client can follow delivery without opening backlog.yaml. .larapilot/ stays the source of truth — the tracker is a window, not a second workflow.

Or run /larapilot-tracker, which picks the provider, collects the credentials into .env, and checks the status map before the first push.

What gets mirrored

Only one provider is active at a time (LARAPILOT_TRACKER_PROVIDER), but links are stored per provider, so switching tools — or switching back — never loses the mapping.

Direction: push writes, pull reports

Push is authoritative. Pull is a report: it reads remote state and lists drift, and changes the backlog only with --apply. Two things it will never do:

• Set a spec to DONE. DONE is a human review gate that records the merge commit — that stays with /larapilot-review and larapilot:spec-approve.
• Change spec text. Titles, bodies, and acceptance criteria are owned by .larapilot/; the card description says so, and edits made in the tracker are overwritten on the next push.

TODO and PLANNED mapping to the same column is normal and is not reported as drift. A remote status outside the map is reported as drift with no suggestion rather than guessed at.

Set LARAPILOT_TRACKER_PULL_COMMENTS=true to import tracker comments as internal feedback (non-blocking, imported once).

Configuration

Credentials live in .env only — never in .larapilot/, which is committed:

Status maps live in config/larapilot.php → tracker.providers.{provider}.status_map. If a mapped column does not exist, the push fails and names the columns that do — Larapilot never creates columns in your tracker.

.larapilot/tracker.yaml holds the spec → remote-id mapping. Commit it: without a shared map, every machine creates duplicate cards. It contains identifiers only, never credentials. php artisan larapilot:config-show reports the wiring under data.tracker, including whether credentials are present — never their values.

Requirements

• PHP ^8.3
• Laravel ^12 or ^13
• Laravel Boost ^2.0 (installed automatically)
• MCP-capable editor (Cursor, Claude Code, VS Code, …)

Quickstart

larapilot:install also scaffolds Larastan level 5+ and Laravel Pint (phpstan.neon.dist, pint.json, Composer scripts, dev dependencies). Run php artisan larapilot:quality before merge; larapilot:doctor fails when the gate is missing.

Already on Boost? Refresh skills once:

Register MCP servers in your editor if needed:

First run in your editor:

Then /larapilot-spec, and the per-story loop above.

Upgrade

Runtime-only refresh (skip Boost republish): php artisan larapilot:update --skip-boost.

larapilot:update overwrites .larapilot/design-systems/ with the packaged references; pass --preserve-design-systems to keep local customizations.

Learn more

• Why & how it works
• Five walkthrough examples — new product, legacy port, feature, bug, frontend companion
• Frontend companion — split FE repo + shared PRD sync
• Backstage portal — catalog entity, TechDocs, delivery snapshot
• Design systems
• Team personas

License

MIT © Andrea Pollastri