Harness-Driven Development

Software best practices don't fail because teams don't know them — they fail because nobody enforces them.

The Problem

The gap between knowing and doing is not a knowledge problem — it's an enforcement problem.

What we KNOW	What we DO	What gets ENFORCED
Commit conventions	Sometimes	Almost never
No secrets in code	After the incident	Sporadically
Tests before merge	On new projects	Until there's pressure
Traceable issues	On "important" PRs	When there's an audit
Definition of Done	In retros	Never mechanically

How It Works

4 skills. 15+ automated actions. Full audit trail.

/start-issue DEMO-1

→

Reads Linear, creates branch, moves to In Progress

"implement dark mode"

→

Writes code, runs tests, validates secrets + refs, push + PR

/close-issue DEMO-1

→

Runs 3 gates, posts evidence, moves to Done

4 Layers of Enforcement

Pre-commit (local)

gitleaks + issue-ref hook. Won't let you commit bad code.

CI (GitHub Actions)

Tests + gitleaks. If it fails, auto-creates bug in Linear.

Harness (AI agent)

close_issue.sh with 3 gates. Won't let you close without evidence.

Webhook (GitHub → Linear)

PR → In Progress, merge → Done. Status syncs automatically.

The "Wow Moment"

A secret blocked in real time — it never reaches GitHub.

    # Moment 1: The mistake we've all made

    git commit -m "add dark mode"

    BLOCKED — gitleaks detected a secret

    # Moment 2: The fix

    mv API_KEY → .env

    git commit -m "add dark mode"

    PASSED

    # Moment 3: Second layer (if --no-verify)

    GitHub Actions → gitleaks

    PR BLOCKED + bug auto-created in Linear

System Components

S Skills

Intelligent commands the agent executes: /create-issue, /start-issue, /close-issue, /status. Each one orchestrates multiple harness actions.

H Harness

Validation scripts that enforce rules: linear_client.py, close_issue.sh, check_issue_ref.sh. ~415 lines total.

T Hooks

Automatic triggers that fire on git events. Pre-commit scans for secrets. Commit-msg validates issue references.

R CLAUDE.md

The agent's rulebook. Defines available skills, harness rules, commit format, and what's forbidden.

Get Started

Fork the repo. Star it. Adapt it to your team.

GitHub Repository Linear Guide GitHub Guide Architecture