Gravitas Agent Skill

GRAVITAS

Gives Gemini Claude-grade engineering discipline: read before writing, plan in proportion to risk, verify against executed evidence, and report only what the evidence supports.

GRAVITAS is an open-source reliability runtime for AI coding agents. It ships as portable Agent Skills plus optional host enforcement (an Antigravity plugin and an OpenCode shim) backed by one policy engine. The goal is a coding workflow whose claims can be checked after the fact: scoped changes, executed validators, tamper-evident records, and a completion gate that refuses to pass on stale or missing proof.

GRAVITAS changes the engineering process, not model weights.

Research preview: comparative performance is not yet measured.

Problem

Coding agents fail in predictable ways. They edit files they never read. They make broad changes for narrow tasks. They run no tests, or run them before the final edit and report the old green result. They retry the exact call that just failed. And they announce completion that no record supports. Each of these is a process failure, not a capability failure: the model could have done the right thing, but nothing in the loop required it.

Gravitas puts those requirements into the loop. Six invariants state them. Skills teach them. Hooks and guards enforce the subset that can be checked mechanically. Validators produce the evidence. A gate reads the evidence before the session is allowed to stop.

Why now

In late 2026, Google restricted third-party models in Antigravity on licensing grounds: Claude access is now reserved for direct, non-promotional paid subscriptions, and the Claude 4.6 models remaining on other plans are removed on November 2, 2026 (models table). Users on promotional routes, including the free Jio tier and student plans, lost the Claude option they had built their workflows around.

What remains on every plan, Free included, is Gemini 3.8 Flash: a fast model built for agentic work, but one that still fails in exactly the predictable ways listed above when nothing constrains its process. That is the opportunity inside the disruption. Gravitas does not bring Claude back. It gives the model you still have the working discipline people miss about Claude: grounded edits, declared scope, executed proof, and no completion without evidence.

Installation

Three setups, in order of increasing machinery. All three share the same six invariants.

Core. Portable behavioral policy delivered as Agent Skills. No enforcement, no dependencies beyond the skill files. This is the recommended default.

npx skills add udaysharmadev/Gravitas --skill gravitas --agent antigravity --yes

Then address the agent directly:

Use Gravitas to fix this bug and verify the result.

Native. Core plus an Antigravity plugin (gravitas-native) with PreToolUse, PostToolUse, PostInvocation, and Stop hooks. For teams that want tool calls checked and completion gated by the runtime rather than by instruction alone.

git clone --depth 1 https://github.com/udaysharmadev/Gravitas.git
cd Gravitas
bash scripts/build-native-bundle.sh
agy plugin install "$PWD/dist/gravitas-antigravity"
agy plugin validate "$PWD/dist/gravitas-antigravity"

OpenCode. Core plus a permission profile and a tool.execute.before shim (gravitas guard) that applies the same policy engine to OpenCode tool calls.

gravitas init --host opencode --profile balanced

Detailed instructions, update paths, and uninstall steps are in docs/install.md. First tasks are in docs/quickstart.md.

The six invariants

These are the entire contract. Everything else in the repository implements them.

#	Invariant	Consequence
1	Ground before mutating	The agent reads the target, its tests, and its callers before editing. File state is observed, never assumed.
2	Stay in declared scope	Each task declares allowed_write_scope. Writes outside it are denied. A wrong scope is amended openly, not routed around.
3	Completion needs evidence	A criterion is complete only when a Gravitas-owned validator passed after the last relevant mutation. Prior green runs, self-review, and prose summaries do not count.
4	Never exact-retry a failure	A failed approach may be retried only after the diagnosis, context, or strategy changes. Byte-identical retries are blocked; gravitas resolve-failure re-arms a fingerprint once a transient cause is resolved.
5	Satisfy the contract	Acceptance criteria and their required validators gate completion. A passing test suite for unrelated code proves nothing about the task.
6	Say what you cannot verify	Claims without backing are labeled as such. Uncertainty lowers confidence instead of being rounded up to certainty.

Planning effort follows risk, not ritual. gravitas decide --signals '{...}' emits a machine-readable record (direct, compact, deep, replan) with reason codes. A one-line fix in one file is direct. An auth migration across twelve files is deep with a reviewer. The profiles eco, balanced, deep, and team set intended process cost. None of them claims a performance advantage; that awaits measured comparison.

How it works

The whole system is one loop, in plain words:

flowchart LR
  A[You describe the task] --> B[Agent reads the code and the tests]
  B --> C[Agent writes a short plan]
  C --> D[Agent edits only the allowed files]
  D --> E[Real checks run on the computer]
  E --> F{Proof for everything?}
  F -->|No| C
  F -->|Yes| G[Finished, proof attached]

