CONTRIBUTING.md

Contributing to Better Harness

Thank you for helping improve Better Harness. This guide is the human entry point for contributions to Better Harness. Repository location: https://github.com/QoderAI/better-harness.

By submitting a contribution, you confirm that you have the right to contribute it and agree that it may be distributed under the repository's MIT License.

Before You Start

• Follow the Code of Conduct.
• Search existing issues before proposing a change. Use the bug or feature issue form when the repository issue tracker is available.
• Read Community Extensibility before adding a Skill, model, hook, analysis capability, host adapter, report mode, or style.
• Read Architecture Principles and the root agent instructions before changing ownership boundaries or runtime behavior.
• Read the Developer Experience System ADR before changing public entrypoints, Quickstarts, CLI/help/error contracts, Preview prerequisites, host support claims, diagnostics, privacy or support behavior, release claims, or DX measures.
• Follow Contributing a New Coding Agent Host before adding or widening host support.

Small, focused fixes can go directly to a pull request. Open an issue first when the change affects public behavior, schemas, report contracts, packaging, compatibility boundaries, or more than one canonical owner.

Development Setup

Better Harness 0.5.0 supports Node.js >=22.20.0 <25.0.0 and npm >=10.9.3 <12.0.0. The supported project targets are Windows, macOS, and Linux.

npm ci
npm test

Useful focused checks:

# Markdown links and the generated Harness routing graph
node --test test/doc-link-graph.test.mjs

# Package and runtime-bundle boundaries
npm run pack:verify

# Local visual preview for Canvas changes
npm run preview

For visual changes, also check http://localhost:58575/health and http://localhost:58575/canvas-module.js, inspect browser console errors, and retain a screenshot for review. Do not run package publishing commands as part of an ordinary contribution.

If a documented baseline command fails before your change, record the exact failure in the issue or pull request instead of silently omitting the check.

Choose the Correct Owner

Start with the two common extension routes in docs/community.md:

• Workflow guidance belongs in skills/<skill>/references/ or shared references/.
• Visual style grammar belongs in templates/style/ and must be registered in templates/style/routing.md.

Executable behavior, host adapters, models, hooks, packaging, and report contracts have additional owner and evidence requirements. Follow the complete extensibility matrix instead of adding a parallel implementation.

For a Coding Agent host, use the dedicated host contribution guide. It separates shell, configured-asset, session, output, and packaging claims so a host can land partial support without overstating its coverage.

Plan the Change

For non-trivial behavior, hook, Skill, template, adapter, report, or review-flow changes, follow the spec policy in AGENTS.md. Keep one canonical spec, stable acceptance-criteria IDs, explicit non-goals, and named validation evidence. Documentation-only maintenance can explain why no Story or behavior spec is required.

Keep the pull request bounded to one outcome. Do not mix generated artifacts, unrelated cleanup, dependency changes, or local host state into the same change.

Test and Document

Run the smallest relevant tests while developing, then the broader gate justified by the risk:

• Markdown moves or links: node --test test/doc-link-graph.test.mjs.
• Runtime logic: focused node --test test/<area>.test.mjs, then npm test.
• Package/runtime roots: npm run pack:verify.
• Visual output: preview smoke, console inspection, and screenshot review.
• Cross-platform command changes: verify argv-based execution and avoid shell-specific syntax.

Update user-facing documentation and CHANGELOG.md when a change alters installation, commands, output, compatibility, or public extension contracts.

Commits and Pull Requests

Use Conventional Commits:

<type>(<scope>): <imperative summary>

Explain what changed, why it changed, and how it was validated.

Prefer feat, fix, test, docs, refactor, or chore. Keep the summary concise and add a prose body for non-trivial changes.

Complete the pull request template with:

• linked issue or a clear no-issue rationale;
• spec and acceptance-criteria references when applicable;
• exact changed owners and explicit non-goals;
• test commands and observed outcomes, not intended future checks;
• compatibility, packaging, and rollback risks;
• material AI assistance and the human review performed on its output.

Review and Merge

Maintainers review correctness, evidence, scope, architecture ownership, cross-platform behavior, compatibility impact, and license compatibility. Approval does not imply immediate merge when release or compatibility questions remain open.