Contributing to claude-code-harness

May 27, 2026 · View on GitHub

Thank you for your interest in contributing to claude-code-harness! This document provides guidelines for contributing.

How to Contribute

Reporting Issues

Security vulnerabilities are not normal issues. Follow SECURITY.md and do not include exploit details, secrets, tokens, or private data in public GitHub issues.

  1. Check if the issue already exists in GitHub Issues
  2. If not, create a new issue with:
    • Clear title describing the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • Claude Code version and OS

Submitting Changes

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature-name
  3. Make your changes
  4. Test your changes locally
  5. Commit with clear messages: git commit -m "feat: add new feature"
  6. Push to your fork: git push origin feature/your-feature-name
  7. Open a Pull Request

Commit Message Format

We follow Conventional Commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

Code Style

  • Use clear, descriptive names
  • Add comments for complex logic
  • Keep commands/agents/skills focused on single responsibilities

Plugin Structure

claude-code-harness/
├── .claude-plugin/
│   ├── plugin.json      # Plugin manifest
│   └── marketplace.json # Marketplace config
├── skills/              # Skills (primary - v2.17.0+)
├── agents/              # Subagents
├── hooks/               # Lifecycle hooks
├── templates/           # Template files
├── README.md
├── LICENSE
└── CONTRIBUTING.md

Note: As of v2.17.0, commands have been migrated to skills. Skills are the recommended approach for new functionality.

  1. Create skills/your-skill/SKILL.md with YAML frontmatter: 
    ---
name: your-skill
description: "Description with trigger phrases. Use when... Do NOT load for..."
allowed-tools: ["Read", "Write", "Edit", "Bash"]
---
  2. Add supporting files to skills/your-skill/references/ if needed
  3. Update README.md with the new skill

Adding a New Agent

  1. Create agents/your-agent.md
  2. Define the agent with YAML frontmatter
  3. Update README.md (recommended)

Note: agents/ are auto-discovered by Claude Code. You typically do not need to manually enumerate them in plugin.json.

Version Management

Version is defined in two places that must stay in sync:

  • VERSION - Source of truth
  • .claude-plugin/plugin.json - Used by plugin system

Normal feature/docs PRs should leave both files unchanged and record user-facing changes in CHANGELOG.md under [Unreleased]. Use a version bump only when you are intentionally cutting a release.

Version Scripts

# Check if versions are in sync
./scripts/sync-version.sh check

# Sync plugin.json to VERSION
./scripts/sync-version.sh sync

# Bump patch version for a release (e.g., 2.0.0 → 2.0.1)
./scripts/sync-version.sh bump

Release-only Versioning Policy

  • Normal PRs: do not edit VERSION or .claude-plugin/plugin.json; add notes under [Unreleased]
  • Release work: run ./scripts/sync-version.sh bump, add a versioned CHANGELOG.md entry, then create the tag / GitHub Release
  • The repo pre-commit hook only syncs plugin.json to VERSION when you intentionally edit release metadata; it does not auto-bump patch versions

Version Consistency Checks

  • Local (recommended): run ./scripts/sync-version.sh check before committing
  • CI (recommended): run ./tests/validate-plugin.sh and ./scripts/ci/check-consistency.sh on PRs

CHANGELOG 記載ルール（必須）

Keep a Changelog フォーマットに準拠

各バージョンエントリには以下のセクションを使用:

## [X.Y.Z] - YYYY-MM-DD

### Added
- 新機能について

### Changed
- 既存機能の変更について

### Deprecated
- 間もなく削除される機能について

### Removed
- 削除された機能について

### Fixed
- バグ修正について

### Security
- 脆弱性に関する場合

#### Before/After（大きな変更時のみ）

| Before | After |
|--------|-------|
| 変更前の状態 | 変更後の状態 |

セクション使い分け:

セクション使うとき
Added完全に新しい機能を追加したとき
Changed既存機能の動作や体験を変更したとき
Deprecated将来削除予定の機能を告知するとき
Removed機能やコマンドを削除したとき
Fixedバグや不具合を修正したとき
Securityセキュリティ関連の修正をしたとき

Before/After テーブル: 大きな体験変化（コマンド廃止・統合、ワークフロー変更、破壊的変更）があるときのみ追加。軽微な修正では省略可。

バージョン比較リンク: CHANGELOG.md 末尾に [X.Y.Z]: https://github.com/.../compare/vPREV...vX.Y.Z 形式で追加

Testing

Before submitting:

  1. Validate plugin structure and consistency:

    ./tests/validate-plugin.sh
./scripts/ci/check-consistency.sh

  2. (Recommended) Enable pre-commit hooks (keep release metadata in sync without auto-bumping):

    ./scripts/install-git-hooks.sh

    Windows users: Git hooks require Git for Windows which includes Git Bash. The hooks run automatically via Git Bash regardless of your shell (PowerShell, CMD, etc.).

  3. Test locally in a separate project using --plugin-dir:

    cd /path/to/your-project
claude --plugin-dir /path/to/claude-code-harness

  4. Verify commands work as expected (/help), and the core loop runs:

    • /harness-init
    • /plan-with-agent
    • /work
    • /harness-review

Questions?

  • Open an issue for questions
  • Check existing documentation

Thank you for contributing!