Maestro-Flow: the install line pins 0.5.82 and the package is at 0.5.89

The install line pins a version seven releases old

The install section pins an exact version:

npm install -g [email protected]
maestro install          # 交互式选择安装组件

The comment on the second line is Chinese and says the install step is an interactive component selection. package.json declares 0.5.89, and the three newest tags are v0.5.87 on 2026-09-18, v0.5.88 on 2026-09-21 and v0.5.89 on 2026-09-24, which is also the last push to the master branch. The pinned 0.5.82 is therefore not the current build, and no second command on the page installs the current one.

Requirements are Node.js 22.19 or newer plus at least one host CLI, Claude Code by default and/or Grok Build, with Codex CLI and agy CLI optional for multi-agent workflows. The Grok paragraph adds the sharpest constraint: install the official 0.5.82 first, run the install script at the repository root, which takes a `--path` option, and a mismatch against the official version fails outright instead of downgrading. Project instructions land in `.grok/rules/maestro.md`, and the Maestro section of a legacy `.grok/AGENTS.md` is stripped on reinstall. Project-level MCP and hooks require trusting the Grok folder in that directory, through an interactive confirmation or `/hooks-trust`, while user-level `maestro-tools` does not depend on that trust. If patches are applied and only project assets are missing, running the same script again is the documented fix. That makes the pin load-bearing rather than decorative.

Four executables on PATH, one of them documented

A global install puts four binaries on PATH. The bin map is `maestro`, `maestro-mcp`, `maestro-statusline` and `maestro-context-monitor`, and this page documents only the first.

After installing, the page teaches a four-command sequence and labels it v3 only:

maestro session open
maestro run next
maestro run complete --advance
maestro session complete

Everything else is taught in the other vocabulary. The intent entries are slash commands: `/maestro-ralph` for the closed-loop strategy layer, `/maestro` for intent-to-chain planning, `/maestro-next` as a pure router to a companion run or a single Run, `/maestro-companion` for a minimal run lifecycle, and `/maestro-odyssey` for the long-running loops. Ralph carries two flags of its own: `-c` resumes from a decision pause point, and `-y` runs fully automatic without confirmation. Its chain is built as analyze, plan, execute, verify, review and test, with brainstorm and blueprint prepended for a new project, and the page is explicit that no YAML and no pipeline configuration are involved. The docs index describes one guide as covering 64 slash commands and another as a quick reference for 35 or more terminal commands, so the four shown are a fraction of either surface, and nothing on this page maps one vocabulary onto the other.

Six backends in prose, five in the table, agy in neither list

Backend coverage is stated three times and the three statements do not line up. The orchestration paragraph names Claude, Codex, Gemini, Qwen, OpenCode and Grok as backends that can be mixed inside one workflow. The comparison table at the bottom of the page says four modes across five backends. The install section names a different set again: Claude Code as the default host, Grok Build as an alternative, and Codex CLI plus agy CLI as optional extras for multi-agent work.

So Gemini, Qwen and OpenCode appear as schedulable backends without appearing in the requirements, and agy appears in the requirements without appearing in the backend list. Nothing on the page says whether these are the same set described at different levels of detail.

The comparison table is also cut off partway through its last row, so the entry about long-running work, the one that would say how each rival handles hours of unattended execution, stops after its first cell.

A literal route that skips ranking, and four capabilities left off

Search has a second path that bypasses ranking entirely:

maestro search "Authorization: Bearer" --exact
maestro search "needle" --exact --include-linked-code --json

`--exact` goes straight to a bundled `@vscode/ripgrep` and reports a relative filePath with line and column and a preview, and it deliberately does not take part in the default search ranking or fusion. By default only the current repository is searched, and linked code requires both `--include-linked-code` and a `codebase` read share. `.gitignore`, `.maestroignore`, sensitive directories and the timeout, result and byte limits apply in every mode.

Ranked search defaults to low latency BM25, and embedding reranking turns on only when `--semantic` is passed. `--diagnostics` returns bounded, request-scoped diagnostics that ride inside the response under `--json` and go to stderr otherwise. The search guide in the docs index calls the ranking stack BM25F, one letter from the BM25 named here. Four capabilities, adaptive candidate budget, compiled postings, file incremental indexing and structured chunks, are described as controlled experiments that stay off by default and do not change the default search contract.

Three old tarballs at the root, and an allowlist that hides them

The repository root mixes product directories with working files. Next to `src/`, `dashboard/`, `guide/`, `docs/` and `workflows/` sit three packed tarballs of the package itself, `maestro-flow-0.2.0.tgz`, `maestro-flow-0.5.60.tgz` and `maestro-flow-0.5.64.tgz`, plus `.mcp.json.bak`, `diff-indexer.txt`, `diff-root.txt`, `diff-wiki.txt`, `docs-site-snap.txt`, `sidebar-snapshot.txt`, `toc-check.png`, `repro-atomic.mts`, `test-goal.txt`, and the directories `tmp/`, `coverage/`, `test-ui/`, `.history/` and `ref/`.

None of that reaches npm, because the package declares an allowlist instead of shipping the tree. The files array covers `bin`, `dist`, `resources/lifecycle-fs`, `resources/arch-kb`, `shared`, `templates`, `prepare`, `workflows`, `ref`, `overlays/_shipped`, the `.claude`, `.codex`, `.agy` and `.agents` command, agent and skill folders, and `dashboard/dist-server` with `dashboard/package.json` and `dashboard/vendor`.

