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.

Upgrade

Larapilot ships as a Composer package. Updating is two steps: pull the new version, then refresh the files Larapilot publishes into your project — without touching your workflow data in .larapilot/config.yaml, specs, plans, or PRD.

What each step does

Options & checks

• php artisan larapilot:update --skip-boost — refresh shared runtime and design-system copies only; run php artisan boost:update yourself when you want new skills/guidelines
• php artisan larapilot:doctor — verify install health after an upgrade (includes Larastan/Pint gate)
• 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"
    ]
}

Omit --skip-boost if you always want Boost guidelines and skills republished on every Composer update. Run php artisan boost:update manually when you use --skip-boost in the hook.

Skills

Fifteen editor-native skills cover the full product lifecycle — discovery, delivery, ship, settings, usage (Lucille), Backstage, trackers, and frontend companion. Each is a SKILL.md file with a name, description, persona roster, execution steps, and allowed CLI calls. Laravel Boost publishes them on php artisan boost:install; coding guidelines ship alongside (not a skill).

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

1. Loads the skill instructions and .larapilot/shared-runtime.md
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

Project settings

Persistent modes for effort, backlog granularity, Git, testing, auto-approve, Lucille, and optional GitHub / GitLab / Bitbucket + Slack / Discord / Telegram (forges and chat OFF by default). Configure with /larapilot-settings (AskQuestion). Values live under settings: in .larapilot/config.yaml. Every skill reads and honors them via config-show.

CLI: php artisan larapilot:settings-set --effort=… --backlog=… --git-mode=… --testing=… --auto-approve=… --lucille=… --github=… --gitlab=… --bitbucket=… --notifications=… --notify-slack=… persists one or more keys. php artisan larapilot:config-show returns data.settings (YES/NO for booleans; YAML stores booleans).

Defaults when unset: effort: STANDARD · backlog: STANDARD · git_mode: GITFLOW · testing: NORMAL · auto_approve: NO · lucille: YES · github|gitlab|bitbucket: NO · notifications: NO · notify_*: NO.

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.

Remote forges opt-in

settings.github, gitlab, and bitbucket (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

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.

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.

php artisan larapilot:settings-set \
  --effort=STANDARD \
  --backlog=STANDARD \
  --git-mode=GITFLOW \
  --testing=NORMAL \
  --auto-approve=NO \
  --lucille=YES \
  --github=NO \
  --gitlab=NO \
  --bitbucket=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); Mike, Sarah, and Lucille joined in v2.4.0.

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.

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.

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).

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.

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 mirrors charts, Gantt, and a 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

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

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 · download /larapilot/usage/report.md (dev/staging only). MCP RunArtisanTool allows larapilot:usage-report.

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

Settings tables: Remote forges · Notifications.

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. Skills resolve paths via php artisan larapilot:config-show → paths.design_systems.

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.

External frontend repo

Laravel is the only Larapilot cockpit. When topology is API + external frontend, the SPA lives in another folder on disk. Larapilot links that path and implements UI there via repo: frontend tasks. 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:** /Users/dev/acme-web
**External frontend stack:** React

Three CLI commands (all from Laravel)

Delivery

• Laravel — PRD, backlog, plans, mockups, workflow. All /larapilot-* skills.
• Frontend folder — application code from larapilot-implement tasks with repo: frontend. No Larapilot workflow here.
• Mockups — always in Laravel .larapilot/mockups/; Joe implements in the FE folder.

End-to-end

Walkthrough: External frontend repo example.

1. Inception → API + external frontend + absolute path → frontend-set
2. frontend-scan when the FE already has code
3. /larapilot-spec → plan → implement (BE + FE tasks from Laravel)

Code quality

Every Larapilot project stays compatible with Larastan (PHPStan level 5+) and Laravel Pint. Introduced in v2.3.1 — not optional after install.

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

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/

Artisan CLI

Optional and under the hood. Skills call these commands — you do not need to memorize them. They persist artifacts, validate YAML/Markdown, enforce workflow guards, and return structured JSON for the agent to parse.

JSON envelope

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

Errors return "kind": "error" with code, message, and optional hint. Skills never invent persistence — they always go through these commands.

Command reference

MCP exposes backlog, spec, and diagnostics tools — larapilot server alongside laravel-boost. Skills prefer CLI for writes; MCP is for read/query during conversation (including larapilot:diagnostics, larapilot:quality, larapilot:usage-report, and larapilot:backstage-export via RunArtisanTool).

Dashboard

Read-only web UI over the artifacts in .larapilot/. Review backlog progress, read the PRD, inspect settings/choices, and Lucille usage — then drill into spec detail between skill sessions. You can also post internal feedback comments from the spec page (dev/staging only) — workflow state still changes only via skills/CLI.

Activation

The dashboard is on by default after php artisan larapilot:install. Routes register automatically when the package boots. All of the following must be true:

• LARAPILOT_ENABLED=true (default) — master switch in config/larapilot.php
• LARAPILOT_DASHBOARD_ROUTE=true (default) — dashboard route toggle
• App environment is not production
• Environment is in the allowlist: local, development, testing, or staging

Start your Laravel app (php artisan serve, Sail, Herd, etc.) and open /larapilot. If routes 404, check APP_ENV and the flags above.

'dashboard_route' => [
    'enabled' => env('LARAPILOT_DASHBOARD_ROUTE', true),
    'prefix' => 'larapilot',           // change to customize URL prefix
    'middleware' => ['web'],
    'environments' => ['local', 'development', 'testing', 'staging'],
],

Pages

