From product idea to reviewed Laravel code.

How it works

Three layers: skills orchestrate the conversation, artifacts in git are the source of truth, and Artisan CLI persists state under the hood.

What the agent loads — and what it skips

A skill opens with one command, php artisan larapilot:context {skill}. One envelope answers the settings, the paths the skill uses, what the PRD says about the project, and the runtime files to read. Three things keep the context small, and keep an agent from applying a rule that is not the project's:

Runtime files are read with the editor's file-read tool, never cat/head/sed; each stays under 15 KB so one read returns it whole, and a truncated preview counts as a failed load. Commands answer with the slice, too: spec-list is the backlog without the bodies (--full for everything), prd-show reads the PRD by the piece (its outline, --ids=FR-004,J-001, --section="Technical Architecture"), and spec-show US-004 --task=TASK-02 one task. Chat stays short; artifacts on disk stay complete.

.larapilot/shared-runtime.md and the runtime-*.md files stay in the repository as the index for people, and as the fallback when the command cannot run. .larapilot/cache/ is derived, ignores itself in git, and is rebuilt whenever it is stale.

Upgrade

Larapilot ships as a Composer package and follows semantic versioning. Every upgrade makes the same two moves: bring the new package into vendor/, then run larapilot:update to refresh the files Larapilot publishes into your project. Your workflow data is never migrated — .larapilot/config.yaml, PRD, backlog, specs, plans, and decisions are read as they are. What the release changes is how you bring it in.

Which release is waiting

composer show andreapollastri/larapilot --latest | grep -E '^(versions|latest)'
# versions : * 4.1.2
# latest   : 5.0.4 released 2026-10-07

composer why andreapollastri/larapilot
# laravel/laravel dev-main requires andreapollastri/larapilot (^4.0)

versions is what the project runs, latest what Packagist has: a different first number is a major. composer why gives the constraint and where it sits — requires is require, requires (for development) is require-dev, where the install command puts it. A major upgrade needs to know which.

Patch and minor releases

Commit what changed — composer.lock, the runtime in .larapilot/, the skills and guidelines Boost republished for your editors — then open a new conversation with your agent: the one already open keeps the skills it loaded when it began.

Major releases, step by step

Shown for 4.x → 5.0; for a later major, change the numbers. Work on a branch, so the upgrade is one commit you can read, test, and throw away.

1. Read what breaks. The Breaking section of the new version in the changelog says which scripts and custom skills may need a change; step 6 finds them. For 5.0, the whole picture is Version 5 vs version 4.
2. Pick a quiet moment. No /larapilot-implement or /larapilot-autopilot running: the package, the runtime, and the skills would change under the agent halfway through a story. Specs in progress are fine — they are read as they are.
3. Branch from a clean tree, and rehearse.
   Terminal — rehearsal, writes nothing

   git switch -c upgrade/larapilot-5
   git status --short    # prints nothing: the upgrade will be the only change here
   composer require andreapollastri/larapilot:^5.0 --dev --with-all-dependencies --dry-run

   The dry run resolves the new version and lists every package it would move. It writes nothing — not even composer.json, although it prints that it was updated. --with-all-dependencies lets Composer move what Larapilot depends on, Laravel and Boost included, within the constraints of your composer.json. When it cannot resolve, its message names the package that holds the upgrade back.

4. Upgrade.
   Terminal — major, 4.x → 5.0

   1. 1 composer require andreapollastri/larapilot:^5.0 --dev --with-all-dependencies Copy
   2. 2 php artisan larapilot:update Copy
   3. 3 php artisan larapilot:doctor --human Copy
   • composer why said requires, not requires (for development)? Drop --dev, from the rehearsal too. With it, Composer moves Larapilot to require-dev — and without asking when it runs non-interactively, as in a script.
   • Edited the packaged design systems? Run php artisan larapilot:update --preserve-design-systems: without the option, the packaged copies overwrite .larapilot/design-systems/.
5. Read what larapilot:update printed. Most of it reports work done; these lines ask something of you.

   The line says	What to do
   config.yaml is missing setting keys …	Nothing is broken: the defaults already apply. To keep a choice on record, set it with /larapilot-settings or php artisan larapilot:settings-set.
   Design systems refreshed …	Printed on every run without --preserve-design-systems. If you had edited them: git restore .larapilot/design-systems, then php artisan larapilot:update --preserve-design-systems --skip-boost.
   Left in _project_docs …	Merge the files it names by hand, then delete _project_docs/; larapilot:doctor warns until it is gone.
   … date(s) do not hold and … finding(s) need a decision	Run /larapilot-schedule when you are ready to re-plan: the update changes no priority, blocker, estimate, or date.
   boost:update is not available / failed	Not available: Boost is missing — composer require laravel/boost --dev. Then, either way, php artisan boost:install once and php artisan larapilot:update again.

6. Find what the major breaks — 4.x → 5.0.
   Terminal — 4.x → 5.0 checks

   # scripts and CI — the files Larapilot and Boost publish are left out
   git grep -nE "larapilot:spec-list|larapilot-boogle|larapilot:vps-provision" -- \
     ':!.larapilot' ':!*SKILL.md' ':!CLAUDE.md' ':!AGENTS.md'
   
   # your custom skills
   git grep -nE "spec-list|larapilot-boogle|runtime-[a-z]+-[0-9]+\.md" -- .larapilot/skills

   No output means nothing to change. A hit in another editor's guideline file (.cursor/rules/, .github/copilot-instructions.md, …) is Larapilot's own text, refreshed by the upgrade: skip it. For each other hit:

   • spec-list answers without the bodies now: add --full where the script or skill reads body or status_history.
   • larapilot-boogle is /larapilot-error. The boogle-* commands still answer under their old names.
   • larapilot:vps-provision is gone, with the provision.sh it generated: drop the call. A server already set up with that script is not touched by the upgrade — the prj-* tools it installed never called the package — but nothing maintains them any more: deploy those projects with the platform their PRD records (Forge, Ploi, Cipi, …) through /larapilot-ship.
   • runtime-…-N.md in a custom skill names a part of a pack that v5 re-split by audience: cite the heading instead, or start the skill with php artisan larapilot:context {its name} --with=delivery-1,dev-docs (Custom skills).
   • An external frontend is linked? Run /larapilot-frontend-companion once: in a monorepo it asks which projects are this product's, and it reads the team's agent rules from then on.
7. Commit, and open a new conversation.
   Terminal — one commit for the upgrade

   git add -A
   git commit -m "Upgrade Larapilot to 5.0"

   The commit holds composer.json, composer.lock, the runtime in .larapilot/, and the skills and guidelines for your editors; .larapilot/cache/ ignores itself. Open a new conversation with your agent — the one already open keeps the 4.x skills it loaded when it began. After the merge, teammates run composer install, and the published files come with the pull; where the editors' skill folders are kept out of git, each teammate also runs php artisan boost:update. larapilot:update stays with whoever makes the upgrade commit: it also runs composer update laravel/boost, which belongs in that commit.

Roll back

# not committed yet? stash the attempt: kept, not lost
git stash push --include-untracked -m "larapilot 5 attempt"

git switch main            # or the branch you started from
composer install           # 4.x back in vendor/
php artisan boost:update   # the 4.x skills back in your editors

The switch brings back composer.json, composer.lock, and .larapilot/ as they were. The upgrade branch stays until you delete it: git branch -D upgrade/larapilot-5.

What each step does

Options & checks

• php artisan larapilot:update --skip-boost — refresh shared runtime and design-system copies only (does not bump laravel/boost or republish skills); run composer update laravel/boost --with-dependencies and php artisan boost:update yourself when you want the latest Boost
• php artisan larapilot:update --preserve-design-systems — keep .larapilot/design-systems/ as it is, your edits included
• php artisan larapilot:doctor --human — verify install health after an upgrade, as a table (includes Larastan/Pint gate); without --human it answers JSON for scripts
• php artisan boost:update --discover — one-time if Boost was installed before Larapilot and skills are missing

Automate with Composer (optional)

Add a post-update-cmd hook so larapilot:update runs whenever Larapilot is updated via Composer:

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

Keep --skip-boost in the hook so Composer does not recurse into composer update laravel/boost. Omit it only when you want Boost guidelines and skills republished on every Composer update (the package bump is skipped automatically inside a Composer script). Run php artisan boost:update manually when you use --skip-boost in the hook, or include laravel/boost in the Composer update command so the lockfile tracks latest. The hook keeps patch and minor releases in step; a major still takes the steps above.

Skills

Twenty-nine skills cover the life of a product: discovery, delivery, changes after launch, security and upgrades, ship, and the tools around them. Each one is a SKILL.md file that names the personas who speak, the steps they follow, and the commands they may call. Laravel Boost publishes them into your editor on php artisan boost:install.

Your own skills live in .larapilot/skills/ — see Custom skills. A short Boost guideline ships alongside: it tells the agent what Larapilot is and which skill to reach for.

When you type /larapilot-plan US-001, the agent:

1. Loads the skill instructions and runs larapilot:context plan: settings, paths, and the runtime files this skill reads — minus the ones the conversation already loaded
2. Reads current artifacts (PRD, spec, backlog status)
3. Runs the guided conversation with the right personas
4. Persists output via Artisan commands defined in the skill — never inventing its own file writes

The skills below are grouped by when you reach for them: the core loop runs on every story; the other groups plug in around it.

Custom skills

The twenty-nine packaged skills are the base layer. On top of them, every project can keep its own Boost skills in .larapilot/skills/ — committed with the code, registered with Boost automatically, and built on the same CLI the packaged skills use. They extend the loop; they never replace it. Walkthrough: Your own skill.

Good candidates

