Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (109 loc) · 5.9 KB

CONTRIBUTING.md

File metadata and controls

145 lines (109 loc) · 5.9 KB

Contributing

Thanks for helping improve harness-starter-kit. This project is a prompt-first reference kit for adding durable agent rules, feedback loops, memory, and drift checks to other repositories.

Before proposing broad automation, read docs/decisions/0001-prompt-first-adoption.md. The target repository remains the source of truth.

Good First Contribution Ideas

Good first contributions usually improve evidence, examples, or clarity without changing the adoption model.

  • Add or refine an adoption example.
  • Improve Harness Doctor evidence messages.
  • Add a GitLab CI or monorepo adoption note.
  • Strengthen documentation around /harness update or /harness refresh.
  • Improve localized README consistency.
  • Add a new stack profile only when it includes a fixture and smoke test.

See ROADMAP.md for the current project direction.

Development

Use Python 3.11 or newer for local validation. On macOS/Linux, use python3 instead of python when python is unavailable. Before opening a pull request, run:

python -m unittest discover -s tests
python -m py_compile scripts/apply_harness.py scripts/check_docs_drift.py scripts/check_structure.py scripts/check_encoding_hygiene.py scripts/check_effectiveness_plan.py scripts/check_failure_memory.py scripts/check_decision_memory.py scripts/harness_doctor.py
python scripts/check_docs_drift.py
python scripts/check_structure.py
python scripts/check_encoding_hygiene.py
python scripts/check_effectiveness_plan.py
python scripts/check_failure_memory.py
python scripts/check_decision_memory.py
python scripts/harness_doctor.py --target .

Change Guidelines

  • Keep templates generic and conservative.
  • Preserve prompt-first adoption: target repositories remain the source of truth.
  • Do not blindly copy starter-kit defaults into profile guidance.
  • When changing profile README files, also review docs/templates/profile-readme.md, docs/checklists/profile-maintenance.md, and tests/test_profile_consistency.py.
  • Add or update tests for installer behavior, templates, drift scripts, command workflows, and scoring behavior.

Adding A New Profile

Profiles are reference material, not automatic transformations. Do not add a profile README by itself.

A profile contribution should usually include:

  • templates/profiles/<profile>/README.md with conditional, practical guidance.
  • Any merge-only snippets, such as gitignore.harness.txt, package-scripts.harness.json, pyproject.harness.toml, or eslint.config.harness.mjs.
  • A minimal fixture under tests/fixtures/<profile>-basic/.
  • Smoke coverage in tests/test_smoke_fixtures.py.
  • Installer coverage in tests/test_apply_harness.py when the profile adds new snippet files.
  • README and validation documentation updates when the public profile list changes.

Profile guidance should tell agents what to inspect, adopt, adapt, skip, or defer. It should not assume that every target repository wants the same lint rules, package scripts, CI workflow, or generated-file policy.

Adding A Drift Check

Drift checks should enforce a real rule that future agents are likely to miss.

Before adding one:

  • Name the repeated mistake, stale-doc risk, or architecture boundary it catches.
  • Prefer a small Python script with clear failure output.
  • Keep defaults safe for small repositories and easy to override.
  • Add regression tests for false positives and expected failures.
  • Document when maintainers should run the check locally or in CI.

If a check fixes a failed harness check, repeated agent mistake, or cross-environment mismatch, add a docs/failures/*.md record unless the failure was purely transient.

Adding An Adoption Example

Adoption examples should be based on real or fixture-backed repository behavior.

Include:

  • target stack, package manager, and verification commands
  • files added or changed
  • snippets adopted, adapted, skipped, or deferred
  • checks run and their results
  • effectiveness measurement plan or result location
  • remaining manual steps and assumptions

Use docs/templates/adoption-report.md as the shape. If the example records actual outcomes, use docs/templates/effectiveness-report.md.

When Not To Add Automation

Do not add automation that makes the starter kit guess target-specific policy.

Avoid changes that:

  • overwrite existing target files by default
  • add package managers, CI providers, or framework tooling without target evidence
  • treat stack profiles as mandatory migrations
  • replace maintainer judgment with broad generated rewrites
  • make scripts/apply_harness.py the primary adoption mechanism

Prefer better prompts, diagnostics, report templates, examples, and safe patch guidance before adding mutation-heavy behavior.

Required Tests By Change Type

Use the smallest relevant set, then run the full local validation before a release.

Change type Required checks
Installer behavior python -m unittest tests.test_apply_harness and python -m py_compile scripts/apply_harness.py
Drift scripts Matching tests/test_check_*.py, python -m py_compile scripts/check_*.py, and the changed script directly
Harness Doctor scoring python -m unittest tests.test_harness_doctor and python scripts/harness_doctor.py --target .
Profile README guidance python -m unittest tests.test_profile_consistency plus profile fixture smoke coverage
New profile python -m unittest tests.test_apply_harness tests.test_smoke_fixtures tests.test_profile_consistency
README prompt block python -m unittest tests.test_readme_prompt_drift
Adoption or effectiveness reports python scripts/check_effectiveness_plan.py
Release preparation Full local validation from the Development section

Pull Requests

Keep each pull request focused on one logical harness change. Summarize changed files, checks run, assumptions, and any manual follow-up needed.