Board

Summary metrics at the top: total specs, done count, completion rate, and WIP. Each workflow column lists spec cards — code, title, epic, story points, priority, subtask progress bar, mockup indicator when HTML exists, pill badges for comment and blocking counts when feedback exists, and merge-request link when the story is DONE.

PRD

The living product document from /larapilot-inception (and later /larapilot-feature or /larapilot-bug updates). Headings become anchor links in the sidebar; the body is rendered Markdown — the same file skills write to .larapilot/docs/PRD.md.

Settings & Usage

Settings shows the live project modes (effort, backlog, git, testing, auto-approve, lucille, forges, notifications) and the inception choices snapshot. Usage is Lucille's surface — category breakdowns, schedule Gantt, and a one-click Markdown resoconto. Same data as larapilot:usage-report --insights / /larapilot-usage.

Spec detail

Click any card to open /larapilot/specs/{code}:

• User story — acceptance criteria and narrative from the spec YAML
• Mockups — when /larapilot-design created HTML in .larapilot/mockups/{code}/, an embedded preview and screen links appear (served via /mockups/{code} in dev/staging)
• Internal feedback — accordion list of PM/dev comments (author, date, status, preview); blocking items show a Needs rework badge. Post new comments with a Markdown toolbar and compact footer (blocking checkbox, log path) until the story is DONE. Toggle globally with LARAPILOT_COMMENTS_ENABLED.
• Technical plan — plan Markdown once /larapilot-plan has run
• Tasks — expandable subtasks with status, type, body, and commit SHA when marked done

Status badge, story points, and merge commit appear in the header. The dashboard mirrors repo state — skills remain the only way to change it.

API

JSON API over the same artifacts as the dashboard. Read endpoints for scripts, CI dashboards, external frontend repo setup, bug-triage diagnostics, or tooling; POST /specs/{code}/comments appends internal feedback when enabled. Workflow state still changes only via skills/CLI.

Activation

API routes share the dashboard gate: enabled when dashboard activation conditions are met. Base path: /{prefix}/api (default /larapilot/api). Returns 404 in production or when disabled.

Authentication

Set LARAPILOT_API_TOKEN to require a shared token on every API request — send it as Authorization: Bearer <token> or an X-Larapilot-Token header. Strongly recommended on shared staging hosts. Without a token configured, read endpoints stay open in the allowed environments, but write endpoints (POST /comments) are refused outside local/development/testing.

Endpoints

Diagnostics

Read-only app status for /larapilot-bug and local debugging. Same dashboard gate as the rest of the API (never in production). Disable with LARAPILOT_DIAGNOSTICS_ENABLED=false (returns 404).

Checks: storage_writable, cache, database, queue, log_file. healthy is true when critical checks (storage + database) pass. Log lines redact secrets ([REDACTED]). Defaults: LARAPILOT_DIAGNOSTICS_LOG_LINES=100, LARAPILOT_DIAGNOSTICS_MAX_LOG_LINES=500.

{
  "collected_at": "2026-07-24T16:00:00+00:00",
  "app": {
    "name": "My App",
    "env": "local",
    "debug": true,
    "laravel_version": "13.x",
    "php_version": "8.4.0"
  },
  "checks": {
    "storage_writable": { "ok": true, "detail": "…" },
    "cache": { "ok": true, "detail": "…" },
    "database": { "ok": true, "detail": "…" },
    "queue": { "ok": true, "detail": "…" },
    "log_file": { "ok": true, "detail": "…" }
  },
  "healthy": true
}

Response shape

Plain JSON — not the larapilot/v1 CLI envelope. Example from /larapilot/api/board:

{
  "metrics": { "total": 3, "done": 1, "completion_rate": 33.3, "wip": 1 },
  "status_order": ["TODO", "PLANNED", "IN PROGRESS", "REVIEW", "DONE"],
  "columns": {
    "TODO": [{
      "code": "US-002",
      "title": "Project Management",
      "task_progress": { "total": 0, "done": 0 },
      "mockups": { "available": false, "screen_count": 0, "screens": [] },
      "feedback": { "enabled": true, "available": false, "entry_count": 0, "blocking_count": 0, "writable": true, "entries": [] }
    }],
    "DONE": [{
      "code": "US-001",
      "title": "User Registration",
      "task_progress": { "total": 4, "done": 4 },
      "mockups": {
        "available": true,
        "screen_count": 2,
        "entry_url": "https://app.test/mockups/US-001",
        "screens": [
          { "file": "index.html", "label": "Index", "url": "https://app.test/mockups/US-001" },
          { "file": "desktop.html", "label": "Desktop", "url": "https://app.test/mockups/US-001/desktop.html" }
        ]
      },
      "feedback": {
        "enabled": true,
        "entry_count": 1,
        "blocking_count": 0,
        "writable": true,
        "entries": [
          { "at": "2026-07-15 17:00", "author": "PM", "status": "REVIEW", "body": "Looks good.", "blocks_merge": false }
        ]
      }
    }]
  },
  "workflow": { "todo": "TODO", "planned": "PLANNED", "in_progress": "IN PROGRESS", "review": "REVIEW", "done": "DONE" }
}

No authentication is built in — the API is intended for local/dev use behind your existing app middleware. Do not expose it in production (routes are not registered there). Mockup preview URLs are absolute in API responses when the mockup route is browsable. Comment writes honor LARAPILOT_COMMENTS_ENABLED and reject DONE specs with 422. Diagnostics honor LARAPILOT_DIAGNOSTICS_ENABLED and redact secrets in log tails.