Reliable, auditable delivery for Claude Code agents.

Mavericks persists project state across sessions, routes work through specialised roles, and blocks backlog/task drift before commit.

Built for operators and small teams running agent-driven development across multiple repositories.

323 tasks · 25 waves · 12.5 weeks — tracked from one central backlog across 10 of the 20 Git repositories of a live AWS system (15 active Lambda functions). Measured through 13 July 2026.

See it in action · Why Mavericks is different · Quick start

Close Claude Code, come back tomorrow — the wave goal and handoff are handed to you, not reconstructed from chat history.

Anyone juggling more than one project knows this trap: you close the laptop mid-thought, get pulled away, and by the next session you're rebuilding what you were doing from memory or a long scroll of chat history — both slow, and easy to get wrong. Mavericks writes that down instead: what was in progress and what to do next live in the project itself, so the next session opens with a clear starting point, not a guess. See Pick up exactly where you left off.

• Close it, come back tomorrow — no state archaeology. State lives in versioned artifacts; every session resumes from written state, not a chat log. See Pick up exactly where you left off.
• Auditable runs. You can see — and diff — why the system did what it did, because state and decisions live in files, not model memory. See What actually carries over between sessions.
• Drift caught before commit. A validator blocks out-of-sync BACKLOG/TASK_STATUS before it reaches a commit. See A status that isn't written down isn't real.

Synth is a production AWS system of 20 Git repositories and 15 active Lambda functions. Mavericks ran the operation from a single control repository whose central backlog declared 10 of those 20 repositories as task targets — the coordination is production-exercised, not merely designed, and it comes with the honest caveats of an N=1, no-control-group observation.

This is an observational, N=1 case study — one operator, one control backlog, no control group — so the numbers show operational continuity and auditability across a coordinated system, not causal productivity.

These figures are a one-time snapshot, measured through 13 July 2026; they are not re-measured with each release. Any later re-measurement is compared against the case study's own "Measurement method" section, so a new figure and today's mean the same thing.

Read the full methodology, findings, and limitations →

Most agent workflows fall into one of three categories below. Mavericks overlaps with parts of each, but its shipped combination — versioned state, a validator gate, specialised roles, and production-exercised multi-repo coordination — is what the table below is comparing.

Legend: ✅ built-in and shipped · ⚠️ possible, but manual or partial · ❌ not addressed

Before you run this: Mavericks defaults to autonomous tool execution (bypassPermissions, no per-action confirmation prompts once a session starts). See Security model below for exactly what that means and how to opt out.

There are two different things you might want to do here — try Mavericks, or adopt it into a project you already have. They're separate steps.

One command, no follow-up needed:

curl -fsSL https://raw.githubusercontent.com/yahor-punko/mavericks-os/main/install.sh | sh -s -- --demo

This clones Mavericks to $HOME/.mavericks, prompts for consent on your terminal (the bypassPermissions disclosure — see SECURITY.md for exactly what that means and how to opt out), then runs a narrated, throwaway walkthrough of the operator loop against a disposable fixture — no docs required.

To re-run the demo later without reinstalling:

"$HOME/.mavericks/scripts/mavp-operator" --demo

(Use the absolute path above, not a relative ./scripts/mavp-operator — that only works from inside the Mavericks checkout itself.)

The one-liner above only clones the framework — it does not touch your own project. Adopting Mavericks into a project is a separate step, run against the checkout the demo just created:

node "$HOME/.mavericks/scripts/mavp-install.js" /path/to/your-project

See Manual install below (or docs/core/BOOTSTRAP_GUIDE.md for the full step-by-step) for what this creates and how to configure it.

1. Restart your editor (Claude Code or VS Code) so it picks up what was just installed.
2. Type /session-start and let your agent take it from there.

A session is one sitting: you tell your agent where things stand or what you'd like to do next, it does the work, and when you're ready to stop for the day you ask it to close up — it remembers where things left off for next time.

A wave is the bigger container: a batch of work aimed at one goal you set together with your agent. Once that goal is met, you close the wave together and move on to the next one.

Closing a session never closes a wave: the wave closes only when you tell your agent its goal is met (--close-wave), as the 0.52.0 upgrade step in CHANGELOG.md explains.

• Node.js 20+
• Claude Code CLI (claude)
• git

For people who'd rather not curl | sh:

Clone this repository somewhere on disk, e.g.:

