PHPackages andreapollastri/larapilot - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. andreapollastri/larapilot ActiveLibrary[Utility & Helpers](/categories/utility) andreapollastri/larapilot ========================= Spec-driven AI product workflow for Laravel β€” discovery, backlog, planning, implementation, and review via Laravel Boost. 2.4.2(2w ago)9284β€”0%MITPHPPHP ^8.3CI passing Since Jul 8Pushed 1mo agoCompare [ Source](https://github.com/andreapollastri/larapilot)[ Packagist](https://packagist.org/packages/andreapollastri/larapilot)[ RSS](/packages/andreapollastri-larapilot/feed)WikiDiscussions main Synced 2w ago READMEChangelog (10)Dependencies (45)Versions (33)Used By (0) Larapilot ========= [](#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](https://laravel.com/ai/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](https://larapilot.web.ap.it) Β· [Walkthrough](https://larapilot.web.ap.it/#examples) Β· [API](https://larapilot.web.ap.it/#deep-dive-api) --- Why Larapilot ------------- [](#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 **27 personas** (Mark, John, Alex, Anne, …) as review lenses, not costumes. 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 --------- [](#core-loop) Greenfield β€” repeat steps 3–5 per user story: ``` /larapilot-inception "…" β†’ /larapilot-spec β†’ /larapilot-plan US-XXX β†’ /larapilot-implement US-XXX β†’ /larapilot-review US-XXX ``` WhenStart withNew product, pivot, or legacy rewrite`/larapilot-inception`One new capability on an existing product`/larapilot-feature "…"`Defect or regression`/larapilot-bug "…"`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`**. Configure with `/larapilot-settings`. Details on the [docs site](https://larapilot.web.ap.it/#deep-dive-gitflow). --- What lands in `.larapilot/` --------------------------- [](#what-lands-in-larapilot) PathPurpose`config.yaml`Project workflow config + `settings` (`effort`, `backlog`, `git_mode`, `testing`, `auto_approve`)`docs/PRD.md`Product Requirements Document`backlog/`User stories (`US-XXX`) with status machine`plans/`Technical plans and tasks per spec`mockups/{spec}/`Static HTML previews (optional)`internal-feedback/{code}.md`PM/dev comments until **DONE**`design-systems/`Packaged references (Filament, Starter Kit, Bootstrap 5, Tailwind, AdminLTE)`techdocs/`Generated Backstage TechDocs sources (only after `larapilot:backstage-export --write`)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 [](#two-configuration-layers) LayerFileOwnsChanged via**Laravel config**`config/larapilot.php` (publishable) + `.env`Environment toggles: routes, environments, diagnostics, `LARAPILOT_API_TOKEN`, package defaults`php artisan vendor:publish --tag=larapilot-config`, env vars**Project workflow**`.larapilot/config.yaml` (committed)Per-project `settings` (effort, backlog, git mode, testing, auto-approve), paths, statuses`/larapilot-settings` or `php artisan larapilot:settings-set`The YAML wins for workflow settings; Laravel config only provides their defaults on first install. --- Skills ------ [](#skills) Published via Laravel Boost after `php artisan boost:install`: SkillRole`/larapilot-inception`Product discovery β†’ PRD (includes **Frontend Topology**)`/larapilot-spec`MoSCoW backlog from PRD`/larapilot-feature`Mini-inception for one evolutiva`/larapilot-bug`Bug triage β†’ fix spec or rework`/larapilot-frontend-companion`Sync shared PRD into an **external frontend** repo`/larapilot-design`Static HTML mockups from design system`/larapilot-plan`Technical plan + tasks for a spec`/larapilot-implement`Code + tests on a feature branch`/larapilot-review`Human gate β†’ **DONE** or rework`/larapilot-ship`Release checklist when MVP is done`/larapilot-autopilot`Batch plan + implement`/larapilot-settings`Persist effort / backlog granularity / git mode / testing / auto-approve for the project`/larapilot-backstage`Publish the repo into a **Backstage** developer portal (catalog entity + TechDocs)`/larapilot-tracker`Mirror the backlog into **Linear Β· Asana Β· Jira Β· Trello Β· ClickUp Β· Monday**During inception, **John + Joe** ask **Frontend Topology**: `Laravel-coupled` (Blade/Livewire/Inertia in this repo), `SPA-in-Laravel` (Vite SPA in this repo), or `API + external frontend` (Laravel API-only + separate FE repo). For the split-repo case, install/copy `/larapilot-frontend-companion` in the FE project and sync via `GET /larapilot/api/companion` or `php artisan larapilot:companion-export`. Details: [Frontend companion](https://larapilot.web.ap.it/#deep-dive-frontend-companion). --- Dashboard & API (dev/staging) --------------------------------- [](#dashboard--api-devstaging) When the dashboard is browsable (never in production): - **`/larapilot`** β€” Kanban board, PRD reader, 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/companion`** β€” PRD + frontend topology bundle for an external frontend repo - **`GET /larapilot/api/backstage`** β€” Backstage catalog entities + delivery snapshot (see [Developer portal](#developer-portal--backstage)) - **`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) [](#diagnostics-bug-triage) Read-only runtime snapshot for `/larapilot-bug` and local debugging β€” **never mutates workflow state**. SurfaceHow**API**`GET /larapilot/api/diagnostics` β€” same dashboard gate (dev/staging only); `404` when `LARAPILOT_DIAGNOSTICS_ENABLED=false`**CLI**`php artisan larapilot:diagnostics` β€” `--lines=` (cap log tail), `--no-logs` (status + checks only)**MCP**Larapilot `diagnostics` tool, or `RunArtisanTool` with `larapilot:diagnostics`**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. --- Developer portal β€” Backstage ---------------------------- [](#developer-portal--backstage) Larapilot is repo-level; [Backstage](https://backstage.io) 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. ``` php artisan larapilot:backstage-export # preview the bundle (writes nothing) php artisan larapilot:backstage-export --write # generate catalog + TechDocs ``` Or run `/larapilot-backstage`, which asks for owner/system/lifecycle first and persists them to `.env`. GeneratedContents`catalog-info.yaml` (repo root)`Component` entity + one `API` entity per OpenAPI contract found (`storage/api-docs/api-docs.json`, `openapi.json`, …)`mkdocs.yml` (repo root)TechDocs config β€” `docs_dir: .larapilot/techdocs`, plugin `techdocs-core``.larapilot/techdocs/``index.md` (delivery snapshot), `prd.md`, `backlog/index.md`, `backlog/US-XXX.md` (spec + plan + tasks)`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): Env varDefaultPurpose`LARAPILOT_BACKSTAGE_ENABLED``true`Master switch for the integration and its endpoints`LARAPILOT_BACKSTAGE_OWNER``guests`Backstage Group/User that owns the entity β€” **set this**, Backstage flags unresolvable owners`LARAPILOT_BACKSTAGE_SYSTEM`β€”Parent System entity, when your org uses them`LARAPILOT_BACKSTAGE_LIFECYCLE``experimental``experimental` Β· `production` Β· `deprecated``LARAPILOT_BACKSTAGE_COMPONENT_TYPE``service`Backstage component type`LARAPILOT_BACKSTAGE_NAME`slug of `app.name`Entity name override`LARAPILOT_BACKSTAGE_BASE_URL``app.url`Base URL for catalog links/annotations β€” **non-production only**`LARAPILOT_BACKSTAGE_TECHDOCS``true`Generate the TechDocs site`LARAPILOT_BACKSTAGE_WORKFLOW_API``false`Also register the dev-only Larapilot API as an `API` entity### Live delivery data [](#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 --------------------------------------------------------------- [](#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. ``` php artisan larapilot:tracker-status --ping # provider, status map, credentials check php artisan larapilot:tracker-push --dry-run # what would change, no API calls php artisan larapilot:tracker-push # backlog β†’ tracker php artisan larapilot:tracker-pull # tracker β†’ drift report (read-only) php artisan larapilot:tracker-pull --apply # write mapped statuses back ``` 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 [](#what-gets-mirrored) LarapilotTrackerUser story `US-XXX`Issue / task / card / item titled `US-XXX β€” Title`, with the spec body, priority, points, and epicPlan task `TASK-XX`A **native** sub-issue, subtask, subitem, or checklist item β€” not a checklist buried in the descriptionWorkflow statusThe provider's own column: workflow state, status, section, list, or status-column labelProviderAuthDestinationSubtasksStatus maps to**Linear**personal API keyteam keysub-issues (`parentId`)workflow state**Jira** (Cloud, REST v2)email + API tokenproject keysubtasks (`parent`)status, via a workflow **transition****Asana**personal access tokenproject gidsubtaskssection (a DONE story is also marked complete)**Trello**key + tokenboard idchecklist itemslist (board column)**ClickUp**personal token `pk_…`list idsubtasks (`parent`)list status**Monday**API tokenboard idsubitemsstatus-column labelOnly 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 [](#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 [](#configuration) Credentials live in `.env` only β€” **never** in `.larapilot/`, which is committed: Env varPurpose`LARAPILOT_TRACKER_ENABLED`Master switch (default `false`)`LARAPILOT_TRACKER_PROVIDER``linear` Β· `asana` Β· `jira` Β· `trello` Β· `clickup` Β· `monday``LARAPILOT_TRACKER_SYNC_TASKS`Mirror plan tasks as native subtasks (default `true`)`LARAPILOT_TRACKER_PULL_COMMENTS`Import remote comments as internal feedback (default `false`)`LARAPILOT_LINEAR_API_KEY` / `_TEAM`Linear key and team key (e.g. `ENG`)`LARAPILOT_JIRA_BASE_URL` / `_EMAIL` / `_API_TOKEN` / `_PROJECT`Jira site, account, token, project key`LARAPILOT_ASANA_TOKEN` / `_PROJECT`Asana PAT and project gid`LARAPILOT_TRELLO_KEY` / `_TOKEN` / `_BOARD`Trello credentials and board id`LARAPILOT_CLICKUP_TOKEN` / `_LIST`ClickUp token and list id`LARAPILOT_MONDAY_TOKEN` / `_BOARD` / `_DESCRIPTION_COLUMN`Monday token, board, and the long-text column that carries the spec bodyStatus 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 ------------ [](#requirements) - PHP **^8.3** - Laravel **^12** or **^13** - [Laravel Boost](https://laravel.com/ai/boost) `^2.0` (installed automatically) - MCP-capable editor (Cursor, Claude Code, VS Code, …) --- Quickstart ---------- [](#quickstart) ``` composer require andreapollastri/larapilot --dev php artisan larapilot:install php artisan boost:install ``` Already on Boost? Refresh skills once: ``` php artisan boost:update --discover ``` Register MCP servers in your editor if needed: ``` { "mcpServers": { "laravel-boost": { "command": "php", "args": ["artisan", "boost:mcp"] }, "larapilot": { "command": "php", "args": ["artisan", "mcp:start", "larapilot"] } } } ``` First run in your editor: ``` /larapilot-inception "your product idea" ``` Then `/larapilot-spec`, and the per-story loop above. ### Upgrade [](#upgrade) ``` composer update andreapollastri/larapilot php artisan larapilot:update php artisan larapilot:doctor ``` 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 ---------- [](#learn-more) - [Why & how it works](https://larapilot.web.ap.it/#how-it-works) - [Five walkthrough examples](https://larapilot.web.ap.it/#examples) β€” new product, legacy port, feature, bug, frontend companion - [Frontend companion](https://larapilot.web.ap.it/#deep-dive-frontend-companion) β€” split FE repo + shared PRD sync - [Backstage portal](https://larapilot.web.ap.it/#deep-dive-backstage) β€” catalog entity, TechDocs, delivery snapshot - [Design systems](https://larapilot.web.ap.it/#deep-dive-design-systems) - [Team personas](https://larapilot.web.ap.it/#deep-dive-team) --- License ------- [](#license) MIT Β© [Andrea Pollastri](https://web.ap.it) ### Health Score 49 β€” FairBetter than 94% of packages Maintenance95 Actively maintained with recent releases Popularity22 Limited adoption so far Community6 Small or concentrated contributor base Maturity60 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 31 Last Release 19d ago Major Versions 0.3 β†’ 1.02026-07-08 1.9.1 β†’ 2.0.02026-07-24 ### Community Maintainers ![](https://www.gravatar.com/avatar/d5a4aca6f4b1579cf2e9094c907ae2a9587fab913af88535fdd2a11661443e4b?d=identicon)[andreapollastri](/maintainers/andreapollastri) --- Top Contributors [![andreapollastri](https://avatars.githubusercontent.com/u/18210420?v=4)](https://github.com/andreapollastri "andreapollastri (95 commits)") --- Tags aiautomationboostlaravelmcpmockupproduct-developmentproductivityspec-driven-developmentspecificationslaravelmcpaiboostspec-drivenproduct-development ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/andreapollastri-larapilot/health.svg) ``` [![Health](https://phpackages.com/badges/andreapollastri-larapilot/health.svg)](https://phpackages.com/packages/andreapollastri-larapilot) ``` ### Alternatives [laravel/mcp Rapidly build MCP servers for your Laravel applications. 80427.1M249](/packages/laravel-mcp)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M342](/packages/laravel-ai)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.5k31.8M163](/packages/laravel-cashier)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)