Skip to main content

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.

PyPI License: MIT Python 3.11+

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.

init writes an AGENTS.md (and a CLAUDE.md that imports it) telling your agent when to open a change request and which commands to run; it reads and writes the DHF through medharness item, which refuses a bad edit, and the checks name the item and field that are wrong. What to call when is in Working with your coding agent.

Two ways to run it:

  • At your desk, with the agent you already use: it works in your tree and you commit.
  • Unattended, from an issue: CI opens the change request and a pull request with the design, revises on review, then does the code the same way (recipe). This runs an agent with a shell: 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
│       └── …
├── AGENTS.md                    # product context and DHF steps, for any coding agent
└── CLAUDE.md                    # @AGENTS.md, so Claude Code reads it too

The item types, their lifecycles and the specification templates ship in the package; a project overrides only what it changes (configuration.md). An item is a small YAML file, with links written on the child and pointing 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

One CLI, medharness, in four groups: item reads and changes items, verify checks and writes nothing, build produces items, code and release artifacts, init scaffolds. What each command does, prints and exits with is in interface.md; --help lists its options.

ContourLab is an example project used to exercise MedHarness end to end.

Documentation

adopting.md starting fresh or bringing an existing DHF
ci.md the CI recipe, cutting and signing a release
ai-workflow.md a change request from design to code
agents.md working with your coding agent
soup.md the SOUP register, SBOM, vulnerability scanning
configuration.md changing the defaults
interface.md what a script or pipeline can rely on
validation.md the tool's own validation
ai-security.md what the AI stages can do
architecture.md how the code is organised
charter.md what it is for, and what it does not do
CHANGELOG.md version history

License

MIT. See LICENSE.

Metadata

Release files for medharness 0.72.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for medharness 0.72.0
File Size Uploaded Provenance Actions
medharness-0.72.0.tar.gz 207.2 kB With provenance Details for medharness-0.72.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for medharness 0.72.0
File Interpreter ABI Platform Actions
medharness-0.72.0-py3-none-any.whl Python 3 none any Details for medharness-0.72.0-py3-none-any.whl

Total release size: 466.8 kB

Release files / medharness-0.72.0.tar.gz

Download URL medharness-0.72.0.tar.gz
Size 207.2 kB
Tags Source
SHA-256 checksum
How to use checksums
907905d538af1803a1bddb730f43cb67ddaeaaa37720d0977da1b6c2c42713bf
BLAKE2b-256 checksum
How to use checksums
bf41cad895a4a29c6ffbf074fb53064503fa6b0de9fd956b44a3c2c6f0fb1be2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 7, 2026.

Transparency log

Release files / medharness-0.72.0-py3-none-any.whl

Download URL medharness-0.72.0-py3-none-any.whl
Size 259.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8e2ecaa3cd2cf4710a9f106f386ac9644231a6b1febe3f751773d6a238eafd4
BLAKE2b-256 checksum
How to use checksums
a63f6083eb52ff9b417f050fcba099e648af73c4bfb4906100d4dfd879d3f80e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 7, 2026.

Transparency log

Security for medharness 0.72.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for medharness-0.72.0.tar.gz

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 Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.72.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page