OpenParable
Skip to content
← Back to skills

Lerd Add Framework

Development
lerd-add-framework

Lerd Add Framework is an Agent Skill for development published in the lerd-env/lerd repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add or extend a lerd framework definition (a new PHP framework or a new major version) as versioned YAML in the lerd-frameworks store. Use whenever the task involves framework detection, per-framework workers, env wiring, doctor checks, custom commands, or scaffolding — never branch on a framework name in Go.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/lerd-env/lerd/blob/HEAD/.claude/skills/lerd-add-framework/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/lerd-add-framework, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Add a lerd framework definition

Frameworks are submitted to the lerd-env/frameworks repo (https://github.com/lerd-env/frameworks) as frameworks/<name>/<version>.yaml, one file per major version. lerd is framework-agnostic: no Go code knows a framework's name. Everything a framework needs is declared here as data and ships to every install within ~24h with no binary release.

The lerd-frameworks/ directory in the lerd repo is a local checkout you can edit and test against, but the pull request goes to lerd-env/frameworks.

Procedure

  1. Copy the closest existing definition. laravel/12.yaml is the most complete reference (workers, env services, doctor, commands, tinker). For a new major version of an existing framework, copy the previous version file and adjust. The existing YAML is the schema of record — do not invent fields.

  2. Fill the sections that apply (all keyed by real examples in the store):

    • name, version, label, public_dir, create (scaffold command)
    • php.min / php.max — the versions the framework supports
    • detect — marker file, lockfile, or composer: package that identifies it, including the major version
    • env — .env file/format, key_generation, and the services map that wires each service (mysql, postgres, redis, mailpit, …) with detection rules and the vars to inject. Env vars belong to the site, declared here — never on workers.
    • workers — queue, schedule, and any framework-specific long-runners. Each has command, restart, optional check/exclude_check (composer package or file gating), conflicts_with, proxy, per_worktree, host. New workers go here, not in Go.
    • setup — post-link steps (migrate, storage:link…) with sensible default:
    • doctor.checks — declarative health checks (env_combo, symlink, command) with a fix: command and a human detail: string
    • commands — dashboard/TUI custom commands with icon and confirm where destructive
    • tinker, logs, console, composer, npm
  3. Update frameworks/index.json if the store requires it (check how the existing entries are registered), and the README table in the lerd-env/frameworks README.md.

  4. Validate end-to-end against a real project:

    lerd link           # in a project of that framework — detection must fire
    lerd site:doctor    # the declared checks must run
    

    Confirm detection, PHP pinning, .env wiring, workers, and doctor all behave.

Rules

  • The PR goes to lerd-env/frameworks, not the lerd binary repo.
  • Data only. If you're tempted to write Go that branches on the framework name, the logic belongs in this YAML instead.
  • Version the file by major version; keep detection specific enough to pick the right one.