• Gates — pre-deploy GO/NO-GO, a hotfix checklist, a "ready for client demo" check
• Compliance — GDPR data-map refresh, an accessibility pass, a licence audit of new dependencies
• Communication — client release notes from the stories DONE since the last tag, a weekly status digest from metrics and usage-report
• House rules — how your team scaffolds a Filament resource, names queues, or wires a webhook

If it changes workflow state (a spec's status, the backlog, the PRD), it belongs in a packaged skill or its CLI — a custom skill calls those commands, it does not reinvent them.

Anatomy of a SKILL.md

---
name: acme-release-notes                 # kebab-case, 1–63 chars — also the slash command
description: "Client release notes from the stories DONE since the last tag. Use when someone asks
  what shipped, for a changelog, or for notes to send the client."   # required — Boost routes on it
---

# Acme — Release notes                   # optional title, shown on the dashboard Skills page

One paragraph on what it does — shown on the Skills page when there is no description.

## Context                               # larapilot:context {name} — settings, paths, files to read
## The Team                              # personas who speak, from the 30-persona roster
## CLI                                   # the larapilot:* commands the skill calls
## Workflow                              # numbered steps, each naming its larapilot:* command
## Output Economy                        # how much goes in chat vs on disk

Three ways to save one

# 1. Guided — Zoey interviews, Sarah saves (recommended)
/larapilot-custom-skill

# 2. From a file you wrote — name taken from --name, or from the front matter
php artisan larapilot:custom-skill-add --file=path/to/SKILL.md
php artisan larapilot:custom-skill-add --name=acme-release-notes --file=path/to/SKILL.md --force

# 3. Piped from stdin (or inline with --content=)
cat SKILL.md | php artisan larapilot:custom-skill-add --name=acme-release-notes

What custom-skill-add checks and does

A skill folder can carry more than SKILL.md — a template, a checklist, a script. Everything in the folder is mirrored.

Lifecycle

Quality bar

• Start with php artisan larapilot:context {name} (add --with=delivery-1,dev-docs for the packs it needs), read what it lists, and honor data.settings (effort, git mode, security scan, notifications…) like a packaged skill.
• Persist only through larapilot:* commands. New files go under existing .larapilot/ paths — never ad-hoc YAML beside the workflow artifacts.
• Reuse persona names from the roster (config-show --only=personas).
• No machine-specific absolute paths — use env vars, as in Environment paths.
• Prefix the name with your team or client (acme-) so it never collides with a packaged larapilot-* skill.

Runtime pack: .larapilot/runtime-custom-skills.md. There is no setting to turn custom skills on — once saved, a skill is available through its slash command.

Workflow hooks opt-in

A story always moves through the same transitions — planned, started, task done, review, approved or sent back, released, shipped. Hooks attach your team's own commands and skills to those moments. They live in .larapilot/hooks.yaml, committed so the team shares them, and run only while settings.hooks is YES.

hooks:
  task.done:
    before:
      - name: Tests
        run: php artisan test --compact
        timeout: 900
  spec.review:
    before:
      - name: Static analysis
        run: vendor/bin/phpstan analyse --no-progress
      - skill: acme-a11y-check
  spec.approved:
    after:
      - name: Deploy to staging
        run: curl -fsS -X POST "$FORGE_STAGING_DEPLOY_URL"
  ship:
    before:
      - skill: acme-predeploy-gate
    after:
      - name: Deploy to production
        run: php vendor/bin/envoy run deploy

Events

Phases and kinds

• before runs after the command's own checks and before anything is written. A hook that fails — an exit code other than 0, or past its timeout — refuses the transition with E_PRECONDITION and details.hooks, and nothing is written. blocking: false turns it into a warning.
• after runs once the state is written. A failure is reported under data.hooks.after.warnings; the transition stands.
• run: — Larapilot runs the command from the project root, with LARAPILOT_HOOK_EVENT, _PHASE, _SPEC, _SPEC_TITLE, _TASK, _STATUS_FROM, _STATUS_TO, _COMMIT, _RELEASE in its environment and the event as JSON on stdin. The answer carries the last 40 lines of its output; the whole of it is in .larapilot/cache/hooks/.
• skill: — the agent runs that skill, often one of your custom skills. Before a transition, the command refuses until the agent reports it run with --skill-hooks-done=name; after one, the answer lists it under data.hooks.after.skills.

What to hook

• Gates an agent cannot skip — the test suite, Larastan, npm run build, composer audit, a coverage floor, before task.done or spec.review. An instruction in a prompt can be forgotten; a hook runs inside the command.
• Deploys — staging after spec.approved, production after a GO from /larapilot-ship or after release.shipped.
• Your rituals at the right moment — an architecture review after spec.planned, an accessibility pass before spec.review, client release notes after release.shipped.
• What Larapilot does not integrate — Teams, Mattermost, or email; a time tracker on spec.started; a wiki export after prd.written; an n8n, Zapier, or Make webhook.

php artisan larapilot:settings-set --hooks=YES
php artisan larapilot:hook-list
php artisan larapilot:hook-run task.done --phase=before --spec=US-001 --task=TASK-01 --dry-run

Guarantees

• Nothing runs until you say so. Install writes hooks.yaml with every event listed and every example commented out, and hooks is NO. LARAPILOT_HOOKS_ENABLED=false in .env runs none on one machine.
• A file with errors is a closed gate. While hooks are on, every transition is refused until hook-list is clean or hooks are off; doctor reports checks.hooks.
• Artisan only. Hooks never run from the dashboard, the API, or MCP, where hook-list is read-only. /larapilot/settings lists the hooks of the project.
• The hooks are yours. Agents never edit a hook or turn hooks off to get past one unless you ask, and --force on spec-review / spec-approve never skips a hook.
• Secrets stay in .env. A hook reads them from its environment. Timeout 300 s by default (LARAPILOT_HOOKS_TIMEOUT), at most 3600 per hook.

Runtime pack: .larapilot/runtime-hooks.md, read by the skills that move a spec, write the PRD, or ship, while hooks is YES.

Project settings

Persistent project modes — how much effort the agent spends, how the backlog is cut, how Git and tests behave, and which opt-in extras are on. Configure with /larapilot-settings (AskQuestion) or larapilot:settings-set. Values live under settings: in .larapilot/config.yaml, which is committed, so the whole team works in the same mode. Every skill reads them first via larapilot:context.

The developer domain docs have no setting on purpose: they are always written.

Set one or several at once: php artisan larapilot:settings-set --effort=MAX --testing=BEST. Read them back with php artisan larapilot:config-show --only=settings. Yes/no settings are stored as booleans in the YAML and reported as YES / NO. A setting that is missing from the file takes its default. Every flag is listed at the end of this chapter.

Effort

Backlog granularity

Granularity changes spec cardinality only — never coverage: merged scope stays traceable via FR-XXX citations in spec bodies and plan tasks. Epics are always consolidated: reuse existing EP-XXX before proposing a new one.

Git mode

Push is never implied by GITFLOW alone. See also Git workflow.

Testing

Auto-approve

Lucille

settings.lucille controls the silent usage ledger and schedule interviews. Missing key = ON. Exclusion is opt-out only.

Re-enable anytime with php artisan larapilot:settings-set --lucille=YES without leaving ECO. Details: Usage & Lucille.

Decision journal & regression guard on by default

settings.decision_log (default YES) keeps an append-only, timestamped log of every explicit user choice — fixed-choice answers and free-text directives like “the background must be orange” — in .larapilot/decisions.yaml.

• After a choice is settled a skill runs php artisan larapilot:decision-log --topic="…" --value="…" --source=askquestion|chat --skill=….
• Before recording a value for a topic that already has a decision it runs php artisan larapilot:decision-check --topic="…" --value="…". When today’s value differs from an earlier non-superseded one the check returns that decision (with its date) so the skill can ask you to confirm — “on 2026-05-01 you chose orange; confirm red supersedes it” — then re-logs with --supersedes=<id>.
• The file is never rewritten in place; a reversal is a new entry. Read-only larapilot:decision-check is also on the MCP allowlist.
• Turn it off with php artisan larapilot:settings-set --decision-log=NO.
• The dashboard renders the journal on the PRD page (project / discovery vs per-story groups, timeline) and on each spec detail page (entries for that story only).

Prior-art check on by default

settings.prior_art (default YES) adds one step to /larapilot-inception, after the goal is challenged and before scope is written: is there already a product, an open-source project, or a package that does this?

• Consent first. A search query can expose a confidential idea. Sebastian shows the queries he would run and asks: Search now · Search with generic terms only · Skip — I know the alternatives · Skip — confidential.
• Where he looks depends on the project kind: Packagist and GitHub for a package; GitHub, self-hosted catalogs, and alternatives directories for an application; Laravel CMS and commerce platforms for a site. A Personal project skips the step.
• What you get — .larapilot/research/prior-art.md: up to five candidates with license, stack, last release, what each covers and lacks, and what adopting it would cost.
• You decide: Build anyway, Adopt / fork, Integrate as dependency, or Not checked. The verdict is written in the PRD as **Prior Art:** and shown on the dashboard's Inception page.
• When a mature product already does it and is not built on Laravel, inception says so and stops with the report.
• With no web access in the editor, or with the setting off, the PRD says Not checked — never "nothing exists". Turn it off with php artisan larapilot:settings-set --prior-art=NO.

Code change history opt-in

settings.code_history (default NO) records, per spec/task, which files and line ranges were touched — read straight from the task’s git commit — into .larapilot/code-history.yaml.

• Enable with php artisan larapilot:settings-set --code-history=YES; then larapilot-implement runs php artisan larapilot:code-log --spec=US-XXX --task=TASK-NN --skill=larapilot-implement after each task-done (--commit= / --range= override; falls back to the working-tree diff).
• php artisan larapilot:code-history --file=app/Models/Post.php (read-only, also on the MCP allowlist) reports every touchpoint for a path.

Account opt-in

settings.account is NONE (default), FREELANCE, or COMPANY. Anything but NONE unlocks /larapilot-economics and the Economics page: FREELANCE prices with sole-trader regimes (Italian forfettario, IRPEF, autónomo, …), COMPANY with corporate tax plus dividend extraction (SRL, SPA, Ltd, GmbH, C-Corp, …). OFF is accepted as an alias of NONE.

php artisan larapilot:settings-set --account=FREELANCE
php artisan larapilot:economics-set --country=IT --regime=forfettario_15 --hourly-rate=55

Release mode opt-in

settings.release_mode (default NO) turns on semver release tracking in .larapilot/releases.yaml, the /larapilot-release skill, release AskQuestion rounds in inception/adopt/feature, Gitflow release/x.y.z branches when git_mode is Gitflow, and the release ship ceremony in /larapilot-ship. Enable with php artisan larapilot:settings-set --release-mode=YES. Skill: /larapilot-release.

Project docs opt-in

settings.project_docs (default NO) obligates Albert to maintain the handbook in .larapilot/docs/handbook/ — bootstrap + incremental chapter updates after material product changes. Enable with php artisan larapilot:settings-set --project-docs=YES. Skill: /larapilot-project-docs.

Workflow hooks opt-in

settings.hooks (default NO) runs the commands and skills of .larapilot/hooks.yaml on the transitions of the loop: a before hook that fails blocks the transition, an after hook is reported. Enable with php artisan larapilot:settings-set --hooks=YES; LARAPILOT_HOOKS_ENABLED=false turns them off on one machine. Details: Workflow hooks.

Internal feedback / comments opt-in

settings.comments (default NO) gates the comment form on dashboard spec pages, POST /larapilot/api/specs/{code}/comments, and larapilot:spec-comment. Turn it on with php artisan larapilot:settings-set --comments=YES. Comments land in .larapilot/internal-feedback/{code}.md; a comment flagged [blocks-merge] stops spec-approve until it is resolved (or --force). The env kill-switch LARAPILOT_COMMENTS_ENABLED=false still disables writes even when the project setting is ON. Projects installed before v3.0.3 with an explicit comments: true keep it.

Dashboard auth opt-in

settings.dashboard_auth (default NO) puts HTTP Basic Auth in front of the dashboard UI and of the mockups at /mockups. It never gates /larapilot/api/* (that stays LARAPILOT_API_TOKEN) or the MCP server, and the dashboard is still never served in production. On a shared staging host, turn it on before anything else: with the setting OFF, the board, the PRD, the specs, the git history, and the security findings are open to whoever reaches the host.

• Credentials are argon2id/bcrypt hashes in .larapilot/auth.yaml — no database, no User model, never cleartext. The file is added to .gitignore automatically the first time a user is written.
• Manage users with php artisan larapilot:dashboard-user {list|add <username>|remove <username>} — add prompts for the password (or takes --password=).
• Failed sign-ins are rate-limited per IP (LARAPILOT_DASHBOARD_AUTH_MAX_ATTEMPTS, default 30/min). With the setting ON and no users configured the dashboard fails closed with HTTP 503: every page shows a notice that the area is protected by this setting and gives the command that creates the first user. auth.yaml is git-ignored, so a fresh clone or a deploy starts on that notice.
• The File manager, Database, and Logs pages go further: outside local/development/testing they answer 404 until this setting is YES.
• Enable with php artisan larapilot:settings-set --dashboard-auth=YES. Serve over HTTPS on shared hosts — Basic Auth sends credentials on every request. Setup: Forges & notifications · .larapilot/integrations.md.

API auth opt-in

settings.api_auth (default NO) makes LARAPILOT_API_TOKEN mandatory on every /larapilot/api/* request — the JSON API only. It never gates the dashboard UI (dashboard_auth) or the MCP server, and the API is still never served in production.

• With api_auth=NO (default): the token is enforced on every endpoint when it is set; when it is not, read endpoints stay open in the allowed environments and writes are refused outside local/development/testing.
• With api_auth=YES: every request — reads and writes, including /diagnostics, /openapi.json, and /docs — must carry the token as Authorization: Bearer <token> or X-Larapilot-Token: <token>. With the setting ON and no LARAPILOT_API_TOKEN configured the API fails closed with HTTP 503 and says why — a JSON message that names the setting and tells how to add the token, or the same explanation as a page when a browser opens the API docs; a wrong or missing token is HTTP 401.
• The token lives in the caller's environment, never in .larapilot/. Enable with php artisan larapilot:settings-set --api-auth=YES. Client setup + curl / Laravel HTTP / fetch / CI examples: .larapilot/integrations.md → API access.
• The php artisan larapilot:diagnostics CLI and the MCP diagnostics tool are local and need no token — only the HTTP endpoint is gated.

Security scan opt-in

settings.security_scan (default NO) folds a static Laravel security scan into /larapilot-review and the pre-ship gate. It uses the optional dev package andreapollastri/checkpoint (php artisan checkpoint:scan — static checks plus composer/npm audit), run through php artisan larapilot:checkpoint-scan so the result lands on Security → Checkpoint. Larapilot never bundles the scanner; with the setting off it runs only when someone asks — the command, or Run the scan on the dashboard. See SBOM, CVE & Checkpoint.

composer require --dev andreapollastri/checkpoint
php artisan larapilot:settings-set --security-scan=YES

• FAIL findings are review blockers: fix them, or record a waiver with larapilot:decision-log. WARN findings become review notes.
• If the package is missing, the review skill stops and asks you to install it.
• Owned by Lars, alongside dashboard_auth and api_auth. The client quote only promises a security scan when this setting is YES. Setup: .larapilot/integrations.md → Security scan.

Aikido opt-in

settings.aikido (default NO) reads the findings of Aikido for the repository. Aikido scans on its side; Larapilot runs no scanner and only reads the result, with credentials kept in .env. While the setting is off, Aikido is never called.

php artisan larapilot:settings-set --aikido=YES
php artisan larapilot:aikido-status

Owned by Lars. Everything else — the credentials, the skill, the gate — is in Aikido.

Production errors opt-in

settings.errors (default NO) reads the errors the running application throws from one tracker, and settings.errors_provider names it: boogle (the default), sentry, bugsnag, flare, datadog, rollbar, honeybadger, or cloudwatch. The credentials stay in .env. While errors is off no tracker is called, and the tracker that was named is kept for when it is turned on again. /larapilot-error asks which tracker when none is set, and turns the errors on.

php artisan larapilot:settings-set --errors=YES --errors-provider=sentry
php artisan larapilot:errors-status

settings.boogle is the name the setting had when Boogle was the only tracker: --boogle=YES is --errors=YES --errors-provider=boogle, and the key is kept in step with the two. A project that turned Boogle on before 4.1.3 has nothing to change.

Owned by Sophia. The trackers, what each needs in .env, and the skill are in Production errors.

Remote forges opt-in

settings.github, gitlab, bitbucket, and azure (all default NO) are orthogonal to git_mode. Enable the forge matching origin:

• GitHub — gh CLI; probe larapilot:github-status
• GitLab — glab CLI (MR); probe larapilot:gitlab-status
• Bitbucket Cloud — REST API with access token or app password; probe larapilot:bitbucket-status
• Azure DevOps — az repos (azure-devops extension) or REST API with a PAT; probe larapilot:azure-status

When ON, skills open/update the PR/MR, always print the URL, and can notify pr_opened / pr_updated. Full setup: Forges & notifications · .larapilot/integrations.md.

Notifications opt-in

Master switch settings.notifications plus notify_slack / notify_discord / notify_telegram (all default NO). Secrets stay in .env. Fan-out via php artisan larapilot:notify. Hard hooks: task-done → task_done, spec-approve → spec_done. Full event list: Forges & notifications.

Environment paths

Machine-specific absolute paths must not appear in committed YAML or skill examples. Store them in .env and resolve via config-show:

When a skill needs a path that is missing from env, it keeps asking until you provide it, then persists with the matching CLI command. The PRD records the stack, not the absolute path.

Every flag, with its default

php artisan larapilot:settings-set \
  --effort=STANDARD \
  --backlog=STANDARD \
  --git-mode=GITFLOW \
  --testing=NORMAL \
  --account=NONE \
  --auto-approve=NO \
  --lucille=YES \
  --decision-log=YES \
  --code-history=NO \
  --prior-art=YES \
  --release-mode=NO \
  --project-docs=NO \
  --hooks=NO \
  --comments=NO \
  --dashboard-auth=NO \
  --api-auth=NO \
  --security-scan=NO \
  --aikido=NO \
  --errors=NO \
  --errors-provider=boogle \
  --github=NO \
  --gitlab=NO \
  --bitbucket=NO \
  --azure=NO \
  --notifications=NO \
  --notify-slack=NO \
  --notify-discord=NO \
  --notify-telegram=NO

Personas

30 personas are lenses, not costumes. Each skill activates a subset of the squad — they speak in chat as 💎 Mark:, 📐 John:, etc., applying a specific kind of scrutiny to the work at hand. Zoey (AI Guru) is active in every skill; Lucille is active quietly by default (usage ledger). Nothing here is a separate agent with its own memory: a persona is the point of view the agent takes while it does one part of the work.

Output economy varies by phase: concise status lines during implement/review; full artifacts and code stay complete. See .larapilot/shared-runtime.md for brevity rules.

Workflow

Every user story moves through a strict state machine on a Gitflow branch model. Skills drive transitions; invalid jumps are blocked automatically. After inception and backlog creation, you repeat the per-story loop until the MVP is shipped.

Git workflow — Gitflow

Git behavior is gated by settings.git_mode (set via /larapilot-settings). Default is GITFLOW without automatic push. Choose GITFLOW_PUSH for push-after-each-task, or NO_GITFLOW to skip branch/PR ceremony. Jack proposes the workflow at inception; Sarah owns Git mechanics (conflicts, rebase), forge automation, and CI pipeline scripts; Robert enforces the active mode.

When two developers work the same project and a merge conflict lands — in source or in a .larapilot/ artifact like backlog.yaml — resolve code with git, but for .larapilot/ files take the other side and re-run the Larapilot command that produced your change rather than hand-editing the markers.

In Gitflow modes: no direct commits to main or develop; one atomic Conventional Commit per plan task. Push and remote PR updates run only when git_mode is GITFLOW_PUSH (or the user asks). Critical production defects route through hotfix/* via /larapilot-bug. Mode table: Git mode settings.

When release_mode=YES and Gitflow is active, specs assigned to an in_progress release branch from release/x.y.z and merge back into that branch (see /larapilot-release). Unassigned specs keep branching from develop. Multiple release/* branches may run in parallel — Sarah confirms which release context is active before starting work.

Status machine

Transition guards

The workflow engine rejects invalid state changes — for example, you cannot implement before planning, or approve before review. When you reject a review, the spec returns to TODO with your feedback attached so the agent can replan and reimplement.

Human-in-the-loop

Discovery interviews use AskQuestion wizards. By default, review is yours — the agent proposes, you approve or send back. No spec reaches DONE without explicit acceptance unless you set auto_approve: YES in project settings (opt-in for /larapilot-autopilot).

The PRD

The PRD is the product contract: what the product promises, to whom, and how well. Everything downstream is measured against it. A story exists because a requirement does, a bug is a promise that was not kept, and a review checks that it was. It is one Markdown file, .larapilot/docs/PRD.md, written by inception and changed only through skills.

What is in it

The PRD is written in the language of your conversation. Ids and the MoSCoW labels stay as they are in every language. A complete example is in the New product walkthrough.

What validate-prd checks

An error fails the command. A warning never does, so an older PRD stays valid — and /larapilot-prd "Upgrade the PRD" clears the warnings.

How the PRD changes after inception

Three skills may change the PRD, and each one leaves a row in the revision history. Find what happened in the first column.

When in doubt, leave the PRD alone and write the story. A story can be corrected next week. A PRD that collects fixes stops being a contract.

## PRD Revision History

| Date | Trigger | Summary |
| --- | --- | --- |
| 2026-07-01 | larapilot-inception | Initial PRD |
| 2026-07-15 | larapilot-feature US-011 | Added FR-011 Export PDF (MoSCoW: Should) |
| 2026-07-15 | larapilot-bug → FR-003 gap | SSO must work on Safari 17+ (macOS/iOS) |
| 2026-08-02 | larapilot-prd — Re-scope + Sharpen | FR-009 retired; FR-006 Could → Must; NFR-001 p95 < 300 ms |
| 2026-08-20 | larapilot-feature US-019 (change request) | FR-011: PDF opens in the browser instead of downloading |

Revision kinds

/larapilot-prd starts by naming the kind of change, because the kind decides how many questions it asks and how much of the backlog moves. One request can carry several.

Whatever the kind, nothing is written before the readback: Mark shows before and after for each item, then asks Apply · Revise · Cancel. When a security, privacy, or accessibility target goes down, Lars or Violet states the consequence first. Walkthrough.

Ids are permanent

Stories, plans, commits, and developer docs cite FR-, J-, NFR-, and Q- ids. A revision never breaks those citations.

The backlog follows

A changed promise is worth nothing if the stories still describe the old one. larapilot:prd-impact lists the stories that cite the ids being changed, and says what each one needs. What it needs depends on how far the story has gone.

php artisan larapilot:prd-impact --ids=FR-004,J-001   # the stories that cite these ids
php artisan larapilot:prd-impact                       # the whole PRD: every id and the stories that cite it

Without --ids the command is a coverage report. untraced lists the ids no story cites, and uncovered_must the Must requirements among them — the ones that would ship unbuilt. /larapilot-spec runs it after every backlog change.

Feature, bug, or revision — side by side

Rule files: .larapilot/runtime-ops-1.md (PRD Living Document) and runtime-ops-3.md (PRD Revision).

Artifacts

Everything the workflow produces lives in .larapilot/ inside your repo. Skills read and write these files; they survive across editor sessions and give every agent the same ground truth.

JSON responses from CLI commands use schema larapilot/v1 — skills parse these envelopes to confirm writes and status changes. Inspect artifacts visually via the dashboard or programmatically via the API.

Developer domain docs

The code says what; the PRD says what the client wanted. Neither says why it is built this way. .larapilot/docs/devs/ is where that reasoning survives the session that produced it: one Markdown file per domain, written for whoever maintains the code next. It is always on — there is no setting for it.

README.md                 # index — one row per domain, last spec that touched it
TEMPLATE.md               # the skeleton every file follows
billing.md
user-authentication.md
webhook-ingestion.md

The skeleton

Rules that keep them useful

• Always English, whatever language the PRD and the conversation use — the files address whoever inherits the codebase, not the client.
• Updated in the same spec that changes the behavior, inside the task commit — code, tests and doc together. A task is not task-done while its doc describes the old code.
• Never deferred. effort: ECO makes the prose terse; the file is still written.
• One file per domain, not per class. An entity gets its own file only when it carries behavior beyond CRUD.
• Rewrite, don't append. The folder is the current truth; history belongs to Git.

Who enforces it

A project with no docs is brought level on the first change

config-show (and doctor) report the state under data.dev_docs: path, documented, count, and the domains already written. When documented is false and the codebase already has domains, the first spec, fix, or hotfix inventories every existing domain, writes a file for each, commits the backfill on its own — docs(US-XXX): bring developer domain docs level — and only then runs its own work. No question asked, no partial pass, no ECO exemption. Where the original reasoning can't be recovered from git history, the PRD, decisions.yaml, or the plans, the file says <!-- TODO: verify --> instead of inventing a motive.

Usage & Lucille

Lucille keeps a committed ledger of AI tokens and wall-clock time, plus delivery deadlines. Every skill may append an entry at session end; /larapilot-usage interrogates the data. Dashboard Usage is the token and hour ledger; Plan is the Gantt and the deadlines. Usage still offers the Markdown download.

Categories

analysis · planning · implementation · support · feature · review · ship · other.

Commands

php artisan larapilot:usage-log --category=implementation --tokens=12000 --minutes=45 --skill=implement --spec=US-001
php artisan larapilot:usage-report --format=json --insights
php artisan larapilot:usage-report --format=md --output=.larapilot/usage/report.md --insights --from=2026-08-01 --to=2026-08-31
php artisan larapilot:schedule-set --deadline=2026-09-15 --label="MVP go-live" --status=on_track
php artisan larapilot:schedule-set --deadline=2026-07-10 --label="Beta" --release=0.2.0
php artisan larapilot:schedule-show --only=alerts,findings
php artisan larapilot:schedule-apply --file=.larapilot/tmp-payload-schedule.json --dry-run

Report filters: --category= · --user= · --skill= · --spec= · --from= · --to= · --limit= · --insights. Formats: json · md · human.

Estimate vs build

The Usage page opens with what the delivered specs took. For every spec that is DONE: the hours it was estimated at — the hours of its plan's tasks, its story points when it has no plan, before the PM/QA buffer: the same estimate Economics prices — the time it took to build, how long it then waited in review, and the tokens the ledger holds for it. A spec that review sent back, or that was started over, says so. Above the table: the estimated hours, the build time, and how many times the first holds the second — given from three specs with a build time, since one spec proves nothing.

fernway.test/larapilot/usage

The times are not logged by anyone: spec-start, spec-review, and spec-approve already write the moment of every step in the backlog, and the page reads them. So they cost no tokens, and they are there with Lucille off. What they are is worth keeping in mind. Build is the time the spec was IN PROGRESS, pauses included: a session left open overnight counts the night. In review is a wait, not the hours someone spent reviewing. And the estimate is the agent's own. The figure says how the plans compare with the builds; it does not say what a person would have taken. Only the tokens come from the ledger, which is why Lucille logs with --spec= whenever a session works one spec.

The same figures: a section of report.md, insights.actuals in usage-report --insights, build in GET /larapilot/api/metrics, and one line on Economics — for you, never in the client quote.

When Lucille is OFF

usage-log refuses writes. /larapilot-usage states she is excluded and may still run a read-only report on historical data. Re-enable: php artisan larapilot:settings-set --lucille=YES. ECO switches set lucille: NO automatically unless you pass --lucille=YES together with --effort=ECO.

Dashboard: /larapilot/usage for tokens and estimate vs build · /larapilot/plan for the Gantt and deadlines · download /larapilot/usage/report.md (dev/staging only). MCP RunArtisanTool allows larapilot:usage-report.

Laravel, PHP & DB upgrades

Three skills move the project to a new version: /larapilot-laravel-upgrade, /larapilot-php-upgrade, and /larapilot-db-upgrade. All three start with a readiness report and its criticalities — blocker, high, medium, low, info — and change nothing until you choose upgrade now, add it to the backlog, or stop at the report.

php artisan larapilot:stack                                   # versions, support windows, packages, pins
php artisan larapilot:upgrade-check --laravel=13 --report
php artisan larapilot:upgrade-check --php=8.4 --php-from=8.2
php artisan larapilot:upgrade-check --db=pgsql:17 --db-from=mysql:8.0
php artisan larapilot:upgrade-check --laravel=13 --offline    # the lock only, no Packagist

What the check reads

• Dependencies — composer.lock, and Packagist for the releases of each direct dependency that support the target Laravel on the PHP that Laravel needs. It follows self.version into the packages of the same vendor, so Filament is measured by filament/support. Verdicts: ok, update (fits the constraint), bump (a new constraint, often a major), blocker, abandoned, private (Nova, Spark, a Satis — Packagist cannot see it). Answers are cached for a day.
• PHP — the PHP the project is on (config.platform.php, else the floor of require.php), every installed package whose PHP requirement excludes the target with what requires it, code the target deprecates (implicitly nullable parameters on 8.4, non-canonical casts on 8.5, …), extensions that left core.
• Database — raw SQL, column types, reserved words, and server options the target does not accept, with file and line (MySQL functions on the way to PostgreSQL, GROUP BY … DESC on MySQL 8.0, default-authentication-plugin on 8.4, …), and the checklist no scan can see.
• Pins — Dockerfile and compose images, CI matrices, vapor.yml, .php-version, .nvmrc, phpstan.neon, rector.php.

Composer has the last word: the report names the --dry-run that asks it. The reports go to .larapilot/docs/upgrades/ (paths.upgrades).

Upgrade now

1. A clean tree, a branch by git_mode, and a baseline: tests, Pint, Larastan, the build.
2. PHP first when the target Laravel needs it; one Laravel major at a time; the database last, once the code runs on the target engine locally.
3. Each step: the Composer change, the upgrade guide of that version (Boost Search Docs, never from memory), the package playbooks, Rector when the project has it, the gates, one commit.
4. An upgrade report: criticalities resolved, followed up, or accepted; dependencies before and after; the deploy runbook; the rollback.

/larapilot-db-upgrade never connects to a production or shared database: it rehearses on a scratch database and writes the data move (pgloader with sequences reset, counts to compare) and the cutover. The About page of the dashboard shows each version with its support window and the command that checks the next upgrade.

fernway.test/larapilot/about

Forges & notifications

Optional remote forges and chat fan-out — all OFF by default, orthogonal to git_mode. Full install steps live in .larapilot/integrations.md (published on install/update). Toggle via /larapilot-settings or larapilot:settings-set.

Remote forges

When ON, skills open/update the PR/MR (still respecting git_mode), always print the URL, and may emit pr_opened / pr_updated notifications. Secrets stay in .env — never in config.yaml.

Chat notifications

Master switch settings.notifications plus notify_slack / notify_discord / notify_telegram. Fan-out: php artisan larapilot:notify.

• Hard hooks: task-done → task_done, spec-approve → spec_done
• Skill events: PR/MR opened/updated, review, ship, schedule drift
• Env: LARAPILOT_SLACK_WEBHOOK_URL, LARAPILOT_DISCORD_WEBHOOK_URL, LARAPILOT_TELEGRAM_BOT_TOKEN, LARAPILOT_TELEGRAM_CHAT_ID; Bitbucket BITBUCKET_ACCESS_TOKEN or username + app password; Azure DevOps AZURE_DEVOPS_EXT_PAT (or az login)

Settings tables: Remote forges · Notifications.

Dashboard access

Optional HTTP Basic Auth on the dashboard UI, via the dashboard_auth setting (default NO). UI-only — never /larapilot/api/* or MCP.

php artisan larapilot:dashboard-user add andrea        # prompts for the password (or --password=)
php artisan larapilot:dashboard-user list
php artisan larapilot:dashboard-user remove andrea
php artisan larapilot:settings-set --dashboard-auth=YES

• Credentials are argon2id/bcrypt hashes in .larapilot/auth.yaml — no database, no User model; the file is added to .gitignore automatically.
• Env: LARAPILOT_DASHBOARD_AUTH_REALM, LARAPILOT_DASHBOARD_AUTH_MAX_ATTEMPTS (failed sign-ins per minute per IP, default 30; 0 disables throttling).
• dashboard_auth=YES with no users → dashboard fails closed (HTTP 503) on a notice that tells how to add the first one. Serve over HTTPS on shared hosts.

Settings table: Dashboard auth.

Security scan

Optional static scan with andreapollastri/checkpoint in /larapilot-review and before ship — FAIL blocks, WARN becomes a note. Off until you install the package and set security_scan=YES. Details: Project settings → Security scan.

Backstage portal

Larapilot is repo-level; Backstage is org-level. The integration publishes .larapilot/ into the developer portal — a catalog entity, a TechDocs site built from the PRD and backlog, and a live delivery snapshot. The direction is one-way: the workspace stays the source of truth, and workflow state never changes from the portal.

When it is worth it

Generate

/larapilot-backstage

The skill asks for owner, system, and lifecycle, persists them to .env, then generates. Equivalent CLI:

php artisan larapilot:backstage-export           # preview the bundle — writes nothing
php artisan larapilot:backstage-export --write   # generate catalog + TechDocs
php artisan larapilot:backstage-export --write --force        # overwrite existing files
php artisan larapilot:backstage-export --write --no-techdocs  # catalog entity only

The two root files may already belong to the project (an existing catalog entry, an existing MkDocs site), so Larapilot keeps them unless you pass --force; the envelope's data.hint names what was kept. Everything under .larapilot/techdocs/ is generated output — fix the PRD or the spec and regenerate rather than editing a page.

Catalog entity

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: acme-shop
  namespace: default
  title: 'Acme Shop'
  description: 'A thing.'          # PRD elevator pitch, when present
  annotations:
    backstage.io/techdocs-ref: 'dir:.'
    larapilot.io/version: 2.2.0
    larapilot.io/workspace: .larapilot
    larapilot.io/prd: .larapilot/docs/PRD.md
    larapilot.io/board-url: 'https://staging.acme.test/larapilot'
    larapilot.io/api-url: 'https://staging.acme.test/larapilot/api'
  tags: [laravel, larapilot]
spec:
  type: service
  lifecycle: production
  owner: 'group:default/platform'
  system: commerce
  providesApis:
    - acme-shop-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: acme-shop-api
  title: 'Acme Shop API'
spec:
  type: openapi
  lifecycle: production
  owner: 'group:default/platform'
  definition:
    $text: ./openapi.json          # resolved by Backstage relative to this file

The name defaults to a slug of app.name, the description to the PRD Elevator Pitch (falling back to the composer description), and the larapilot.io/* annotations let a plugin locate the board and API for this entity.

Catalog identity

Identity describes the org catalog, not the delivery workflow — so it lives in Laravel config and .env, not in .larapilot/config.yaml. Never set it with larapilot:settings-set.

php artisan larapilot:config-show reports the resolved mapping under data.backstage (entity ref, owner, system, lifecycle, TechDocs paths, whether the catalog file exists).

TechDocs

MkDocs config and sources are generated together, so Backstage builds the docs site straight from the repository:

site_name: 'Acme Shop'
site_description: 'A thing.'
docs_dir: .larapilot/techdocs
plugins:
  - techdocs-core
nav:
  - Overview: index.md
  - 'Product Requirements': prd.md
  - Backlog:
      - Overview: backlog/index.md
      - 'US-001 — Login': backlog/US-001.md

Specs and plans are YAML on disk, so each story page is rendered to Markdown: status/priority/points/epic table, task progress, internal-feedback counts, then the spec body, the technical plan, and the task checklist. Internal feedback bodies stay in the repo — only counts are published.

Live delivery data

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

{
  "entity_ref": "component:default/acme-shop",
  "metrics": { "total": 12, "done": 5, "completion_rate": 41.7, "total_tasks": 61, "done_tasks": 40 },
  "counts_by_status": { "TODO": 5, "PLANNED": 2, "IN PROGRESS": 1, "REVIEW": 1, "DONE": 3 },
  "blocking_feedback": { "count": 1, "specs": ["US-003"] },
  "stories": [
    {
      "code": "US-001", "title": "Login", "status": "PLANNED", "priority": "HIGH", "points": 3,
      "tasks": { "total": 2, "done": 0 }, "blocking_feedback": 0,
      "techdocs_path": "backlog/US-001.md"
    }
  ],
  "links": { "board": "https://staging.acme.test/larapilot", "api": "https://staging.acme.test/larapilot/api" }
}

Register & keep fresh

• Commit catalog-info.yaml, mkdocs.yml, and .larapilot/techdocs/ on the default branch.
• In Backstage: Create → Register existing component → paste the repo URL of catalog-info.yaml. Orgs with catalog discovery configured skip this step.
• TechDocs builds from mkdocs.yml; the backstage.io/techdocs-ref: dir:. annotation is already set.
• Regenerate after PRD, backlog, or plan changes — a CI job on the default branch running --write --force and committing the diff keeps the portal from drifting.

Personas & boundaries

• Matt — owns the catalog mapping: owner, system, lifecycle, which APIs get registered
• Jack — CI regeneration and environment reachability
• Albert — TechDocs nav and readability
• Lars — token/proxy boundary; the portal is never pointed at production

Project trackers

Optional, API-key based sync between the backlog and the tool the rest of the organisation already lives in — Linear, Asana, Jira, Trello, ClickUp, or Monday. A PM or a client follows delivery without ever opening backlog.yaml. The workspace stays the source of truth; the tracker is a window, not a second workflow.

When it is worth it

Setup

/larapilot-tracker

The skill picks the provider, tells you where to generate the API key, writes it to .env, validates the status map against the real board, dry-runs, then pushes. By hand:

php artisan larapilot:tracker-status --ping   # credentials + target board
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

What gets mirrored

A user story becomes an issue titled US-XXX — Title carrying the spec body, priority, points, and epic. Plan tasks are mirrored as native subtasks, not a checklist buried in the description. One provider is active at a time, but links are stored per provider — switching tools, or switching back, never loses the mapping.

Push writes, pull reports

The direction is deliberately asymmetric. Push is authoritative: .larapilot/ decides what a story says and which column it sits in, and unchanged stories are skipped without an API call. Pull is a report — it lists drift and changes nothing until you pass --apply.

• DONE is never applied from a tracker. DONE is a human review gate that records the merge commit — it stays with /larapilot-review and larapilot:spec-approve.
• Spec text is never read back. 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 sharing one column is normal and is not drift — a story is in sync when its forward mapping matches the remote label.
• A remote status outside the map is reported as drift with no suggestion, never guessed at.

Set LARAPILOT_TRACKER_PULL_COMMENTS=true to import tracker comments as internal feedback — non-blocking, and imported once each.

Configuration

Per-provider credentials follow the same shape: LARAPILOT_LINEAR_API_KEY / _TEAM, LARAPILOT_JIRA_BASE_URL / _EMAIL / _API_TOKEN / _PROJECT, LARAPILOT_ASANA_TOKEN / _PROJECT, LARAPILOT_TRELLO_KEY / _TOKEN / _BOARD, LARAPILOT_CLICKUP_TOKEN / _LIST, LARAPILOT_MONDAY_TOKEN / _BOARD. 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.

Personas & boundaries

• Matt — provider choice, status mapping, link hygiene
• Mark — what non-developers should see on the board
• Jack — the CI push step on the default branch
• Lars — the credential boundary: API keys live in .env, never in .larapilot/

Aikido

Optional. Aikido scans the repository on its side — dependencies, code, leaked secrets, infrastructure, licenses — through its connection to the git provider. Larapilot runs no scanner and installs nothing: it reads what Aikido found over the public REST API, says what was already decided about each finding, and brings the rest into the workflow through /larapilot-triage.

Setup

1. Connect the repository in Aikido, through the git provider (GitHub, GitLab, Bitbucket, Azure DevOps). Larapilot cannot do this step.
2. Create the credentials in Aikido under Settings → Integrations → Public REST API. Reading needs the issues:read and repositories:read scopes; telling Aikido a decision needs issues:write; asking for a scan needs repositories:write.
3. Put them in .env — never in .larapilot/, which is committed.
4. Turn the setting on and check the connection.

LARAPILOT_AIKIDO_CLIENT_ID=
LARAPILOT_AIKIDO_CLIENT_SECRET=
LARAPILOT_AIKIDO_REGION=eu        # eu (default) · us · au · me
LARAPILOT_AIKIDO_REPOSITORY=      # id or name in Aikido, for this machine; empty = chosen or found from the git remote
LARAPILOT_AIKIDO_FAIL_ON=high     # critical · high · medium · low · none
LARAPILOT_AIKIDO_PUSH_DECISIONS=true  # false = decisions stay in the project
LARAPILOT_AIKIDO_CACHE=300        # seconds the dashboard keeps what it read
LARAPILOT_AIKIDO_BASE_URL=        # only when the workspace is reached through another address

php artisan larapilot:settings-set --aikido=YES
php artisan larapilot:aikido-status

aikido-status answers with enabled, configured, authenticated, the repository it matched (id, name, branch, last scan), and hints: one line for each thing that is missing, with what to do about it.

The repository

The repository is found from the git remote, by its address or by its name. When the code is scanned under another repository — a fork, a mirror, a monorepo, a name that differs — nothing matches: aikido-status answers needs_repository: true, and you are asked which one it is. /larapilot-aikido asks in chat, /larapilot/security shows the list with a form, and the terminal has a command. Nothing is chosen for you: a name that looks alike is not a match.

php artisan larapilot:aikido-repos                # the repositories of the workspace
php artisan larapilot:aikido-repos --search=shop  # only the names that hold these letters
php artisan larapilot:aikido-repos --use=12       # this project is repository 12 (or its exact name)
php artisan larapilot:aikido-repos --forget       # back to the git remote

The choice is kept in .larapilot/aikido.yaml, which is committed, so every machine reads the same repository. LARAPILOT_AIKIDO_REPOSITORY in .env names it for one machine, and wins there.

The skill

/larapilot-aikido

1. Status — one line: repository, branch, last scan, the severity the gate fails on. With something missing, the hints are printed and the skill stops.
2. Download — aikido-issues --new --report. The findings nobody decided about are shown in a table, the most severe first, 15 rows at most; the detail of all of them goes to .larapilot/docs/security/aikido.md.
3. Scope — one question: the findings that stop the ship gate, every new finding, the ones you name, or none.
4. Confirm — finding by finding (or in batches when there are many): resolve, waive with a reason, or skip for now. Waives are recorded immediately with aikido-link.
5. Plan — aikido-plan --ids=… groups the confirmed ids by kind and fix; you approve the groups. Leaked secrets never merge with anything else.
6. Hand off to triage — each group goes to /larapilot-triage in the same turn, with the block below. Triage measures it against the PRD like any request: a known vulnerability in shipped code is a bug when a requirement names security for that area, a bug with a requirement gap otherwise, and the verdict is not asked. /larapilot-bug then writes the fix spec, with a criterion that Aikido no longer reports the finding.
7. Record — aikido-link 24 --spec=US-012, so the finding is not handed over again, on this machine or another.

Aikido finding
ids: 24, 25
severity: critical (95/100)
kind: Vulnerable dependency
title: guzzlehttp/psr7
where: fjord-invoices
cves: CVE-2026-1111
fix: Upgrade guzzlehttp/psr7 to 2.7.0 or later

What a finding can be

Decisions are told to Aikido

What you decide here is sent to Aikido, so the workspace says the same as the project.

• A finding can be in several repositories of the workspace. When it is, only the issues of this repository are ignored, and the other projects keep theirs.
• The credentials need the issues:write scope. When Aikido refuses, or cannot be reached, the decision is kept and listed as unsent; larapilot:aikido-push tells it later. It also tells the decisions taken with an earlier version.
• A waiver Aikido would not take back is not forgotten here, so the two never disagree.
• --local on aikido-link keeps one decision in the project; LARAPILOT_AIKIDO_PUSH_DECISIONS=false keeps them all.

The register for the client

larapilot:aikido-register writes {paths.security}/aikido-register.md, and Register for the client (.md) on /larapilot/security downloads it: one document with every finding of the repository — open with the fix that is planned, resolved with the date, ignored with the date and the reason — and a count by severity. It is what a client or an auditor asks for when a certification requires that every vulnerability is tracked to a decision, and it is written in the language of the PRD.

The reason of a finding waived here is the one you wrote. Aikido does not give back the reason of a finding ignored there by hand: the register lists it, and says the reason is kept in Aikido.

The verdict of the gate is FAIL when a finding at LARAPILOT_AIKIDO_FAIL_ON (default high) or above counts, WARN when only lower ones do, PASS otherwise. /larapilot-ship runs larapilot:aikido-issues --gate --report: FAIL is a release blocker, WARN a note in the assessment. The same command exits 1 on FAIL, so a pipeline can use it.

Commands

aikido-status, aikido-issues, aikido-plan, and aikido-repos (the list only) are allowed through the MCP RunArtisanTool; the commands and the options that write are not.

On the dashboard

/larapilot/security is always in the menu. With the setting off it is two lines: what Aikido scans, and how to turn the link on. With the setting on it opens on the verdict of the gate, in a sentence — A release is stopped: 3 open findings are high or above, 2 with no decision yet — then the open findings by severity, then every finding, the most severe first. A row opens on what the finding is, how to fix it, where it is, its CVE, when it was first seen, and what was decided: the spec it is in the backlog as, with its status, or the reason it was waived. Findings filter by decision and by text. What was read is kept for five minutes; Read again asks Aikido anew, Download report (.md) saves the same document the skill writes, and Register for the client (.md) saves every finding — open, resolved, ignored with its reason. A decision Aikido was not told yet is said under the list. When the git remote matches no repository of Aikido, the page lists the repositories of the workspace and asks which one the project is. When Aikido cannot be read the page says what to check, and the rest of the dashboard is untouched.

What is kept, and where

Production errors

Optional. The running application throws, one tracker records it, and Larapilot reads the open errors back: it puts them together into bugs, says what was already decided about each, and brings the rest into the workflow through /larapilot-triage. settings.errors turns it on and settings.errors_provider names the tracker: /larapilot-error asks which one when none is set. The skill (/larapilot-error) and the commands (larapilot:errors-*) are the same for every tracker; the names the commands had when Boogle was the only one (larapilot:boogle-*) still answer, and the ledger keeps its name, .larapilot/boogle.yaml.

The trackers

Every credential is one that reads the tracker — never the key the application reports with (FLARE_KEY, BUGSNAG_API_KEY, ROLLBAR_TOKEN, HONEYBADGER_API_KEY). SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT, DD_API_KEY, DD_APP_KEY, and DD_SITE are taken when the project has them already. One tracker is read at a time. Laravel Nightwatch is not among them: it publishes no API to read exceptions with.

• One row is a throw — Boogle, CloudWatch, the logs of Datadog. Larapilot puts together the rows that share the exception, the file, and the line, counts them, and draws them day by day on the dashboard.
• One row is a bug — Sentry, Bugsnag, Flare, Rollbar, Honeybadger, Datadog Error Tracking. The tracker grouped already: its grouping and its count are kept. The dashboard has no day chart, since such a tracker says when a bug was last thrown and not each time.

Setup with Boogle

1. Have the application send its exceptions to Boogle: composer require andreapollastri/boogle-client, then php artisan boogle:install. Larapilot does not do this step.
2. Create a token in Boogle, as an admin user, in the profile under API tokens. The admin API answers to admin users only.
3. Put the address and the token in .env — never in .larapilot/, which is committed.
4. Turn the setting on and check the connection.

LARAPILOT_BOOGLE_URL=https://boogle.example.com   # empty = taken from BOOGLE_SERVER
LARAPILOT_BOOGLE_TOKEN=                            # the token of an admin user of Boogle
LARAPILOT_BOOGLE_PROJECT=                          # id or title in Boogle; empty = found by itself
LARAPILOT_BOOGLE_CACHE=300                         # seconds the dashboard keeps what it read

php artisan larapilot:settings-set --errors=YES --errors-provider=boogle   # or --boogle=YES
php artisan larapilot:errors-status

errors-status answers with enabled, provider, configured, authenticated, the project it matched (id, title, address, group, whether the uptime is watched), remote_resolve, and hints: one line for each thing that is missing. The project is the one named in LARAPILOT_BOOGLE_PROJECT; with nothing named, the one whose key is BOOGLE_PROJECT_KEY — what the client package sends with — and then the one whose address is APP_URL.

Setup with another tracker

The application sends its exceptions to the tracker as it already does — Larapilot changes nothing there. Put what reads the tracker in .env, name the tracker, and check: with the errors on, errors-status asks the tracker, so a token it refuses is known before the skill runs.

# Sentry — an auth token with event:read (event:write to close an issue)
LARAPILOT_SENTRY_AUTH_TOKEN=             # or SENTRY_AUTH_TOKEN
LARAPILOT_SENTRY_ORGANIZATION=           # or SENTRY_ORG: the slug of the organization
LARAPILOT_SENTRY_PROJECT=                # or SENTRY_PROJECT: the slug of the project
LARAPILOT_SENTRY_URL=https://sentry.io   # self-hosted, or a region: https://de.sentry.io

# Bugsnag — a personal auth token (My account → Personal auth tokens)
LARAPILOT_BUGSNAG_AUTH_TOKEN=
LARAPILOT_BUGSNAG_PROJECT_ID=            # Project settings → General

# Flare — a personal access token with the read scope (write to resolve an error)
LARAPILOT_FLARE_TOKEN=
LARAPILOT_FLARE_PROJECT_ID=

# Datadog — an API key and an application key
LARAPILOT_DATADOG_API_KEY=               # or DD_API_KEY
LARAPILOT_DATADOG_APP_KEY=               # or DD_APP_KEY
LARAPILOT_DATADOG_SITE=datadoghq.com     # or DD_SITE: datadoghq.eu, us3.datadoghq.com, …
LARAPILOT_DATADOG_SERVICE=               # the service tag; empty = APP_NAME
LARAPILOT_DATADOG_SOURCE=error_tracking  # or logs: the error logs of two weeks
LARAPILOT_DATADOG_TRACK=trace            # in Error Tracking: trace (APM), logs, rum

# Rollbar — a project access token with the read scope (write to resolve an item)
LARAPILOT_ROLLBAR_ACCESS_TOKEN=

# Honeybadger — the personal authentication token of a user (profile → Authentication)
LARAPILOT_HONEYBADGER_AUTH_TOKEN=
LARAPILOT_HONEYBADGER_PROJECT_ID=        # as in the address of the project page

# AWS CloudWatch Logs — read with the AWS CLI signed in on the machine: no key is kept
LARAPILOT_CLOUDWATCH_LOG_GROUP=          # the log group the application writes to
LARAPILOT_CLOUDWATCH_REGION=eu-west-1    # or AWS_DEFAULT_REGION
LARAPILOT_CLOUDWATCH_PROFILE=            # optional: a profile of the AWS CLI
LARAPILOT_CLOUDWATCH_FILTER="?ERROR ?Exception ?CRITICAL"

# Every tracker
LARAPILOT_ERRORS_CACHE=300               # seconds the dashboard keeps what it read
LARAPILOT_ERRORS_TIMEOUT=15              # seconds a call to the tracker may take

php artisan larapilot:settings-set --errors=YES --errors-provider=sentry
php artisan larapilot:errors-status

*_PROJECT_NAME (Bugsnag, Flare, Rollbar, Honeybadger) is optional, and gives the report its title. A provider Larapilot does not know, written by hand in config.yaml, is named by errors-status with the ones it does.

One entry for each bug

Boogle keeps one row for each time an exception is thrown, and gives each a code (#BUG12, #OUT3). Fourteen rows of one exception at one line are one bug thrown fourteen times, and that is how Larapilot shows them. A tracker that groups by itself — Sentry, Bugsnag, Flare, Rollbar, Honeybadger, Datadog Error Tracking — answers with the bug and its count: both are kept as they are, under the code the tracker gives (SHOP-1A, #RB57, #FL9001).

The skill

/larapilot-error

1. Tracker — with the errors off, one question: which tracker records them — Boogle, Sentry, Bugsnag, Flare, Datadog, Rollbar, Honeybadger, CloudWatch — or none. The skill never chooses for you; your answer is saved with settings-set --errors=YES --errors-provider=…. Ask for another tracker and it asks again.
2. Status — one line: tracker, project, address, whether the uptime is watched. With a credential missing, the skill says which variable and where its value is created; with anything else missing, the hints are printed and the skill stops.
3. Download — errors-list --new --kind=error --report. The bugs nobody decided about are shown in a table, the ones thrown the most first, 15 rows at most; the detail of all of them goes to .larapilot/docs/support/errors.md (dashboard route /larapilot/errors/errors.md; boogle.md is kept as an alias). A bug that came back after its fix is said first.
4. Scope — one question: the three thrown the most and the ones that came back, every one, the ones you name, or none.
5. Confirm — bug by bug (or in batches when there are many): resolve, ignore with a reason, or skip for now. Ignores are recorded immediately with errors-link.
6. Plan — errors-plan --codes=… groups the confirmed codes by domain (application, package, outage) and by place in the code: the same exception thrown in the same folder is one group, so one spec fixes it. You approve the groups. Outages and errors in a package never merge with application code, and a bug the tracker gives no file for stays alone.
7. Read the code first — every where in the group is opened in the repository before the handoff. When it is in a package, the call of the application that leads there is found.
8. Hand off to triage — each group goes to /larapilot-triage in the same turn, with the block below. /larapilot-bug then writes the fix spec, with a test that throws the same exception before the fix.
9. Record — errors-link BUG12,BUG15 --spec=US-012, with every code of the group. A decision is about the bug, so one code for each bug is enough, however many times it was thrown.
10. Close in the tracker — only when the fix is released and you say so: errors-resolve BUG12, where the tracker can be closed from Larapilot.

Production error
codes: #BUG12, #BUG15
class: Illuminate\Database\QueryException
message: SQLSTATE[23000]: Integrity constraint violation
where: app/Services/CustomerImporter.php:88, app/Services/CustomerImporter.php:102
request: POST /admin/customers/import
thrown: 14 times
returned: false

What a bug can be

A decision is kept under what the occurrences of a bug share — the exception, the file, the line — and not under a code. The next time the bug is thrown, under a code nobody has seen, it is known and not handed over again.

Commands

errors-status, errors-list, and errors-plan are allowed through the MCP RunArtisanTool; the two that write — errors-link to the ledger, errors-resolve to the tracker — are not. The names the commands had when Boogle was the only tracker still answer: boogle-status, boogle-errors, boogle-plan, boogle-link, boogle-resolve.

On the dashboard

/larapilot/errors is always under Insights. With the setting off it says what Boogle is and how to connect it, and lists under it the other trackers that can be read instead. With the setting on it names the tracker it read and opens on what is open, in a sentence — 5 open errors, thrown 33 times: 2 with no decision yet. 1 came back after its fix — then four figures. For a tracker that records every throw — Boogle, CloudWatch, the logs of Datadog — the errors are then drawn day by day over the last two weeks, with the same numbers as a table. Every bug is a row: how many times it was thrown, the exception and what it said, its codes in the tracker, the file and the line, how long ago it last happened, and the decision. A row opens on the whole message, the route, the first and the last time, and what to do next. Bugs filter by decision and by text. What was read is kept for five minutes (LARAPILOT_ERRORS_CACHE); Read again asks the tracker anew, and Download report (.md) saves the same document the skill writes, named after the tracker and the day. When the tracker cannot be read the page says what to check, and the rest of the dashboard is untouched.

What is kept, and where

SBOM, CVE & Checkpoint

Two local views of security next to Aikido: the SBOM of every package the project ships, checked against OSV.dev for known vulnerabilities, and the last scan of Checkpoint.

The SBOM

larapilot:sbom reads the lockfiles — composer.lock, the JavaScript lockfile of the repository (npm, pnpm, Yarn, Bun), and the frontend companion's, its own or the workspace's in a monorepo — and lists each package with its version, direct or transitive, production or development, license, and package URL. Nothing is installed or downloaded. --write=both saves sbom.md and sbom.cdx.json (CycloneDX 1.5) under paths.security.

fernway.test/larapilot/sbom

Known vulnerabilities

php artisan larapilot:vendor-audit --report --gate
php artisan larapilot:vendor-link GHSA-xxxx-xxxx-xxxx --spec=US-012
php artisan larapilot:vendor-link GHSA-xxxx-xxxx-xxxx --waive --reason="Never fed user input."

• Only the name and the version of each package leave the machine. No account, no key.
• Severity is the advisory's word, else its CVSS 3 score. Each vulnerable package comes with the version that fixes all its advisories and the command that moves to it — an update when its constraint already allows the fix.
• --gate exits 1 on an open advisory at --fail-on (default high) or above; /larapilot-ship runs it. A waived advisory does not count; one in the backlog does until the update lands. Decisions and the trend live in .larapilot/vendor-audit.yaml: commit it.
• /larapilot-vendor-check runs it with you, package by package.

Checkpoint on the dashboard

Security has two tabs: Aikido and Checkpoint. The second shows the last scan — verdict, checks by area (dependencies, configuration, code), each finding with its suppression hash, the trend — with Run the scan and a Markdown report. php artisan larapilot:checkpoint-scan runs checkpoint:scan --json (--only=, --skip=, --report, --gate) and keeps the result in .larapilot/cache/checkpoint/, out of git, because the details can quote code. With security_scan=YES, review and ship run it and stop on a failed check.

External frontend repo

Laravel is the only Larapilot cockpit. When topology is API + external frontend, the UI lives in another repository — one app, or a monorepo shared with other products — in Angular, React / Next.js, Vue / Nuxt, or Svelte / SvelteKit. Larapilot finds the projects that are this product's, reads the rules the frontend team wrote for agents, measures how its code is written, and implements UI there via repo: frontend tasks — or hands the work to that team. The FE repo holds application code only — no mirrored PRD.

Topology choices

PRD fields

**Frontend Topology:** API + external frontend
**Frontend stack (in-repo):** N/A
**External frontend repo:** acme/frontend (path in LARAPILOT_FRONTEND_REPO_PATH — never here)
**External frontend stack:** Angular
**Frontend projects:** portal, portal-admin
**Frontend delivery:** driven

Where the settings are stored

The absolute FE directory is stored in LARAPILOT_FRONTEND_REPO_PATH inside .env — never in config.yaml, whatever else frontend-set changes (a path an older version left in the YAML moves to .env). The stack, the target projects, and the mode (driven or handoff) live in config.yaml → frontend. The context envelope carries them as data.frontend.

What the scan reads

An app in its own repository, built inside a monorepo

Some teams keep each app in a repository of its own and build it inside the monorepo they share: the app holds a project.json and no nx.json, and its tsconfig extends the monorepo's. Cloned at its place inside the monorepo, the scan finds the monorepo among its parent folders; checked out somewhere else, larapilot:frontend-set --workspace=/absolute/path links it (LARAPILOT_FRONTEND_WORKSPACE_PATH in .env). Every path of the scan is then relative to root, the monorepo; commands run in run_in; commits go to the app's own repository (git_root), where the monorepo's affected cannot see them, so the scan leaves it out. Out of reach, run_in is null and the scan says where the app expects to sit. An Angular CLI app cloned inside a monorepo is a workspace of its own, but the agent rules of the monorepo around it still apply: they come under rules.inherited.

Checks that run, and commits that look like the team's

Karma runs headless — the launcher the karma config defines, or ChromeHeadless — with --watch=false. A target the installed CLI can no longer run is left out of the commands and named in unavailable: the TSLint builder left the Angular CLI in v13, Protractor in v19, and once the packages are installed their own builder catalog decides. A project with no spec file, or whose generators skip them, is a question for the user, recorded in the decision journal. The scan reads the commit history (git.commits): Conventional Commits or not, types, scopes, the language of the subjects, commitlint and hooks; a task's commit follows it with US-012 TASK-03 in the subject. Vendored packages — built third-party code copied into the repository — are listed under write_scope.vendored and never edited.

The frontend team's rules win on code

The editor loads the agent rules of the workspace it opened — the Laravel one — never those of the frontend repository. So implement reads every rule that governs the target projects before its first frontend edit, and asks frontend-rules --file=… before each task which rules govern the files it writes: a Cursor rule on *.component.ts, a Copilot rule on **/*.spec.ts, an AGENTS.md deep in a feature folder. Inside the frontend repository those rules decide structure, naming, state, tests, commits; Larapilot decides only the workflow. A deeper folder wins; two rules that disagree go to the user. Review checks the diff against the same rules.

Playbooks

For what the rules and the code leave open, one playbook per stack — Angular, React (Next.js, React Router, React Native), Vue (Nuxt), Svelte (SvelteKit) — says what each major version adds, so an Angular 15 workspace never receives Angular 20 code.

CLI commands (all from Laravel)

Delivery

• Laravel — PRD, backlog, plans, mockups, workflow. All /larapilot-* skills.
• Frontend repository — application code from larapilot-implement tasks with repo: frontend (and project: in a monorepo), committed with its hooks on and US-012 TASK-03 in the subject. task-done finds that commit in the frontend repository. No Larapilot workflow there.
• Handoff — in handoff mode implement runs the backend tasks and writes the brief; the frontend team builds in its own session, where its rules load by themselves, and names its commits.
• Mockups — always in Laravel .larapilot/mockups/; Joe implements them in the FE repository.

End-to-end

Walkthrough: External frontend repo example.

1. Inception → API + external frontend + absolute path → frontend-set
2. frontend-scan → in a monorepo, name the projects → frontend-set --project=…
3. /larapilot-spec → plan → implement (BE + FE tasks from Laravel, or the brief in handoff)

Design systems

Five packaged visual references ship in .larapilot/design-systems/ on larapilot:install and refresh on larapilot:update. /larapilot-design picks the folder that matches the PRD stack choice — Elise and Joe enforce token and component consistency through implement and review.

Open each folder's html/index.html locally as a visual catalog — or browse every project mockup in the dashboard Design gallery (/larapilot/design). Skills resolve paths via php artisan larapilot:config-show → paths.design_systems.

Sign-in screens: the fields are drawn, never built

A mockup is a picture of the screen, not a working form. Password managers (1Password, Bitwarden, iCloud Keychain, the browser's own) scan every <input> they find, and the Design gallery renders the same screen several times at once — the card, the viewer, the style comparison. One real sign-in field makes them pop up, fill in, and offer to save on every preview. So /larapilot-design follows one hard rule, and the five packaged systems ship a login.html that shows how:

• No <input>, <textarea>, or <form> for credentials — username, login email, password, confirm password, PIN, one-time code — on login, register, reset, two-factor, change-password, and create-user screens.
• No workaround counts. A masked type="text", autocomplete="off", data-1p-ignore, or a renamed label are all ignored by password managers, which guess from the layout.
• The field is drawn: a <div> styled like the input of the design system, holding sample text (jane@example.com, ••••••••••), with role="img" and an aria-label. Its label is a <span>.
• The button is a link to the next screen (<a role="button" href="dashboard.html">), so the flow stays clickable in the viewer. Error, empty, and focus states are separate screens.
• Every other control stays real: search, name, amount, select, the Remember me checkbox.

Filament and Starter Kit carry the classes in tokens.css — .mock-label, .mock-field, .mock-field--secret, .mock-field--empty. The real Fortify or Filament fields are built by Alex at implementation time.

Custom design systems & templates

You can add your own design system or UI template under .larapilot/design-systems/{your-name}/ and use it for mockups (/larapilot-design) and implementation — not only the five packaged references.

• Drop tokens, component notes, HTML starters, and brand assets in that folder (same shape as the packaged ones helps: README.md, tokens.css, components.md, optional html/).
• Record the choice in the PRD (or tell the agent during inception/design) so Elise, Joe, and Alex treat it as the source of truth for mockups and shipped UI.
• larapilot:update refreshes only the packaged systems — your custom folder is never overwritten.

Code quality

Every Larapilot project stays compatible with Larastan (PHPStan level 5+) and Laravel Pint. The gate is installed with the package and is not optional.

What install scaffolds

Run the gate

php artisan larapilot:quality

php artisan larapilot:quality --fix

Equivalent Composer shortcuts after composer install:

composer lint:check   # pint --test
composer analyse      # phpstan analyse --memory-limit=1G

When to run

• Implement — /larapilot-implement runs larapilot:quality on Laravel tasks before each task-done
• CI — add php artisan larapilot:quality (or composer lint:check && composer analyse) on every PR; failing Pint or Larastan blocks merge
• Health check — larapilot:doctor reports quality_pint, quality_larastan, and quality_packages; install is not healthy when the gate is missing

Rules

• Minimum level 5 — never lower level in phpstan.neon(.dist) without an explicit human waiver
• Legacy codebases — generate a baseline with vendor/bin/phpstan analyse --generate-baseline (see Larastan docs); do not drop below level 5 for new code
• larapilot:install --skip-composer — write config files only; run composer require --dev larastan/larastan laravel/pint yourself

Artisan CLI

Skills save everything through php artisan larapilot:* commands. You do not need to learn them: they are how the agent writes files, checks them, and moves a story from one status to the next. Run one by hand for debugging, scripting, or CI — for example php artisan larapilot:doctor --human to check the install.

JSON envelope

{ "schema": "larapilot/v1", "kind": "plan_result", "data": { "code": "US-001", "task_count": 4 } }

{ "schema": "larapilot/v1", "kind": "error",
  "error": { "code": "E_PRECONDITION", "message": "…", "hint": "…" } }

Skills never invent persistence — they always go through these commands and parse the envelope. Errors carry a stable code and a matching exit status:

Ask for the slice you need

Envelopes stay small on purpose, so an agent's context does not fill up with data it will not use:

php artisan larapilot:context implement                              # settings, paths, project facts, files to read
php artisan larapilot:context review --session=k3f9x2                 # same conversation: only what is new
php artisan larapilot:context plan --fresh                            # after a compaction: everything again
php artisan larapilot:spec-list                                       # the backlog without the bodies (--full for all)
php artisan larapilot:prd-show                                        # outline of the PRD: sections, ids, MoSCoW
php artisan larapilot:prd-show --ids=FR-004,J-001 --section="Technical Architecture"
php artisan larapilot:config-show --only=tracker                      # a slice context does not carry: tracker, backstage, workflow, personas
php artisan larapilot:spec-show US-004 --fields=id,title,status,dependencies
php artisan larapilot:spec-show US-004 --task=TASK-02                 # one task only
php artisan larapilot:spec-next --status=PLANNED --fields=id,title
php artisan larapilot:quality -v                                      # raw Pint/Larastan output inside the JSON
php artisan larapilot:doctor --human                                  # a table instead of JSON (also metrics --human)

Command reference