{"id":50708182,"url":"https://github.com/harnessprotocol/harness-protocol","last_synced_at":"2026-06-09T13:03:02.052Z","repository":{"id":362621981,"uuid":"1177482702","full_name":"harnessprotocol/harness-protocol","owner":"harnessprotocol","description":"Open spec for portable AI coding agent configuration","archived":false,"fork":false,"pushed_at":"2026-06-05T06:00:59.000Z","size":810,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:24:12.047Z","etag":null,"topics":["ai-agents","ai-coding","claude-code","copilot","cursor","developer-tools","harness-protocol","mcp","specification","yaml"],"latest_commit_sha":null,"homepage":"https://harnessprotocol.ai","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harnessprotocol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T04:13:43.000Z","updated_at":"2026-06-05T05:10:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harnessprotocol/harness-protocol","commit_stats":null,"previous_names":["harnessprotocol/harness-protocol"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/harnessprotocol/harness-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnessprotocol%2Fharness-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnessprotocol%2Fharness-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnessprotocol%2Fharness-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnessprotocol%2Fharness-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harnessprotocol","download_url":"https://codeload.github.com/harnessprotocol/harness-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnessprotocol%2Fharness-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34107866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","claude-code","copilot","cursor","developer-tools","harness-protocol","mcp","specification","yaml"],"created_at":"2026-06-09T13:03:01.133Z","updated_at":"2026-06-09T13:03:02.040Z","avatar_url":"https://github.com/harnessprotocol.png","language":"MDX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Harness Protocol\n\n\u003e **Status:** v1 Schema layer — candidate\n\nThe Harness Protocol is an open specification for portable AI coding harnesses — a vendor-neutral `harness.yaml` format that captures the complete operational context for an AI coding agent: plugins, skills, MCP servers, environment requirements, behavioral instructions, permissions, and governance policy. It is to AI coding harnesses what the Model Context Protocol (MCP) is to tool communication.\n\nAI coding tools like Claude Code, Cursor, and GitHub Copilot each have their own proprietary formats for capturing agent context. A developer who crafts a well-tuned configuration for one tool cannot share it with a teammate on a different tool, publish it for their team to reuse, or carry it when they switch tools. The Harness Protocol defines a common format so that harness configurations become portable, shareable artifacts — the same way MCP made tool communication portable.\n\n---\n\n## Protocol Layers\n\nThe specification is organized into three layers, each building on the previous.\n\n| Layer | Description | Status |\n|-------|-------------|--------|\n| **Schema** | The `harness.yaml` format, JSON Schema validation, security model, plugin manifest | v1 — current |\n| **Exchange** | Harness-to-harness sharing: publish, fetch, and compose harnesses across tools and teams | v2 — draft ([HEP-7](heps/hep-0007-exchange-layer.md)) |\n| **Registry** | Hosted discovery at harnessprotocol.io: search, publish, version resolution, integrity verification | v2/v3 — draft ([HEP-8](heps/hep-0008-registry-layer.md)) |\n\nLayers are intentionally decoupled. A tool can implement Schema-layer validation today without any dependency on exchange or registry infrastructure.\n\n---\n\n## harness.yaml\n\nA harness profile is a YAML file validated against the Harness Protocol JSON Schema. The minimal valid profile:\n\n```yaml\n$schema: https://harnessprotocol.io/schema/v1/harness.schema.json\nversion: \"1\"\nmetadata:\n  name: my-harness\n  description: A minimal valid Harness Protocol v1 profile.\n```\n\nA fuller example showing common fields:\n\n```yaml\n$schema: https://harnessprotocol.io/schema/v1/harness.schema.json\nversion: \"1\"\nmetadata:\n  name: data-engineer\n  description: Harness for data engineering work in Go and SQL.\n  author:\n    name: acme-org\n\nplugins:\n  - name: sql-explorer\n    source: acme-org/sql-explorer\n    version: \"^1.2.0\"\n    integrity:\n      sha256: \"abc123def456...\"\n\nmcp-servers:\n  filesystem:\n    transport: stdio\n    command: npx\n    args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/workspace\"]\n\nenv:\n  - name: DATABASE_URL\n    description: Primary database connection string\n    required: true\n    sensitive: true\n\ninstructions:\n  operational: file://./instructions/operational.md\n  import-mode: merge\n\npermissions:\n  tools:\n    allow: [Read, Glob, Grep, Write, Edit]\n    deny: [\"mcp__*__drop_*\"]\n```\n\nThe full field reference is in [protocol/profile-schema.md](protocol/profile-schema.md). The JSON Schema is the authoritative validation source.\n\n---\n\n## Getting Started\n\n[harness-kit](https://github.com/harnessprotocol/harness-kit) is the reference implementation of the Harness Protocol. It provides a parser, validator, plugin loader, MCP server lifecycle manager, and CLI for working with `harness.yaml` profiles. Start there to use the protocol today.\n\nConformance does not require harness-kit — any implementation that correctly validates and applies `harness.yaml` per this specification is conformant.\n\n---\n\n## Documentation\n\nFull documentation is available at [harnessprotocol.io/spec](https://harnessprotocol.io/spec).\n\n| Document | Content |\n|----------|---------|\n| [protocol/overview.md](protocol/overview.md) | What the protocol is and how the layers fit together |\n| [protocol/terminology.md](protocol/terminology.md) | Glossary of all terms used in the spec |\n| [protocol/architecture.md](protocol/architecture.md) | System diagram, layer interactions, trust model |\n| [protocol/profile-schema.md](protocol/profile-schema.md) | Full `harness.yaml` field reference |\n| [protocol/plugin-manifest.md](protocol/plugin-manifest.md) | `plugin.json` format for plugin authors |\n| [protocol/mcp-declarations.md](protocol/mcp-declarations.md) | MCP server transport types, variable substitution, security |\n| [protocol/instructions.md](protocol/instructions.md) | Instruction slots, content sources, import modes |\n| [protocol/environment.md](protocol/environment.md) | Environment variable declarations and sensitive data handling |\n| [protocol/fragments.md](protocol/fragments.md) | `kind: fragment` — partial harness documents for composition |\n| [protocol/inheritance.md](protocol/inheritance.md) | `extends` resolution order and per-section merge rules |\n| [protocol/application.md](protocol/application.md) | Application pipeline, effective configuration, error handling |\n| [protocol/source-resolution.md](protocol/source-resolution.md) | Source resolution algorithm for `owner/repo` and local path references |\n| [protocol/exchange.md](protocol/exchange.md) | *(v2 draft)* Exchange layer — the signed offer envelope and consent-first sharing flow |\n| [protocol/registry.md](protocol/registry.md) | *(v2 draft)* Registry layer — hosted discovery, integrity hashing, and the transparency log |\n| [security/threat-model.md](security/threat-model.md) | Threat model and security design |\n| [security/trust-boundaries.md](security/trust-boundaries.md) | Trust boundaries between spec, implementations, profiles, and remote content |\n| [security/secrets.md](security/secrets.md) | Sensitive variable handling and secrets patterns |\n| [security/permissions.md](security/permissions.md) | Permission model and enforcement |\n| [security/integrity.md](security/integrity.md) | Content integrity verification |\n| [security/instruction-injection.md](security/instruction-injection.md) | Instruction injection threat and mitigations |\n| [security/skill-injection.md](security/skill-injection.md) | Skill behavioral injection threat and mitigations |\n| [security/exchange.md](security/exchange.md) | *(v2 draft)* Exchange threat model — authenticity, consent, confidentiality in transit |\n| [security/registry.md](security/registry.md) | *(v2 draft)* Registry threat model — the registry is an index, not a trust anchor |\n| [security/crypto-map.md](security/crypto-map.md) | How SHA-256 integrity, ed25519 (Exchange), and minisign signing compose |\n\n## Where to Start\n\n**Harness authors** (writing `harness.yaml` files):\n1. [protocol/profile-schema.md](protocol/profile-schema.md) — the complete field reference\n2. [examples/](examples/) — annotated example profiles to copy from\n3. [schema/draft/harness.schema.json](schema/draft/harness.schema.json) — validate your file\n\n**Tool implementers** (building a harness implementation):\n1. [protocol/overview.md](protocol/overview.md) — what the protocol is and how layers fit together\n2. [protocol/architecture.md](protocol/architecture.md) — system model and trust boundaries\n3. [protocol/application.md](protocol/application.md) — the 7-step application pipeline\n4. [protocol/source-resolution.md](protocol/source-resolution.md) — how `owner/repo` references resolve\n5. [protocol/profile-schema.md](protocol/profile-schema.md) — the normative field specification\n6. [security/](security/) — security model, sensitive data rules, and threat model\n\n---\n\n## Contributing\n\nSpec changes go through the HEP (Harness Enhancement Proposal) process. Editorial fixes can be submitted directly as pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the security policy and responsible disclosure process.\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharnessprotocol%2Fharness-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharnessprotocol%2Fharness-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharnessprotocol%2Fharness-protocol/lists"}