{
  "markdown": "# harnish\n\n> Claude Code plugin — autonomous implementation engine\n\n![version](https://img.shields.io/badge/version-0.4.0-blue)\n![license](https://img.shields.io/badge/license-MIT-green)\n![claude-code](https://img.shields.io/badge/claude--code-plugin-purple)\n![tests](https://img.shields.io/badge/tests-145%20passing-brightgreen)\n![python](https://img.shields.io/badge/python-3.14%2B-blue)\n\n**harnish** (harness + ish) — an implementation environment that gets smarter as you work. Failures become guardrails, patterns accumulate, and context persists across sessions and worktrees.\n\n[한국어](./README.ko.md)\n\n## Skills\n\n| Skill | Command | Role |\n|-------|---------|------|\n| **drafti-feature** | `/harnish:drafti-feature` | Planning-based implementation spec PRD |\n| **drafti-architect** | `/harnish:drafti-architect` | Tech-driven design PRD generation |\n| **impl** | `/harnish:impl` | Autonomous implementation engine — the \"harnish\" engine (seeding + ralph loop + anchoring + experience) |\n\n> **Decision & inspection moved**: `forki` (`galmuri:forki`) and `ralphi` (`galmuri:ralphi`) have graduated to the sibling plugin **galmuri**. harnish now calls them cross-plugin where needed.\n\nEach skill operates in an **independent orbit**, connected only through **shared artifacts (files)**.\n\n```\ngalmuri:forki  ──→  forces a binary decision (sibling plugin, pre-PRD)\n                       ↓\ndrafti  ──→  docs/prd-*.md  ──→  harnish  ──→  implementation code\n                                     │\n                                     └── .harnish/ (work coordinates + experience, in user project CWD)\n                                     │\n                                     └── galmuri:ralphi (post-Done inspection, sibling plugin)\n```\n\n## Requirements\n\n- **Python 3.14+** — runtime for all `scripts/*.sh` (they delegate to `scripts/harnish_py/` via 1-line wrappers; the `sys.version_info < (3, 14)` guard exits with code 4 on older interpreters).\n- **Claude Code** — plugin host.\n- **No `jq` dependency** as of v0.1.0.\n\n## Install\n\n### Option 1 — `npx skills add` (recommended)\n\nWorks with Claude Code, Cursor, Codex, Windsurf, and other skills.sh-compatible agents.\n\n```bash\nnpx skills add jazz1x/harnish               # install into ./.claude/skills/ (project)\nnpx skills add jazz1x/harnish -g            # install into ~/.claude/skills/ (global)\nnpx skills add jazz1x/harnish --list        # list skills before installing\nnpx skills add jazz1x/harnish --skill impl  # install a single skill\n```\n\nExpected output:\n\n```\n✓ Installed jazz1x/harnish — 3 skills (drafti-feature, drafti-architect, impl)\n```\n\n### Option 2 — Claude Code native plugin\n\nInside a Claude Code session:\n\n```\n/plugin marketplace add https://github.com/jazz1x/harnish.git\n/plugin install harnish\n```\n\nExpected output:\n\n```\n✓ Installed harnish@0.4.0 — 3 skills registered (drafti-feature, drafti-architect, impl)\n```\n\nVerify with `/plugin list`. The three slash commands below should be invocable:\n\n```\n/harnish:drafti-feature\n/harnish:drafti-architect\n/harnish:impl\n```\n\nHooks are auto-registered via `hooks/hooks.json` — see the [Hooks](#hooks) section.\n\n### Uninstall\n\n```\n/plugin uninstall harnish\n/plugin marketplace remove harnish\n```\n\nThe `.harnish/` directory inside your project is **not** removed automatically — delete it manually if you want to wipe the accumulated assets.\n\n---\n\n## Quickstart\n\nOnce installed, the fastest path end-to-end:\n\n```\n# Inside a Claude Code session, in any project that has a PRD or planning doc\n/harnish:impl\n```\n\nSample flow:\n\n```\nuser > /harnish:impl docs/prd-redis-cache.md\n       → 3 phases, 12 atomic tasks seeded into .harnish/harnish-current-work.json\nuser > loop\n       → task 1.1 → code → log → asset recorded → auto-advance 1.2 → … → Phase 1 done\n       → milestone report → continue Phase 2? (y/n)\n```\n\nIf invoked with no PRD path or task description, harnish will ask:\n\n```\nWhat would you like to implement? Provide a PRD file path or describe the task.\n```\n\nIn a new session, simply say \"continue where I left off\" — harnish restores coordinates from `harnish-current-work.json` and resumes from the break point.\n\n## Usage\n\n> Decision forcing has moved to `galmuri:forki` (install [galmuri](https://github.com/jazz1x/galmuri)). Use it pre-PRD when a binary fork needs to be surfaced.\n\n### 1. PRD Generation (Design)\n\n```\nUser: \"Create a PRD from this planning doc\" (with planning document attached)\n→ drafti-feature generates implementation spec PRD (feature flags only when needed)\n→ generates docs/prd-user-profile-edit.md\n\nUser: \"Design a Redis cache layer\"\n→ drafti-architect explores 2-3 design alternatives with trade-off analysis\n→ generates docs/prd-redis-cache.md\n```\n\n### 2. Autonomous Implementation (harnish)\n\n```\nUser: /harnish:impl\n→ \"What would you like to implement? Provide a PRD file path or describe the task.\"\n\nUser: \"Start implementation\" or \"Decompose tasks\"\n→ Decomposes PRD into atomic tasks → generates harnish-current-work.json\n→ \"3 Phases, 12 Tasks seeded — review then 'run the loop'\"\n\nUser: \"Run the loop\"\n→ The ralph loop runs one task at a time until the phase is done\n  (named after Ralph Wiggum — keep trying, don't give up; not an acronym)\n→ Updates harnish-current-work.json every 3 actions, milestone report on phase completion\n\nUser: (in a new session) \"Continue where I left off\"\n→ Restores coordinates from harnish-current-work.json, auto-resumes from break point\n```\n\n### 3. Experience Accumulation\n\n```\nUser: \"Remember this pattern\"\n→ Records as pattern asset → auto-referenced in future work\n\nUser: \"Asset status\"\n→ Shows accumulated failure/pattern/guardrail/snippet/decision assets\n\nUser: \"Make this a skill\"\n→ Bundles compressed assets into a SKILL.md scaffold (with raw asset\n  bodies + a TODO marker). The LLM must finalize the body — this is a\n  draft generator, not autonomous skill graduation. Truly autonomous\n  promotion is a planned future feature.\n```\n\n## Hooks\n\nharnish registers the following hooks automatically on install via `hooks/hooks.json`. No configuration needed.\n\n| Event | Trigger | What it does |\n|-------|---------|--------------|\n| `PostToolUse` | Bash, Edit, Write, NotebookEdit | Scans tool output for failure patterns, guardrails, and reusable snippets → records to `.harnish/` |\n| `PostToolUseFailure` | Bash, Edit, Write, NotebookEdit | Captures meaningful failure context (noise patterns filtered) → records as failure asset for future reference |\n| `Stop` | Session end | Runs quality gate + threshold check on accumulated assets, then cleans up session pending files |\n\nFailures are classified by signal-to-noise: simple errors (`No such file`, `permission denied`, `command not found`, etc.) are filtered out so only meaningful failures become assets.\n\n## Memory Model\n\nharnish runs a **two-tier memory** system. Each tier serves a different role; the bridge between them is currently semi-manual.\n\n| Tier | Storage | Lifetime | Role | Loaded as |\n|------|---------|----------|------|-----------|\n| **Tier 1 — Asset Store** (episodic) | `.harnish/harnish-assets.jsonl` | Per-project, accumulates across sessions, TTL-purged | Records what happened (failures, patterns, guardrails, snippets, decisions) | Injected into context on demand via `query-assets.sh --format inject` (this is the actual RAG path) |\n| **Tier 2 — Skills** (procedural) | `skills/*/SKILL.md` | Permanent (versioned in source tree) | Codifies stable behavior | Auto-loaded by Claude Code as triggerable skills |\n\n`skillify.sh` is the bridge — it bundles compressed Tier-1 assets into a Tier-2 SKILL.md scaffold. The scaffold is **production-grade** (since v0.0.5; reimplemented in Python in v0.1.0):\n\n- Frontmatter `Triggers:` auto-extracted from asset titles\n- Body sectioned by asset type, with metadata (level / confidence / stability / resolved)\n- `references/source-assets.jsonl` preserves originals for traceability\n- §1 still needs LLM finalization of 1-3 actionable guidelines — draft generator, not autonomous graduation\n\n**Trigger → Record → Skillify pipeline** (closed in v0.0.5; pure-Python implementation in v0.1.0, `.sh` files are 1-line wrappers):\n\n```\nPostToolUseFailure  →  detect-asset.sh (noise filter)  →  /tmp/harnish-pending-*.jsonl\nStop                →  promote-pending.sh (dedup)      →  harnish-assets.jsonl\n\"make it a skill\"   →  skillify.sh                     →  SKILL.md draft + references/\n```\n\n> **Why \"assets\" not \"RAG\"?** Only `query-assets.sh --format inject` is RAG in the strict sense. The rest is capture / summarize / age-out / feed-into-skill — i.e. asset CRUD + lifecycle.\n\n## Assets\n\nEvery accumulated learning is recorded in `.harnish/harnish-assets.jsonl` (one JSON object per line). Six asset types:\n\n| Type | Captured when |\n|------|---------------|\n| `failure` | A meaningful tool failure occurs (filtered for signal) |\n| `pattern` | User says \"remember this pattern\" or recurring success structure detected |\n| `guardrail` | A rule emerges from repeated failures (e.g. \"always retry with backoff on 503\") |\n| `snippet` | Reusable code fragment worth quoting verbatim |\n| `decision` | A `galmuri:forki` output worth carrying forward |\n| `compressed` | Multiple related assets merged into one summary (auto-suggested at threshold) |\n\nInspect / manage assets:\n\n```bash\nbash scripts/check-thresholds.sh [--threshold N]              # current count vs. compression threshold\nbash scripts/query-assets.sh --tags api,retry --format text   # query by tag\nbash scripts/compress-assets.sh --dry-run --all               # preview compression\nbash scripts/quality-gate.sh                                  # rerun the Stop-event quality check\nbash scripts/purge-assets.sh                                  # dry-run purge (--execute to apply)\nbash scripts/migrate.sh                                       # backfill schema to latest version\n```\n\n`.harnish/` lives inside your project CWD and persists across sessions. `impl`, `drafti-feature`, and `drafti-architect` reference relevant assets automatically (tag-based query in Step 2 of each skill).\n\n## Worktrees\n\nEach worktree gets its own `.harnish/` directory based on CWD. Work coordinates and experience are fully isolated per worktree — no shared state, no write conflicts.\n\n```\n/project/.harnish/                      ← main tree\n/project/.claude/worktrees/A/.harnish/  ← worktree A\n/other/path/worktree-B/.harnish/        ← worktree B (physical separation)\n```\n\n## Fork & Customize\n\nThree ways to use this repo as a base:\n\n### A. Cherry-pick a single skill into your project\n\n```bash\nmkdir -p .claude/skills\ncp -r /path/to/harnish/skills/impl .claude/skills/\n```\n\nThe skill is available as `impl` (no plugin namespace). Replace `impl` with any of: `drafti-feature`, `drafti-architect`.\n\n### B. Fork as your own plugin marketplace\n\n```bash\ngh repo fork jazz1x/harnish --clone\ncd harnish\n# edit .claude-plugin/plugin.json (name, author, repository)\n# edit .claude-plugin/marketplace.json (owner, plugin entries)\n# add/remove/modify skills under skills/\ngit commit -am \"fork: rebrand\"\ngit push\n```\n\n### C. Use as read-only upstream\n\n```bash\ngit clone https://github.com/jazz1x/harnish.git\ncd your-project\nclaude --plugin-dir /path/to/harnish\ngit -C /path/to/harnish pull   # update later\n```\n\n## Naming\n\n- **harnish** = harness + ish (autonomous implementation engine)\n  - The ralph loop inside impl is named after Ralph Wiggum from The Simpsons — keep trying, don't give up\n- **drafti** = draft + i (PRD generation — drafti-feature + drafti-architect)\n- **forki** = fork + i (decision forcing) — **moved to [galmuri](https://github.com/jazz1x/galmuri)**\n- **ralphi** = ralph + i (inspection) — **moved to [galmuri](https://github.com/jazz1x/galmuri)**\n\n## Triad\n\nharnish sits in a triad of sibling plugins — independent, connected by shared artifacts only:\n\n```\nharnish (make)  ──→  honne (know)  ──→  galmuri (keep)\n  execution         reflection          refinement\n```\n\n- [harnish](https://github.com/jazz1x/harnish) — autonomous implementation engine\n- [honne](https://github.com/jazz1x/honne) — evidence-backed self-reflection (6-axis persona)\n- [galmuri](https://github.com/jazz1x/galmuri) — summary · decision-deck · documentation\n\n## License\n\nMIT — See [LICENSE](./LICENSE).\n",
  "bytes": 12250,
  "sha": "da6c7ddaddc8b23756fa4e5cfd6bc87129b58b0d3afa3a0811f111035ccbecf5",
  "repo_slug": "jazz1x/harnish",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jazz1x_harnish_harnish_a6783e58/readme"
}