Godharness logo

Godharness: Temporary Product Brief

Status: Working notes — not a Viewstone product document Date: 2026-08-05

Problem

Coding agents can enforce deterministic rules after changing code, but they do not automatically know a repository's architecture decisions, product intent, engineering practices, or the rationale behind policies. Raw documentation is easy to miss, too broad to load in full, and difficult to keep structurally healthy.

Desired Outcome

Godharness gives coding agents the right engineering context before they act. It ships a small, versioned, opinionated default suite of best practices and lets each repository add its own standards, decision records, product context, and service-specific guidance.

Product Positioning

Godharness is an agent-context and documentation-governance framework. It is related to Oh My Claude Code and Superpowers in that it supports coding-agent workflows, but its job is distinct:

Workflow frameworks prescribe how an agent works.
Godharness supplies the project-specific and default context the agent needs to make sound decisions.
Godlint deterministically verifies the codifiable subset in code and CI.

The family promise is:

Godharness helps agents understand the project. Godlint makes sure the project stays true to what it decided.

Relationship to Godlint

Godlint and Godharness have deliberately different authority boundaries.

Product	Authority	Example
Godharness	Guidance before a change	"Validate untrusted data at runtime boundaries."
Godlint	Deterministic enforcement after a change	"Do not read environment variables outside the configured boundary."

Godharness handles decisions that cannot safely be inferred from syntax:

product intent and non-goals;
architecture tradeoffs and ADRs;
testing philosophy and recovery strategy;
domain vocabulary and service ownership;
instructions for evaluating ambiguous cases.

Godlint handles objective, explainable checks against source and workflows. Godharness must not claim that injecting guidance proves compliance; Godlint, tests, review, and other deterministic checks remain the proof mechanisms.

Version 1 Scope

Godharness v1 is a local-first, installable CLI with Markdown and Git as the source of truth. It has no user interface and no Obsidian integration in v1.

Recommended suite

recommended@1 ships a small, curated, versioned set of broadly useful standards, such as:

testing and verification;
error handling;
small focused units;
security and secrets hygiene;
configuration boundaries;
CI expectations;
documentation and decision-record practices.

The suite is not injected wholesale. The resolver selects a tiny universal core plus standards relevant to the task and changed paths. Suites must remain small enough that their context is useful rather than generic noise.

Repository context

Repositories compose the default suite with their own Markdown standards, architecture decisions, product context, playbooks, and service-specific guidance. Project content can refine the default guidance without copying it.

Illustrative configuration:

version: 1
suites: [recommended@1]

