@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.

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).