And here is the honest difference. Gemini alone is capable of every good practice below; the difference is that nothing requires them, checks them, or keeps the receipts. Gravitas makes each step required and verifiable.

Stage	Gemini alone (what actually happens)	Gemini plus Gravitas
Reading code	Usually reads the relevant files, but nothing stops a blind edit when context is long or the model is confident.	Read-before-write is enforced: editing an existing file without a recorded read is denied.
Planning	Plans when it judges the task needs one. No record survives the session.	A machine-readable plan (direct to replan) is emitted with reason codes and stored; effort scales with risk and blast radius.
Scope	Can touch any file the tools allow. A wrong turn edits the wrong package.	Each task declares allowed_write_scope. Outside writes are denied with the violating path named.
Running checks	Often runs tests, sometimes before the final edit, and reports the result in prose you cannot re-run.	A declared validator executes after the last mutation; its exit code and output hash are recorded. A PASS from before the final edit is stale and rejected.
Retrying failures	Happily retries the identical call that just failed, burning quota.	An exact retry of a failed fingerprint is banned until the diagnosis, context, or strategy changes.
Claiming completion	Announces done. Nothing re-checks the claim.	The Stop gate demands a fresh owned PASS per criterion over an intact evidence chain. If proof is missing after bounded retries, the session ends marked unverified, never passed.
When something breaks	The error sits somewhere in the chat history.	Every denial and failure states what failed, which component decided, and the next safe action.

Enforcement semantics

Instruction is not enforcement, so the repository distinguishes the two everywhere. What the skill asks for and what the runtime guarantees are documented separately per host.

Capability	Core (any host)	Native (Antigravity)	OpenCode
Planning and read-before-write policy	Instruction	Instruction plus action lock	Instruction plus permission profiles
Write and scope gating	None	Hook deny	Shim deny plus host permissions
Destructive confirmation	None	force_ask	Hard deny (no ask channel exists)
Evidence ledger	None	Automatic, hash-linked	Manual, via CLI
Completion gate	None	Automatic Stop hook	Manual (summarize plus evidence)
Session isolation	None	Per conversation	Per workspace contract
Guard dependency	None	None (in-process)	python3 plus gravitas on PATH

The failure policy is fail-closed. An unreachable, slow, or broken guard denies mutating calls. A missing or corrupt contract denies mutations while still permitting reads (reported as unconfigured or degraded, never as silent permission). A hook payload that cannot be parsed blocks rather than passes. Host differences, stated without softening, are in docs/hosts.md.

What enforcement is not: hooks are workflow controls, not an operating-system sandbox. The shell classifier described below is a conservative capability estimate, not filesystem containment. Full limits are in SECURITY.md.

Evidence model

Completion-grade evidence has a precise definition: a record produced by a Gravitas-owned execution (validator_runner.py), naming a declared validator and criterion, carrying exit code 0, timestamped strictly after the latest file write in the ledger, and sitting in an intact hash chain. Anything weaker (hook telemetry, reproducer output, prose) is recorded as supporting context and cannot satisfy the gate.

Three mechanisms protect this definition. First, the Stop gate verifies chain integrity before reading any verdict, so edited or reordered ledger lines refuse completion instead of passing it. Second, freshness is recomputed from the ledger on every run; a file write after a PASS returns the criterion to pending until new evidence covers every assigned validator. A validator's newer failure cannot be masked by its older PASS or another validator's success, and recovery state uses the same criterion reducer. Third, validator identity is bound: the executed command must equal the contract declaration, the criterion must be assigned to that validator, and timeouts or interruptions record FAIL, never PASS. Output is capped and hashed digest-only so verbose tools cannot exhaust the runner.

Hash chains deserve one unsentimental sentence: they make silent edits detectable, they do not stop an attacker who can rewrite the whole ledger. The model assumes filesystem integrity and states so.

Shell classification

Shell strings are classified by tokenizer plus operator scan into five capability levels. The classifier is deliberately pessimistic: unknown executables, unparsable segments, wrappers (sudo, env, VAR= prefixes), newlines, sh -c payloads, and xargs tails all resolve against the inner command, worst segment wins.

