convez.ai
Skill
jazz1x

harnish

jazz1x/harnish

Ver no GitHub
InicialPluginScore · de 0 a 100

Harness Claude for autonomous implementation — turn every failure into a guardrail and let context persist across sessions and worktrees.

Instalação

$npx convez-ai jazz1x/harnish

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
v0.4.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

harnish

Claude Code plugin — autonomous implementation engine

version license claude-code tests python

harnish (harness + ish) — an implementation environment that gets smarter as you work. Failures become guardrails, patterns accumulate, and context persists across sessions and worktrees.

한국어

Skills

SkillCommandRole
drafti-feature/harnish:drafti-featurePlanning-based implementation spec PRD
drafti-architect/harnish:drafti-architectTech-driven design PRD generation
impl/harnish:implAutonomous implementation engine — the "harnish" engine (seeding + ralph loop + anchoring + experience)

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.

Each skill operates in an independent orbit, connected only through shared artifacts (files).

galmuri:forki  ──→  forces a binary decision (sibling plugin, pre-PRD)
                       ↓
drafti  ──→  docs/prd-*.md  ──→  harnish  ──→  implementation code
                                     │
                                     └── .harnish/ (work coordinates + experience, in user project CWD)
                                     │
                                     └── galmuri:ralphi (post-Done inspection, sibling plugin)

Requirements

  • 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).
  • Claude Code — plugin host.
  • No jq dependency as of v0.1.0.

Install

Option 1 — npx skills add (recommended)

Works with Claude Code, Cursor, Codex, Windsurf, and other skills.sh-compatible agents.

npx skills add jazz1x/harnish               # install into ./.claude/skills/ (project)
npx skills add jazz1x/harnish -g            # install into ~/.claude/skills/ (global)
npx skills add jazz1x/harnish --list        # list skills before installing
npx skills add jazz1x/harnish --skill impl  # install a single skill

Expected output:

✓ Installed jazz1x/harnish — 3 skills (drafti-feature, drafti-architect, impl)

Option 2 — Claude Code native plugin

Inside a Claude Code session:

/plugin marketplace add https://github.com/jazz1x/harnish.git
/plugin install harnish

Expected output:

✓ Installed harnish@0.4.0 — 3 skills registered (drafti-feature, drafti-architect, impl)

Verify with /plugin list. The three slash commands below should be invocable:

/harnish:drafti-feature
/harnish:drafti-architect
/harnish:impl

Hooks are auto-registered via hooks/hooks.json — see the Hooks section.

Uninstall

/plugin uninstall harnish
/plugin marketplace remove harnish

The .harnish/ directory inside your project is not removed automatically — delete it manually if you want to wipe the accumulated assets.


Quickstart

Once installed, the fastest path end-to-end:

# Inside a Claude Code session, in any project that has a PRD or planning doc
/harnish:impl

Sample flow:

user > /harnish:impl docs/prd-redis-cache.md
       → 3 phases, 12 atomic tasks seeded into .harnish/harnish-current-work.json
user > loop
       → task 1.1 → code → log → asset recorded → auto-advance 1.2 → … → Phase 1 done
       → milestone report → continue Phase 2? (y/n)

If invoked with no PRD path or task description, harnish will ask:

What would you like to implement? Provide a PRD file path or describe the task.

In a new session, simply say "continue where I left off" — harnish restores coordinates from harnish-current-work.json and resumes from the break point.

Usage

Decision forcing has moved to galmuri:forki (install galmuri). Use it pre-PRD when a binary fork needs to be surfaced.

1. PRD Generation (Design)

User: "Create a PRD from this planning doc" (with planning document attached)
→ drafti-feature generates implementation spec PRD (feature flags only when needed)
→ generates docs/prd-user-profile-edit.md

User: "Design a Redis cache layer"
→ drafti-architect explores 2-3 design alternatives with trade-off analysis
→ generates docs/prd-redis-cache.md

2. Autonomous Implementation (harnish)

User: /harnish:impl
→ "What would you like to implement? Provide a PRD file path or describe the task."

User: "Start implementation" or "Decompose tasks"
→ Decomposes PRD into atomic tasks → generates harnish-current-work.json
→ "3 Phases, 12 Tasks seeded — review then 'run the loop'"

