LeanSpec Development Skill

Unified guide for all LeanSpec development: coding, commands, publishing, CI/CD, and runner research.

Quick Navigation

Goal Reference

Mandatory rules & conventions RULES.md

Changelog format & workflow Changelog (below)

i18n file locations & patterns I18N.md

Monorepo structure & packages STRUCTURE.md

Full release checklist PUBLISHING.md

npm distribution architecture NPM-DISTRIBUTION.md

Dev publishing workflow DEV-PUBLISHING.md

CI workflow details CI-WORKFLOWS.md

gh CLI command reference CI-COMMANDS.md

CI troubleshooting CI-TROUBLESHOOTING.md

Runner ecosystem catalog runners-catalog.md

Core Principles

• Use pnpm — Never npm or yarn

• DRY — Extract shared logic, avoid duplication

• Test What Matters — Business logic and data integrity, not presentation

• Leverage Turborepo — Smart caching (19s → 126ms builds)

• i18n is MANDATORY — Every user-facing string needs both en AND zh-CN (see I18N.md)

• Follow Rust Quality — All code must pass cargo clippy -- -D warnings

Commands

Daily Development

pnpm install # Install dependencies pnpm dev # Start web UI + Rust HTTP server pnpm dev:watch # Same + auto-rebuild Rust on changes pnpm dev:web # Start web UI only pnpm dev:desktop # Start desktop app pnpm build # Build all TS packages pnpm build:rust # Build Rust (debug) pnpm build:rust:release # Build Rust (release) pnpm typecheck # ← NEVER SKIP before marking work complete pnpm test # Run all tests pnpm test:watch # Watch mode pnpm test:coverage # With coverage pnpm test:rust # Rust tests only pnpm format # Format all code pnpm cli # Run LeanSpec CLI

Validation

pnpm pre-push # Quick: typecheck + clippy pnpm pre-release # Full: build + typecheck + test + lint

⚠️ Always run pnpm typecheck before marking work complete.

Rust

pnpm build:rust # Debug build pnpm build:rust:release # Release build pnpm check:rust # Quick check without building pnpm lint:rust # Clippy with warnings as errors pnpm format:rust # Format Rust code pnpm format:rust:check # Check Rust formatting

Low-level

cargo build --manifest-path rust/Cargo.toml node scripts/copy-rust-binaries.mjs --debug

Documentation

pnpm docs:dev # Start docs dev server pnpm docs:build # Build docs site

Desktop

pnpm dev:desktop # Start desktop app in dev mode cd packages/desktop pnpm bundle:linux # Debian package pnpm bundle:macos # DMG pnpm bundle:windows # NSIS installer

Critical Rules

Rules enforced by hooks or CI:

• Light/Dark Theme — ALL UI must support both themes

• i18n — Update BOTH en and zh-CN → I18N.md ⚠️ commonly forgotten

• Regression Tests — Bug fixes MUST include failing-then-passing tests

• Rust Quality — Must pass cargo clippy -- -D warnings

• Rust Params Structs — Functions with >7 args must use a params struct (enforced by clippy.toml )

• Use shadcn/ui — No native HTML form elements

• cursor-pointer — All clickable items must use cursor-pointer

See RULES.md for complete requirements.

Publishing & Releases

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)

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

Development Release

Publish dev version via GitHub Actions

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

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

Version Management

• Root package.json is the single source of truth for versions

• 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 optional dependencies for platform-specific Rust binaries:

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

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

See PUBLISHING.md and NPM-DISTRIBUTION.md for details.

Changelog

Update CHANGELOG.md following Keep a Changelog format and Semantic Versioning.

Discovering Changes

Commits since last tag

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Files changed since last release

git diff $(git describe --tags --abbrev=0)..HEAD --stat

Entry Format

Only include shipped/implemented changes — not planned specs, drafts, or WIP.

Add under ## [Unreleased] using these categories: Added, Changed, Fixed, Deprecated, Removed, Security, Technical.

• Feature Name (spec 123) - Brief description
  • Sub-bullet with implementation details

Writing Style

• Bold feature name followed by description

• Link related specs when applicable

• Present tense — "Adds support for..." not "Added"

• Be specific — include command names, flag names, component names

• Group related changes under single bullet with sub-bullets

• Include breaking changes with Breaking: prefix

Creating a Release

• Move entries from [Unreleased] to new version: ## [X.Y.Z] - YYYY-MM-DD

• Add release link at bottom: [X.Y.Z]: https://github.com/codervisor/lean-spec/releases/tag/vX.Y.Z

CI/CD (GitHub Actions)

All workflow interactions use the gh CLI. Check status before triggering new runs; minimum 30s between polls.

Available Workflows

Workflow File Triggers Purpose

CI ci.yml

push, PR to main Build, test, lint (Node.js + Rust)

Publish publish.yml

release, manual Publish to npm (all platforms)

Desktop Build desktop-build.yml

push, PR, manual Build Tauri desktop apps

Copilot Setup copilot-setup-steps.yml

push, PR, manual Setup environment for Copilot agent

Quick Reference

Check status

gh run list --limit 10 gh run list --workflow ci.yml --limit 5 gh run view <run-id> gh run watch <run-id>

Trigger

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

Debug failures

gh run view <run-id> --log-failed gh run rerun <run-id> --failed

Artifacts

gh run download <run-id> gh run download <run-id> --name ui-dist

See CI-WORKFLOWS.md, CI-COMMANDS.md, and CI-TROUBLESHOOTING.md for details.

Runner Research

Research AI agent runners to keep LeanSpec's runner registry current as the ecosystem evolves.

Workflow

• Read current state: rust/leanspec-core/src/sessions/runner.rs (RunnerRegistry::builtins() )

• Read catalog: runners-catalog.md

• Research via web_search : Config format changes, CLI changes, new env vars, new capabilities, deprecations, new runners

• Compare & identify gaps: Cross-reference findings against registry

• Report: Minor updates → update catalog directly; major changes → create a spec

Runner Tiers

• Tier 1 (high priority): Claude Code, Copilot, Cursor, Windsurf, Codex, Gemini

• Tier 2 (medium): Kiro, Amp, Aider, Goose, Continue, Roo Code

• Tier 3 (monitor): Droid, Kimi, Qodo, Trae, Qwen Code, OpenHands, Crush, CodeBuddy, Kilo, Augment

Key Source Files

File Purpose

rust/leanspec-core/src/sessions/runner.rs

Runner registry with detection config

schemas/runners.json

JSON schema for custom runner config

packages/cli/templates/_shared/agents-components/

AGENTS.md template components