codervisor/leanspec-development
.agents/skills/leanspec-development/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add codervisor/lean-spec leanspec-developmentInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 17, 2026, 2:18 PM5.9s11 files scanned
SKILL.md
- 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
- 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.jsonis the single source of truth for versions pnpm sync-versionspropagates 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 |
Related Skills
codervisor/leanspec
development
VerifiedTrustedCommunity
The spec-coding methodology for AI-assisted development. Use when planning features, creating/refining/implementing/verifying specs, or organising a project. Works with whatever spec backend your team already uses — local markdown, GitHub Issues, Azure DevOps, Jira — by delegating platform-specific details to a LeanSpec adapter.
245SKILL.mdUpdated May 21, 2026
codervisor/leanspec
development
VerifiedTrustedCommunity
The spec-coding methodology for AI-assisted development. Use when planning features, creating/refining/implementing/verifying specs, or organising a project. Works with whatever spec backend your team already uses — local markdown, GitHub Issues, Azure DevOps, Jira — by delegating platform-specific details to a LeanSpec adapter.
227SKILL.mdUpdated Apr 17, 2026
codervisor/watch-ci
development
VerifiedTrustedCommunity
Watch GitHub Actions CI status for the current commit until completion. Use after pushing changes to monitor build results.
227SKILL.mdUpdated Apr 17, 2026
codervisor/parallel-worktrees
development
VerifiedTrustedCommunity
Run multiple AI coding agent sessions in parallel using git worktrees — each agent isolated in its own worktree, working on a separate branch. Use this skill whenever the user wants to: run two or more AI agents simultaneously on different features or bugs, set up isolated agent workspaces in the same repo, push parallel branches to GitHub and open/update PRs, coordinate between concurrent agent sessions, or clean up after merging. Triggers on: "parallel agents", "multiple agent sessions", "git worktree", "run agents in parallel", "work on two things at once", "isolated agent workspace", "spin up another agent", or any request involving simultaneous AI-assisted development streams.
227SKILL.mdUpdated Apr 17, 2026