EN · ES

Harness-Driven
Development

Orchestrating Linear + GitHub with AI Agents

by Felipe Rangel

Navigate: arrow keys · Back to site

The 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

Why?

"The agent doesn't just write code — it self-enforces the rules your team already knows but can't consistently follow."

4 Commands, 15+ Actions

/create-issue
Add dark mode
→
Criteria
→
Linear
/start-issue
DEMO-1
→
Read Linear
→
Create branch
→
In Progress
code + commit
→
Code
→
Tests
→
Push + PR
/close-issue
DEMO-1
→
3 gates
→
Evidence
→
Done

4 Layers of Enforcement

1 Pre-commit gitleaks + issue-ref hook — "Won't let you commit bad code"
2 CI Tests + gitleaks — "If it fails, the agent detects and fixes it"
3 Harness close_issue.sh with 3 gates — "Won't let you close without evidence"
4 Webhook PR → In Progress, merge → Done — "Status syncs automatically"

System Components

YOU
/create-issue · /start-issue · /close-issue · /status
↓
Skills
Intelligent commands
CLAUDE.md
Rules
↓ invoke
Harness Scripts
linear_client.py · close_issue.sh · check_issue_ref.sh · ci_failure_bridge.py
↓ activate via
Hooks
Auto triggers
↓
Linear
GitHub
CI

The Restaurant Analogy

CLAUDE.md = The operations manual

Skills = The menu recipes

Harness = Quality control

Hooks = Automatic sensors (oven alarm, timer)

The chef (agent) follows the recipes, quality control verifies,
and the sensors fire on their own.

Secret Blocked — Multi-layer Defense

1
git commit — API key in code
gitleaks pre-commit hook scans...
BLOCKED
↓ never reached GitHub
2
Agent detects the problem and fixes it
Removes key from code → moves it to .env
AUTO-FIX
3
git commit — clean code, key in .env
gitleaks scans... clean
PASSED
↓ what if someone uses --no-verify?
4
GitHub Actions runs gitleaks again
Second layer catches it if someone bypasses pre-commit
PR BLOCKED
▷ Live Demo 1 — Metemos una API key → gitleaks bloquea → corregimos → ciclo completo

CI Catches a Bug

1
Add “Export JSON” button
New feature requested via Linear issue
FEATURE
2
Accidental bug in deleteTask
Filter logic inverted during refactor: === instead of !==
BUG
↓ pre-commit passes (no tests) → push → PR
3
GitHub Actions runs tests
“deleteTask removes the card” → FAIL
CI FAILED
4
Fix the bug, push again
Revert === to !== → CI passes → close with evidence
FIXED
▷ Live Demo 2 — Feature + bug accidental → CI lo atrapa → corregimos y cerramos con 3 gates

Gate System

/close-issue DEMO-1

✓
Gate 1/3 — Tests passing? npm test → PASS
✓
Gate 2/3 — CI green? gh run list → PASS
✓
Gate 3/3 — Criteria? Linear API → PASS
ALL PASSED (3/3)
→
Post evidence
→
Done

Before vs After

Without Harness

×
10 manual steps
×
0 automatic verifications
×
0 evidence
×
0 audit trail
×
Secrets can leak

With Harness

✓
4 skills
✓
5+ automatic verifications
✓
Evidence on every close
✓
Full audit trail
✓
Secrets blocked at commit

Key Lesson

"If your tools don't give you control, build your own — it's simpler than you think."

The entire enforcement system fits in <900 lines.
No frameworks. No dependencies. Full control.

Get Started

Fork it. Star it. Adapt it.

github.com/felirangelp/harness-driven-dev

Linear Guide
Team, API key, webhooks
 GitHub Guide
Secrets, CI, Pages, hooks

Setup: ~2 hours · Harness: <900 lines · ROI: immediate

Made by Felipe Rangel