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.

Project links

Data verified by PyPI on Aug 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.7)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tomerwave from gravatar.com tomerwave

GitHub Statistics

Data verified by PyPI on Aug 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.8

Classifiers

Report project as malware

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.

godharness-0.1.1-py3-none-win_amd64.whl (3.1 MB view details)

Uploaded Python 3Windows x86-64

godharness-0.1.1-py3-none-musllinux_1_2_x86_64.whl (4.5 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

godharness-0.1.1-py3-none-musllinux_1_2_aarch64.whl (4.2 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

godharness-0.1.1-py3-none-manylinux_2_17_x86_64.whl (4.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

godharness-0.1.1-py3-none-manylinux_2_17_aarch64.whl (4.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

godharness-0.1.1-py3-none-macosx_11_0_arm64.whl (3.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

godharness-0.1.1-py3-none-macosx_10_12_x86_64.whl (3.8 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: godharness-0.1.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.1 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.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 446cc1522669c0e6264a116721cf6d513fdafc580bfeabbbd0a6e5ec7529583c
MD5 947eef417442c0ff31598fd5b0f4a0a0
BLAKE2b-256 a4c7e1ef294ce1e0d56fab6a41cac2a2b46ac0076c76d32e2bc267246a11f724

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 5bdc9f5ac01ac62d95e8a27cb4f2e9d1c03c7faa81f61affdb76e7fc24ca0955
MD5 b0bfc3eb22a1ce2e0d1324144129b911
BLAKE2b-256 56ad2b9f90d1f8c1db00d8c293db2e68720171765260cd433aac86d5cddd4b0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 19dffdffbe5a50a67c6cd5476023a2963e1a2a420c06d13d2ec9a584a881d34e
MD5 2438bef1ce12455af127fc6b8e9ff651
BLAKE2b-256 77caa9a424e933f58f74542f0224712c646bf5f163a2901b0a9417d580920a0b

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 b86aad71f989408917d1e603736f38ca1728e76bdce73f173be3a39a9ec83e66
MD5 429e57143125b42a0c4983ec9a3bf0bc
BLAKE2b-256 0ac48724f5fb6142b873bb84d5c94e890ca55b4df6f19003c662941a76fb0221

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 b3ad8af138d86ead4773443afa13f2a734127c9aafd23429572a4f3784ef9164
MD5 028804084bf218d0bdd89972bf9b8241
BLAKE2b-256 3f9edb46ff9f783173c45059900ad7764ded46d0c518203b44697a68a22087eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 75cb76a85e7a759a431d36d0c24b27909e4606f273af8f6585e31528d865ccc5
MD5 89bcee61807307e8fdc8d49aee27fe27
BLAKE2b-256 0bbb00d8b4d1a20da38373e813dff05fea0df473cf47455e245db430d8cdcb71

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

File details

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

File metadata

File hashes

Hashes for godharness-0.1.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 78441421f6441405750be39af19683745f5f660177e40cdd6cf8c01267f08965
MD5 5a8dfb1250f6e990cb0b1f0b15bfeff8
BLAKE2b-256 db8b097779371b0fe0885ed3d3c419817fcc9b9e8788babc5ecc7a80dc3ea45c

See more details on using hashes here.

Provenance

The following attestation bundles were made for godharness-0.1.1-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.

Release history Release notifications | RSS feed

0.1.7

7 files

0.1.6

7 files

0.1.5

7 files

0.1.4

7 files

0.1.3

7 files

0.1.2

7 files

This release

0.1.1 This release

7 files

0.1.0

7 files

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