The two negations are the interesting part: `!ref/zvec-grep` excludes a native binary and `!dashboard/vendor/transformers/.cache` excludes a model cache, so the tarball ships the transformers build output without the cache that would have made it large.

Subpath imports point into compiled dashboard output

Several entry points resolve into build output rather than source. The imports map sends the transformers alias to the vendored build and the dashboard aliases into the compiled server directory:

"imports": {
  "#built-search-adapter-contract": "./shared/built-search-adapter-contract.mjs",
  "#maestro-transformers": "./dashboard/vendor/transformers/dist/transformers.node.mjs",
  "#maestro-dashboard/agents/*": "./dashboard/dist-server/dashboard/src/server/agents/*",
  "#maestro-dashboard/shared/*": "./dashboard/dist-server/dashboard/src/shared/*",
  "#maestro-dashboard/wiki/*": "./dashboard/dist-server/dashboard/src/server/wiki/*",
  "#async/*": "./dashboard/dist-server/src/async/*"
}

`main` is `dist/src/index.js` and `types` is `dist/src/index.d.ts`. The build script runs a native lifecycle verification, compiles the dashboard against its own tsconfig, compiles the root project, and then runs an inline node step whose body is cut off in the manifest as published.

The consequence for an installer is concrete: `dashboard/dist-server` has to exist before those four subpath imports resolve, which is why the allowlist carries it, and the vendored transformers distribution travels with every install.

The same compilation boundary shows in the source layout. `src/commands/` holds the 35 or more CLI commands, `src/mcp/` the MCP server over stdio, `src/graph/` the knowledge graph built on SQLite and tree-sitter, and `src/core/` tool registration and extension loading, with the React 19 dashboard in its own directory and the slash commands, agent definitions and skill packs under `.claude/`. The declared stack is Commander.js, MCP SDK, better-sqlite3, web-tree-sitter, React 19, Zustand, Tailwind CSS 4, Hono and Vite 6.

A LICENSE badge and an INSTALL.md reference with neither file present

Two links point at files the tree does not hold. The badge row links to LICENSE, and no LICENSE entry appears among the top-level files, while the repository's license metadata is empty. The Grok instructions send you to INSTALL.md at the repository root, which is absent too, while the product-level detail is pointed at `guide/install-guide.md`, and a `guide/` directory does exist.

The documentation followed here is the Simplified Chinese README, and the tree carries `README.en.md` beside it, with a language switch at the top of the page linking the two. The page also counts itself twice. The scale line gives 333 TypeScript files, about 80k lines, 64 slash commands, 45 skill packs, 23 agent definitions, 35 or more CLI commands and 92 templates. The directory listing describes `workflows/` as 115 workflow definitions and `templates/` as 92 JSON templates. Behind all of it the docs index numbers 22 guides, including one covering 17 hooks, one covering 9 MCP endpoint tools and a Collab mode sized for 2 to 8 people.

Three quality modes and two Odyssey loops that only read

Pipeline depth is chosen by name. Three quality modes set how much runs: `full` runs verify, business-test, review, test-gen and test for production and security-critical work, `standard` runs verify, review and test as the balanced default, and `quick` runs verify then CLI-review for prototypes and hot fixes. The core pipeline itself is brainstorm, optional blueprint, analyze, plan, execute and verify, with a decision node after verify that continues, rolls back or inserts a debug, fix and retry loop.

Odyssey adds a separate entry point, `/maestro-odyssey <intent> --mode <name>`, with seven loops. debug, planex, improve, review and ui all run to fixes and verification. `security` is read-only and layers OWASP checks with dependency, secret and STRIDE analysis. `defensive` is read-only as well, running from business anchors through reverse slicing, a scan of eight defensive node categories, forward propagation and a risk score. Odyssey runs until its acceptance criteria are met and persists what it learns.

Multi-agent work is the fourth dimension: Delegate for asynchronous delegation, Team for role collaboration, Wave for dependency-parallel work and Swarm for exploratory fan-out.

What ties the layers together is the knowledge store. Patterns, pitfalls and decisions an agent runs into are persisted automatically as Spec and Knowhow entries, and the hook system injects the relevant ones into the prompts of later agents, so the same finding is paid for once. The graph lives in SQLite with tree-sitter parsing, the knowledge management guide covers Spec, Knowhow and Wiki together, and one of the 22 guides is dedicated to the 17 hooks and their context budget.

Editorial conclusion

Maestro-Flow is a large surface with a small, precise install contract, and the two are documented in different files. It suits someone who already runs a coding agent CLI and wants slash commands that classify intent instead of hand-picked pipelines, and it does not suit anyone who installs from the page without noticing the version pin or who needs to know which backends are actually wired up, since the prose names six, the comparison table says five, and agy appears only in the requirements. Before the first run, read the version you are installing, check which of the four global executables you want on your PATH, decide whether a bundled ripgrep literal route or BM25 ranking fits your searches, and treat the four disabled search capabilities as absent until something turns them on.

Frequently asked questions

Official sources

1. catlog22/maestro-flow on GitHub
2. Issues
3. Project website
4. README
5. Releases