Level	Meaning	Examples
none	Provably read-only query	git status, ls, sed without -i, git -C dir status
write	Scoped file mutation	write_to_file inside allowed scope
mutation	Code execution or unenumerable writes	pytest, python3 -c, pipelines, redirects
destructive	Deletion, blind overwrite, infra, exfiltration	rm -rf, git branch -D, find -execdir rm, `curl …
unknown	Unclassifiable	Fails closed to mutation at minimum

Quoted separators are a known over-approximation (echo "a;b" classifies as mutation). That direction is safe and documented; precise quote-aware splitting is deferred work, listed in the audit.

Verification

The suite covers action locking, a shell-bypass corpus, scope and path-traversal checks, session isolation, evidence tampering, stale/latest-validator gate behavior, packaging integrity, CLI integration, benchmark outcome/publication integrity, and deterministic fuzzing. The 2026-11-03 pre-upgrade baseline passed 391 tests; run the command below for the current count. Research findings and upgrade scope are recorded in the project review. Reproduce locally:

python -m unittest discover -s tests

The full gate, as run by CI on Python 3.9, 3.12, and 3.14 with Node 22 for adapter tests, is:

python -m unittest discover -s tests
python benchmarks/runner/audit.py
python benchmarks/runner/validate.py --episodes benchmarks/results --allow-empty
python -m py_compile gravitas_cli.py gravitas_init.py plugins/gravitas-antigravity/scripts/*.py
python .github/scripts/validate_skill.py
python scripts/check_readme_claims.py
bash scripts/build-native-bundle.sh

CI builds the wheel and source distribution, installs the wheel with dependencies into a fresh virtual environment, and checks the console CLI and both host initialization paths in external temporary workspaces. The pre-push review also tested a disposable user installation and repaired its asset resolution. Strict native validation now loads both skills and all three agents. See pre-push verification and the readiness board for platform and live-host limits.

Star History

<br />

<br />

Contributors

Uday Sharma	Devansh Singh	Manan Bharti	Rudra Makwana	Neel Dharmendra	Ankit Tiwari	Pasit Nusso
maintainer	shell-injection hardening (#1)	init safety, classifier + policy/gate hardening	evidence freshness, sed/exec-config hardening	shell classifier fixes (#34–#36)	gate/contract hardening, Windows portability	PR #82

<br />

Benchmark status

GravitasBench currently holds 48 registered task specifications across 10 planned lanes (30 core + 5 negative + 5 trap + 8 harvested). The executable runner still rotates five synthetic fixtures; harvested specifications do not yet execute their pinned repositories. That is infrastructure, not results. No solve rates, requirement-coverage numbers, token or latency comparisons, or model rankings are published. The publication gate requires explicit repository provenance, matching experiment inputs, unique run identities, and at least 30 distinct tasks with five valid paired runs each; current smoke/synthetic runners are ineligible regardless of sample size. Declarations still require independent artifact review before release. Methodology and release gates: docs/benchmark.md, docs/production-readiness.md. The latest source-linked research and integrity upgrade are in the 2026-11-03 project review.

Related work

Each source below motivates one mechanism. None of them establishes an effect size for Gravitas; they are cited for the design reasoning they support, which docs/research.md separates from project hypotheses.

• ReAct: grounding reasoning in actions and observations. Motivates invariant 1 (observed file state before editing).
• Plan-and-Solve: explicit decomposition for multi-step tasks. Motivates contracts plus the adaptive planning record; applying it to coding workflows is the project hypothesis.
• Huang et al.: unaided self-correction fails on the studied reasoning tasks. Motivates invariant 3 (external validators over self-review).
• SWE-bench: judge repository state, not final prose. Motivates executed validators and the completion gate.
• Harness-Bench and Harness-IF: evaluate model-plus-harness configurations as systems, with stated methodology. This is the standard the benchmark track holds itself to before publishing any comparison.

Limitations

Stated plainly, so nobody discovers them in production: Native hooks do not sandbox processes. An enclosing validator shell command can still invalidate its own evidence during host post-processing; this lifecycle boundary needs separate hardening. OpenCode has session-scoped read tracking, but a confirmed after-hook argument-shape mismatch and version differences prevent a blanket compatibility claim. No new live model-backed OpenCode run was performed during this review. Child handoff scope/evidence checks still have documented remaining gaps; the subsequent pre-push review repaired user-install asset resolution. Concurrent sessions are isolated by directory and conversation hash, not by OS controls. See the project review for reproductions, priorities, and verification limits.

Documentation

Quickstart · Concepts · Hosts · Configuration · Benchmark methodology · Install and troubleshooting · Contributing · Security policy · Research foundations · Architecture decisions

Contributing

Useful contributions, in rough order of value: licensed benchmark tasks, hidden deterministic validators, live host compatibility checks, privacy review, independent replications. Contributors to date are listed in CONTRIBUTORS.md. Working agreement is in CONTRIBUTING.md: read before writing, keep changes reviewable, add a regression test per confirmed bug, verify with executed output.

Citation

Use CITATION.cff and pin a commit until a versioned release and archived benchmark dataset exist.

License

MIT © Uday Sharma.