Agent-Skills.md

Agent Skills: LeanSpec Development Skill

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.

UncategorizedID: codervisor/lean-spec/leanspec-development

Repository

codervisor/lean-spec
codervisorLicense: MIT
22717

Install this agent skill to your local

pnpm dlx add-skill https://github.com/codervisor/lean-spec/tree/HEAD/.agents/skills/leanspec-development

Skill Files

Browse the full folder contents for leanspec-development.

Download Skill

Loading file tree…

.agents/skills/leanspec-development/SKILL.md

Skill Metadata

Name
leanspec-development
Description
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.

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

  1. Use pnpm — Never npm or yarn
  2. DRY — Extract shared logic, avoid duplication
  3. Test What Matters — Business logic and data integrity, not presentation
  4. Leverage Turborepo — Smart caching (19s → 126ms builds)
  5. i18n is MANDATORY — Every user-facing string needs both en AND zh-CN (see I18N.md)
  6. 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:

  1. Light/Dark Theme — ALL UI must support both themes
  2. i18n — Update BOTH en and zh-CN → I18N.md ⚠️ commonly forgotten
  3. Regression Tests — Bug fixes MUST include failing-then-passing tests
  4. Rust Quality — Must pass cargo clippy -- -D warnings
  5. Rust Params Structs — Functions with >7 args must use a params struct (enforced by clippy.toml)
  6. Use shadcn/ui — No native HTML form elements
  7. 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

  1. Bold feature name followed by description
  2. Link related specs when applicable
  3. Present tense — "Adds support for..." not "Added"
  4. Be specific — include command names, flag names, component names
  5. Group related changes under single bullet with sub-bullets
  6. Include breaking changes with Breaking: prefix

Creating a Release

  1. Move entries from [Unreleased] to new version: ## [X.Y.Z] - YYYY-MM-DD
  2. 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

  1. Read current state: rust/leanspec-core/src/sessions/runner.rs (RunnerRegistry::builtins())
  2. Read catalog: runners-catalog.md
  3. Research via web_search: Config format changes, CLI changes, new env vars, new capabilities, deprecations, new runners
  4. Compare & identify gaps: Cross-reference findings against registry
  5. Report: Minor updates → update catalog directly; major changes → create a spec

Runner Tiers

  1. Tier 1 (high priority): Claude Code, Copilot, Cursor, Windsurf, Codex, Gemini
  2. Tier 2 (medium): Kiro, Amp, Aider, Goose, Continue, Roo Code
  3. 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 |