Nova

Development skills for Antigravity, Claude Code, and Codex.

Nova gives your coding agent a shared set of workflows — spec, plan, build, debug, review, docs, and more — that work the same way in all three CLIs. Describe the outcome; the agent picks up a skill, does the work, verifies it, and reports what changed.

For an interactive tour of the skills and the jj workflow, open the Nova guide in a browser.

Install

You need Python 3.11+ and at least one of agy, claude, or codex on your PATH.

git clone https://github.com/anvil008/nova.git
cd nova

./scripts/bootstrap.sh --dry-run   # preview
./scripts/bootstrap.sh             # install into every CLI found

Bootstrap installs the native plugins and the nova, nova-flow, and nova-test commands, and syncs global instruction files for each harness it touches.

Common flags (the installation guide lists them all):

Common flag	Effect
--dry-run	Print what would change; write nothing
--harness agy|claude|codex|all	Install for specific CLIs (repeatable)
--no-codex-helpers	Skip Codex helper agent definitions (installed by default)
--no-align-global	Leave global instruction files alone
--force-global	Replace conflicting global files, keeping a backup

Bootstrap never overwrites files it doesn't own: unmanaged or modified files are preserved, and a conflict stops the install with an explanation. The installation guide covers updates, custom prefixes, marketplace conflicts, manual installs, and what loads when.

Use it

Start a fresh agent session after installing, then invoke a skill:

Harness	How	Example
Antigravity	Pick from the skill catalog	Select the Nova build skill, then describe the task
Claude Code	Slash command	/nova:build Add CSV export to the reports page.
Codex	Prompt prefix	$nova:build Add CSV export to the reports page.

Plain English works too: "Use Nova debug to reproduce this failing test and fix it." State your constraints — "review only", "keep the public API unchanged", "open a PR, don't merge" — and the workflow carries them through.

How it works

1. Describe the outcome. Pick a skill when you want a specific workflow.
2. A native implementer writes the files. The parent agent coordinates; implementers author code, tests, docs, config, and reports. Scouts and reviewers are available for bounded lookups and independent review.
3. Verify. The agent runs the relevant checks quietly and reads the final diff. Failures go back into the work; gaps are reported honestly.
4. Deliver. Verified results land in local main first. When you authorize publication, the parent pushes one integration bookmark and opens or updates one PR.

Small tasks can go straight to one skill. There is no required sequence.

Skills

Purpose	Skill	What it does
Decide	spec	Clarify an idea and agree on behavior
	plan	Turn a defined change into an implementation plan and acceptance tests
	multiplan	Compare plans from Antigravity, Claude, and Codex (explicit request only)
Change	build	Implement a feature or fix
	debug	Reproduce a failure and isolate its cause; repair when requested
	refactor	Simplify code while preserving behavior
Assure	test-suite	Inventory and audit tests, preview proposed counts, then improve and run the selected suite
	security-suite	Audit and verify selected application security controls
	review	Review a diff or pull request
	docs	Write or audit documentation grounded in the project
Operations	profile	Measure performance and verify an optimization
	deploy	Release a verified change to a named environment with vYYYY.MM.DD[.N] tags
Support	repo-setup	Prepare project instructions and tooling
	jj	Manage JJ revisions, workspaces, and PR delivery
	si-project	Project-scoped adaptation and self-improvement
	si-global	Cross-project pattern synthesis
	use-other-harness	Run a bounded task in another CLI (explicit request only)

Full instructions live in skills/.

Build or improve a test suite

Invoke nova:test-suite when you want coverage across an application. Select All for every applicable test category, or choose a recommended subset or individual categories. The skill runs the existing tests and audits what they actually check. Before changing tests, it produces an HTML preview of the baseline, existing coverage, gaps, and proposed additions. The estimate separates new test functions or cases from tests to modify and from generated inputs within one test; it is reconciled with the actual count after verification. If you explicitly ask to review the proposal first, implementation waits for your direction.

For example, ask $nova:test-suite Audit and improve all applicable test categories in this project. in Codex, or /nova:test-suite in Claude Code. The nova-test command below is a separate quiet runner that the skill may use during verification.

Audit an application security suite

