@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

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.

Commands

Deterministic tools (no agent, no tokens)

Command	Does
ok init	install OK, detect host, create .ok/, sync skills store
ok scaffold	create files/folders from STRUCTURE.md + blueprint stubs
ok blueprint-status (ok bp)	score which blueprints are filled
ok skills	search/import skill packs (1000+ library)
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, record results
ok drift	architecture & blueprint drift detection
ok audit	assemble FINAL-REPORT evidence
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:graphify /ok:execute /ok:review /ok:test /ok:audit /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).