frob

frob is the enforcement layer for agentic development: an obligation graph tracks every symbol's identity, a statically-checkable ticket queue tracks every unit of work, and a set of gates turn unaccounted-for change -- code with no ticket, a doc that drifted, a test that vanished -- into a frob check failure. Your editor or an agent's own tools navigate and edit code; frob accounts for it.

Highlights

• Obligation graph. Every symbol's identity, tests, docs, and tickets are tracked edges, not tribal knowledge -- frob check fails the moment one of them drifts.
• Statically-checkable ticket queue. Work lives in the tickets/ directory, tracked in git, with declared scope, blockers, and evidence -- not a side channel that can silently fall out of sync with the code.
• Gates with a remedy built in. frob check runs ruff, ty, cycle/dup/arch/bind/exports, and every enforcement gate in one pass; every violation message embeds the command that fixes it.
• A comment DSL, not a wiki. frob:ticket, frob:tests, frob:doc, frob:invariant, and frob:waive bind code to its own accounting inline, where a diff can't leave it behind.
• Visible debt, never silence. A waiver (frob:waive RULE-ID reason="...") is an explicit, reason-carrying exception -- it shows up in every report instead of quietly suppressing a check.
• An MCP server for agent hosts. frob serve exposes doable tickets, stale docs, and graph queries as read-only tools over stdio.

Install

uv tool install frob

frob doctor

frob version: 0.530.0

  frob_core: available (version=unknown)
  strata_core: available (version=unknown)

all native extensions available

frob doctor is a good first command: it confirms the install and reports whether the two native acceleration extensions (frob-core, frob-strata) are present. Both are default dependencies of a plain install; if either is absent frob still runs, in pure-Python mode, and says so loudly rather than degrading silently -- see docs/guides/install.md.

Quickstart

The enforcement loop is annotate -> check -> fix-or-waive: bind code to a ticket and its tests with comment directives, let frob check fail on anything undeclared, then either close the gap or waive it with a reason.

frob graph build                                  # build the obligation graph cache
frob ticket new --title "Add multiply function" \
    --kind feature --scope "src/demo/calc.py"     # T-0001
frob ticket start T-0001                          # pre-work sweep, -> in-progress

# write code, bind it: `# frob:ticket T-0001` above the new symbol,
# `# frob:tests <symref>` above the test that covers it

frob check . --ticket T-0001                      # fails: undeclared change
# ... add the directives, write the test ...
frob check . --ticket T-0001                      # coverage/scope/drift clean

frob test --base main                             # run exactly the touched-set tests
frob ack src/demo/calc.py::multiply --facet sig    # acknowledge a described contract
frob ticket close T-0001                           # requires evidence + a Done report

See docs/guides/quickstart.md for the full walkthrough with real command output.

Command groups

frob --help groups its surface into seven verb collections -- explore, quality, design, ops, ticket, vet, serve -- and every member also works as its own standalone top-level command. docs/guides/command-reference.md has the full per-group breakdown; docs/modules/cli.md carries the tier ledger behind the grouping. The complete table is below.

Contributing

See CONTRIBUTING.md for the ticket-queue workflow, comment-directive conventions, and the evidence/close/land dance. Please also read the Code of Conduct. Found a security issue? See SECURITY.md -- please do not file it as a public issue.

More

• docs/guides/install.md -- native extensions, the T-0133 degrade contract, editable dev installs
• docs/guides/quickstart.md -- the loop above with real command output
• docs/guides/command-reference.md -- the seven verb groups and the full command table
• docs/modules/cli.md -- the CLI regrouping history and per-command tier ledger
• docs/ -- per-command references and module design docs
• CHANGELOG.md -- what shipped, grouped by area