puppetmaster

# Puppetmaster Multi-agent orchestrator that runs adapter workers (Cursor SDK / Claude Code / Codex / Hermes) as durable, SQLite-backed subprocesses with leases, structured JSON artifacts, per-task model routing, and isolated git worktrees. Published on PyPI as `puppetmaster-ai`; the **CLI mirrors every MCP verb**. Prefer Puppetmaster verbs over a solo grep/read loop or the built-in delegation for: single focused edits that benefit from CodeGraph or cheap-model routing, broad investigation, multi-file audits, and cross-cutting changes. ## Surfaces (two, in priority order) 1. **MCP tools** — names are prefixed `mcp_puppetmaster_puppetmaster_*`. Use `tool_search` to find a verb, `tool_describe` to load its schema, `tool_call` to invoke. This is the primary path. 2. **CLI fallback** (`python -m puppetmaster ...`) when MCP isn't connected. The MCP server shells out to its own resolved interpreter, so MCP can work even when `python -m puppetmaster` fails in the *current* venv. ## Match the verb to the task shape | Task shape | Verb | Why | |---|---|---| | **One focused edit** ("fix this fn", "add a flag", "wire up retries") | `edit` | Cheapest sufficient model + CodeGraph + in-place edit + synchronous diff. The snappy path between editing inline and a full implement job. | | **One coupled multi-file feature** | `start_implement` | Isolated clean worktree, one coherent PATCH artifact. Grok Bot contained path is agentic (keys-only), not Cursor SDK. | | **One focuse...