New harness adapter authoring

Use this runbook when authoring a new harness adapter for first-party inclusion in Apothem or as a third-party package.

PrerequisitesCopy Anchor Link

• Familiarity with the HarnessAdapter protocol
• Understanding of the target harness config format
• Python 3.10+

StepsCopy Anchor Link

1. Implement the adapterCopy Anchor Link

Follow the Authoring a harness adapter example to implement HarnessAdapter for the target harness.

If the adapter writes a plain-text template (a file that is not JSON or YAML) with mode: write_text and ownership_class: operator-owned, uninstall deletes the file only while it is an unedited copy of a template Apothem shipped. When a later release changes the template, add the SHA-256 digest of the previous text to that manifest entry's earlier_digests list in the same change, or uninstall leaves every unedited copy the earlier release wrote in place. Take the digest of the text at the latest release tag with git show <tag>:<template path> | sha256sum; the template must carry no ${...} path token. tests/unit/test_template_digests.py fails when a shipped template is not accounted for.

2. Write the docs pageCopy Anchor Link

Create site/content/docs/harnesses/<slug>.mdx covering:

• Installation flow
• Profile-to-native-config mapping
• Compatibility caveats
• Verification recipes
• Update and uninstall recipes
• Conformity gate surface
• Troubleshooting table
• Configuration knobs table

3. Write testsCopy Anchor Link

tests/packaging/test_<slug>_adapter.py
tests/unit/test_<slug>_adapter.py

Minimum test coverage:

• test_install_creates_expected_files
• test_verify_passes_after_install
• test_uninstall_removes_files

4. Verify locallyCopy Anchor Link

apothem install --harness <slug>
apothem verify --harness <slug>
python -m apothem.conformity.gate --all .

5. Submit pull requestCopy Anchor Link

Open a PR with:

• Adapter implementation
• Docs page at site/content/docs/harnesses/<slug>.mdx
• Tests
• Entry-point registration in pyproject.toml, a HARNESS_REGISTRY entry in src/apothem/lib/harness_registry_data.py (bump SUPPORTED_HARNESS_COUNT there), and the ID in the harnessId enum of src/apothem/schemas/profile.schema.json
• Changelog entry