User: "Run the loop"
→ The ralph loop runs one task at a time until the phase is done
  (named after Ralph Wiggum — keep trying, don't give up; not an acronym)
→ Updates harnish-current-work.json every 3 actions, milestone report on phase completion

User: (in a new session) "Continue where I left off"
→ Restores coordinates from harnish-current-work.json, auto-resumes from break point

3. Experience Accumulation

User: "Remember this pattern"
→ Records as pattern asset → auto-referenced in future work

User: "Asset status"
→ Shows accumulated failure/pattern/guardrail/snippet/decision assets

User: "Make this a skill"
→ Bundles compressed assets into a SKILL.md scaffold (with raw asset
  bodies + a TODO marker). The LLM must finalize the body — this is a
  draft generator, not autonomous skill graduation. Truly autonomous
  promotion is a planned future feature.

Hooks

harnish registers the following hooks automatically on install via hooks/hooks.json. No configuration needed.

EventTriggerWhat it does
PostToolUseBash, Edit, Write, NotebookEditScans tool output for failure patterns, guardrails, and reusable snippets → records to .harnish/
PostToolUseFailureBash, Edit, Write, NotebookEditCaptures meaningful failure context (noise patterns filtered) → records as failure asset for future reference
StopSession endRuns quality gate + threshold check on accumulated assets, then cleans up session pending files

Failures 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.

Memory Model

harnish runs a two-tier memory system. Each tier serves a different role; the bridge between them is currently semi-manual.

TierStorageLifetimeRoleLoaded as
Tier 1 — Asset Store (episodic).harnish/harnish-assets.jsonlPer-project, accumulates across sessions, TTL-purgedRecords what happened (failures, patterns, guardrails, snippets, decisions)Injected into context on demand via query-assets.sh --format inject (this is the actual RAG path)
Tier 2 — Skills (procedural)skills/*/SKILL.mdPermanent (versioned in source tree)Codifies stable behaviorAuto-loaded by Claude Code as triggerable skills

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):

  • Frontmatter Triggers: auto-extracted from asset titles
  • Body sectioned by asset type, with metadata (level / confidence / stability / resolved)
  • references/source-assets.jsonl preserves originals for traceability
  • §1 still needs LLM finalization of 1-3 actionable guidelines — draft generator, not autonomous graduation

Trigger → Record → Skillify pipeline (closed in v0.0.5; pure-Python implementation in v0.1.0, .sh files are 1-line wrappers):

PostToolUseFailure  →  detect-asset.sh (noise filter)  →  /tmp/harnish-pending-*.jsonl
Stop                →  promote-pending.sh (dedup)      →  harnish-assets.jsonl
"make it a skill"   →  skillify.sh                     →  SKILL.md draft + references/

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.

Assets

Every accumulated learning is recorded in .harnish/harnish-assets.jsonl (one JSON object per line). Six asset types:

TypeCaptured when
failureA meaningful tool failure occurs (filtered for signal)
patternUser says "remember this pattern" or recurring success structure detected
guardrailA rule emerges from repeated failures (e.g. "always retry with backoff on 503")
snippetReusable code fragment worth quoting verbatim
decisionA galmuri:forki output worth carrying forward
compressedMultiple related assets merged into one summary (auto-suggested at threshold)

Inspect / manage assets:

bash scripts/check-thresholds.sh [--threshold N]              # current count vs. compression threshold
bash scripts/query-assets.sh --tags api,retry --format text   # query by tag
bash scripts/compress-assets.sh --dry-run --all               # preview compression
bash scripts/quality-gate.sh                                  # rerun the Stop-event quality check
bash scripts/purge-assets.sh                                  # dry-run purge (--execute to apply)
bash scripts/migrate.sh                                       # backfill schema to latest version

.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).

Worktrees

Each worktree gets its own .harnish/ directory based on CWD. Work coordinates and experience are fully isolated per worktree — no shared state, no write conflicts.

/project/.harnish/                      ← main tree
/project/.claude/worktrees/A/.harnish/  ← worktree A
/other/path/worktree-B/.harnish/        ← worktree B (physical separation)

Fork & Customize

Three ways to use this repo as a base:

A. Cherry-pick a single skill into your project

mkdir -p .claude/skills
cp -r /path/to/harnish/skills/impl .claude/skills/

The skill is available as impl (no plugin namespace). Replace impl with any of: drafti-feature, drafti-architect.

B. Fork as your own plugin marketplace

gh repo fork jazz1x/harnish --clone
cd harnish
# edit .claude-plugin/plugin.json (name, author, repository)
# edit .claude-plugin/marketplace.json (owner, plugin entries)
# add/remove/modify skills under skills/
git commit -am "fork: rebrand"
git push

C. Use as read-only upstream

git clone https://github.com/jazz1x/harnish.git
cd your-project
claude --plugin-dir /path/to/harnish
git -C /path/to/harnish pull   # update later

Naming

  • harnish = harness + ish (autonomous implementation engine)
    • The ralph loop inside impl is named after Ralph Wiggum from The Simpsons — keep trying, don't give up
  • drafti = draft + i (PRD generation — drafti-feature + drafti-architect)
  • forki = fork + i (decision forcing) — moved to galmuri
  • ralphi = ralph + i (inspection) — moved to galmuri

Triad

harnish sits in a triad of sibling plugins — independent, connected by shared artifacts only:

harnish (make)  ──→  honne (know)  ──→  galmuri (keep)
  execution         reflection          refinement
  • harnish — autonomous implementation engine
  • honne — evidence-backed self-reflection (6-axis persona)
  • galmuri — summary · decision-deck · documentation

License

MIT — See LICENSE.

Ver o original no GitHub

Bom para

Relacionados