LeanSpec Development Skill

LeanSpec Development Skill

Quick activation context for AI agents working on LeanSpec development.

When to Use

Activate when:

• Setting up development environment
• Contributing code or fixing bugs
• Running tests or validation
• Working with the monorepo structure

Quick Navigation

Everything else: Read root README.md, package.json scripts, or explore the codebase.

Core Principles

The non-negotiable mental model:

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. Maintain i18n - Update both en and zh-CN translations
6. Follow Rust Quality - All code must pass cargo clippy -- -D warnings
7. Delegate Complex Tasks - Use runSubagent for multi-step investigations

Working with Subagents

For AI agents: Delegate complex tasks to subagents rather than attempting extensive manual searches.

When to Use runSubagent

✅ Delegate:

• Searching patterns across multiple files
• Investigating unfamiliar code areas
• Cross-package changes requiring context
• Debugging with comprehensive exploration

❌ Don't delegate:

• Simple single-file edits
• Well-known commands
• Already clear and scoped tasks

Delegation Pattern

runSubagent({
  description: "Find validation logic",
  prompt: `Search for all spec validation logic.
  
  Return:
  1. Where rules are defined
  2. What checks are performed
  3. Where validation is called
  
  Focus on: packages/​mcp, rust/​leanspec-core`
});

Critical Commands

The 20% you need 80% of the time:

# Setup
pnpm install              # Install dependencies
pnpm build                # Build all packages

# Development (see package.json for all scripts)
pnpm dev                  # Start all dev servers
pnpm dev:cli              # CLI watch mode
pnpm dev:web              # Web UI only

# Validation (run before PR)
pnpm pre-release          # Full validation: typecheck, test, build, lint
pnpm test:run             # All tests (CI mode)
pnpm lint:rust            # Rust clippy checks

All commands are in root package.json - AI agents should read it directly.

Critical Rules

Rules enforced by hooks or CI:

1. Light/​Dark Theme - ALL UI must support both themes

   // ✅ Good
   className="text-blue-700 dark:text-blue-300"
   

2. i18n - Update BOTH en and zh-CN locales

3. Regression Tests - Bug fixes MUST include failing-then-passing tests

4. Rust Quality - Must pass cargo clippy -- -D warnings

5. Use shadcn/​ui - No native HTML form elements (<input>, <select>, <button>, etc.)

   // ✅ Good - shadcn/​ui
   import { Input } from '@/​components/​ui/​input';
   <Input placeholder="..." />
   
   // ❌ Bad - native HTML
   <input type="text" />
   

6. cursor-pointer on interactive items - All clickable dropdown/​select items must use cursor-pointer

   // ✅ Good - cursor-pointer for clickable items
   className="... cursor-pointer ..."
   
   // ❌ Bad - cursor-default on interactive items
   className="... cursor-default ..."
   

See RULES.md for complete requirements.