← Back to home
Open Source

Contributing to Design Harness

Thank you for considering contributing to Design Harness. This guide shows seven ways to contribute and the complete workflow from fork to merge.

How Can I Contribute?

1. Build Skills

The most impactful way to contribute is by building new skills for the harness.

What makes a good skill:

  • Solves a real, repeated design workflow problem
  • Has clear trigger phrases for the orchestrator
  • Follows the skill template structure
  • Includes examples and references
  • Documents its own limitations

See: docs/HOWTO-BUILD-A-SKILL.md

2. Improve Existing Skills

Found a skill that could be better? Submit improvements:

  • Add self-improvement loops
  • Expand references
  • Fix bugs or edge cases
  • Improve trigger phrase matching
  • Add examples

3. Enhance the Orchestrator

Help improve automatic routing:

  • Add new routing patterns
  • Improve intent signal matching
  • Add new skill chains
  • Improve the plan gate logic

4. Expand Platform Support

Currently supports Cursor, Codex, Claude Code. Help add:

  • Gemini CLI
  • OpenCode
  • Other AI coding tools

5. Improve Documentation

  • Fix typos or unclear instructions
  • Add examples and screenshots
  • Write tutorials or guides
  • Translate documentation

6. Report Bugs

Found a bug? Open an issue with:

  • Clear title
  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment (OS, tool, version)
  • Screenshots if applicable

7. Request Features

Have an idea? Open an issue describing:

  • The problem you're trying to solve
  • Your proposed solution
  • Why this would be valuable
  • Any alternatives you considered

Getting Started

Prerequisites

  • Node.js 18+ and npm
  • Git
  • Cursor, Codex, or Claude Code
  • Basic understanding of the orchestrator pattern

Setup

# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/design-harness.git
cd design-harness

# 3. Install dependencies
npm install

# 4. Create a branch
git checkout -b feature/your-feature-name

# 5. Make your changes
# ... edit files ...

# 6. Test locally
npm run dev

Contribution Workflow

Before You Start

  1. Check existing issues - Someone might already be working on it
  2. Open an issue first for major changes - Discuss the approach
  3. Keep changes focused - One feature/fix per PR

Commit Messages

Use clear, descriptive commit messages:

Add motion-choreography skill

- Adds spec/review/opportunities/audit modes
- Includes frequency gate and reduced-motion
- Documents in ORCHESTRATOR.md routing table
- Adds self-improvement loop

Pull Request Process

  1. Update documentation - Add/update skill in routing standards and orchestrator
  2. Test thoroughly - Test in at least one AI tool
  3. Create PR - Use a clear, descriptive title
  4. Respond to feedback - Address review comments promptly
  5. Merge - Maintainer will merge once approved

Skill Development

Skill Template

Every skill must have:

harness/skills/your-skill/
├── SKILL.md              # Required: Main skill file
├── references/           # Optional: Supporting docs
│   └── examples.md
└── scripts/              # Optional: Helper scripts

SKILL.md Structure

---
name: your-skill
description: One-line trigger description for the orchestrator
---

# Your Skill Name

## When this fires
[Routing conditions from ORCHESTRATOR.md]

## Prerequisites
[Any MCPs, files, or context needed]

## Steps
1. Step one
2. Step two
3. Step three

## Output
[What this skill produces]

## Self-improvement loop
[How to gather feedback and improve]

Adding to the Orchestrator

Add your skill to harness/ORCHESTRATOR.md §2 routing table:

| **"your trigger phrases here"** | **`your-skill`** | One-line explanation |

Documentation

Writing Good Docs

  • Use examples - Show, don't just tell
  • Be specific - "Click X, then Y" not "configure settings"
  • Test your instructions - Follow them exactly as written
  • Keep it current - Update docs when code changes
  • Link generously - Reference related docs

Doc Types

  • HOWTO-*.md - Step-by-step guides
  • SKILL.md - Skill instructions for the agent
  • references/*.md - Supporting material
  • README.md - Project overview
  • INSTALL.md - Installation guide

Style Guidelines

Markdown

  • Use ATX headers (# not underlines)
  • Wrap lines at 80 chars
  • Use fenced code blocks with language tags
  • Use tables for structured data
  • Link to other docs with relative paths

Skills

  • Clear, actionable steps
  • No invented facts or hallucinations
  • Cite sources in references/
  • Include self-improvement loops
  • Follow routing standards

Code

  • Use TypeScript for new code
  • Follow existing patterns in src/
  • No external UI frameworks (we use vanilla + design system)
  • Comment complex logic
  • Use design system tokens, never hardcoded values

Git

  • Keep commits focused and atomic
  • Write meaningful commit messages
  • Don't commit designer-profile.local.md or context/org-pack.local/
  • Rebase on main before submitting PR

Recognition

Contributors are recognized in:

  • Git history (your commits stay attributed)
  • Release notes for significant contributions
  • Special thanks in major releases

Thank you for contributing! 🎨

Questions?