Skip to content
Back to search

mavericks-os

Orchestrate Claude Code sub-agents across long-running, single- or multi-repo projects. Artifact-first state, task lifecycle, cross-repo dependencies and QA gates that survive every session - not buried in chat history.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/yahor-punko/mavericks-os with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/yahor-punko/mavericks-os'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yahor-punko--mavericks-os/badge.svg)](/listings/yahor-punko--mavericks-os)

HTML

<a href="/listings/yahor-punko--mavericks-os"><img src="/api/listings/yahor-punko--mavericks-os/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

> **Before you run this:** Mavericks defaults to autonomous tool execution (`bypassPermissions`, no per-action confirmation prompts once a session starts). See **[Security model](#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.

Try the demo

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`](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.)

Add Mavericks to a project

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`](docs/core/BOOTSTRAP_GUIDE.md)** for the full step-by-step) for what this creates and how to configure it.

Your first session

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.

Requirements

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

Manual install

For people who'd rather not `curl | sh`:

Step 1 — Get Mavericks onto your machine

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>`.

Step 2 — Bootstrap a new project

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`](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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 437 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/mavericks-os-banner.png" alt="Mavericks OS — reliable, auditable delivery for Claude Code" width="100%">
  3. </p>
  4. # Mavericks OS for Claude Code
  5. [![CI](https://github.com/yahor-punko/mavericks-os/actions/workflows/ci.yml/badge.svg)](https://github.com/yahor-punko/mavericks-os/actions/workflows/ci.yml)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [![Node.js 20+](https://img.shields.io/badge/node-20%2B-brightgreen.svg)](https://nodejs.org/)
  8. Reliable, auditable delivery for Claude Code agents.
  9. Mavericks persists project state across sessions, routes work through
  10. specialised roles, and blocks backlog/task drift before commit.
  11. Built for operators and small teams running agent-driven development
  12. across multiple repositories.
  13. > **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.
  14. [See it in action](#close-it-come-back-tomorrow) · [Why Mavericks is different](#why-mavericks-is-different) · [Quick start](#quick-start)
  15. ## Close it. Come back tomorrow.
  16. ![A wave goal and handoff written in one session, surfaced to the next](docs/assets/session-memory.gif)
  17. *Close Claude Code, come back tomorrow — the wave goal and handoff are handed to you, not reconstructed from chat history.*
  18. Anyone juggling more than one project knows this trap: you close the
  19. laptop mid-thought, get pulled away, and by the next session you're
  20. rebuilding what you were doing from memory or a long scroll of chat
  21. history — both slow, and easy to get wrong. Mavericks writes that down
  22. instead: what was in progress and what to do next live in the project
  23. itself, so the next session opens with a clear starting point, not a
  24. guess. See [Pick up exactly where you left off](#pick-up-exactly-where-you-left-off).
  25. ## Three results
  26. - **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](#pick-up-exactly-where-you-left-off).
  27. - **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](#what-actually-carries-over-between-sessions).
  28. - **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](#a-status-that-isnt-written-down-isnt-real).
  29. ## Case study: Synth
  30. Synth is a production AWS system of 20 Git repositories and 15 active
  31. Lambda functions. Mavericks ran the operation from a single control
  32. repository whose central backlog declared 10 of those 20 repositories as
  33. task targets — the coordination is production-exercised, not merely
  34. designed, and it comes with the honest caveats of an N=1, no-control-group
  35. observation.
  36. | Metric | Value |
  37. |---|---|
  38. | Repositories in the Synth system | 20 |
  39. | Repositories declared as task targets | 10 |
  40. | Active Lambda functions (live prod) | 15 |
  41. | Tasks reaching merge or beyond | 323 (242 merged + 81 deployed_prod) |
  42. | Multi-repo tasks (target > 1 repo) | 19 |
  43. | Delivery waves | 25 |
  44. | Session checkpoints | 81 |
  45. | Control-repo commits, Mavericks era | 523 (vs 364 baseline) |
  46. | Window | 17 Apr – 13 Jul 2026 (~12.5 weeks) |
  47. This is an observational, N=1 case study — one operator, one control
  48. backlog, no control group — so the numbers show operational continuity and
  49. auditability across a coordinated system, not causal productivity.
  50. 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.
  51. [Read the full methodology, findings, and limitations →](docs/case-studies/synth.md)
  52. ## Why Mavericks is different
  53. Most agent workflows fall into one of three categories below. Mavericks
  54. overlaps with parts of each, but its shipped combination — versioned state,
  55. a validator gate, specialised roles, and production-exercised multi-repo
  56. coordination — is what the table below is comparing.
  57. | Capability | Ad-hoc prompting | Chat-memory tools | Single-repo task boards | Mavericks |
  58. |---|---|---|---|---|
  59. | Session continuity across restarts | ❌ | ⚠️ recall, not authoritative state | ⚠️ requires manually re-reading the board | ✅ versioned artifacts (`BACKLOG.md`, `TASK_STATUS.md`, `PROCESS_STATE.json`) |
  60. | Auditable, diffable decision history | ❌ | ❌ | ⚠️ issue/comment history, not structured | ✅ state and decisions live in files, diffable in git |
  61. | Automated drift detection before commit | ❌ | ❌ | ❌ | ✅ validator blocks out-of-sync backlog/task state (exit 2) |
  62. | Role-specialised execution & review | ❌ | ❌ | ⚠️ manual assignment | ✅ spec'd sub-agent roles (developer, QA, UX, security, docs, architect…) |
  63. | Multi-repository backlog coordination | ❌ | ❌ | ❌ single repo | ✅ production-exercised — 10 of 20 repos in the Synth case study |
  64. **Legend:** ✅ built-in and shipped · ⚠️ possible, but manual or partial · ❌ not addressed
  65. ## Quick start
  66. > **Before you run this:** Mavericks defaults to autonomous tool execution (`bypassPermissions`, no per-action confirmation prompts once a session starts). See **[Security model](#security-model)** below for exactly what that means and how to opt out.
  67. 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.
  68. ### Try the demo
  69. One command, no follow-up needed:
  70. ```bash
  71. curl -fsSL https://raw.githubusercontent.com/yahor-punko/mavericks-os/main/install.sh | sh -s -- --demo
  72. ```
  73. This clones Mavericks to `$HOME/.mavericks`, prompts for consent on your terminal (the `bypassPermissions` disclosure — see **[`SECURITY.md`](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.
  74. To re-run the demo later without reinstalling:
  75. ```bash
  76. "$HOME/.mavericks/scripts/mavp-operator" --demo
  77. ```
  78. (Use the absolute path above, not a relative `./scripts/mavp-operator` — that only works from inside the Mavericks checkout itself.)
  79. ### Add Mavericks to a project
  80. 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:
  81. ```bash
  82. node "$HOME/.mavericks/scripts/mavp-install.js" /path/to/your-project
  83. ```
  84. See **Manual install** below (or **[`docs/core/BOOTSTRAP_GUIDE.md`](docs/core/BOOTSTRAP_GUIDE.md)** for the full step-by-step) for what this creates and how to configure it.
  85. ### Your first session
  86. 1. Restart your editor (Claude Code or VS Code) so it picks up what was just installed.
  87. 2. Type /session-start and let your agent take it from there.
  88. 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.
  89. 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.
  90. 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`](CHANGELOG.md) explains.
  91. ### Requirements
  92. - Node.js 20+
  93. - Claude Code CLI (`claude`)
  94. - git
  95. ### Manual install
  96. For people who'd rather not `curl | sh`:
  97. ### Step 1 — Get Mavericks onto your machine
  98. Clone this repository somewhere on disk, e.g.:
  99. ```bash
  100. git clone https://github.com/yahor-punko/mavericks-os.git <path-to-mavericks>
  101. ```
  102. Everything below refers to that checkout as `<path-to-mavericks>`.
  103. ### Step 2 — Bootstrap a new project
  104. From your own project's directory (or pointing at it):
  105. ```bash
  106. node <path-to-mavericks>/scripts/mavp-install.js /path/to/your-project
  107. ```
  108. Use `--check` first to preview what would happen without writing anything:
  109. ```bash
  110. node <path-to-mavericks>/scripts/mavp-install.js --check /path/to/your-project
  111. ```
  112. 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]`.
  113. 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`](SECURITY.md)**). In prompting permission modes a single approval suffices instead. Later sessions inherit the configured permissions and the agent operates autonomously.
  114. This creates, in `your-project/`:
  115. - `scripts/mavp-operator` — a bash wrapper that delegates to this Mavericks installation
  116. - `scripts/mavp-operator-agent.js` — project-specific session-start summary
  117. - `scripts/mavp-operator-close-session.js` — end-of-session ritual
  118. - `BACKLOG.md`, `TASK_STATUS.md`, `PROCESS_STATE.md`, `PROCESS_STATE.json` — live state artifacts, from templates
  119. - `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.claude/rules/*.md` — sub-agent specs, skills, and rules, copied from this repo
  120. - `.claude/settings.json` / `.claude/settings.local.json` — shared and personal Claude Code settings (see **[Security model](#security-model)** below)
  121. - `docs/ARCHITECTURE.md` — an architecture document template, to fill in at project start
  122. - `.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
  123. 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`](docs/core/BOOTSTRAP_GUIDE.md)** for details.
  124. 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.
  125. 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):
  126. ```bash
  127. export MAVERICKS_HOME=<path-to-mavericks>
  128. ```
  129. 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.
  130. 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`](docs/core/BOOTSTRAP_GUIDE.md)**.
  131. ### Updating Mavericks
  132. Updating is two steps — one for the shared framework checkout, one per project.
  133. **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:
  134. ```bash
  135. git -C "$HOME/.mavericks" pull --ff-only # use your <path-to-mavericks> if you cloned elsewhere
  136. ```
  137. Re-running the `curl | sh` installer does the same thing — it is idempotent and pulls an existing checkout instead of re-cloning.
  138. 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>`.
  139. **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:
  140. ```bash
  141. ./scripts/mavp-operator --install --update .
  142. ```
  143. 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.
  144. 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.
  145. ## See more
  146. ![Validator catching backlog/task drift — exit 2, then fixed](docs/assets/validator-drift.gif)
  147. Drift between `BACKLOG.md` and `TASK_STATUS.md` is caught before it reaches a commit.
  148. ![The operator dashboard — one glance at where things stand](docs/assets/operator-dashboard.gif)
  149. One glance at workflow state, context usage, runtime actors, and open waits.
  150. ## How it works
  151. ### Why Mavericks exists
  152. Mavericks emerged from running agent-driven development across multiple
  153. repositories in parallel, not from a whiteboard exercise.
  154. The recurring failure mode was not code generation; it was continuity:
  155. reconstructing project state at the start of a session and losing the
  156. rationale behind decisions when chat context rolled over.
  157. Mavericks addresses that with versioned, artifact-first state (see [Pick up exactly where you left off](#pick-up-exactly-where-you-left-off) and
  158. [A status that isn't written down isn't real](#a-status-that-isnt-written-down-isnt-real) below); a strict separation between the `main_agent` orchestrator and
  159. specialised execution and review roles; and validation that surfaces
  160. backlog/task-state drift before commit.
  161. Every mechanism in this repository was retained because it solved a
  162. recurring problem in active delivery.
  163. ### Pick up exactly where you left off
  164. Losing the thread of a project between sessions is the everyday
  165. failure this framework exists to prevent — not by asking for better
  166. notes, but by having the project keep its own notes and hand them back
  167. automatically.
  168. Every session opens with a short brief, worked out fresh each time,
  169. never from a hand-kept list:
  170. - **What's in flight** — read straight from the task files, so it
  171. can't quietly go stale.
  172. - **One next action** — a single line telling you what to do next.
  173. - **What changed while you were away** — files touched since the last
  174. time a session was formally closed, including anything you haven't
  175. committed yet, drawn from the repository itself, not a guess.
  176. - **A handoff note, when one was left** — mid-thought context, written
  177. to `HANDOFF.md`, handed back immediately.
  178. For example (illustrative, not a literal transcript) — just two of
  179. the four parts above, the changed-files list and the next action:
  180. ```
  181. Must read:
  182. - lambda/handler.py
  183. Next action: T-231 → developer → fix the retry bug
  184. ```
  185. `HANDOFF.md` is not written automatically when a session ends. Writing
  186. it is a separate, deliberate step (`--handoff`); closing a session
  187. (`--close-session`) does not do it, and it's single-use — delivered
  188. once at the next session's start, then deleted. The next-action line
  189. itself stays narrow on purpose — one instruction, never a running
  190. commentary; anything longer belongs in the handoff note instead.
  191. ### A status that isn't written down isn't real
  192. Telling an agent something is done, and having it actually be done,
  193. are two different things — this section closes that gap. A task's
  194. status changes only when it's written into the project's own task
  195. files, never because someone said so in conversation.
  196. Two files carry that status side by side, and they're required to
  197. agree. A check runs automatically after every edit to either one; it
  198. doesn't stop the edit, it just flags the moment they drift apart, so
  199. the gap is caught immediately instead of days later. The strictest
  200. version of that check sits at the door to history: a task can't be
  201. recorded as fully merged without pointing to the real code change that
  202. shipped it — get that wrong and the record can't be committed. Full
  203. state machine and evidence rules:
  204. [`docs/core/TASK_LIFECYCLE.md`](docs/core/TASK_LIFECYCLE.md).
  205. ### What actually carries over between sessions
  206. Closing a chat and starting a new one never loses anything that
  207. matters, because none of it — a task's status, its history, a
  208. decision made along the way — ever lived in an agent's memory to begin
  209. with; all of it lives in the files described above. Every specialised
  210. agent doing a piece of work is briefed fresh from those same files
  211. each time, with no memory of its own carried in from a previous run.
  212. What does travel forward isn't a fact about any one task — it's
  213. practice: lessons about what tends to go wrong, folded back into the
  214. written instructions those agents read next time, only after a person
  215. has reviewed and approved the change. There is no separate memory
  216. store behind any of this — the files are the only place state lives.
  217. ### Cross-repo coordination
  218. Mavericks runs a **direct-reference model**: one framework checkout serves
  219. many projects, and state is never replicated per repository. A single
  220. control repo holds the one `BACKLOG.md`, `TASK_STATUS.md`, and
  221. `PROCESS_STATE.json`; every sibling repository's `scripts/mavp-operator`
  222. wrapper delegates back to that one checkout via `MAVERICKS_PROJECT_ROOT`
  223. rather than carrying its own copy of these files.
  224. Cross-repo tasks declare a `Repos:` field in the backlog (e.g.
  225. `- **Repos:** repo-a, repo-b`). When a sub-agent completes work in a
  226. sibling repository, its evidence is recorded back into the control repo's
  227. `TASK_STATUS.md` as one line per repo — `commit: <hash> (repo-a)`,
  228. `commit: <hash> (repo-b)` — so the control backlog stays the single,
  229. auditable source of truth for *where* work landed even though the diffs
  230. live in the sibling repositories. Before dispatching a cross-repo task, the
  231. main agent runs the cross-repo pre-flight described in
  232. [`docs/core/ORCHESTRATION_RULES.md`](docs/core/ORCHESTRATION_RULES.md);
  233. `./scripts/mavp-operator --check-sync` compares agent/skill files across
  234. known projects against the Mavericks source to catch drift between them.
  235. Cross-repo *ordering* is enforced, not just recorded: a task may declare
  236. `- **Blocked by:** <repo>/T-NNN` (comma-separated for multiple references;
  237. distinct from the same-repo `Depends on:` field). The validator resolves
  238. `<repo>` to a local working copy via the repo-map registry
  239. ([`docs/REPO_MAP.md`](docs/REPO_MAP.md)) and reads the blocker task's status
  240. from that repo's own artifacts: a task recorded `merged` while its blocker is
  241. not yet `merged` is a blocking failure (exit 2), a task at `qa_passed` or
  242. `ready_for_qa` with an unmet blocker gets a warning, and an unresolvable
  243. reference (unknown repo id or missing blocker task) surfaces as an info-level
  244. advisory rather than a block.
  245. This is production-exercised, not a design sketch: 10 of the Synth case
  246. study's 20 repositories were declared as task targets from the one control
  247. backlog, with 19 tasks explicitly targeting more than one repository (see
  248. [Case study: Synth](#case-study-synth)).
  249. ```
  250. ┌──────────────────────────────────┐
  251. │ control repo (mavericks) │
  252. │ BACKLOG.md · TASK_STATUS.md · │
  253. │ PROCESS_STATE.json (single copy) │
  254. └──────────────────────────────────┘
  255. │
  256. main_agent orchestrator
  257. │
  258. task carries `Repo: repo-a, repo-b, ...`
  259. │
  260. ┌───────────────────┬─────────┴─────────┬───────────────────┐
  261. ▼ ▼ ▼ ▼
  262. sibling repo A sibling repo B sibling repo C sibling repo N
  263. (sub-agent (sub-agent (sub-agent (sub-agent
  264. commits code) commits code) commits code) commits code)
  265. │ │ │ │
  266. └───────────────────┴─────────┬─────────┴───────────────────┘
  267. ▼
  268. evidence recorded back to control repo:
  269. `commit: <hash> (repo-a)` · `commit: <hash> (repo-b)` · ...
  270. │
  271. ▼
  272. validator · QA · security review gates
  273. │
  274. ▼
  275. AWS deployment (15 active Lambdas)
  276. ```
  277. ## Under the hood
  278. Reference material for readers who want the details — none of this is required to get started.
  279. - **What files a bootstrapped project has, and why.** See [`docs/core/BOOTSTRAP_GUIDE.md`](docs/core/BOOTSTRAP_GUIDE.md) — "What gets installed".
  280. - **How a task moves from idea to shipped.** See [`docs/core/TASK_LIFECYCLE.md`](docs/core/TASK_LIFECYCLE.md).
  281. - **Who does what — developer, QA, architect, and the rest.** See the summary table in [`docs/core/ROLES.md`](docs/core/ROLES.md).
  282. - **How drift gets caught before it reaches a commit.** See [`docs/core/BOOTSTRAP_GUIDE.md`](docs/core/BOOTSTRAP_GUIDE.md) — "Pre-commit hook".
  283. - **The full list of operator commands.** Run `./scripts/mavp-operator --help` from your bootstrapped project.
  284. ## Security model
  285. 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`](SECURITY.md)** for exactly what it means, how to opt out before your first session, and how to report a vulnerability.
  286. Mavericks is not a deliverable product you run in production — it's a reusable framework that other projects **adopt** into their own repository.
  287. ## Core docs
  288. All in [`docs/core/`](docs/core/):
  289. | Doc | What it covers |
  290. |---|---|
  291. | [`ROLES.md`](docs/core/ROLES.md) | Role definitions |
  292. | [`TASK_LIFECYCLE.md`](docs/core/TASK_LIFECYCLE.md) | Full task state machine |
  293. | [`ORCHESTRATION_RULES.md`](docs/core/ORCHESTRATION_RULES.md) | Main agent coordination rules |
  294. | [`APPROVALS_AND_BLOCKERS.md`](docs/core/APPROVALS_AND_BLOCKERS.md) | Blocker format and silence rule |
  295. | [`QA_HANDOFF.md`](docs/core/QA_HANDOFF.md) | QA handoff protocol |
  296. | [`BOOTSTRAP_GUIDE.md`](docs/core/BOOTSTRAP_GUIDE.md) | Step-by-step new project setup |
  297. | [`NEW_PROJECT_CHECKLIST.md`](docs/core/NEW_PROJECT_CHECKLIST.md) | Bootstrap checklist |
  298. | [`OPERATOR_DASHBOARD.md`](docs/core/OPERATOR_DASHBOARD.md) | Operator dashboard panel reference |
  299. | [`DOC_SYNC.md`](docs/core/DOC_SYNC.md) | Doc-sync advisory (post-merge doc-update reminders) |
  300. | [`DECISIONS.md`](docs/core/DECISIONS.md) | Framework decision records (`DR-NNN`) with greppable lineage fields (`Informed by:` / `Supersedes:` / `Tasks:` / `Session:`) |
  301. | [`RCA_CODIFICATION.md`](docs/core/RCA_CODIFICATION.md) | RCA-to-codification — every root-cause analysis must route each root cause to exactly one durable fix mechanism, with a tracked follow-up task |
  302. | [`SECRET_LEAK_RESPONSE.md`](docs/core/SECRET_LEAK_RESPONSE.md) | Post-publish secret-leak response runbook |
  303. | [`FEEDBACK_INTAKE.md`](docs/core/FEEDBACK_INTAKE.md) | Adopter feedback loop — file friction with `--feedback`, follow the answer, and retire a tagged stop-gap with `--migrate` |
  304. ## Feedback from adopters
  305. 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.
  306. 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.
  307. 2. Copy [`templates/FEEDBACK_ITEM_TEMPLATE.md`](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.
  308. 3. Follow it with `--feedback --status`, and clear the answer's reminder with `--feedback --ack <id>`.
  309. 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`.
  310. 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.
  311. The full loop, including what the maintainer's side does with your item, is in [`docs/core/FEEDBACK_INTAKE.md`](docs/core/FEEDBACK_INTAKE.md).
  312. ## Contributing
  313. See **[`CONTRIBUTING.md`](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](CODE_OF_CONDUCT.md)**.
  314. ## License
  315. Mavericks is licensed under the [MIT License](LICENSE). It vendors one third-party component (the `frontend-design` skill, Apache-2.0) — see **[`NOTICE`](NOTICE)** for the full attribution and carve-out.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.