agentleFS
mas-bandwidthmas-bandwidth/nova-sprint/AGENTS.md

nova-sprint

AGENTS.md22 starsChanged 5 days agoMITView on GitHub

nova-sprint coordinates AI coding work across models, harnesses and machines. Cards, reviews and decisions live in PostgreSQL; nova-bus carries assignments, and the run service schedules work and landing. Start with the detailed guide, shared by humans and AIs. - Inspect a release with version and help, without a running fleet or store. - Set up a sprint when you are configuring the fleet. - Join as a worker when a coordinator invited you. - Coordinate work in an existing sprint.…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start with the detailed guide, shared by humans and AIs.

    line 9
  2. Distinctive:

    Use the CLI for sprint operations.

    line 18
  3. Distinctive:

    Every change keeps all four, for friend rows and bench rows alike (the guide has the detail):

    line 24
  4. Distinctive:

    Before contributing, read the Contributor Assignment Agreement.

    line 56
  5. Distinctive:

    Read the test instructions and the relevant source before editing.

    line 62
  6. Very specific:

    Keep README.md a short human welcome, AGENTS.md the AI entry point, and docs/README.md the shared detailed guide.

    line 77
  7. Distinctive:

    Check existing posts for that tag before creating another.

    line 87

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

nova-sprint for AIs

nova-sprint coordinates AI coding work across models, harnesses and machines. Cards, reviews and decisions live in PostgreSQL; nova-bus carries assignments, and the run service schedules work and landing.

Use or evaluate nova-sprint

Start with the detailed guide, shared by humans and AIs.

  • Inspect a release with version and help, without a running fleet or store.
  • Set up a sprint when you are configuring the fleet.
  • Join as a worker when a coordinator invited you.
  • Coordinate work in an existing sprint.
  • Resolve a refusal using the named remedy.

Use the CLI for sprint operations. Copy the current row, generation and epoch from receipts. A successful finish reports a head; review, CI and landing are separate outcomes. Report only what you observed.

Hard requirements: never regress these

Every change keeps all four, for friend rows and bench rows alike (the guide has the detail):

  1. A row is up while its bus hook is on nova-bus and down after row_silent_gone off it, with nothing manual (no pong, no command): tla/RowAlive.tla AutoUp and HookedWhileUp; modules/run/rowalive_test.go. Two exceptions, on purpose and in the model: a tick whose nova-bus who read fails is no evidence of silence (no row goes down while the bus cannot be read), and last-seen lives in the run's memory (a restarted run counts every row's silence afresh).
  2. A row that goes down or is held returns every card it holds to the queue in the op that closes it, except cards that op cannot touch this tick, which the next tick that can touch them returns; all are dealt again: tla/RowAlive.tla HandEmptyWhenClosed, ReturnedByNextTick and Redealt; TestRowDownWhenHookGoneAndHandDealtAgain, TestHeldRowHandDealtAgain.
  3. Bench-only checks never judge a friend row, and with the roster unreadable no row is judged as a bench: TestShowFriendRowIsNeverABench, TestShowRowWithTheRosterUnreadable (modules/verbs/check_test.go).
  4. A store row nova-config no longer names is retired by the next tick, its hand returned in the same op, and shows nowhere until it hooks in again; a failed or empty roster read retires nothing; a row nova-config names again is hooked again by its running worker (Glenn, 2026-11-15): tla/RowAlive.tla HandEmptyWhenRetired, NothingLost, NoRetireOnBadRead, AutoRetire and ReNamedComesBack; modules/run/retire_test.go, modules/edge/worker/rehook_test.go.

tla/RowAlive.tla is not yet trace-bound to the code (owed).

A change that needs to break one of them is Glenn's decision, asked first.

Change nova-sprint

Before contributing, read the Contributor Assignment Agreement. It assigns copyright in the contribution to Más Bandwidth LLC and grants you a license to use your own contribution; the agreement gives the full terms. The repository's contributor check requires the applicable author signatures; use the authorized commit identity.

Read the test instructions and the relevant source before editing. The layer map and the card contract explain the boundaries. Keep changes scoped and preserve existing work.

Go command packages live in cmd/<command>/; reusable packages and their embedded assets live in modules/<module>/. make build and releases ship only nova-sprint; the other commands are development tools. The canonical role playbooks live beside their embed code in modules/playbooks/.

Build with make build so the binaries carry their source version. Use the Go version in go.mod and run the relevant lint, unit and functional checks from docs/TESTING.md on a suitable build machine. Unit tests use no real clock, network, socket or process; functional tests own their disposable services. Report missing dependencies and skipped checks explicitly.

Keep README.md a short human welcome, AGENTS.md the AI entry point, and docs/README.md the shared detailed guide. Preserve the branding. Document commands, effects and limits as the implementation provides them.

Publish a release update

For each published release, prepare a short update for the project Patreon. Name the exact shipped tag, what changed, the validation actually completed and any remaining limits. Link to that release, the shared guide and the support page. Check existing posts for that tag before creating another. Publish only through the authorized account and within the user's posting instructions. Report a prepared draft as prepared; report it as posted only after verifying the live post and retaining its URL.

An idea or a wanted feature goes into docs/roadmap.sexp (render with nova-roadmap); it is never implemented when it is had.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.