LeanSpec Development Skill
Unified guide for all LeanSpec development: coding, commands, publishing, CI/CD, and runner research.
Quick Navigation
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](https://web.lean-spec.dev/specs/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 |
1---2name: leanspec-development3description: Development workflows, commands, publishing, CI/CD, changelog management, and contribution guidelines for LeanSpec. Use when contributing code, fixing bugs, setting up dev environment, running tests or linting, working with the monorepo structure, looking up build/dev/test/publish/format/lint commands, preparing releases, publishing to npm, bumping versions, syncing package versions, testing dev builds, troubleshooting npm distribution, updating changelogs, triggering CI/CD workflows, monitoring build status, debugging failed runs, managing artifacts, checking CI before releases, or researching AI agent runners. Triggers include any development, scripting, publishing, CI/CD, changelog, or runner research task in this project.4metadata:5 source: https://skillmd.com/skills/codervisor/leanspec-development6 internal: true7---89# LeanSpec Development Skill1011Unified guide for all LeanSpec development: coding, commands, publishing, CI/CD, and runner research.1213## Quick Navigation1415| Goal | Reference |16|------|-----------|17| **Mandatory rules & conventions** | [RULES.md](./references/RULES.md) |18| **Changelog format & workflow** | [Changelog](#changelog) (below) |19| **i18n file locations & patterns** | [I18N.md](./references/I18N.md) |20| **Monorepo structure & packages** | [STRUCTURE.md](./references/STRUCTURE.md) |21| **Full release checklist** | [PUBLISHING.md](./references/PUBLISHING.md) |22| **npm distribution architecture** | [NPM-DISTRIBUTION.md](./references/NPM-DISTRIBUTION.md) |23| **Dev publishing workflow** | [DEV-PUBLISHING.md](./references/DEV-PUBLISHING.md) |24| **CI workflow details** | [CI-WORKFLOWS.md](./references/CI-WORKFLOWS.md) |25| **gh CLI command reference** | [CI-COMMANDS.md](./references/CI-COMMANDS.md) |26| **CI troubleshooting** | [CI-TROUBLESHOOTING.md](./references/CI-TROUBLESHOOTING.md) |27| **Runner ecosystem catalog** | [runners-catalog.md](./references/runners-catalog.md) |2829## Core Principles30311. **Use pnpm** — Never npm or yarn322. **DRY** — Extract shared logic, avoid duplication333. **Test What Matters** — Business logic and data integrity, not presentation344. **Leverage Turborepo** — Smart caching (19s → 126ms builds)355. **i18n is MANDATORY** — Every user-facing string needs both en AND zh-CN (see [I18N.md](./references/I18N.md))366. **Follow Rust Quality** — All code must pass `cargo clippy -- -D warnings`3738---3940## Commands4142### Daily Development4344```bash45pnpm install # Install dependencies46pnpm dev # Start web UI + Rust HTTP server47pnpm dev:watch # Same + auto-rebuild Rust on changes48pnpm dev:web # Start web UI only49pnpm dev:desktop # Start desktop app50pnpm build # Build all TS packages51pnpm build:rust # Build Rust (debug)52pnpm build:rust:release # Build Rust (release)53pnpm typecheck # ← NEVER SKIP before marking work complete54pnpm test # Run all tests55pnpm test:watch # Watch mode56pnpm test:coverage # With coverage57pnpm test:rust # Rust tests only58pnpm format # Format all code59pnpm cli # Run LeanSpec CLI60```6162### Validation6364```bash65pnpm pre-push # Quick: typecheck + clippy66pnpm pre-release # Full: build + typecheck + test + lint67```6869**⚠️ Always run `pnpm typecheck` before marking work complete.**7071### Rust7273```bash74pnpm build:rust # Debug build75pnpm build:rust:release # Release build76pnpm check:rust # Quick check without building77pnpm lint:rust # Clippy with warnings as errors78pnpm format:rust # Format Rust code79pnpm format:rust:check # Check Rust formatting8081# Low-level82cargo build --manifest-path rust/Cargo.toml83node scripts/copy-rust-binaries.mjs --debug84```8586### Documentation8788```bash89pnpm docs:dev # Start docs dev server90pnpm docs:build # Build docs site91```9293### Desktop9495```bash96pnpm dev:desktop # Start desktop app in dev mode97cd packages/desktop98pnpm bundle:linux # Debian package99pnpm bundle:macos # DMG100pnpm bundle:windows # NSIS installer101```102103---104105## Critical Rules106107Rules enforced by hooks or CI:1081091. **Light/Dark Theme** — ALL UI must support both themes1102. **i18n** — Update BOTH en and zh-CN → [I18N.md](./references/I18N.md) ⚠️ commonly forgotten1113. **Regression Tests** — Bug fixes MUST include failing-then-passing tests1124. **Rust Quality** — Must pass `cargo clippy -- -D warnings`1135. **Rust Params Structs** — Functions with >7 args must use a params struct (enforced by `clippy.toml`)1146. **Use shadcn/ui** — No native HTML form elements1157. **cursor-pointer** — All clickable items must use `cursor-pointer`116117**See [RULES.md](./references/RULES.md) for complete requirements.**118119---120121## Publishing & Releases122123### Production Release (Recommended)124125```bash126# 1. Update version (root only)127npm version patch # or minor/major128129# 2. Sync all packages130pnpm sync-versions131132# 3. Validate everything133pnpm pre-release134135# 4. Commit and push with tags136git add .137git commit -m "chore: release vX.X.X"138git push --follow-tags139140# 5. Create GitHub Release (triggers publish workflow)141gh release create vX.X.X --title "vX.X.X" --notes "Release notes here"142```143144### Development Release145146```bash147# Publish dev version via GitHub Actions148gh workflow run publish.yml --field dev=true149150# Dry run (validates without publishing)151gh workflow run publish.yml --field dev=true --field dry_run=true152153# Install and test154npm install -g lean-spec@dev155lean-spec --version156```157158### Version Management159160- Root `package.json` is the single source of truth for versions161- `pnpm sync-versions` propagates to all packages (including Rust crates)162- CI automatically validates version alignment163- **Never manually edit package versions** — use `npm version` + `pnpm sync-versions`164165### Distribution Architecture166167LeanSpec uses optional dependencies for platform-specific Rust binaries:168169| Type | Packages |170|------|----------|171| **Main** (published) | `lean-spec`, `@leanspec/mcp`, `@leanspec/ui` |172| **Platform** (published) | `@leanspec/cli-{platform}`, `@leanspec/mcp-{platform}` (5 platforms each) |173| **Internal** (not published) | `@leanspec/desktop`, `@leanspec/ui-components` |174175⚠️ **Platform packages MUST be published before main packages.** The CI workflow handles this automatically.176177See [PUBLISHING.md](./references/PUBLISHING.md) and [NPM-DISTRIBUTION.md](./references/NPM-DISTRIBUTION.md) for details.178179---180181## Changelog182183Update `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).184185### Discovering Changes186187```bash188# Commits since last tag189git log $(git describe --tags --abbrev=0)..HEAD --oneline190191# Files changed since last release192git diff $(git describe --tags --abbrev=0)..HEAD --stat193```194195### Entry Format196197**Only include shipped/implemented changes** — not planned specs, drafts, or WIP.198199Add under `## [Unreleased]` using these categories: **Added**, **Changed**, **Fixed**, **Deprecated**, **Removed**, **Security**, **Technical**.200201```markdown202- **Feature Name** ([spec 123](https://web.lean-spec.dev/specs/123)) - Brief description203 - Sub-bullet with implementation details204```205206### Writing Style2072081. **Bold feature name** followed by description2092. **Link related specs** when applicable2103. **Present tense** — "Adds support for..." not "Added"2114. **Be specific** — include command names, flag names, component names2125. **Group related changes** under single bullet with sub-bullets2136. Include breaking changes with **Breaking:** prefix214215### Creating a Release2162171. Move entries from `[Unreleased]` to new version: `## [X.Y.Z] - YYYY-MM-DD`2182. Add release link at bottom: `[X.Y.Z]: https://github.com/codervisor/lean-spec/releases/tag/vX.Y.Z`219220---221222## CI/CD (GitHub Actions)223224All workflow interactions use the `gh` CLI. Check status before triggering new runs; minimum 30s between polls.225226### Available Workflows227228| Workflow | File | Triggers | Purpose |229|----------|------|----------|---------|230| **CI** | `ci.yml` | push, PR to main | Build, test, lint (Node.js + Rust) |231| **Publish** | `publish.yml` | release, manual | Publish to npm (all platforms) |232| **Desktop Build** | `desktop-build.yml` | push, PR, manual | Build Tauri desktop apps |233| **Copilot Setup** | `copilot-setup-steps.yml` | push, PR, manual | Setup environment for Copilot agent |234235### Quick Reference236237```bash238# Check status239gh run list --limit 10240gh run list --workflow ci.yml --limit 5241gh run view <run-id>242gh run watch <run-id>243244# Trigger245gh workflow run ci.yml246gh workflow run publish.yml --field dev=true247248# Debug failures249gh run view <run-id> --log-failed250gh run rerun <run-id> --failed251252# Artifacts253gh run download <run-id>254gh run download <run-id> --name ui-dist255```256257See [CI-WORKFLOWS.md](./references/CI-WORKFLOWS.md), [CI-COMMANDS.md](./references/CI-COMMANDS.md), and [CI-TROUBLESHOOTING.md](./references/CI-TROUBLESHOOTING.md) for details.258259---260261## Runner Research262263Research AI agent runners to keep LeanSpec's runner registry current as the ecosystem evolves.264265### Workflow2662671. **Read current state**: `rust/leanspec-core/src/sessions/runner.rs` (`RunnerRegistry::builtins()`)2682. **Read catalog**: [runners-catalog.md](./references/runners-catalog.md)2693. **Research via `web_search`**: Config format changes, CLI changes, new env vars, new capabilities, deprecations, new runners2704. **Compare & identify gaps**: Cross-reference findings against registry2715. **Report**: Minor updates → update catalog directly; major changes → create a spec272273### Runner Tiers2742751. **Tier 1** (high priority): Claude Code, Copilot, Cursor, Windsurf, Codex, Gemini2762. **Tier 2** (medium): Kiro, Amp, Aider, Goose, Continue, Roo Code2773. **Tier 3** (monitor): Droid, Kimi, Qodo, Trae, Qwen Code, OpenHands, Crush, CodeBuddy, Kilo, Augment278279### Key Source Files280281| File | Purpose |282|------|---------|283| `rust/leanspec-core/src/sessions/runner.rs` | Runner registry with detection config |284| `schemas/runners.json` | JSON schema for custom runner config |285| `packages/cli/templates/_shared/agents-components/` | AGENTS.md template components |