LeanSpec Publishing Skill

Teach agents how to publish and release LeanSpec packages to npm.

Core Principles

• Root as Source of Truth: All versions come from root package.json

• Platform Packages First: Platform binaries must be published before main packages

• Automated Sync: Use scripts, don't manually edit package.json files

• Test Before Release: Always run pnpm pre-release before publishing

• Dev Tags for Testing: Use -dev tags for testing across platforms

Release Workflow

Production Release (Recommended)

1. Update version (root only)

npm version patch # or minor/major

2. Sync all packages

pnpm sync-versions

3. Validate everything

pnpm pre-release

4. Commit and push with tags

git add . git commit -m "chore: release vX.X.X" git push --follow-tags

5. Create GitHub Release (triggers publish workflow automatically)

gh release create vX.X.X --title "vX.X.X" --notes "Release notes here"

Development Release

Publish dev version via GitHub Actions (all platforms)

gh workflow run publish.yml --field dev=true

Dry run (validates without publishing)

gh workflow run publish.yml --field dev=true --field dry_run=true

Install and test dev version

npm install -g lean-spec@dev lean-spec --version

Version Management

• Root package.json is the single source of truth

• pnpm sync-versions propagates to all packages (including Rust crates)

• CI automatically validates version alignment

• Never manually edit package versions — use npm version

• pnpm sync-versions

Distribution Architecture

LeanSpec uses the optional dependencies pattern for Rust binaries:

Main Package (lean-spec) ├── bin/lean-spec.js (wrapper) └── optionalDependencies: ├── @leanspec/cli-darwin-arm64 ├── @leanspec/cli-darwin-x64 ├── @leanspec/cli-linux-x64 └── @leanspec/cli-windows-x64

⚠️ Platform packages MUST be published before main packages. The workflow handles this automatically.

Package Structure

Type Packages

Main (published) lean-spec , @leanspec/mcp , @leanspec/ui

Platform (published) @leanspec/cli-{platform} , @leanspec/mcp-{platform} (5 platforms each)

Internal (not published) @leanspec/desktop , @leanspec/ui-components

Troubleshooting

Binary not found: npm view @leanspec/cli-darwin-arm64 versions to check, pnpm rust:build to rebuild.

Version mismatch: pnpm sync-versions --dry-run to check, pnpm sync-versions to fix.

Permission issues: chmod +x /path/to/binary (usually auto-fixed by postinstall).

Detailed References

• references/NPM-DISTRIBUTION.md - Architecture details

• references/DEV-PUBLISHING.md - Development workflow

• references/PUBLISHING.md - Full release checklist

• For CI/CD workflow details, use skill: github-actions

• For all scripts, use skill: leanspec-scripts