@ok-org/overkill

OK (Overkill)

A spec-driven, blueprint-first agentic coding OS that works inside any coding agent — Claude Code, Cursor, Codex, Cline, Windsurf, or anything that reads markdown. OK is a deterministic Node CLI plus a set of markdown workflows. It never calls an LLM — your coding agent is the brain; OK is the skeleton, memory, and power tools around it.

The core idea: before any real code is written, every source file gets a semantic English blueprint (purpose, functions, flow, dependencies, constraints). Agents code from blueprints instead of reading the whole codebase — which slashes context usage and keeps work consistent. Everything mechanical is done by deterministic tools, so it costs zero tokens.

[!IMPORTANT]

💡 The OK Philosophy: Autonomous Leverage for Developers Who Know How to Code

Most AI builders are toys built for "no-coders" who want simple, throwaway UI prototypes. They guess your folder structures, write buggy spaghetti code, and break completely at scale.

OK is the opposite. It is designed for expert developers who refuse to trade away their architectural control, security standards, and standard coding practices for speed.

With OK, you—the senior architect—use your expertise to scaffold the layout (STRUCTURE.md), inject performance/security rules (.ok/skills/), and draft semantic boundaries in plain English (.blueprint.md). Once your expert boundaries are locked, OK's autonomous sequencer (ok goal) executes construction, wave scheduling, unit testing, and self-repair unattended.

You get 10x engineering leverage without losing 1% of your professional control.

Install

npm install -g overkill      # provides `ok` and `overkill`
cd your-project
ok init                      # detects your agent, installs entry files + .ok/,
                             # and syncs the global skills store once

Quick start — one command

ok mvp --idea "a CLI that splits a bill across people with tip"

Then run /ok:mvp in your coding agent: it refines the idea (planning mode → measurable GOAL) and drives the whole pipeline — research → structure → blueprints → build → verify → audit — to a working, verified MVP. Track it with ok mvp --status.

Pipeline

FRONT (you review)                         BACK (autonomous — `ok goal`)
/ok:new-project → /ok:research →           /ok:graphify → /ok:execute →
/ok:import-skills → /ok:structure (review) /ok:test (repair loop) → /ok:audit
→ /ok:precode (review blueprints)

• Front half has two human checkpoints: STRUCTURE.md and the blueprints.
• /ok:goal runs the back half unattended (no per-file prompts) until the software is working and audited against .ok/GOAL.md.

What's new in 0.2 — "Verifiable Overkill"

Earlier OK measured the shape of work, never its correctness — so a generic, templated blueprint scored "DONE" and a one-line file counted as "written." 0.2 makes every "done" gate ungameable and fail-closed:

• ok bp anti-gaming — generic/duplicated blueprints are flagged SUSPECT (a stamped template lights up as one cluster). ok bp --audit reports them, and SUSPECT blocks the pipeline. A "DONE" count is no longer the definition of done.
• ok verify — a 4-level artifact ladder (Exists → Substantive → Wired → DataFlows) plus blueprint↔code correspondence: every identifier a blueprint names must be defined in the source. Closes the "byte-presence = written" loophole.
• ok test fails closed — no tests ≠ passing (exit non-zero); ok drift blocks.
• Independent verifier agents — ok-precode-reviewer and ok-verifier (goal-backward, "don't trust the summary") gate work that the deterministic checks can't reason about. See overkill/references/verification-before-completion.md.
• Token discipline — ok workflow <name> and ok context --phase <p> give every host a cheap, self-describing surface, so agents stop reading the whole repo.
• ok guard (opt-in) — file integrity & self-healing: snapshots, manual-edit detection, risk classification (trivial/structural/dangerous), and a propose-only /ok:repair pipeline that never silently overwrites human work.
• Autonomous orchestration — ok orchestrate turns the back half into a real gated state machine (precode → execute → review → verify → test → audit) that runs the deterministic gates in-process and blocks on any failure; /ok:autonomous drives it hands-free. ok doctor is a one-shot readiness check (works out of the box); ok worktree isolates parallel zones; ok models resolves model tiering.

Commands

Deterministic tools (no agent, no tokens)

Command	Does
ok init	install OK, detect host, create .ok/, sync skills store
ok workflow <name>	print an agent workflow prompt (host-portable; no spelunking)
ok context --phase <p>	the token-cheap list of only what a phase should read
ok scaffold	create files/folders from STRUCTURE.md + blueprint stubs
ok blueprint-status (ok bp)	score blueprints; --audit flags generic/duplicated (SUSPECT)
ok verify	prove code matches its blueprint (artifact ladder + symbol correspondence)
ok skills	search/import skill packs
ok graphify	build dependency graph + execution zones
ok graph	query the project knowledge graph (file/zone/search)
ok brief	per-zone execution brief (blueprints + skill rules + graph context)
ok next	wave scheduler — zones ready now / mark done (parallel exec)
ok finish	completion check — files still tagged OK:PRECODE (--sync clears)
ok checklist	living project checklist, auto-ticked from real state
ok test	detect + run tests/lint (fails closed: no tests ≠ passing)
ok drift	architecture & blueprint drift (blocks on any drift)
ok audit	assemble FINAL-REPORT evidence (cites test/verify/drift)
ok guard	file integrity / self-healing — opt-in (snapshot/check/diff/restore)
ok orchestrate	the autonomous driver loop — gated state machine (--start/--next/--run-gate)
ok doctor	one-shot readiness/health check (run before /ok:goal)
ok worktree	git-worktree isolation per zone (add/list/merge/remove)
ok models	resolve the configured model tiering per agent role
ok milestone	archive milestone, open the next
ok progress (ok status)	project dashboard
ok lock	file-ownership lock table for parallel agents
ok goal	conduct the autonomous back-half run

Agent workflows (run inside your coding agent)

/ok:new-project /ok:research /ok:import-skills /ok:structure /ok:precode /ok:goal /ok:autonomous /ok:graphify /ok:execute /ok:review /ok:test /ok:audit /ok:repair /ok:milestone /ok:quick /ok:progress /ok:settings

Skills

A library of 1000+ skill packs (agent-readable rules, pitfalls, patterns) lives in a global store at ~/.overkill/skills/, synced once at ok init. Projects copy only what they need into .ok/skills/.

ok skills sync                 # populate the global store (once)
ok skills --search auth        # find skills
ok skills --skills react,jwt   # import specific packs
ok skills                      # auto-detect from the project stack

The deterministic indexer scans every skill's frontmatter into INDEX.json; the /ok:import-skills workflow has your agent select the right packs semantically.

State (.ok/)

GOAL.md (north star) · spec/ · docs/ · skills/ · structure/STRUCTURE.md · blueprints/ · graph/execution-zones.json · runs/ (autonomous run logs) · STATE.md (machine-rendered: phase, locks, activity).

Develop

npm test    # runs deterministic unit tests (tools/test-runner.js)

Docs

• WALKTHROUGH.md — gentle, worked-example guide (start here)
• WORKFLOW.md — the complete command-by-command pipeline
• PRD.md — full system design
• overkill/GUIDELINES.md — engineering discipline for agents
• CONTRIBUTING.md · CHANGELOG.md · LICENSE

MIT licensed. Vendors the graphify worker (MIT).