The Gibson

The governance harness for your coding agents.

A portable, self-improving SDLC harness for agent fleets: describe what you want in
plain language, and the fleet plans, builds, tests, reviews, and ships it under gates
you can audit.

Start here, based on who you are:

• 🙂 "I'm not technical — I just want software built." Read
  VIBECODING.md. It's the only page you need, and it has no jargon.
  Wondering what you'd even build? Five real examples.
• 🔧 "I run the fleet." QUICKSTART.md then GUIDE.md.
• 🍴 "I want to fork this for my own team." Read
  docs/18-fork-and-upstream.md — customize in
  local/, keep getting upstream improvements.
• 🤖 "I'm an agent." Load AGENTS.md (always mandatory). If a role is dispatched, also load that role playbook. If no role is named, you are a builder and must load playbooks/builder.md. If a job is dispatched, also load that job's dispatch prompt. docs/ is on-demand and non-normative.
• 📚 Reading order by audience: docs/00-INDEX.md ·
  FAQ.md · docs/00-glossary.md

Everything in this repo follows one interaction rule, the Ask Contract:
whenever the system asks a human for anything, it says what it's asking, what
it does, why, and the risks — in plain language, with every technical term
explained. If any doc here fails that standard, that's a bug: open an issue.

Point it at any repo. Give it a well-scoped plan. The fleet decomposes the plan into
issues, builds, tests, reviews, security-scans, UI/UX-grades against live deployments,
and ships to Vercel — and does not stop unless a human gate requires it. Every failure
that happens twice becomes a permanent improvement to the harness itself.

"Agent = Model + Harness." The model is rented. The harness is yours, and it
compounds. — after Fowler, Harness Engineering

Named for the supercomputer in Hackers (1995) — which shares its name with
William Gibson, who said "The future is already here — it's just not evenly
distributed." The Gibson is a piece of that unevenly-distributed future. It's
Apache-2.0 so it doesn't have to stay that way. You don't hack The Gibson.
The Gibson hacks the backlog.

What it is

The Gibson is a doctrine + tooling repo that gets installed into target projects.
It is deliberately agent-agnostic: the canonical harness is plain Markdown, shell
scripts, and GitHub Actions — things every runtime (Claude Code, OpenAI Codex, Grok,
Hermes, pi) can read and every CI can enforce. Vendor-specific ergonomics (Claude
skills, Codex configs, Grok loop drivers) are thin adapters over the same core.

Three layers:

The Gibson is the harness. Mission Control
remains the runtime control plane (task queue, telemetry, cross-vendor dispatch).
They compose: Mission Control decides who works; The Gibson decides how they work.

The pipeline at a glance

PLAN ─▶ DECOMPOSE ─▶ BUILD ─▶ TEST ─▶ REVIEW ─▶ UI/UX EVAL ─▶ SECURITY ─▶ MERGE ─▶ DEPLOY ─▶ RETRO
 │         │           │        │        │          │            │          │         │        │
 spec +    GitHub      worktree green    multi-lens Playwright   SAST/DAST/ human     Vercel   lessons →
 design    issues w/   + scope  gate     tiered,    vs. preview  authz/     gate on   promote  harness
 language  contracts   claims            x-vendor   deployment   secrets    Tier C    + verify PRs

flowchart LR
  subgraph doctrine["Doctrine"]
    AG["AGENTS.md"]
    DOCS["docs/01–19"]
    PB["playbooks/"]
  end
  subgraph pipeline["SDLC pipeline"]
    P[Plan] --> D[Decompose]
    D --> B[Build]
    B --> T[Test]
    T --> R[Review]
    R --> U[UX eval]
    U --> S[Security]
    S --> M[Merge]
    M --> V[Deploy + verify]
    V --> H[Retro / historian]
    H -.->|ratchet| AG
  end
  subgraph enforce["Enforcement"]
    SCR["scripts/"]
    CI["ci/"]
  end
  subgraph memory["Memory"]
    LES["LESSONS.md"]
    DEC["DECISIONS.md"]
  end
  subgraph external["Control plane"]
    MC["Mission Control\nqueue + telemetry"]
  end
  AG --> P
  PB --> B
  PB --> R
  PB --> U
  SCR --> B
  CI --> R
  H --> LES
  MC -.->|dispatch| B
  MC -.->|dispatch| R

Full detail: docs/02-sdlc-pipeline.md

Core principles (the short version)

1. Guides + Sensors. Feedforward controls steer agents before they act (docs,
   conventions, scaffolds); feedback controls catch and correct after (linters, tests,
   review agents). Both are harness artifacts, both are improvable.
2. Never grade your own homework. Generation and evaluation are separate agents,
   ideally separate vendors. Evaluators are tuned to skepticism and verify against
   running software, not diffs.
3. Primitives, not features. A minimal core any runtime can execute; everything
   else is an extension. (After pi.dev.)
4. The ratchet. A failure that happens twice is a harness bug, not a model bug.
   It must become a new guide or sensor — often authored by the agent that hit it.
5. Agent-agnostic core, vendor-thin edges. If a rule only works in one vendor's
   runtime, it isn't doctrine yet.
6. Autonomy by default, human gates by exception. Agents do not stop to ask
   permission for reversible work inside a claimed scope. The closed stop list
   is in AGENTS.md; docs/14-human-gates.md
   is on-demand rationale only.

Documentation map

Provenance

Synthesized from five sources, credited throughout:

• ConferenceOS (mrhinkle/conference-os) — the battle-tested mechanics: worktree
  isolation, scope claims, green gate, tiered review, schema safety, Vercel guard.
• Mission Control (mrhinkle/mission-control) — cross-vendor dispatch, task
  queue, shared runtime memory, "route by task class, not loyalty."
• Fowler — Harness Engineering —
  guides/sensors, computational vs. inferential controls, the self-correcting loop.
• Anthropic — Harness design for long-running agents —
  planner/generator/evaluator separation, sprint contracts, Playwright evaluation,
  context resets via file handoffs, frontend design language at plan time.
• pi.dev and ruvnet — primitives-not-features,
  self-modifying extensions, multi-host adapters, versioned memory substrates.

License

Apache License 2.0 — Copyright 2026 Mark Hinkle. Fork it, customize it, run it
(see docs/18-fork-and-upstream.md); contributions
back are welcome through the same pipeline the harness uses on itself.