lean-dist

name	lean-dist
description	Use when prepping package release, `.gitattributes` missing/thin, or keeping `composer archive` / Packagist `--prefer-dist` tarballs lean. Activates: lean dist, gitattributes, export-ignore, dist size, packagist tarball, composer archive bloat, lean-package-validator, stolt lpv, AI files in dist, .ai shipping to dist, .claude in tarball, CLAUDE.md in tarball, AGENTS.md in tarball.

Lean Dist

.gitattributes export-ignore controls what lands in composer require --prefer-dist tarballs and GitHub release archives. Dev-only paths and AI-tooling artifacts have no business in a consumer's vendor/ tree — they bloat installs and occasionally leak working-copy context.

This skill is the on-ramp to stolt/lean-package-validator (lpv). Once installed, lpv's three shipped skills (creating-gitattributes-file, updating-gitattributes-file, validating-gitattributes-file) take over the per-command work. This skill covers only what those don't: install caveats, AI-era gaps, commit-ordering, and OSS-norm review.

When to activate

• Cutting a release and composer archive HEAD shows files that shouldn't ship.
• A .gitattributes is missing, or hasn't been touched since the repo grew an .ai/ / .claude/ / AGENTS.md / CLAUDE.md.
• Auditing a package after switching to AI-assisted development.

Step 1 — Install lpv

composer require --dev stolt/lean-package-validator

Pin ^5.7.1 if your composer cache resolves to v5.7.0 — that release had a Symfony 8 / Laravel 13 install break, fixed in 5.7.1. composer clear-cache && composer require --dev stolt/lean-package-validator forces fresh Packagist metadata.

After install, boost sync discovers lpv's resources/boost/skills/ directory automatically (vendor-skill discovery, 0.9.0+). The three lpv skills surface in every selected agent's skill dir on the next sync — hand off all command-level work to them.

Step 2 — Audit, then create or update

Run lpv's audit:

vendor/bin/lean-package-validator validate

Then hand off:

• No .gitattributes → lpv's creating-gitattributes-file skill.
• Drift on existing file → lpv's updating-gitattributes-file skill. Always validate --diff before any overwrite.

lpv's preset is opinionated. v5.7.0 ignores LICENSE.md, README.md, CHANGELOG.md, and SECURITY.md by default — most OSS maintainers want those in the dist. Review the generated file before committing; remove lines you disagree with.

Step 3 — Add AI-era export-ignore lines

lpv's preset (v5.7.1) already covers .ai/, .claude/, .cursor/, .junie/, .agents/, and .kiro/. The gaps it does not know about:

AGENTS.md           export-ignore
CLAUDE.md           export-ignore
GEMINI.md           export-ignore
.cache/             export-ignore
.cursorrules        export-ignore
.windsurfrules      export-ignore

Append directly to .gitattributes — do not use a .lpv file, which overrides rather than extends lpv's preset.

Verify against your installed lpv version before relying on this list. lpv's preset evolves: v5.6.1 picked up .ai/ and .claude/; v5.7.1 added .cursor/, .junie/, .agents/, .kiro/. Run lean-package-validator validate after create and trust the expected_gitattributes_content diff over this list — preset growth means today's gap may be tomorrow's default.

Re-running lpv update after this step may strip these manual lines. update regenerates from preset. Treat the appended block as the source of truth: commit .gitattributes and use validate (read-only) in CI rather than re-running update.

Step 4 — Commit, then validate the archive

Critical ordering: git archive reads .gitattributes from HEAD, not the working tree. An uncommitted .gitattributes is invisible to the archive — validate --validate-git-archive will report every preset entry as unexpected_artifacts until you commit.

git add .gitattributes
git commit -m "Add lean .gitattributes"
vendor/bin/lean-package-validator validate --validate-git-archive

Exit 1 on bloat, exit 0 on lean. Output lists each leaked path under unexpected_artifacts, so the failure is actionable.

Step 5 — CI

Hand off to lpv's validating-gitattributes-file skill for the composer-script and GitHub Action snippets. The gate command is lean-package-validator validate --validate-git-archive — exit 1 on bloat, exit 0 on lean.

Output format note

lpv v5.6.1+ auto-detects agentic invocation and emits JSON instead of text when triggered through a Claude Code skill. Shape: { "command", "status", "message", ... } with category-specific fields like unexpected_artifacts (array). Parse the JSON when chaining steps; don't assume the human-readable format.

Edge cases

• Testing-helper packages — */testing, orchestra-style harnesses, and Pest plugins legitimately ship tests/ so consumers can extend the base test case. lpv's preset wants tests/ ignored; remove that line from the generated .gitattributes before committing, then re-validate.
• Monorepos — run lpv per leaf package, not at repo root. Each package has its own composer.json and its own dist; root .gitattributes doesn't propagate into split tags.
• Hand-rolled .gitattributes — validate --diff first. Never blanket-update a curated file.