{"id":50118750,"url":"https://github.com/mr-shaper/keel-harness","last_synced_at":"2026-06-06T00:00:49.471Z","repository":{"id":355686808,"uuid":"1228437550","full_name":"mr-shaper/keel-harness","owner":"mr-shaper","description":"Keel — the unseen infrastructure that keeps Claude Code agents honest. 24h cross-session continuity + canonical honesty enforcement + P10-9-8-7 nested parallel agent topology. Karpathy's agentic engineering, made enforceable.","archived":false,"fork":false,"pushed_at":"2026-05-20T17:40:35.000Z","size":11369,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T17:26:19.049Z","etag":null,"topics":["agentic-engineering","ai-agents","claude-code","developer-tools","karpathy","shell"],"latest_commit_sha":null,"homepage":"https://github.com/mr-shaper/keel-harness","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mr-shaper.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":"audit/romeo-6-dim-framework.md","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-04T02:36:04.000Z","updated_at":"2026-05-16T20:42:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mr-shaper/keel-harness","commit_stats":null,"previous_names":["mr-shaper/keel-harness"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/mr-shaper/keel-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-shaper%2Fkeel-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-shaper%2Fkeel-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-shaper%2Fkeel-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-shaper%2Fkeel-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mr-shaper","download_url":"https://codeload.github.com/mr-shaper/keel-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-shaper%2Fkeel-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33964367,"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-05T02:00:06.157Z","response_time":120,"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":["agentic-engineering","ai-agents","claude-code","developer-tools","karpathy","shell"],"created_at":"2026-05-23T17:08:25.275Z","updated_at":"2026-06-06T00:00:49.300Z","avatar_url":"https://github.com/mr-shaper.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# keel-harness\n\n**24-hour Claude Code sessions that don't drift, forget, or fake-pass tests.**\n\n[![CI](https://github.com/mr-shaper/keel-harness/actions/workflows/tests.yml/badge.svg)](https://github.com/mr-shaper/keel-harness/actions/workflows/tests.yml)\n[![Version](https://img.shields.io/badge/version-v0.3.0-blue)](https://github.com/mr-shaper/keel-harness/releases)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n· **🇺🇸 English** · [🇨🇳 中文](README.zh-CN.md)\n\n[Quickstart](#quickstart-5-min) · [What's Inside](#whats-inside-kernel-scope) · [Architecture](#architecture-4-layer-nested-parallel-topology) · [Docs](#documentation)\n\n![Same fresh Claude Code session, with vs without keel — Act 1 Without (lost context, leaked secret, fake test pass) → Act 2 With (handoff carried, secret blocked, claim verified)](demo/demo-5.gif)\n\n\u003e **Without keel:** new session, blank slate. The agent forgets last sprint, re-decides settled questions, commits a stray API key, and tells you the tests pass without running them.\n\u003e\n\u003e **With keel:** new session, same momentum. 9 hooks fire on every tool call. A 7-field handoff carries context across the restart. Secrets get blocked at commit time. *\"Done\"* requires the command output to prove it.\n\n```bash\n# After installing superpowers + PUA (see Required Dependencies below):\ngit clone https://github.com/mr-shaper/keel-harness \u0026\u0026 cd keel-harness \u0026\u0026 bash install.sh\n```\n\nA hook framework + handoff schema + audit gate. Apache-2.0. macOS + Linux. Built on top of [superpowers](https://github.com/obra/superpowers) and [PUA](https://github.com/tanweai/pua).\n\n---\n\n## 30-Second Elevator Pitch\n\nLong Claude Code sessions decay. The agent forgets last sprint's decisions,\nre-debates settled questions, leaks the occasional secret into commits, and\nclaims tests pass without running them. **keel-harness is the infrastructure\nunderneath** — a 7-field handoff schema that survives session restart, 9 hooks\nthat fire on every tool call, a 6-dimension audit gate, and a 4-layer agent\ntopology that keeps the tech-lead AI from quietly slipping into IC mode. Same\nmodel, same prompts — bounded by hooks, anchored to evidence. Apache-2.0,\nmacOS + Linux.\n\n---\n\n## The 4 Gaps It Fills\n\n![4 Gaps + Solutions concept map](docs/visuals/gaps-sketchnote.png)\n\nMost teams hit these walls within weeks of using Claude Code for serious engineering:\n\n- **Gap 1 — 24h session memory loss**: Every new session, the AI forgets what it decided last\n  sprint. harness fixes this with an immutable 7-field handoff schema — written at session stop,\n  read at session start, enforced by hooks. Zero context drift.\n\n- **Gap 2 — Paper victory (Romeo audit blind spots)**: AI claims \"done\" when hooks are registered\n  but never fire. The Romeo 6-dimensional audit framework (Honesty / Ownership / TechDepth /\n  PatternReplay / Density / Candidates) enforces a hardcore ≥0.99 bar across 6 independent\n  dimensions — not a single-axis pass/fail.\n\n- **Gap 3 — P9 role drift**: Your tech lead AI starts writing code instead of writing prompts.\n  The P10-9-8-7 topology with 8 iron rules hard-separates strategy (P10), task-prompt writing\n  (P9), implementation (P8), and sub-tasks (P7) — and enforces it via pre-tool hooks that block\n  role violations before they happen.\n\n- **Gap 4 — Silent dead hooks**: Hooks appear registered in settings.json but never trigger\n  because the Layer 0 contract (CLAUDE.md + settings.json) is incomplete or inconsistent. harness\n  ships a Layer 0 enforcement spec — 5 elements that must all be present or the system silently\n  dies — plus templates you can fill in and ship.\n\n---\n\n## Required Dependencies (install BEFORE running install.sh)\n\nkeel-harness is the **kernel + workflow MDs**. The runtime protocols its\nworkflow MDs reference live in two upstream OSS plugins. Both are MIT-licensed\nand Apache-2.0 compatible. **harness will not function without these.**\n\n`install.sh` Phase 0.5 detects both and ABORTS if either is missing.\n\n### 1. superpowers (MIT, Jesse Vincent / @obra)\n\nProvides: `writing-plans`, `dispatching-parallel-agents`, `test-driven-development`,\n`verification-before-completion`, `brainstorming`, `executing-plans`,\n`subagent-driven-development`.\n\n```bash\nclaude plugin marketplace add obra/superpowers-marketplace\nclaude plugin install superpowers@superpowers-marketplace\n```\n\nRepo: https://github.com/obra/superpowers · License: MIT · Version tested: 5.0.7\n\n### 2. PUA (MIT, TanWei Security Lab / @tanweai)\n\nProvides: P10/P9/P8/P7 role protocols, red-line enforcement, Romeo evaluator,\nparallel agent topology, performance pressure escalation.\n\n```bash\ngit clone https://github.com/tanweai/pua ~/.claude/plugins/pua\n```\n\nRepo: https://github.com/tanweai/pua · License: MIT · Version tested: 3.0.0\n\n### Verification\n\n```bash\nls ~/.claude/plugins/pua/plugin.json   # PUA installed\nls -d ~/.claude/plugins/cache/superpowers-marketplace 2\u003e/dev/null \\\n  || ls -d ~/.claude/plugins/marketplaces/superpowers-marketplace\n```\n\nIf either path is missing, `bash install.sh` will exit 2 with install\ninstructions printed inline. Use `--skip-deps-check` ONLY for\ndevelopment/dogfood.\n\n---\n\n## Bundled Plugins (auto-installed by install.sh)\n\nThese ship inside `plugins/` and get copied to `~/.claude/plugins/\u003cname\u003e/`\nduring Phase 1.5. No separate download.\n\n| Plugin | License | What it provides |\n|---|---|---|\n| **OODC** v1.4.0 | Apache-2.0 (by mr-shaper) | Cognitive loop: Observe → Orient → Decide → Create. 4 reference protocols. Used by `workflows/oodc-superpower-harness-orchestration.md` |\n| **compound-selfcheck** v0.1.0 | Apache-2.0 (by mr-shaper) | PostToolUse soft-prompt: when a Write/Edit produces \u003e 100 LOC or \u003e 5KB, emits a stderr reminder to ingest the change into a knowledge base (Compound Engineering, not one-shot). Audit-logs `[COMPOUND-CHECK]` entries to `.harness/hook-trace.log` for \"real-trigger vs performance\" detection. Soft-prompt only — never blocks. |\n| **kb-fs-adapter** v1.0.0 | Apache-2.0 (by mr-shaper) | Zero-dependency reference KB store adapter (markdown on disk). Implements [KB Store Spec v1.0](docs/kb-store-spec.md) so the compound flywheel works without any specific backend — copy it to adapt Obsidian / Notion / tacit-kb / your own store. |\n\n---\n\n## Quickstart (5 min)\n\n\u003e **Prerequisites**: superpowers + PUA installed (see Required Dependencies above).\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mr-shaper/keel-harness/main/install.sh | bash\n```\n\nUntil you have the one-liner cached, manual bootstrap:\n\n```bash\n# Step 1: Clone the kernel\ngit clone https://github.com/mr-shaper/keel-harness.git ~/.claude/plugins/keel-harness-mp\n\n# Step 2: Apply Layer 0 contract templates\ncp ~/.claude/plugins/keel-harness-mp/templates/CLAUDE.md.global.template ~/.claude/CLAUDE.md\n# Edit ~/.claude/CLAUDE.md — fill in the \u003cPLACEHOLDER\u003e fields for your context\n\n# Step 3: Merge hooks into settings.json (requires jq)\njq -s '.[0] * .[1]' \\\n  ~/.claude/settings.json \\\n  ~/.claude/plugins/keel-harness-mp/templates/settings.json.template \\\n  \u003e /tmp/settings-merged.json \u0026\u0026 mv /tmp/settings-merged.json ~/.claude/settings.json\n# Restart Claude Code — harness hooks are now active\n```\n\nAfter install, start your first harnessed session:\n\n```\n1. Read .harness/handoff-S\u003cN-1\u003e-to-S\u003cN\u003e.md   — previous session's authoritative next_action\n2. Answer 5 self-checks (Q1 project / Q2 next_action / Q3 clarity / Q4 handoff name / Q5 week)\n3. Work — Stop hook writes the next handoff automatically\n```\n\n### Standard Plan-Authoring Prompt (copy-paste this for any non-trivial task)\n\nWhen you give the agent a task that has 3+ steps, multi-file changes, or\ncrosses module boundaries, paste this prompt verbatim. It binds the agent\nto the harness execution contract and prevents the most common failure\nmode (skipping workflow reads, which causes the UserPromptSubmit hook to\nemit warnings mid-conversation).\n\n```text\nFor this task, design and execute the plan under the four-layer nested\nparallel topology of harness:\n\n  Harness  ⊃  OODC  ⊃  PUA P10-9-8-7  ⊃  Superpower Pipeline\n\nThe plan itself must read as a guide that future executing agents follow\nunder the same topology — annotate each Wave / Phase with which layer\ndrives it (which OODC step, which role tier, which Pipeline phase).\n\nBefore drafting the plan, READ these five workflow MDs (skipping them\ntriggers a UserPromptSubmit warning that interrupts the conversation):\n\n  1. workflows/pua-topology.md\n  2. workflows/oodc-superpower-harness-orchestration.md\n  3. workflows/superpower-pipeline.md\n  4. workflows/skill-loading-sop.md\n  5. workflows/kb-ingestion-sop.md\n\nThen verify any Skill you intend to invoke is REALLY loaded\n(skill-loading-sop §5 — five dimensions: tool-call, references body Read,\nprotocol applied, sub-agent injection, evidence-aligned self-eval).\nA Skill listed in inventory is not the same as a Skill actually loaded.\n\nWave / Phase tracking is mandatory: every Wave and every Phase in the\nplan MUST have a TaskCreate entry. The TaskCreate list IS the Superpower\nPipeline stage tracker — update statuses as you progress\n(pending → in_progress → completed). No Wave without a task entry.\n\nOnce the plan is drafted with topology annotations, ratification gates,\nand TaskCreate entries, present it for approval before execution.\n```\n\nThe full version of this contract — failure modes, role definitions,\nskill verification protocol — lives in\n[`docs/agent-execution-standard.md`](docs/agent-execution-standard.md).\n\nFor more user-facing prompts (project bootstrap, sprint kickoff, sprint\nclose, etc.), see [`docs/quickstart-prompts.md`](docs/quickstart-prompts.md).\n\n---\n\n## What's Inside (Kernel Scope)\n\nThe kernel is the minimum viable harness — no private configuration, no personal plugins,\nno company-specific logic. Everything that ships is universally applicable to any Claude Code\npower user.\n\n### Workflow Documentation (5 files)\n\n| File | What it encodes |\n|---|---|\n| `workflows/pua-topology.md` | P10-9-8-7 nested parallel topology + 8 iron rules |\n| `workflows/oodc-superpower-harness-orchestration.md` | OODC loop (Observe → Orient → Decide → Create) orchestration across Harness + Superpower + PUA layers |\n| `workflows/superpower-pipeline.md` | Phase 0-4 engineering pipeline (kickoff → parallel explore → decision convergence → dev → close) |\n| `workflows/skill-loading-sop.md` | Skill discovery + loading SOP — prevents hallucinated tool calls |\n| `workflows/kb-ingestion-sop.md` | Knowledge base ingestion pipeline — Compound Engineering, not one-shot generation |\n\n### Hooks (9 enforce-core hooks)\n\n| Hook | Type | What it enforces |\n|---|---|---|\n| `stop-handoff-writer.sh` | Stop | Writes 7-field handoff at every session end |\n| `pre-tool-handoff-read-gate.sh` | PreToolUse | Blocks file writes until handoff is read (sticky flag) |\n| `pre-tool-handoff-semantic-gate.sh` | PreToolUse | Semantic check — prevents writing wrong session's handoff |\n| `user-prompt-l42-workflow-trigger-gate.sh` | UserPromptSubmit | Routes trigger words (harness/OODC/PUA/Superpower) to the correct workflow MD |\n| `pre-tool-doc-sync-sop-enforce.sh` | PreToolUse | Enforces doc-sync routing before any knowledge base write |\n| `post-tool-chmod-ci-gate.sh` | PostToolUse | chmod guard — prevents CI scripts from losing execute bit silently |\n| `session-start-layer0-health.sh` | SessionStart | Layer 0 health check — verifies all 5 contract elements are present |\n| `pre-tool-plan-quality-gate.sh` | PreToolUse | Blocks low-quality plan writes (Romeo ≥0.99 gate) |\n\n### Templates\n\n- `templates/handoff-template.md` — 7-field handoff schema (sprint / next_action / blockers / decisions / files_changed / self_check / romeo_score)\n- `templates/cat-h-rule-template.md` — Category H canonical law template (for adding new ratified rules)\n- `templates/CLAUDE.md.global.template` — Generic global Claude Code contract (~180 LOC, scrubbed of personal config)\n- `templates/CLAUDE.md.project.template` — Generic project contract (~50 LOC, 5-must-reads + 5-self-checks + bible principles placeholder)\n- `templates/settings.json.template` — Generic settings.json with 9 hooks registered (~125 LOC, 8 enforce-core + 1 compound-selfcheck plugin hook)\n\n### Audit Framework\n\n- `audit/romeo-6-dim-framework.md` — Romeo 6-dimensional audit spec (Honesty / Ownership / TechDepth / PatternReplay / Density / Candidates), ≥0.99 hardcore gate, evidence-alignment rules\n- `docs/sprint-kickoff-checklist.md` — Five-layer GATE self-check (Layer A entity / B content / C gate / D config / E behavior fire). Mandatory at every sprint kickoff to prevent score inflation\n\n### Tooling\n\n- `sync.sh` — 5-command sync (init / export / import / diff / release) with 5-layer privacy protection\n- `scripts/sync-self-check.sh` — Cross-platform 5-layer evidence dump. Read-only by design: maintainer reads the dump and self-evaluates sprint outcome (the script never decides outcome itself — P9-doesn't-decide-L4 pattern)\n- `manifest.json` — Kernel file whitelist + private blacklist keywords (what stays in, what never ships)\n- `install.sh` — One-line bootstrap (ships W3)\n- `CHANGELOG.md` — [Keep a Changelog](https://keepachangelog.com/) format, semver tags\n- `LICENSE` — Apache-2.0\n\n---\n\n## Demos (asciinema → agg-rendered GIFs)\n\nThree additional reproducible demos cover the gaps in motion:\n\n| # | Demo | Length | Gap |\n|---|---|---|---|\n| 1 | [24h Cross-Session Continuity](demo/demo-1.gif) | 3 min | Gap 1 — AI memory loss |\n| 2 | [4-Layer Nested Parallel — 7 P8 → 7× speedup](demo/demo-2.gif) | 2 min | Gap 3 — P9 role drift |\n| 3 | [Canonical Honesty Hooks — 5-layer defense](demo/demo-3.gif) | 2.5 min | Gap 2 — paper victory |\n\nReproduce locally: `brew install asciinema agg \u0026\u0026 bash demo/record.sh all`\n\n---\n\n## Architecture: 4-Layer Nested Parallel Topology\n\n![4-Layer Nested Parallel Topology infographic](docs/visuals/topology-infograph.png)\n\n```\n═══════════════════════════════════════════════════════════════════\nHarness (cross-session, weeks to months)\n   │\n   └─ OODC (Observe → Orient → Decide → Create, 1 major goal = 1 loop)\n        │\n        └─ Superpower Pipeline (Phase 0 → 1 → 2 → 3 → 4)\n             │   Phase 0  kickoff (load skills + create tasks + manifest draft)\n             │   Phase 1  parallel exploration (brainstorm, retro, compete scan)\n             │   Phase 2  decision convergence (P10 ratifies, no more options)\n             │   Phase 3  development  (N waves of true parallel P8 agents)\n             │   Phase 4  close (launch / retrospective / handoff)\n             │\n     CEO (the human user) — ultimate authority, sits above all AI roles\n       │  ratifies / overrides P10 ; final trump card on every strategic decision\n       ↓\n             └─ PUA P10 / P9 / P8 / P7  (all AI roles)\n                  P10  = CTO (AI strategy layer) — ratifies under CEO, dispatches to P9, never writes code\n                  P9   = Tech Lead — writes Task Prompts, never writes code\n                  P8   = Senior Eng — same-message true parallel, owns a file domain\n                  P7   = P8-spawned sub-agent — granular sub-tasks\n═══════════════════════════════════════════════════════════════════\n```\n\n### The 8 P9 Iron Rules (never violate)\n\n1. P9 dispatches multiple P8s in a single message — true parallel, not sequential\n2. P8 spawns P7 internally — P9 never manages P7 directly\n3. P10 never writes Task Prompts, never manages P8\n4. **P9 never writes code** — writing code = role drift = automatic PUA 3.5 penalty\n5. **CEO (the human user) always overrides P10** — CEO is human, P10 is the AI CTO; CEO is the ultimate authority above the entire AI hierarchy\n6. File domain isolation — grep-verify no overlap before dispatch\n7. Same-message multi-Agent = true parallel (not loop-sequential)\n8. P9 runs verification commands and pastes output — no empty claims\n\n---\n\n## The 5 Words We Want in the Agent Engineering Vocabulary\n\nharness-engineering introduces 5 precise concepts that fill gaps in the current agent\nengineering lexicon:\n\n| Term | Definition |\n|---|---|\n| **Thin Watering Principle** | Apply harness constraints as a thin, universal layer — never couple enforcement to private personal config. The harness should work for anyone without modification. |\n| **7-Field Handoff Schema** | The minimum viable handoff: `sprint / next_action / blockers / decisions / files_changed / self_check / romeo_score`. Missing any field = the next session is flying blind. |\n| **Romeo 6-Dim Audit** | Six independent dimensions — Honesty, Ownership, TechDepth, PatternReplay, Density, Candidates — each scored 0-1.00. Overall bar: average ≥0.99 hardcore. Not a checklist, a judgment framework. |\n| **Canonical Honesty Rule** | Every claim requires evidence paste. \"It works\" without command output = 0 points. The hook system enforces this at the PreToolUse layer, before the AI can write a completion. |\n| **4-Layer Nested Parallel** | Harness ⊃ OODC ⊃ Superpower Phase 0-4 ⊃ PUA P10-9-8-7. Concurrency at every layer. Not just \"run agents in parallel\" — structured parallelism with role separation and file domain isolation. |\n\n---\n\n## Documentation\n\nWorkflow MDs ship as part of the kernel. English versions land in W2:\n\n- [`workflows/pua-topology.md`](workflows/pua-topology.md) — P10-9-8-7 topology + 8 iron rules\n- [`workflows/oodc-superpower-harness-orchestration.md`](workflows/oodc-superpower-harness-orchestration.md) — OODC loop orchestration\n- [`workflows/superpower-pipeline.md`](workflows/superpower-pipeline.md) — Phase 0-4 engineering pipeline\n- [`workflows/skill-loading-sop.md`](workflows/skill-loading-sop.md) — Skill loading SOP\n- [`workflows/kb-ingestion-sop.md`](workflows/kb-ingestion-sop.md) — KB ingestion + Compound Engineering\n\n---\n\n## Optional Integrations (advanced)\n\nThe two REQUIRED plugins (superpowers + PUA) and the BUNDLED plugin (OODC) are\ncovered above. Below are three additional plugins referenced indirectly by\nharness workflow MDs. They are **not bundled** and **not auto-installed**.\nReview each project's license before use — Apache-2.0 compatibility is your\nresponsibility.\n\n- **claude-mem** (`--with-claude-mem`): Persistent semantic memory across sessions. **AGPL-3.0** — strong copyleft, your responsibility to comply.\n- **tacit-kb** (`--with-tacit-kb`): **MIT, public** ([github.com/mr-shaper/tacit-kb](https://github.com/mr-shaper/tacit-kb)). The Compound Engineering KB that powers the harness's compound flywheel (decisions / exemplars / analogies / evolution). Works key-free with local BM25 search; an optional embedding key upgrades it to hybrid semantic search. As of **v0.3**, tacit-kb is just *one* backend behind the generic **[KB Store Spec](docs/kb-store-spec.md)** — the kernel ships a zero-dependency markdown adapter ([`plugins/kb-fs-adapter/`](plugins/kb-fs-adapter/)) by default and works with **no** KB store at all (compound features degrade to the reminder hook). Bring Obsidian, Notion, or your own store by implementing the contract.\n- **doc-sync** (`--with-docsync`): Document synchronization + knowledge-base ingestion routing. The KB engine is the published **[tacit-kb](https://github.com/mr-shaper/tacit-kb)** (MIT, public) — same backend as `--with-tacit-kb`.\n\n\u003e These plugins were built for a specific engineering context. They work best\n\u003e when you already understand the harness topology. Start with the\n\u003e required + bundled, add these only when you feel the gap.\n\n---\n\n## Compatibility\n\n| Platform | Status |\n|---|---|\n| macOS Sonoma 14+ (Apple Silicon + Intel) | Tested |\n| macOS Monterey 12 / Ventura 13 | Should work (bash 3.2+) |\n| Ubuntu 22.04 LTS (x86_64) | Tested (W6 cross-platform verify) |\n| Ubuntu 20.04 LTS | Should work |\n| Windows (WSL2) | Untested, community welcome |\n\n**Requirements**: `bash 3.2+` · `jq` · `git` · Claude Code CLI\n\nInstall jq if missing:\n```bash\n# macOS\nbrew install jq\n\n# Ubuntu / Debian\nsudo apt-get install -y jq\n```\n\n---\n\n## License\n\n[Apache-2.0](LICENSE)\n\nYou are free to use, modify, and distribute this software for any purpose. The Apache-2.0 license\nincludes a patent grant — appropriate for infrastructure frameworks. See LICENSE for full terms.\n\n---\n\n## Credits\n\n- **Mitchell Hashimoto** — \"harness engineering\" naming. The concept of a thin harness layer\n  that constrains and shapes a more powerful underlying system without replacing it.\n- **Andrej Karpathy** — Agentic engineering vision. The Why behind structured AI agent\n  engineering: systems that are reliable, auditable, and production-grade. harness is the How.\n- **Jesse Vincent** — superpowers plugin architecture. The Skill system that makes harness\n  workflow MDs composable and discoverable.\n\n---\n\n## Contributing\n\nIssues and PRs welcome. Before opening a PR:\n\n1. Read `workflows/pua-topology.md` — understand the P8 file domain isolation rule\n2. Every claim in the PR description needs evidence (command output, test results)\n3. New hooks: must pass Layer 0 health check + add a test in `tests/`\n4. New workflow MDs: must follow the 7-field handoff schema and Romeo audit format\n\nIf you find a use case the kernel doesn't cover, open an issue before building — the kernel\nscope is intentionally narrow. Scope creep is the enemy of a reusable harness.\n\n---\n\n*\"The goal is not to make AI smarter. The goal is to make AI reliable.\"*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-shaper%2Fkeel-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmr-shaper%2Fkeel-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-shaper%2Fkeel-harness/lists"}