Contributing Overview

​

Welcome Contributors

​

Quick Start

​

Prerequisites

• Bun: Fast JavaScript runtime and package manager
• No external dependencies required

​

Get the Code

git clone https://github.com/yourusername/impeccable.git
cd impeccable

​

Build the Project

# Build all provider formats
bun run build

# Clean dist folder
bun run clean

# Rebuild from scratch
bun run rebuild

​

Test Locally

# Start development server
bun run dev

# Run tests
bun run test

​

Project Structure

• Source files (source/): Single source of truth with full metadata
• Build system (scripts/): Transforms source to provider-specific formats
• Distribution (dist/): Generated output files for 4 providers (committed for users)

​

Key Directories

impeccable/
├── source/              # EDIT THESE! Source of truth
│   ├── commands/        # Command definitions
│   └── skills/          # Skill definitions
├── dist/                # Generated (committed for users)
│   ├── cursor/
│   ├── claude-code/
│   ├── gemini/
│   └── codex/
├── scripts/             # Build system (Bun)
│   ├── build.js
│   └── lib/
├── public/              # Website (impeccable.style)
└── api/                 # Vercel Functions

​

Types of Contributions

​

Adding Skills

​

Adding Commands

​

Improving Documentation

​

Bug Fixes

• Description of the issue
• Steps to reproduce
• Your fix with tests if applicable

​

Website Improvements

​

Development Workflow

​

1. Create a Branch

git checkout -b feature/your-feature-name

​

2. Make Changes

​

3. Build and Test

bun run build
# Test with your provider of choice

​

4. Commit Both Source and Dist

git add source/ dist/
git commit -m "Add: your feature description"

​

5. Submit a Pull Request

• Clear description of changes
• Rationale for the change
• Testing you’ve done

​

Best Practices

​

Command Writing

1. Clear descriptions: Make purpose obvious
2. Meaningful argument names: Use descriptive names
3. Flexible prompts: Write prompts that work even without argument substitution (for Cursor compatibility)
4. Test across providers: Verify it works in multiple contexts

​

Skill Writing

1. Focused scope: One clear domain per skill
2. Clear instructions: LLM should understand exactly what to do
3. Include examples: Where they clarify intent
4. State constraints: What NOT to do as clearly as what to do

​

Code Quality

• Keep transformer functions focused (30-85 lines each)
• Use descriptive variable names
• Add comments for complex logic
• Follow existing code style

​

Testing

1. Build the project
2. Copy the relevant dist/ output to your test project
3. Verify the skill/command works as expected
4. Check edge cases (missing arguments, unusual inputs)

​

Getting Help

• Architecture questions: See Architecture
• Build system questions: See Build System
• Adding content: See Adding Content
• General questions: Open an issue on GitHub

​

Code of Conduct

​

License

​

Related Documentation

• Architecture - System architecture details
• Adding Content - How to add skills and commands
• Build System - Build system internals