Nosedive: intentional velocity

note input, know output

Nosedive turns a plain notes repo into a bridge -- one repo that holds the plan and drives the work across your other repos. Work is split into small vertical slices before anything is built, and what "done" looks like is captured as executable checks that agents can run to find out whether they are actually finished.

Watch a dive -- empty repo to a pushed branch, delegated to opencode with a free model.

Install

npm i -g nosedive

Requires Node 22 or newer.

Quickstart

Start from a clone of a repo you control -- an empty GitHub repo on the free tier is enough. Nosedive pushes to that repo's remote, so it needs an origin.

git clone <your-notes-repo> ~/BASE && cd ~/BASE

# the tool commits on your behalf, so give it an identity
git config user.name "Test Pilot"
git config user.email "test@nosedive.invalid"

nosedive seed                                 # commits and pushes bridge config,
                                              # AGENTS.md, and a repo doc for the bridge
                                              # add --headless if you are an agent

nosedive record.feat --gist "Add a hello note"
nosedive record.dive --feat add-a-hello-note --gist "..." --brief "..."
nosedive jump                                 # hydrates the workspace and rebuilds context

# do the work in the hydrated workspace/__self worktree, and commit

nosedive pack                                 # stopping partway; banks WIP as patches
nosedive jump                                 # picks the same dive back up
nosedive land                                 # pushes work/add-a-hello-note

Every command prints a suggestion for the next one, so you can follow the prompts.

A few things worth knowing:

• seed registers the bridge itself as a repo in the kb, named after its own directory -- BASE above -- using a self-referential worktree (__self). Add other repos with record.repo when you need them.
• You never have to commit or push the bridge between steps. Nosedive does it for you.
• land only pushes committed work in the scoped repos. Uncommitted edits cause a refusal, even if the gate is green.
• Made a wrong turn? nosedive bail --reason "<why>" abandons the active dive. The reason is always required, so it never fires by accident.

Next: your first gate, which is how an agent learns when its work is done.

The problem

Agents can make code appear quickly. Getting from there to something we understand and are willing to ship still takes work.

A change can span days, people, agents, and repositories. When its context is scattered across tickets, chats, branches, and people's heads, three basic questions get harder to answer: What are we doing? Where did we leave off? How will we know it works?

Nosedive keeps the answers next to the work, so a human or an agent can pick it up without relying on one machine, one chat, or one person's memory.

Concepts

The entity roles Nosedive tracks in the knowledge base:

• bridge -- the notes repo itself, holding the plan and driving the work.
• repo -- an implementation boundary.
• feat -- a goal we want to accomplish.
• dive -- one bounded attempt at that goal.
• gate -- a repeatable check on the work.
• memo -- durable information found by following a breadcrumb.

The lifecycle actions that move them:

• jump -- begin or resume scoped work and rebuild context.
• pack -- hand off work for review or later pickup.
• land -- publish a completed dive and record its outcome.
• bail -- abandon a dive while preserving its history.
• test -- run regression gates and plan work to fix failures.

Reference

• Commands -- every command, what it does, and the doc behind it. Also carries the compatibility level Nosedive is on.
• Contributing -- development setup and conventions.

FAQ

• How do I add a command? — Clone repo, run deterministic id script, create command doc, adapter and impl files.
• How do I change what Nosedive adds to commit messages? — Configure per-repo Nosedive commit provenance trailers.
• How do I rebase my pull request onto trunk and publish it? — Open a new dive pinned at the branch head, rebase there by hand, and publish with nosedive land --hard.