sasanksai/harness-writer

Purpose and entry points

harness-writer is a Claude Code plugin/skill that converts a user mission into a generated, persistent “lane”: documents, state, and an .mjs execution engine that a later Claude session can operate. It authors the lane but deliberately does not start execution.

Primary entry points are the Claude Code skill instructions in SKILL.md and plugin metadata in .claude-plugin/plugin.json and .claude-plugin/marketplace.json.

Skill authoring pipeline

The central control flow is a 12-step authoring procedure: scope a mission, create a work plan and lane artifacts, perform adversarial review, fix findings, then distill lessons into the skill’s doctrine. SKILL.md defines this procedure and its non-negotiable red lines.

Generated output is expected to include PLAN.md, CLAUDE.md, HARNESS.md, PROMPT.md, a harness/ runtime, and persisted state/. These are templates/specifications rather than committed example lanes.

Generated harness runtime

The runtime template is references/mjs-template.mjs. It defines the per-task tick lifecycle: rubric-first planning, implementation, blind verification, one repair attempt, and a final drift guard.

The intended runtime boundary is Claude Code’s dynamic Workflow environment and model routing: Fable handles supervision/driver/guard work, Sonnet handles implementation and research, and Opus independently verifies results. The repository itself does not contain a deployed service or long-running application.

Three-ring orchestration model

The architecture separates responsibility across nested loops:

1. Mission loop: human plus Fable manages phases, triage, and retrospectives.

2. Driver loop: Fable gates work, invokes one tick, persists state, commits locally, and schedules continuation.

3. Tick loop: the .mjs engine performs one task through plan, implement, verify, repair, and guard stages.

The generated driver protocol is constrained so state has a single writer, while shell gating is pure-read. The ring-to-playbook binding strategy is documented in references/skill-rings.md.

Reliability and safety gates

The harness doctrine requires fail-closed behavior: preflight checks, dependency-DAG validation, exit-code-based blind verification, failure-to-repair enqueueing, permanent regression checks, and circuit-breaker escalation after repeated failure. These mechanisms prevent self-grading, retry storms, silent bypasses, and mission drift.

Their canonical specification is references/self-repair.md, with supporting rationale in references/design-principles.md.

Doctrine, templates, and evidence boundary

references/doc-templates.md provides the canonical skeletons for generated lane documents, keeping generated artifacts structurally consistent. references/design-principles.md holds the underlying engineering doctrine used by the authoring skill.

Claims incorporated into that doctrine are source-gated: references/sources.md is the evidence ledger, and references/CHANGELOG.md records doctrine changes and corrections. This makes source verification and post-run learning explicit inputs to future harness generation.