maxvision

> **Read in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](README.pt-BR.md) # Claude Code MaxVision [](LICENSE) [](https://github.com/produtoramaxvision/maxvision/actions) [](CHANGELOG.md) Dynamic skill + subagent orchestrator for Claude Code — zero session-startup overhead, version integrity on autopilot, human-driven provisioning. > **Pre-1.0 stability notice.** This plugin is in the `0.x.y` series. Breaking changes > can land in minor versions until `1.0.0` ships. Pin to a specific tag if your > automation depends on a particular hook/skill API shape. See [CHANGELOG.md](CHANGELOG.md) > for migration notes on every release. --- ## Overview MaxVision eliminates the 15k-token agent overhead in Claude Code 2.1.x by keeping 500+ specialist subagents and 4,000+ skills in an FTS5 catalog and materializing only what each task requires. The orchestrator reads your cheatsheets, audits locally installed components, checks upstream commits, and presents a single approval prompt before dispatching to the right agent with the right skills loaded. **Three guarantees:** - **Zero-overhead discovery** — BM25 full-text search across 500+ agents and 4,000+ skills. No cumulative agent descriptions in the system prompt; no session-startup overhead. - **Version integrity on autopilot** — upstream commit check before every install or update. One-hour cache with `--force-check` bypass. Origin tracked in `.maxvision-source.json` per component. - **Human-driven provisioning** — single approval prompt (`sim / all / skip-N / none`). Updates run before installs. Tier 4 entries require explicit per-line sign-off even in batch mode. --- ## Skills | Skill | Purpose | | --- | --- | | `orchestrate` | Master entry point — 8-phase flow with clarity gate, multi-task split, lazy-load agents. | | `route-task` | FTS5 + BM25 discovery; picks subagent + skills for the task. | | `discover-skill` | Lookup missing skills in the curated catalog. | | `discover-agent` | BM25/FTS5 lookup for agents by keyword. | | `check-version` | Compare local `gitCommitSha` with upstream (cache 1h, `--force-check` bypass). | | `update-component` | Apply upstream update to a skill or agent. | | `install-skill` | Install via sparse-clone, marketplace, synthesis, or antigravity. | | `install-agent` | Install agent on-demand (lazy-load model — `from_cache`, `sparse_clone`, `raw_url`). | | `uninstall-agent` | Remove a lazy-installed agent (manual only; never auto-invoked). | | `audit-local-skills` | Read-only inventory with redundancy detection and budget report. | | `synthesize-skill` | Create a custom `maxvision-<name>` skill from complementary upstream sources. | | `refresh-catalog` | Re-fetch upstream metadata for the FTS5 catalog. | --- ## Slash Commands 40 commands across 5 categories, all under `/maxvision:`. Full reference: [docs/COMMANDS.md](docs/COMMANDS.md). | Category | Commands | | --- | --- | | **Spec & Planning** | `spec-phase`, `discuss-phase`, `writing-plans`, `executing-plans`, `plan-phase` | | **Execute & Ship** | `execute-phase`, `ship`, `verify-phase`, `pr-branch`, `complete-milestone` | | **Review** | `code-review`, `pr-review`, `security-audit`, `qa`, `inbox` | | **Lifecycle** | `progress`, `pause-work`, `resume-work`, `cleanup`, `health`, `forensics` | | **Update** | `update [--force\|--json]`, `check-update [--force\|--json]` | --- ## Installation ### Option 1 — Marketplace (recommended) ```text /plugin marketplace add produtoramaxvision/maxvision /plugin install maxvision@maxvision ``` ### Option 2 — Local development ```bash git clone https://github.com/produtoramaxvision/maxvision.git claude --plugin-dir ./maxvision ``` --- ## Quick Start ```text # Orchestrate a complex task /maxvision:orchestrate refactor src/components/Foo.tsx to use shadcn Select and add unit tests # Plan before coding /maxvision:plan-phase --phase 2 --interactive # Ship a completed phase /maxvision:ship --phase 3 # Check for plugin updates /maxvision:update --force ``` For the full guided walkthrough, see [docs/QUICKSTART.md](docs/QUICKSTART.md). --- ## How to invoke orchestrate The `orchestrate` skill is the multi-domain dispatcher (10 phases P0..P10). It has **two** activation surfaces: | Form | What it is | Notes | | --- | --- | --- | | `/maxvision:orchestrate <task>` | Canonical slash command (real) | The only real slash. Always works. Use in scripts, docs, and automations. Resolves through the plugin's `commands/` directory. | | Natural-language mention or trigger phrase | Skill `when_to_use` auto-activation | When your prompt matches phrases like "use the best subagent for…", "tarefa complexa: …", "rote essa tarefa", or simply mentions "orchestrate" / "orquestre" in context, Claude reads the skill's `when_to_use` metadata and invokes `orchestrate` on its own. See the skill's frontmatter for the full trigger list. | > **Note.** Plugin slash commands in Claude Code are namespaced — only `/maxvision:orchestrate` resolves through the plugin's command resolver. A bare `/orchestrate` typed in chat is **not** a real plugin slash command; it works (when it works) only because Claude's main thread recognizes the textual mention and dispatches through skill auto-activation. If you need a guaranteed dispatch in a script or automation, use the namespaced form. There is **no LLM in any plugin hook** — auto-activation is driven by the skill's `when_to_use` metadata and Claude Code's main-thread interpretation, not by a subprocess classifier. Hooks in this plugin are 100% deterministic (regex / JSON / file IO). If you previously relied on a `UserPromptSubmit` LLM nudge, see the [v0.1.1 BREAKING CHANGE notes](CHANGELOG.md#011--2026-05-28) — the nudge was removed because subprocess hooks cannot inherit Claude Code's OAuth credentials, so the SDK call always failed. --- ## Statusline (optional) MaxVision ships a Claude Code statusline showing: model · MaxVision state (milestone/status/phase) · directory · context-window progress bar. Composes with the **caveman** plugin automatically. Activate by adding one entry to `~/.claude/settings.json`: **Linux / macOS:** ```json "statusLine": { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/maxvision-statusline.sh" } ``` **Windows:** ```json "statusLine": { "type": "command", "command": "powershell -ExecutionPolicy Bypass -File \"${CLAUDE_PLUGIN_ROOT}/hooks/maxvision-statusline.ps1\"" } ``` Or run `/maxvision:setup-statusline` — the auto-install hook writes the correct absolute path for your platform. --- ## CLI Helpers Four CLI tools are automatically in your `PATH` while the plugin is enabled. All validate identifiers against strict regexes before invoking external dependencies — path traversal and shell metacharacters are rejected with `rc=2`. ### `bin/maxvision-skills` ```bash maxvision-skills list # list all local skills maxvision-skills find <keyword> # search catalog + local by keyword maxvision-skills check [--force] <comp> # version check (cached 1h) maxvision-skills install <skill-id> # interactive install maxvision-skills update <component> # interactive update maxvision-skills audit # redundancy + budget + telemetry report maxvision-skills search <query> # BM25 ranking against indexed skills ``` ### `bin/maxvision-agents` ```bash maxvision-agents list # list installed agents maxvision-agents find <keyword> # search FTS5 catalog by keyword maxvision-agents check [--force] <name> # version-check (sidecar vs upstream) maxvision-agents audit # inventory + 15k-token budget estimate maxvision-agents search <query> # top-10 BM25 ranking ``` ### `bin/maxvision-dispatch` ```bash maxvision-dispatch run <agent> "<task>" [--worktree] [--model=sonnet|opus|haiku] maxvision-dispatch list # list maxvision-* agents available locally maxvision-dispatch status # opens `claude agents` UI maxvision-dispatch attach <session-id> maxvision-dispatch logs <session-id> ``` ### `bin/maxvision-sources` ```bash maxvision-sources list # sources grouped by tier maxvision-sources add <github-url> # add new source (autodetect metadata) maxvision-sources verify <id> # reachability check + FTS5 stats maxvision-sources rebuild # rebuild FTS5 index from sources maxvision-sources stats # tier counts + install-method breakdown ``` --- ## Troubleshooting ### Skill invisible after install (`paths:` bug — CC #49835) Adding `paths: ["**/*.ts"]` to a skill frontmatter makes it undiscoverable in Claude Code ≥ 2.1.84 (upstream bug [#49835](https://github.com/anthropics/claude-code/issues/49835), open). **Workaround:** remove the `paths:` field; encode path-scoping in the `description` instead. This plugin's `validate.yml` CI blocks any PR adding `paths:` to a `SKILL.md`. ### `gh: command not found` / `jq: command not found` Both must be in PATH for catalog operations and version checks: - Windows: `winget install GitHub.cli jqlang.jq` - macOS: `brew install gh jq` - Linux: `apt-get install gh jq` / `dnf install gh jq` Verify with `gh auth status` and `jq --version`. --- ## Requirements - Claude Code ≥ 2.0 - `gh` CLI authenticated (`gh auth status`) — used by `check-version` and `install-agent` - `jq` in PATH — used by version comparison and JSON parsing - `npx` (Node ≥ 18) — only for the antigravity install path --- ## Hard Rules (Guardrails) 1. **Never installs or updates silently** — single approval prompt with `sim / all / skip-N / none`. 2. **`general-purpose` dispatch** is permitted only as Phase 8 fallback with full agent body injection. Set `MAXVISION_DISALLOW_GENERAL_PURPOSE=1` to opt out. 3. **Max 3–4 subagents in parallel** — prevents context pollution. 4. **Updates run before installs** — updates can change resolution of new installs. 5. **Tier 4 entries require per-line approval** even in batch mode. 6. **No `git pull` without `--ff-only`** — prevents accidental merges. 7. **No deletion of user-authored files** — only files installed by this orchestrator. --- ## Architecture See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the 8-phase orchestration flow diagram, FTS5 indexing strategy, synthesis pipeline, cache layout, and `.maxvision-source.json` schema. --- ## Catalog of Sources Four trust tiers documented in [docs/CATALOG-SOURCES.md](docs/CATALOG-SOURCES.md): - **Tier 1 (Official Anthropic):** `anthropics/skills` - **Tier 2 (Curated premium):** Antigravity, Composio, addyosmani, Obra, and others - **Tier 3 (Domain-specific):** Trail of Bits, shadcn/ui, Expo, and others - **Tier 4 (Evaluate with caution):** High-overlap or unmaintained sources --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). Join the community: | Channel | Best for | | --- | --- | | [Discord](https://discord.gg/XnbSGnXEv) | Real-time help, orchestration tips, pairing | | [Discussions](https://github.com/produtoramaxvision/maxvision/discussions) | Design proposals, async Q&A | | [Issues](https://github.com/produtoramaxvision/maxvision/issues) | Reproducible bugs and concrete feature requests | Security findings → [SECURITY.md](SECURITY.md) — never public issues. OpenSSF Scorecard: [securityscorecards.dev](https://securityscorecards.dev/viewer/?uri=github.com/produtoramaxvision/maxvision). --- ## Commercial Services MaxVision offers premium support, custom skill catalog development, and AI workflow consulting for teams. See [docs/COMMERCIAL.md](docs/COMMERCIAL.md) for tiers and pricing. Contact: `contato@maxvision.com.br`. --- ## Changelog See [CHANGELOG.md](CHANGELOG.md). --- ## License MIT — see [LICENSE](LICENSE). Third-party attributions: [LICENSES/THIRD-PARTY-NOTICES.md](LICENSES/THIRD-PARTY-NOTICES.md). --- © 2026 [Produtora MaxVision](https://github.com/produtoramaxvision)