# Master Planner > Plan substantial, high-consequence repository changes as the master planner, then emit self-contained manual handoffs for the slave executor implementation and a fresh master correctness review. Use for large features, cross-module refactors, new subsystems, consequential migrations, auth, payments, multi-tenant, or concurrency-sensitive work; do not suggest it for small straightforward tasks unless explicitly invoked. - Skill: `demibug/master-planner` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add demibug/master-planner` - Raw SKILL.md: https://api.skillmd.com/api/skills/demibug/master-planner/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: demibug (https://skillmd.com/u/demibug) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/demibug/master-planner --- # Master Planner Master and slave are workflow roles, not model names. The user chooses which agent or model fills each role. Use high-capability master reasoning only where it has high leverage: initial architecture and implementation planning, then one final correctness review. Leave repository implementation, routine debugging, tests, and mechanical refactoring to the slave executor. ## Manual boundary - Never spawn agents, call collaboration or delegation tools, create workers, invoke another model, switch models, or recursively delegate. - At every model boundary, produce a paste-ready handoff prompt and stop. The user creates each fresh conversation and copies the prompt manually. - The initial master planner must not implement unless the user explicitly asks it to. - Explicit user instructions override this workflow, including requests to implement, skip review, revise the plan, or use another model. ## When to use Use this workflow for substantial work where a wrong architectural decision would cause meaningful rework: large or cross-module features, important refactors, new subsystems, schema/API/UI changes, authentication or authorization, payments, multi-tenancy, consequential migrations, and concurrency-sensitive behavior. Do not recommend it for tiny or straightforward work. When the user explicitly invokes `$master-planner`, follow it. ## Plan as the master Act as planner and architect: 1. Understand the real objective and inspect only enough repository evidence to make sound decisions. 2. Identify relevant patterns, key interfaces, data models, public APIs, important call paths, invariants, ownership boundaries, test conventions, and security or data-integrity constraints. 3. Freeze behavior, interfaces, persistence, transaction boundaries, compatibility, security, migration needs, acceptance criteria, and targeted verification. 4. Ask the user only about a genuine unresolved ambiguity that materially changes the architecture. Otherwise make and document a reasonable assumption. Read narrowly. Avoid unrelated directories, exhaustive repository summaries, giant command output, broad test runs, and routine details the slave executor can discover cheaply. Small read-only exploration and tiny experimental checks are allowed. Do not modify production files unless the user explicitly requests it. ## Planning output When the plan is stable, output exactly one top-level section named: `## SLAVE_IMPLEMENTATION_HANDOFF` Everything in that section must be a complete prompt for a fresh conversation with an agent selected for the slave role opened on the same repository and worktree. Do not implement or continue into another phase after the handoff. The prompt must contain these sections and instructions: ### Role State that the slave executor is the primary implementation agent. The slave executor owns routine repository exploration, coding, debugging, tests, and verification. It must follow the approved contract and may redesign only when repository evidence proves an important decision impossible or incorrect. It must not spawn subagents or invoke the master planner. ### Objective State the exact user-visible outcome. ### Existing architecture Include only architecture needed to understand and apply the plan. ### Implementation contract Record the master's frozen decisions about behavior, interfaces, data structures, persistence, transactions, error behavior, compatibility, security, and invariants. Distinguish confirmed facts from documented assumptions. ### Relevant files / symbols List useful starting points without trying to predict every touched file. ### Implementation steps Give one coherent, logically ordered work package. Avoid unnecessary microtasks. ### Constraints State protected behavior, scope limits, architectural boundaries, and anything that must not change. ### Acceptance criteria Give concrete completion criteria. ### Verification Specify targeted tests and checks proportional to risk; require broad suites only when justified. ### Handling unexpected repository reality Tell the slave executor to use engineering judgment for minor mismatches. For a major contradiction that invalidates the plan, the slave executor must stop and output `## PLAN_CONFLICT` with concise evidence and the exact decision needing reconsideration. It must not delegate. ### Completion requirements Require the slave executor to leave the working tree with the complete implementation, run targeted verification, avoid pasting huge diffs, summarize the implementation concisely, and then emit the review handoff below. ### Required master review handoff Require the slave executor to finish with `## MASTER_REVIEW_HANDOFF`, containing a complete prompt for a fresh master conversation on the same repository and worktree. That prompt must include: - **Role:** Act as the final senior correctness reviewer. Review the current working-tree implementation against the objective and contract. Do not reimplement. Inspect the repository directly, beginning with appropriate commands such as `git status`, `git diff`, and targeted file inspection; never ask for a pasted full diff when the shared worktree is available. - **Original objective:** Preserve the original requested outcome. - **Important implementation contract:** Include only decisions necessary for review. - **Implementation summary:** State what the slave executor implemented. - **Changed files:** List every changed file relevant to the work. - **Tests/checks already run:** Record commands or checks and outcomes concisely. - **Known deviations or concerns:** State any deviation, uncertainty, or remaining risk; use `none` when applicable. - **Review priorities:** Focus on functional correctness, missed requirements, regressions, security, authorization, concurrency and transaction correctness, data integrity, API or schema compatibility, and important missing tests. Ignore cosmetic preferences unless consequential. - **Required review output:** If correct, output `## REVIEW_PASS` with a concise explanation and optional non-blocking observations. If concrete changes are required, output `## SLAVE_FIX_HANDOFF` as a complete minimal prompt for the existing slave conversation containing only the exact issue, why it matters, relevant files or symbols, required correction, and required verification. Do not create a broad second implementation plan or delegate. ## Review and fix-cycle efficiency The fresh master reviewer must treat the shared worktree as source of truth. Prefer the diff, changed files, relevant surrounding code, and targeted tests. Do not rediscover the whole repository, repeat the slave executor's investigation, reproduce large logs, or rewrite correct code for stylistic preference. When the user pastes a `SLAVE_FIX_HANDOFF` back to the slave executor, the slave executor should make only the requested fixes, preserve unrelated work, and run targeted checks. The slave executor may emit a concise `## MASTER_FINAL_REVIEW_HANDOFF` for one final targeted master review only when the issue concerns correctness, security, authorization, concurrency, transactions, data integrity, or API compatibility. Avoid endless master-to-slave loops. ## Token discipline Keep every handoff self-contained, precise, minimal, and evidence-based. Include decisions and paths or symbols, not entire conversation histories, full files, full diffs, giant logs, or long progress narratives. Do not sacrifice correctness to save tokens.