MedHarness
AI-assisted development with design control: your AI agent writes the code and the design record, and ordinary code checks that they agree before anything merges.
AI development
flowchart LR
A["<b>1 · Design</b><br/>AI drafts the design"] -->|"<b>you review</b>"| B["<b>2 · Code</b><br/>AI codes and tests"]
B -->|"<b>you review</b>"| C(["Merge"])
For each change request, the agent designs first — it assesses the change's risk, then writes the requirements, design and test points it needs as items in your repository's Design History File (DHF), each traced to the next — and codes second, tagging each test with the requirement it verifies. You review the design, then the code. Between them, ordinary code — never a model — checks that the design traces, every requirement is verified, and the branch changed what the request said.
What MedHarness gives the agent:
- The process, in its own instructions.
initwrites anAGENTS.md(and aCLAUDE.mdthat imports it) telling the agent when to open a change request and which commands to run;build plan --promptprints the exact steps and this change's DHF context for whichever agent you use. - Commands instead of files. The agent reads and writes the DHF with
medharness item, which checks the schema first: a bad edit is refused, not saved. - Feedback it can act on. The checks name the item and field that are wrong, so the agent fixes them and runs the check again.
Run it two ways:
- At your desk, with the agent you already use: it does the work in your working tree and you commit.
- Unattended, from an issue: CI opens the change request and a pull request with the design; ask for changes and it revises; the code stage runs the same way. The recipe is in adopting.md.
Unattended, build plan and build code run the claude CLI, or any
provider:model you set (anthropic, openai, deepseek) — they run an agent
with a shell, so use an ephemeral runner and read
ai-security.md first.
Quick start
pip install medharness
mkdir my-device && cd my-device
medharness init # writes DHF/ with sample items, and AGENTS.md for your agent
Then ask your coding agent: "open a CR for PDF export and implement it".
Or use the checks alone, with no AI: medharness verify dhf checks that the
design holds together.
What a project looks like
my-device/
├── DHF/
│ ├── config/global.yaml # the project name — and only what you change
│ └── items/ # one YAML file per item, one directory per type
│ ├── 01_crs/CRS-001.yaml
│ ├── 03_srs/SRS-001.yaml
│ └── … # one directory per configured type
├── AGENTS.md # product context and DHF steps, for any coding agent
└── CLAUDE.md # @AGENTS.md, so Claude Code reads it too
The item types (13 by default), their fields and lifecycles, the required links
and the specification templates are defaults shipped in the package, so
upgrading medharness upgrades them. A project overrides only what it changes,
in DHF/config/: see Changing the defaults.
An item is a small YAML file. Links are written on the child and point up:
id: SRS-012
title: Password must be at least 12 characters
derives_from: [SYS-004]
verification_method: [Test]
testing: |
T1: an 11-character password is rejected
Commands
One CLI, four groups:
medharness init
medharness item list | get | create | update | transition
medharness verify dhf | tests | soup | completion | changes
medharness build plan | code | soup | release
item reads and changes DHF items, verify checks and writes nothing, build
produces items, code and release artifacts. Every command's options and what it
returns are in interface.md; --help on
any command prints the same.
Example project
ContourLab is an example project used to exercise MedHarness end to end: its DHF, its CI, and changes made through AI development.
Documentation
| adopting.md | starting fresh, the CI recipe, bringing an existing DHF, releases |
| interface.md | the gate result, exit codes, what may change |
| ai-security.md | what the AI stages can do, and running without them |
| architecture.md | how the code is organised |
| CHANGELOG.md | version history |
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for medharness 0.49.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| medharness-0.49.0.tar.gz | 152.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| medharness-0.49.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 349.9 kB
Release files / medharness-0.49.0.tar.gz
| Download URL | medharness-0.49.0.tar.gz |
|---|---|
| Size | 152.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a342e00d325a0f0500603728e2f92a8e1a56a95042914bd77c86b0bfe6f76dc
|
|
BLAKE2b-256 checksum How to use checksums |
1f4502e6f677586ec658809ce2046e39582ac66614df8b7198b63cbcb4afc6f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / medharness-0.49.0-py3-none-any.whl
| Download URL | medharness-0.49.0-py3-none-any.whl |
|---|---|
| Size | 197.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bea7dcacb804bd7559003157c8374308a7f01539c04a5554591a3dbc4aff6c5d
|
|
BLAKE2b-256 checksum How to use checksums |
f067182c5192624e83ff15f5b0bf6856f125e0a5eb0a68bf98debd23e70940de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
