{"id":51583039,"url":"https://github.com/hoangnb24/repository-harness","last_synced_at":"2026-07-30T08:00:34.233Z","repository":{"id":356432930,"uuid":"1229708435","full_name":"hoangnb24/repository-harness","owner":"hoangnb24","description":"Turn any repo into an agent-ready workspace for Claude Code, Codex, Cursor, and other coding agents.","archived":false,"fork":false,"pushed_at":"2026-07-26T08:43:02.000Z","size":3399,"stargazers_count":1126,"open_issues_count":0,"forks_count":403,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-07-27T03:05:17.222Z","etag":null,"topics":["agents-md","ai-agents","ai-assisted-development","claude-code","codex","coding-agents","context-engineering","cursor","harness-engineering","software-engineering","templates","vibe-coding"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoangnb24.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-05T10:02:30.000Z","updated_at":"2026-07-26T13:21:26.000Z","dependencies_parsed_at":"2026-07-11T07:05:01.532Z","dependency_job_id":null,"html_url":"https://github.com/hoangnb24/repository-harness","commit_stats":null,"previous_names":["hoangnb24/harness-experimental","hoangnb24/repository-harness"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/hoangnb24/repository-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangnb24%2Frepository-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangnb24%2Frepository-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangnb24%2Frepository-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangnb24%2Frepository-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoangnb24","download_url":"https://codeload.github.com/hoangnb24/repository-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangnb24%2Frepository-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36067204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-30T02:00:05.956Z","response_time":106,"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":["agents-md","ai-agents","ai-assisted-development","claude-code","codex","coding-agents","context-engineering","cursor","harness-engineering","software-engineering","templates","vibe-coding"],"created_at":"2026-07-11T08:00:23.474Z","updated_at":"2026-07-30T08:00:34.144Z","avatar_url":"https://github.com/hoangnb24.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# repository-harness\n\nTurn a software repository into a legible, agent-ready workspace.\n\n`repository-harness` gives coding agents a small entrypoint, structured\nrepository knowledge, durable execution plans when work truly needs them, and\nmechanical validation. The repository—not a hidden workflow database—is the\ndefault system of record.\n\nThe app is what users touch. The harness is what makes the app and its rules\neasy for agents and humans to understand.\n\n## Why This Exists\n\nCoding agents commonly fail for ordinary engineering reasons:\n\n- important constraints live only in chat or in someone's head;\n- the repository does not say which documents are authoritative;\n- small changes are wrapped in process that obscures the actual work;\n- large changes lose decisions and progress between sessions;\n- validation is vague, late, or disconnected from user-visible behavior.\n\nThe answer is not a longer mandatory workflow. It is a repository that exposes\nthe right context at the right time and enforces important invariants with\ntests and scripts.\n\nThis direction is anchored in OpenAI's\n[Harness engineering](https://openai.com/index/harness-engineering/) account:\nkeep the agent entrypoint small, make repository knowledge navigable, store\ncomplex execution plans durably, make application behavior directly\ninspectable, and enforce architectural rules mechanically.\n\n## The Default Workflow\n\nStart with [`AGENTS.md`](AGENTS.md), then follow the map in\n[`docs/WORKFLOW.md`](docs/WORKFLOW.md). The size of the request determines the\namount of durable process:\n\n```text\nread-only question\n  -\u003e inspect the smallest authoritative surface\n  -\u003e answer with evidence\n\nbounded change\n  -\u003e inspect locally\n  -\u003e change code or docs\n  -\u003e run relevant proof\n  -\u003e report the result\n\nmulti-session or coordination-heavy change\n  -\u003e create docs/plans/active/\u003cplan\u003e.md\n  -\u003e record progress, decisions, and validation in Git\n  -\u003e move the finished plan to docs/plans/completed/\n\nconsequential ambiguity\n  -\u003e pause before mutation\n  -\u003e present the concrete choice and its effects\n  -\u003e continue after authority is clear\n```\n\nA typo fix does not need intake, a story row, or a trace. A migration spanning\nseveral sessions does need a durable plan. A request to “simplify permissions”\nwithout saying whether existing access may be revoked needs human judgment\nbefore code changes. These are independent decisions, not risk levels on one\nprocess ladder.\n\n## Repository Knowledge\n\n- [`AGENTS.md`](AGENTS.md) — compact, stable entrypoint for agents.\n- [`docs/WORKFLOW.md`](docs/WORKFLOW.md) — canonical request and execution flow.\n- [`docs/HARNESS.md`](docs/HARNESS.md) — design principles and system model.\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — boundaries and dependency\n  direction.\n- [`docs/product/`](docs/product/) — current product behavior and constraints.\n- [`docs/plans/`](docs/plans/) — active and completed durable execution plans.\n- [`docs/decisions/`](docs/decisions/) — durable architectural decisions.\n- [`docs/templates/exec-plan.md`](docs/templates/exec-plan.md) — plan template.\n- [`docs/README.md`](docs/README.md) — complete documentation map, including\n  optional compatibility surfaces.\n- [`tests/README.md`](tests/README.md) — behavior ownership, validation entry\n  points, and removal boundaries for test suites.\n\nThe default path requires no local database. Product documents, code, tests,\nplans, decisions, and Git history form one inspectable source of truth.\n\n## Install Harness Into A Project\n\nFrom a target project directory, run:\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)\" | bash -s -- --yes\n```\n\nOn Windows PowerShell:\n\n```powershell\n\u0026 ([scriptblock]::Create((irm \"https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1\"))) -Yes\n```\n\nUse `--merge` / `-Merge` to add missing Harness files without replacing\nexisting project files. Use `--override` / `-Override` only when replacement is\nintentional. Use `--dry-run` / `-DryRun` to preview writes.\n\nThe default installation downloads a checksum-verified Rust binary named\n`harness`, then uses it to install the small repository-centered core. It does\nnot install the optional SQLite compatibility CLI, discover schemas, install\ndatabase bootstrap scripts, or add database ignore rules. It also does not copy\nthis upstream repository's README or architecture over consumer-owned truth.\nThe core includes the explicit-only `$onboard-repository` and\n`$audit-onboarding-proposal` skills. They never run during installation or\nordinary tasks.\n\nTo map a brownfield repository after installation, ask the agent to run:\n\n```text\n$onboard-repository\n```\n\nThe first pass is read-only and returns evidence-backed proposals. Exact user\napproval is required before a later pass may apply selected repository\nguidance.\n\n## Optional Engineering Wisdom\n\nThe neutral default does not install engineering philosophy. To add the\nexplicit-only `engineering-wisdom` advisory pack to a fresh project:\n\n```bash\nscripts/install-harness.sh --with-engineering-wisdom --yes /path/to/project\n```\n\n```powershell\n./scripts/install-harness.ps1 -WithEngineeringWisdom -Yes -Directory C:\\path\\to\\project\n```\n\nFor a project that already has Harness, add `--merge` / `-Merge`. This preserves\nexisting files and fills only the missing pack files:\n\n```bash\nscripts/install-harness.sh --merge --with-engineering-wisdom --yes /path/to/project\n```\n\nInstallation does not run or activate the skill. Invoke it explicitly:\n\n```text\n$engineering-wisdom review this payment change\n```\n\nIts review separates repository observations, contextual heuristics,\ncounter-pressure, proposed repository-owned enforcement, and verification.\nAdvice cannot silently become policy or trigger an architecture rewrite.\nRepository intent and tests remain authoritative.\n\nWithout the opt-in flag, a fresh or normal installation does not copy the\npack. Re-running the installer without the flag also leaves an already\ninstalled pack untouched; omission is non-activation, not removal. To remove\nthe stateless pack, delete only `.agents/skills/engineering-wisdom/`:\n\n```bash\nrm -r .agents/skills/engineering-wisdom\n```\n\n```powershell\nRemove-Item -Recurse .agents/skills/engineering-wisdom\n```\n\nThe concise bibliography acknowledges Robert C. Martin's broader body of work,\nincluding code, design, testing, refactoring, architecture, and professional\npractice. Its ideas are paraphrased and presented as fallible heuristics.\n\nAfter installation, preview and apply future core upgrades with:\n\n```bash\nscripts/bin/harness update --dry-run\nscripts/bin/harness update\nscripts/bin/harness status\nscripts/bin/harness doctor\n```\n\n`update` reads the published core-release pointer, downloads the platform binary\nand checksum from that exact versioned `harness-v*` GitHub release, verifies its\nbytes and version identity, and lets that candidate merge its embedded core.\nIt refuses downgrades and replaces only the selected repository's local\nexecutable. The updater keeps\nthe installed upstream base under\n`.harness-core/`, performs a three-way merge, and backs up changed files before\nactivation. On Windows, use `scripts\\bin\\harness.exe`.\n\nAn overlapping local/upstream edit stops without changing managed files or the\ninstalled executable. Harness stages BASE, LOCAL, UPSTREAM, and RESOLVED copies\nunder `.harness-core/update/`, freezes all other managed inputs, and retains the\nremotely re-verifiable candidate under `.harness-core/update-candidate/`. After\nan agent explains the semantic choice and\nreceives human direction, edit the RESOLVED copy and run:\n\n```bash\nscripts/bin/harness update --continue --dry-run\nscripts/bin/harness update --continue\n```\n\nUse `scripts/bin/harness update --abort` to discard the staged resolution. A\ncontinuation fails if any managed file or staged input changed after conflict\ndetection.\n\nInstallations older than the first release containing self-update discovery\ncannot discover that release with their old executable. Refresh those once with\nthe platform installer; subsequent releases use `harness update` directly.\n\nFor an older installation with a generated, long `AGENTS.md`, refresh it to the\nsmall marked block:\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)\" | bash -s -- --merge --refresh-agent-shim --yes\n```\n\nFor Claude Code, add `--claude` (PowerShell: `-Claude`). This creates or updates\na marked block in `CLAUDE.md` that imports `AGENTS.md`; existing local\ninstructions are preserved and backed up before changes.\n\n## Try The Flow\n\n[`docs/demo/README.md`](docs/demo/README.md) follows concrete examples through\nthe four workflow cases. The important cause and effect is simple:\n\n- small entrypoint → less instruction loading and less drift;\n- authoritative repository map → agents retrieve only relevant context;\n- plans only for genuinely durable work → small changes stay cheap while long\n  work survives session boundaries;\n- repo-native tests → completion is proved by behavior rather than workflow\n  bookkeeping;\n- explicit pause conditions → consequential product choices remain human-owned.\n\n## Optional Compatibility Control Plane\n\nThe Rust CLI, SQLite schema, feature intake, story matrix, trace scoring,\nimprovement proposals, and orchestration contract remain supported for an\nexternal runner or team that explicitly selects them. They are not\nprerequisites for ordinary repository work.\n\nInstall that complete compatibility bundle explicitly:\n\n```bash\nscripts/install-harness.sh --with-cli --yes /path/to/project\n```\n\n```powershell\n./scripts/install-harness.ps1 -WithCli -Yes -Directory C:\\path\\to\\project\n```\n\nThen bootstrap its ignored local database:\n\n```bash\nscripts/bootstrap-harness.sh\n```\n\n```powershell\n.\\scripts\\bootstrap-harness.ps1\n```\n\nThen use `scripts/bin/harness-cli` (or the Windows `.exe`). See\n[`scripts/README.md`](scripts/README.md) and\nthe [`compatibility index`](docs/compatibility/README.md).\nOne independent consumer is\n[Symphony](https://github.com/hoangnb24/symphony); it is not installed as part\nof this repository. Symphony owns work selection, agent runs, worktrees,\nconflict/retry policy, changeset coordination, PR/review synchronization, and\nits runtime evidence. Harness retains only the generic atomic protocol\nprimitives that protect repository state.\n\n## Repository Structure\n\n```text\nproject/\n  .agents/\n    skills/\n      onboard-repository/\n      audit-onboarding-proposal/\n  AGENTS.md\n  docs/\n    WORKFLOW.md\n    HARNESS.md\n    ARCHITECTURE.md\n    product/\n    plans/\n      active/\n      completed/\n    decisions/\n    templates/\n  scripts/\n  tests/\n```\n\n## Contributing\n\nSee [the contributing guide](https://github.com/hoangnb24/repository-harness/blob/main/CONTRIBUTING.md).\nEspecially useful contributions are\nreal agent failure cases, examples of application legibility, mechanical\narchitecture checks, smaller default instructions, and validation that proves\nuser-visible behavior.\n\nShort description:\n\n\u003e A repository-centered engineering harness for coding agents: compact\n\u003e instructions, navigable context, durable plans when needed, decisions, and\n\u003e executable validation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangnb24%2Frepository-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoangnb24%2Frepository-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangnb24%2Frepository-harness/lists"}