standards:
  - docs/engineering/**
  - docs/process/**
  - docs/architecture/**

adapters:
  codex: true
  claude-code: true
  pi: true

Commands

The initial CLI surface should be small:

godharness init
godharness check
godharness context --prompt "..."
godharness context --paths services/api/src/auth.ts
godharness doctor

init creates the configuration and starter standards.
check validates document schema, links, classification, selectors, and adapter configuration.
context resolves the standards and decisions relevant to a prompt or set of changed paths in a deterministic machine-readable form.
doctor validates local installation and adapter wiring.

Installing

Homebrew: brew install tomerwave/tap/godharness
cargo: cargo install godharness-cli
npm: npm install --global @godharness/cli
pip: pip install godharness

This repository keeps its own installed copy current automatically: .github/workflows/self-update.yml runs godharness update whenever a new version releases and commits any resulting change directly to main.

Technical Direction

Build the core in Rust.

Reasons:

a single fast binary works locally and in CI without Node or Bun;
the resolver, validator, configuration model, diagnostics, and release approach align with Godlint;
it supports deterministic, local-first behavior and cross-platform installs;
thin agent-specific adapters can call the binary and consume JSON rather than duplicating matching logic.

The existing Viewstone TypeScript harness is a useful reference implementation, not the product core. It proves three useful mechanisms:

prompt-keyword matching;
changed-path glob matching;
adapters for Codex, Claude Code, and Pi that inject selected context.

The extracted core should use a real YAML/frontmatter parser and schema validation rather than preserving the current hand-written parser.

Required Product Properties

Deterministic resolution: no LLM decides which context is mandatory.
Local-first: repository source and context stay local by default.
Markdown and Git native: standards and decisions remain reviewable and portable.
Explainability: users can answer "why was this injected?".
Versioned suites: recommended@1 remains stable when future suites change.
Scoped context: support universal, task, path, service, and repository scope.
Conflict handling: define precedence and surface contradictory standards.
CI validation: prevent broken links, malformed metadata, unindexed standards, stale ownership, and adapter drift.

Explicit Non-Goals for v1

No graphical interface, desktop application, or Obsidian integration.
No generic notes app or knowledge graph.
No vector search/RAG as the policy-selection mechanism.
No LLM-driven enforcement or opaque context selection.
No duplicate source-code linter; Godlint owns deterministic source and workflow policy.
No automatic invention of engineering standards.

Later Possibilities

An Obsidian-like product experience could be valuable later for authoring, exploring relationships, ownership/review dates, contradictions, and context previews. It must remain a view over the Git-backed Markdown source of truth, not replace it.

Future Godlint integration can map a finding to its relevant Godharness standard so developers receive both the deterministic violation and the decision rationale.

Risks

A large default suite will become generic prompt noise and be ignored.
Simple keyword and glob matching can over-match or miss relevant context.
Injecting a rule does not prove an agent followed it.
Project-specific standards can conflict unless precedence and ownership are explicit.
A UI too early would distract from the core resolution and validation loop.

Open Decisions

Adapter protocol and installation model for each supported agent.
The first Godlint-to-Godharness rationale-linking contract.
Conflict-reporting between two standards whose content disagrees (as opposed to resolution order, which is decided — see below).

Decided since this section was first written, with the implementation in crates/godharness-core:

Standard frontmatter schema and selectors: id, title, keywords, paths, must-read, supersedes, relates-to; word-boundary keyword matching; glob path matching.
Resolution precedence: a must-read standard always resolves regardless of prompt or changed paths; supersedes suppresses the standard it names; relates-to surfaces a neighbor alongside a match.
Extension model: a repository adds standards through the standards globs in godharness.yaml. Overriding an existing standard means superseding it under a new id — reusing an existing id is a duplicate-id error, not a silent override.
The minimal universal core every task receives: whichever standards are marked must-read.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

godharness-0.1.7-py3-none-win_amd64.whl (3.2 MB view details)

Uploaded Aug 11, 2026 Python 3Windows x86-64

godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl (4.7 MB view details)

Uploaded Aug 11, 2026 Python 3musllinux: musl 1.2+ x86-64

godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl (4.3 MB view details)

Uploaded Aug 11, 2026 Python 3musllinux: musl 1.2+ ARM64

godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl (4.7 MB view details)

Uploaded Aug 11, 2026 Python 3manylinux: glibc 2.17+ x86-64

godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl (4.5 MB view details)

Uploaded Aug 11, 2026 Python 3manylinux: glibc 2.17+ ARM64

godharness-0.1.7-py3-none-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded Aug 11, 2026 Python 3macOS 11.0+ ARM64

godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl (4.0 MB view details)

Uploaded Aug 11, 2026 Python 3macOS 10.12+ x86-64

File details

Details for the file godharness-0.1.7-py3-none-win_amd64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-win_amd64.whl
Upload date: Aug 11, 2026
Size: 3.2 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`5a540ab6cce3e47c9d4e1ca55eeb64075c571c17403e9e1f6b2a9108134c4a45`
MD5	`9d58a4433ed50d6a6aee109e40f4dc60`
BLAKE2b-256	`a1c17b724460f878cbcd6359ff9bd227ae4267a9bf6ff6c4a3bb76185191646a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-win_amd64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-win_amd64.whl
- Subject digest: 5a540ab6cce3e47c9d4e1ca55eeb64075c571c17403e9e1f6b2a9108134c4a45
- Sigstore transparency entry: 2418293809
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl
Upload date: Aug 11, 2026
Size: 4.7 MB
Tags: Python 3, musllinux: musl 1.2+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl
Algorithm	Hash digest
SHA256	`40903b39276611c5627d4172ea01eb52a448c72861808962dc99978a3827564f`
MD5	`50da3db1e23d756d1311b14353ee68e6`
BLAKE2b-256	`c4b9cce083c5cc1dc3d1b13456e54d6792f8ffa49f048ac550419cc440813b48`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-musllinux_1_2_x86_64.whl
- Subject digest: 40903b39276611c5627d4172ea01eb52a448c72861808962dc99978a3827564f
- Sigstore transparency entry: 2418293453
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl
Upload date: Aug 11, 2026
Size: 4.3 MB
Tags: Python 3, musllinux: musl 1.2+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl
Algorithm	Hash digest
SHA256	`43ad5ac2d4ef03626631de9fdb08b6b1184efe6a7aafc0dbe2766ef14d3f5c36`
MD5	`97a28d66e16e6895802a4e8ff161d1a9`
BLAKE2b-256	`109d46296c67427caa752abd85e63c5d0674637c089641c8f8c7760f94bf3d0d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-musllinux_1_2_aarch64.whl
- Subject digest: 43ad5ac2d4ef03626631de9fdb08b6b1184efe6a7aafc0dbe2766ef14d3f5c36
- Sigstore transparency entry: 2418293875
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl
Upload date: Aug 11, 2026
Size: 4.7 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl
Algorithm	Hash digest
SHA256	`87a451834727e2dcd72d02116996ad268f99ea26a43efd57034eacd1d8e8f68c`
MD5	`e0e287b65a7182e8e0e443959c2c8ecf`
BLAKE2b-256	`f758881eea61bfb6bc78cdfe3067f347023e46cc80ede1eb8fa55be46208c2cc`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-manylinux_2_17_x86_64.whl
- Subject digest: 87a451834727e2dcd72d02116996ad268f99ea26a43efd57034eacd1d8e8f68c
- Sigstore transparency entry: 2418293590
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl
Upload date: Aug 11, 2026
Size: 4.5 MB
Tags: Python 3, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl
Algorithm	Hash digest
SHA256	`64f654b1375a1dd6cb9274217184f8aa1ffdf3d8d8392956acf3fdba557f40bf`
MD5	`9a2c7bad506f2017fdffed74b04c05ad`
BLAKE2b-256	`6b40c0c14147c3fdfc624421af5c3a5745e631f4661306a36dcb052f4f2e7186`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-manylinux_2_17_aarch64.whl
- Subject digest: 64f654b1375a1dd6cb9274217184f8aa1ffdf3d8d8392956acf3fdba557f40bf
- Sigstore transparency entry: 2418293739
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-macosx_11_0_arm64.whl
Upload date: Aug 11, 2026
Size: 3.8 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`f60c06f566e46bce8ea2af2ff4ff4605130478759e46c19a998aa14a889626e3`
MD5	`6ac2cc4684c53f23482b13bb119c1d07`
BLAKE2b-256	`5d0caa4dc7da7f5ccfcdfaba6c8d57d3d191ebf40f31f065123c9fa9f3188a29`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-macosx_11_0_arm64.whl
- Subject digest: f60c06f566e46bce8ea2af2ff4ff4605130478759e46c19a998aa14a889626e3
- Sigstore transparency entry: 2418293686
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

File details

Details for the file godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl.

File metadata

Download URL: godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl
Upload date: Aug 11, 2026
Size: 4.0 MB
Tags: Python 3, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`de9b24568f8b3fedbd757ad664dc8401c9bb304758f9aec001d2e9c18adb87a4`
MD5	`49ce3056da35a2a7a1f89a0aae66dfaf`
BLAKE2b-256	`80dfcdd023cceea268f8bf285f1e256c64cff9241b74b5b2993d3874350d44a3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on tomerwave/godharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: godharness-0.1.7-py3-none-macosx_10_12_x86_64.whl
- Subject digest: de9b24568f8b3fedbd757ad664dc8401c9bb304758f9aec001d2e9c18adb87a4
- Sigstore transparency entry: 2418293528
- Sigstore integration time: Aug 11, 2026
Source repository:
- Permalink: tomerwave/godharness@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/tomerwave
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@afe4a453a4e21480263ba6e28ef75a2b3a3fe1ad
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.1.7 This release

Aug 11, 2026 7 files

Aug 9, 2026 7 files

Aug 8, 2026 7 files

Aug 8, 2026 7 files

Aug 8, 2026 7 files

Aug 8, 2026 7 files

Aug 7, 2026 7 files

Aug 7, 2026 7 files

godharness 0.1.7

Godharness: Temporary Product Brief

Problem

Desired Outcome

Product Positioning

Relationship to Godlint

Version 1 Scope

Recommended suite

Repository context

Commands

Installing

Technical Direction

Required Product Properties

Explicit Non-Goals for v1

Later Possibilities

Risks

Open Decisions

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed