Contributing

Contributing

How to contribute to HES.

---

Overview

We welcome contributions to HES! This guide will help you get started.

---

Ways to Contribute

1. Report Bugs

Use the "Bug Report" issue template on GitHub.

2. Request Features

Use the "Feature Request" issue template on GitHub.

3. Submit Code

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

4. Improve Documentation

1. Fork the repository
2. Make your changes
3. Submit a pull request

---

Development Setup

Prerequisites

• Git
• Python 3.12+
• Bash

Clone the Repository

git clone https://github.com/josemalyson/hes.git
cd hes

Install Dependencies

# No dependencies required for core HES
# Optional: install development tools
pip install bandit semgrep

---

Project Structure

hes/
├── SKILL.md                    # Main orchestrator
├── skills/                     # Skill files
│   ├── 00-bootstrap.md
│   ├── 01-discovery.md
│   └── ...
├── scripts/                    # Helper scripts
│   ├── ci/
│   └── hooks/
├── .hes/                       # Runtime state
│   ├── agents/
│   ├── state/
│   └── schemas/
└── .github/                    # GitHub configuration
    ├── ISSUE_TEMPLATE/
    └── workflows/

---

Commit Conventions

We use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Type	Description
feat	New feature or enhancement
fix	Bug fix
docs	Documentation changes
chore	Maintenance tasks
refactor	Code refactoring
test	Adding or modifying tests
plan	Architectural plan, roadmap
stub	Partial implementation

Examples

feat(harness): add session manager skill
fix(bootstrap): handle missing state file gracefully
docs: add contribution guide
chore: update agent registry
plan(v4.0): add multi-agent orchestration roadmap
stub(planner): add task decomposition protocol

---

Branch Strategy

• main — Protected branch, only merged via PRs
• feat/<n> — Feature branches
• fix/<n> — Bug fix branches
• docs/<n> — Documentation branches
• plan/<n> — Roadmap and architectural plans
• stub/<n> — Partial implementation of new agents

---

Pull Request Requirements

Every PR must include:

• Linked issue (bug or improvement)
• Description of changes
• Testing notes
• Updated documentation if behavior changed
• For stubs v4.0: status: stub and target_version in skill file header

PR Description Template

## What
Brief description of the changes.

## Why
Why the changes are needed.

## Testing
What was tested and how.

## Related Issues
Closes #(issue number)

---

Skill File Conventions

Header Format

# skill-name.md — Description
# version: X.Y.Z
# status: stable | stub
# target_version: X.Y.Z (if stub)
# HES Phase: PHASE_NAME | SYSTEM

Stub Conventions

Stubs are welcome when:

• The complete protocol is specified
• The header includes status: stub and target_version
• The footer includes <!-- HES vX.Y STUB — implementation complete in vX.Y -->

---

Adding a New Agent

1. Create the skill file in skills/
2. Add the header with status: stub and target_version
3. Update .hes/agents/registry.json
4. Add the corresponding rule to SKILL.md
5. Submit a PR

---

v4.0 Contribution Guide

HES v4.0 is implementing 5 new agents. See Agents for details.

Available for Implementation

Agent	Target	Status
planner.md	v3.6	Stub ready
orchestrator.md	v3.7	Stub ready
harness-evolver.md	v3.8	Stub ready
optimizer.md	v3.9	Stub ready
reviewer.md	v4.0	Stub ready

---

Code Style

Markdown

• Use clear headings
• Include code blocks with language tags
• Use tables for structured data

Bash

• Use set -euo pipefail
• Add comments for complex logic
• Use meaningful variable names

Python

• Follow PEP 8
• Add type hints
• Write docstrings

---

Testing

Manual Testing

1. Install HES in a test project
2. Run through the full workflow
3. Verify all gates work correctly

Automated Testing

# Run harness self-tests
/hes test

# Run CI validation
python scripts/ci/validate-harness.py

---

Getting Help

• Open a Discussion
• Check the Wiki
• Read the README

---

Thank you for contributing!