git clone https://github.com/yahor-punko/mavericks-os.git <path-to-mavericks>

Everything below refers to that checkout as <path-to-mavericks>.

From your own project's directory (or pointing at it):

node <path-to-mavericks>/scripts/mavp-install.js /path/to/your-project

Use --check first to preview what would happen without writing anything:

node <path-to-mavericks>/scripts/mavp-install.js --check /path/to/your-project

Runs non-interactively (no prompt) when invoked from an agent's Bash tool or piped/CI, or explicitly via --yes / -y; at a real terminal without either it still asks Create N file(s)...? [Y/n].

If you ask an agent to install Mavericks from a session where shell access is denied, it can't — run the one command above yourself (terminal, or the ! prefix in Claude Code). This one-time human step is deliberate: the person running the installer consents to the prompt-free bypassPermissions default it configures (see SECURITY.md). In prompting permission modes a single approval suffices instead. Later sessions inherit the configured permissions and the agent operates autonomously.

This creates, in your-project/:

• scripts/mavp-operator — a bash wrapper that delegates to this Mavericks installation
• scripts/mavp-operator-agent.js — project-specific session-start summary
• scripts/mavp-operator-close-session.js — end-of-session ritual
• BACKLOG.md, TASK_STATUS.md, PROCESS_STATE.md, PROCESS_STATE.json — live state artifacts, from templates
• .claude/agents/*.md, .claude/skills/*/SKILL.md, .claude/rules/*.md — sub-agent specs, skills, and rules, copied from this repo
• .claude/settings.json / .claude/settings.local.json — shared and personal Claude Code settings (see Security model below)
• docs/ARCHITECTURE.md — an architecture document template, to fill in at project start
• .vscode/settings.json — created, or merged into the one you have, with entries that hide .claude/worktrees from the editor's file tree and search

Pass --transcript-archive to opt into a gitignored session-transcript archive at .mavp/transcripts/, with retention bounded via the MAVP_TRANSCRIPT_RETENTION_DAYS env var — off by default. See docs/core/BOOTSTRAP_GUIDE.md for details.

Core framework scripts (the operator library, dashboard, validator) are not copied into your project — the generated scripts/mavp-operator wrapper runs them directly from this Mavericks checkout.

The wrapper resolves the Mavericks install location in this order: an explicit MAVERICKS_HOME env var, if set, always wins; otherwise the checkout the wrapper was generated from is used, as long as it still holds the framework; otherwise $HOME/.mavericks — the canonical default, and where install.sh clones Mavericks — is used if it exists; otherwise $HOME/Documents/mavericks is used as a legacy fallback. If none of these resolves, the wrapper refuses and names every location it tried. If you moved or deleted the checkout you installed from, set MAVERICKS_HOME to its new path (e.g. in your shell profile or before invoking the wrapper):

export MAVERICKS_HOME=<path-to-mavericks>

The wrapper also exports MAVERICKS_PROJECT_ROOT automatically when it runs, pointing framework scripts at your project's artifacts rather than the Mavericks checkout itself — you don't need to set this one yourself.

For the full step-by-step, including editing PROCESS_STATE.json, adding your first tasks, and setting up the pre-commit validator hook, see docs/core/BOOTSTRAP_GUIDE.md.

Updating is two steps — one for the shared framework checkout, one per project.

1. Update the framework checkout. Bootstrapped projects run core scripts directly from the checkout, so this one step updates the framework for every project at once:

git -C "$HOME/.mavericks" pull --ff-only    # use your <path-to-mavericks> if you cloned elsewhere

Re-running the curl | sh installer does the same thing — it is idempotent and pulls an existing checkout instead of re-cloning.

The clone install.sh creates tracks the stable main branch by default, and stable releases are tagged v<version>. An edge branch carries every working build and is opt-in: switch with git -C "${MAVERICKS_HOME:-$HOME/.mavericks}" checkout edge && git -C "${MAVERICKS_HOME:-$HOME/.mavericks}" pull, and go back with checkout main. Edge moves several times a day, so it trips the installer's behind-upstream guard more often. To pin a branch or tag at clone time, pass install.sh --ref <branch/tag>.

2. Re-sync each bootstrapped project. The files the installer copied into your project (.claude/ agents, skills, rules, hooks, and the wrapper and project scripts) don't update themselves. From each project's directory:

./scripts/mavp-operator --install --update .

This overwrites the copied framework files with the latest versions and records the new framework version in PROCESS_STATE.json. It never touches your task state — BACKLOG.md, TASK_STATUS.md, and the rest of PROCESS_STATE.json are left alone. Pass --no-hooks to skip the hooks refresh, or use --hooks-only to refresh only the hooks.

You don't need to watch for releases: when a project's recorded framework version falls behind the checkout, the session-start brief prints an UPDATE_AVAILABLE notice with the exact re-sync command.

Drift between BACKLOG.md and TASK_STATUS.md is caught before it reaches a commit.

One glance at workflow state, context usage, runtime actors, and open waits.

Mavericks emerged from running agent-driven development across multiple repositories in parallel, not from a whiteboard exercise.

The recurring failure mode was not code generation; it was continuity: reconstructing project state at the start of a session and losing the rationale behind decisions when chat context rolled over.

Mavericks addresses that with versioned, artifact-first state (see Pick up exactly where you left off and A status that isn't written down isn't real below); a strict separation between the main_agent orchestrator and specialised execution and review roles; and validation that surfaces backlog/task-state drift before commit.

Every mechanism in this repository was retained because it solved a recurring problem in active delivery.

Losing the thread of a project between sessions is the everyday failure this framework exists to prevent — not by asking for better notes, but by having the project keep its own notes and hand them back automatically.

Every session opens with a short brief, worked out fresh each time, never from a hand-kept list:

• What's in flight — read straight from the task files, so it can't quietly go stale.
• One next action — a single line telling you what to do next.
• What changed while you were away — files touched since the last time a session was formally closed, including anything you haven't committed yet, drawn from the repository itself, not a guess.
• A handoff note, when one was left — mid-thought context, written to HANDOFF.md, handed back immediately.

For example (illustrative, not a literal transcript) — just two of the four parts above, the changed-files list and the next action:

Must read:
- lambda/handler.py
Next action: T-231 → developer → fix the retry bug

HANDOFF.md is not written automatically when a session ends. Writing it is a separate, deliberate step (--handoff); closing a session (--close-session) does not do it, and it's single-use — delivered once at the next session's start, then deleted. The next-action line itself stays narrow on purpose — one instruction, never a running commentary; anything longer belongs in the handoff note instead.

Telling an agent something is done, and having it actually be done, are two different things — this section closes that gap. A task's status changes only when it's written into the project's own task files, never because someone said so in conversation.

Two files carry that status side by side, and they're required to agree. A check runs automatically after every edit to either one; it doesn't stop the edit, it just flags the moment they drift apart, so the gap is caught immediately instead of days later. The strictest version of that check sits at the door to history: a task can't be recorded as fully merged without pointing to the real code change that shipped it — get that wrong and the record can't be committed. Full state machine and evidence rules: docs/core/TASK_LIFECYCLE.md.

Closing a chat and starting a new one never loses anything that matters, because none of it — a task's status, its history, a decision made along the way — ever lived in an agent's memory to begin with; all of it lives in the files described above. Every specialised agent doing a piece of work is briefed fresh from those same files each time, with no memory of its own carried in from a previous run.

What does travel forward isn't a fact about any one task — it's practice: lessons about what tends to go wrong, folded back into the written instructions those agents read next time, only after a person has reviewed and approved the change. There is no separate memory store behind any of this — the files are the only place state lives.

Mavericks runs a direct-reference model: one framework checkout serves many projects, and state is never replicated per repository. A single control repo holds the one BACKLOG.md, TASK_STATUS.md, and PROCESS_STATE.json; every sibling repository's scripts/mavp-operator wrapper delegates back to that one checkout via MAVERICKS_PROJECT_ROOT rather than carrying its own copy of these files.

Cross-repo tasks declare a Repos: field in the backlog (e.g. - **Repos:** repo-a, repo-b). When a sub-agent completes work in a sibling repository, its evidence is recorded back into the control repo's TASK_STATUS.md as one line per repo — commit: <hash> (repo-a), commit: <hash> (repo-b) — so the control backlog stays the single, auditable source of truth for where work landed even though the diffs live in the sibling repositories. Before dispatching a cross-repo task, the main agent runs the cross-repo pre-flight described in docs/core/ORCHESTRATION_RULES.md; ./scripts/mavp-operator --check-sync compares agent/skill files across known projects against the Mavericks source to catch drift between them.

Cross-repo ordering is enforced, not just recorded: a task may declare - **Blocked by:** <repo>/T-NNN (comma-separated for multiple references; distinct from the same-repo Depends on: field). The validator resolves <repo> to a local working copy via the repo-map registry (docs/REPO_MAP.md) and reads the blocker task's status from that repo's own artifacts: a task recorded merged while its blocker is not yet merged is a blocking failure (exit 2), a task at qa_passed or ready_for_qa with an unmet blocker gets a warning, and an unresolvable reference (unknown repo id or missing blocker task) surfaces as an info-level advisory rather than a block.

This is production-exercised, not a design sketch: 10 of the Synth case study's 20 repositories were declared as task targets from the one control backlog, with 19 tasks explicitly targeting more than one repository (see Case study: Synth).

                   ┌──────────────────────────────────┐
                   │     control repo (mavericks)     │
                   │  BACKLOG.md · TASK_STATUS.md ·   │
                   │ PROCESS_STATE.json (single copy) │
                   └──────────────────────────────────┘
                                     │
                          main_agent orchestrator
                                     │
                 task carries `Repo: repo-a, repo-b, ...`
                                     │
       ┌───────────────────┬─────────┴─────────┬───────────────────┐
       ▼                   ▼                   ▼                   ▼
sibling repo A      sibling repo B      sibling repo C      sibling repo N
  (sub-agent          (sub-agent          (sub-agent          (sub-agent
 commits code)       commits code)       commits code)       commits code)
       │                   │                   │                   │
       └───────────────────┴─────────┬─────────┴───────────────────┘
                                     ▼
                  evidence recorded back to control repo:
        `commit: <hash> (repo-a)` · `commit: <hash> (repo-b)` · ...
                                     │
                                     ▼
                  validator · QA · security review gates
                                     │
                                     ▼
                    AWS deployment (15 active Lambdas)

Reference material for readers who want the details — none of this is required to get started.

• What files a bootstrapped project has, and why. See docs/core/BOOTSTRAP_GUIDE.md — "What gets installed".
• How a task moves from idea to shipped. See docs/core/TASK_LIFECYCLE.md.
• Who does what — developer, QA, architect, and the rest. See the summary table in docs/core/ROLES.md.
• How drift gets caught before it reaches a commit. See docs/core/BOOTSTRAP_GUIDE.md — "Pre-commit hook".
• The full list of operator commands. Run ./scripts/mavp-operator --help from your bootstrapped project.

Mavericks ships with autonomous tool execution enabled by default (permissions.defaultMode: "bypassPermissions" in the committed .claude/settings.json). This means agents can read, write, and execute across your filesystem and shell without a per-action confirmation prompt once you start a session. This is deliberate — see SECURITY.md for exactly what it means, how to opt out before your first session, and how to report a vulnerability.

Mavericks is not a deliverable product you run in production — it's a reusable framework that other projects adopt into their own repository.

All in docs/core/:

When the framework gets in your way, you can say so in a form the maintainers can act on, and find out what became of it. Nothing leaves your machine unless you say so.

1. Set a neutral alias once: ./scripts/mavp-operator --feedback --set-alias <alias>. Never use a private project name — the alias travels with every item.
2. Copy templates/FEEDBACK_ITEM_TEMPLATE.md, fill it in, and file it with ./scripts/mavp-operator --feedback --file <path>. It lands in a per-user local inbox on your machine, and nothing is sent anywhere.
3. Follow it with --feedback --status, and clear the answer's reminder with --feedback --ack <id>.
4. To post an item as a public GitHub issue, use --feedback --github. It goes out only after a blocking scan of the outbound text finds nothing and you pass --operator-confirmed with your own statement. Fetch the maintainer's answer with --feedback --pull.
5. If you wrote a stop-gap to dodge the problem, tag it mavp-workaround:<alias>-NNN. When the fix ships, the read-only ./scripts/mavp-operator --migrate lists the tag as retirable, and you remove it by hand.

The full loop, including what the maintainer's side does with your item, is in docs/core/FEEDBACK_INTAKE.md.

See CONTRIBUTING.md for how work moves through this repository and how to propose a change as an external contributor. Participation is governed by the Contributor Covenant.

Mavericks is licensed under the MIT License. It vendors one third-party component (the frontend-design skill, Apache-2.0) — see NOTICE for the full attribution and carve-out.