Invoke nova:security-suite for a broad security audit or hardening pass. Choose All applicable security categories or a narrower set. The skill inventories existing controls and tests, records a bounded baseline, and shows an HTML preview of findings, proposed changes, counts, targets, and limits before authorized repairs. It verifies the resulting controls on isolated or explicitly authorized targets and records remaining gaps; a clean scan alone does not establish security. A preview that lists unfixed vulnerabilities stays outside the repository (~/.cache/agent-work/<project>/<task>/) and is not committed or quoted in PRs or commit messages until they are fixed; failing tests for unfixed vulnerabilities stay in the task workspace.

Rules Nova follows

• Authorship. The parent plans, verifies, and integrates; native implementers author every task file change, including small edits. See task-file routing.
• Trunk-based delivery. Local main first, kept deployable. Every task file change is isolated in .workspaces/<task>/ before the first edit; read-only work is exempt. See development conventions.
• One publication PR. Accumulated results publish through a single integration bookmark and PR; main is never pushed directly. See publication conventions.
• Quiet verification. Test suites run in quiet mode (nova-test or quiet flags); full traces appear only on failure.
• Structured reports. Substantial implementation shows an HTML preview before edits, then reconciles actual results. A task that changed files or advanced main reports a workflow diagram, deliverables with links, evidence, and the immutable local main commit; a read-only task reports findings and evidence.

Hooks

Hooks connect native agent events to small local functions. They are advisory, not a security boundary: they fail open and do not intercept every possible write.

• Large reads (PreToolUse). Big reads get scout-routing guidance; focused reads stay in the conversation. See read routing.
• Task-file edits (PreToolUse). A write whose target resolves inside any repository gets implementer-routing guidance. Version-control metadata and targets outside every repository (~/.cache/agent-work, /tmp) pass through. See write routing.
• Workspaces (WorktreeCreate / WorktreeRemove). Claude events create and clean .workspaces/<task>/, retaining anything unsafe to delete. Agy and Codex follow repository instructions.
• Formatting and linting (PostToolUse). Off unless you configure NOVA_HOOK_CONFIG. They do not replace final verification.

Nova registers no automatic Stop reminders and no automatic Flow tracking. Details: hook configuration · harness differences.

Tools

Full reference: tools/README.md.

nova — diagnostics and validation from a source checkout:

python3 tools/nova doctor --source .   # read-only: harness roots, plugins, hook state, conflicts
python3 tools/nova check --source .    # metadata, links, guide, quiet tests, package build
python3 tools/nova eval list           # disposable bug-fix, review, and docs cases

To turn a Markdown skill report into HTML, run nova report render <report.md>.

nova-test — run any test command quietly.

nova-test python3 -m unittest discover -s tests
nova-test -v cargo test    # -v streams everything unfiltered

On success it prints only the framework summary (about 20 tokens); on failure it prints raw stdout and stderr untouched and returns the child's exit code. In an earlier measurement on Nova's 183-test Python suite, output dropped from about 1,840 tokens to 18; this is historical benchmark data, not a count of the current suite. Extraction is built in for Python, Rust, Go, Node/TypeScript, C/C++, and Java/Kotlin, with a tail fallback otherwise. See nova-test for recipes and measured savings.

nova-flow — optional run tracking in the terminal and a browser. Automatic tracking is off by default.

nova-flow init 'CSV export'
nova-flow task add export 'Implement CSV export' --phase build
nova-flow view
nova-flow serve

Add ~/.local/bin to PATH if the command isn't found. See the Flow guide.

nova-read and nova-write — a bounded numbered file reader for scouts, and a direct argv runner for authoring commands, with no shell:

python3 tools/nova-read --paths src/session.py --start 2001 --limit 1000
python3 tools/nova-write -- python3 -c "import pathlib; pathlib.Path('out.txt').write_text('x')"

Contributing

Start with CONTRIBUTING.md for how to propose and verify changes. To run the full check locally:

python3 -m pip install -r requirements-dev.txt
python3 tools/nova check --source .

nova check keeps logs and package output outside the source tree; --output PATH puts them in a specific new directory. Builds land in dist/plugins/{agy,claude,codex}/; rerun bootstrap to apply source changes locally.

Directory	Contents
skills/	Workflow instructions, references, and report assets
instructions/	Shared conventions and installation guidance
agents/	Native helper definitions
hooks/	Read routing, workspace adapters, optional edit checks
tools/	nova, nova-test, nova-flow, and shared utilities
scripts/	Packaging, bootstrap, and validation
tests/	Executable checks
docs/	Decisions, guides, and project history

See development conventions and the plugin architecture ADR.