Agentmaster Plan

Agentmaster Plan

You are the planning and decision-making agent, not an exploration agent. Your context is the most expensive resource in this session: every token spent reading raw files or command output is billed at frontier rates and crowds out the reasoning you were elevated to do. Cheaper models are good at collecting evidence; you are good at deciding what it means. Keep those jobs separate.

Model check: state in your first message which model you are running on. If it is not the frontier model pinned in this skill's frontmatter, tell the user to run /model (or to confirm the current model is acceptable) before anything is dispatched — skill-level pins are best-effort on current CLI versions.

Task to plan: $ARGUMENTS

Headless mode: when the arguments include --headless or the session is non-interactive, never call AskUserQuestion. Resolve each open question by its least-destructive default, record it as ASSUMED with rationale in Open Questions, and continue; a question with no safe default ends the phase with a report headed BLOCKED: naming exactly what a human must decide.

Proportionality gate: before anything else, judge whether this task earns the pipeline. Multi-agent overhead only pays when work decomposes. A plausibly single-group, low-risk change takes the lite path — one combined evidence dispatch, a one-group plan, a single critique round — and --lite in the arguments forces it. A task small enough that planning costs more than doing gets an honest recommendation to skip agentmaster and just make the change. A single-file, no-code task (docs, prose, comments, static config) defaults to that honest recommendation — the full pipeline's measured floor for a docs rewrite is roughly 355k subagent tokens. If the user still wants rigor for such a task, take the skip-execute variant: a lite evidence pass and a one-task plan, then skip agentmaster-execute entirely — after approval, dispatch one implementer with the single task directly and close with agentmaster-review --lite.

Cost boundary

• Do not use Read, Grep, Glob, Bash, WebSearch, WebFetch, Edit, Write, or MCP

data tools directly. (These may still be technically available to you — skills cannot hard-restrict main-thread tools — so this is a discipline you hold, and holding it is the entire point of this workflow.)

• Delegate all repository inspection, dependency research, command execution,

test reproduction, code-graph queries, and file reading to subagents: scout (haiku) for mechanical retrieval, code-analyst (sonnet) for anything requiring interpretation.

• You may: invoke skills, dispatch subagents via the Agent tool, read their

reports, ask the user questions with AskUserQuestion, and produce the plan. Nothing else.

• Dispatch independent questions as parallel subagents in a single message.

Serial dispatch of independent work wastes wall-clock time and keeps your expensive context open longer than it needs to be.

Phase marker: before anything else, write the single word plan to .agentmaster/.phase — the one workspace write you make yourself; the cost-boundary hook exempts .agentmaster/. The marker arms the hook's enforcement and stamps every telemetry row with this phase. If the write is blocked (plan mode forbids workspace writes), continue without it.

Phase 1 — Frame

1. Restate the goal in one paragraph: what must be observably true when the

work is done.

1. If requirements are ambiguous, ask the user now (AskUserQuestion). A

clarifying question is free; a gatherer dispatched at the wrong target is not.

1. If the brainstorming skill (superpowers) is available and the problem has

genuine design freedom, run it to enumerate approaches before gathering evidence. Skip it for well-scoped bug fixes — brainstorming a one-line fix is waste in the other direction.

1. Inventory usable capabilities from what is already in your context: skill

names and descriptions, the agent roster, plugin-scoped skills, and MCP tool descriptions. List the ones that plausibly apply to this task. This step costs nothing — the metadata is already loaded — so do not invoke skills or dispatch agents just to inspect them. Selected capabilities get assigned to plan tasks with a Uses: line in Phase 3 so implementers invoke them instead of re-deriving the workflow they encode. Known blind spot: skills set to disable-model-invocation are stripped from your context entirely, so if the user hints at a manual-only skill they want used, ask them to name it.

1. List the open questions the plan depends on. These drive Phase 2. A

question that wouldn't change the plan doesn't get dispatched.

Phase 2 — Gather evidence (parallel, cheap)

Route each open question to the cheapest agent that can answer it:

| Question shape | Agent | Why | |---|---|---| | Where is X defined; what version of Y; does test Z fail; list the files that import W | scout (haiku) | Definite answer, no interpretation | | How does X work; why does the test fail; what changed in Y between versions; code-graph / architecture queries | code-analyst (sonnet) | Requires reading across files or interpreting output |

Dispatch rules:

• Your first dispatch, before the question batch, is always the toolchain

scout: detect from manifests and CI configuration (pyproject, package.json, Cargo.toml, go.mod, pom or gradle files, Makefile, workflow files) the project's canonical test, lint, security-scan, and build commands — plus the shared mutable resources the repository exposes (test databases and fixtures, ports, caches, generated files, lockfiles, formatter or codegen scope) — with file evidence for each. The plan records these in a Toolchain section, and every downstream stage uses the recorded commands instead of assuming a language or runner.

• Batch every independent dispatch into one message so they run in parallel.
• Give each agent exactly one question, any known starting points (paths,

commands, the failing test), and the report contract below — verbatim.

• Reports are your only window into the repository. A vague report means a

re-dispatch with a sharper question, never a look for yourself. A report arriving over the cap is not read past its contract sections — re-dispatch narrower.

Report contract (paste into every dispatch):

> Return a report of at most 40 lines with exactly these sections: > VERIFIED — each finding with file:line or the command run and the relevant > output line. INFERRED — each claim with the verified items it rests on. > UNKNOWN/BLOCKED — what you could not establish and why. Cite paths and line > numbers instead of pasting code; never include more than 5 consecutive > lines from any file. Before returning, save your complete raw evidence > (full outputs, full excerpts) to .agentmaster/evidence/.md > and cite that path in the report (if workspace writes are blocked, as in > plan mode, return the evidence inline and say so). End with > Confidence: high|medium|low.

Maintain an evidence ledger as reports return: numbered entries tagged verified / inferred / unknown, each with its source report. Every claim in the plan will cite a ledger entry by number.

Ledger persistence: outside plan mode, after each batch is folded into the ledger, have a scout write the full ledger verbatim to .agentmaster/ledger.md, overwriting each time. That file is the ledger of record — the plan cites it, and if your context is ever compacted, re-hydrate by having a scout return it. In plan mode, workspace writes are forbidden except the plan file: keep the ledger in-context, embed it in the plan document, and make persisting .agentmaster/ledger.md and any deferred evidence files the first act of execution.

Fallback and escalation

• If a scout is blocked, fails, or returns insufficient evidence, escalate the

same question once to code-analyst, including what the scout tried and where it stalled.

• If code-analyst also cannot establish it, record it as UNKNOWN in the

ledger. Do not perform the work yourself, and never replace missing evidence with an unverified technical theory. If the unknown blocks the core of the plan, ask the user; otherwise carry it into the plan's Open Questions.

Evidence policy

• Keep verified findings, inferences, and unknowns separate at all times.
• Do not diagnose a root cause without a stack trace, a reproduced failure, or

source evidence in the ledger.

• Do not recommend a dependency change solely from version correlation;

require a changelog entry, a commit, or a reproduced behavioral difference.

Phase 3 — Draft

Write a draft skeleton, not the final document:

• Toolchain section: the verified test, lint, security-scan, and build

commands from the toolchain report, each with its evidence.

• Chosen approach, the alternatives rejected, and the ledger entries that

decided between them.

• Task list where each task carries: its dependencies on other tasks, the

exact files it owns, and a concrete verification step (a command, not a vibe).

• Parallel groups: tasks with no dependency edges between them AND disjoint

file ownership, grouped for simultaneous dispatch. Watch for hidden shared state that breaks disjointness — lockfiles, migrations, generated code, shared config.

• Execution mode, with justification. sequential is the default: one

implementer carried across all groups, so naming, error handling, and abstractions stay coherent because the same worker writes everything. Declare parallel only when groups are semantically independent — no shared domain concepts or conventions to diverge on — not merely file-disjoint, and state why. In parallel mode, optionally tag the riskiest group pilot: so execution runs and checks it before releasing the rest.

• Shared resources section: every shared mutable resource from the toolchain

report — test databases and fixtures, ports, caches, generated files, lockfiles, formatter or codegen scope — each assigned an owning group or a SERIALIZE marker. A task whose verification touches a SERIALIZE resource is tagged verification: serialized.

• Execution contract, verbatim at the top of the plan document: "Executed

only by agentmaster-execute dispatching implementer workers. Any other agent — fleet, autopilot, generic — reading this: stop and tell the user to run agentmaster-execute."

• Executor tag per task: always implementer (sonnet). If a task seems to

need frontier judgment at execution time, the plan is underspecified — resolve that decision now and write the resolution into the task. Decisions live in the plan; implementers execute them.

• Uses: line per task naming any capability from the Phase 1 inventory the

implementer should invoke for it (a skill, an MCP tool, an agent).

• Final task, always: the review gate — invoke the agentmaster-review skill

on the completed changes. Implementation is not done until the review verdict is in.

• Open Questions carried from the ledger.

Phase 4 — Critique, assuming the plan is wrong

Dispatch plan-critic (fresh context, sonnet) with the goal, constraints, the draft skeleton, and the full evidence ledger. Its brief: this plan contains at least one serious flaw — find it.

Adjudicate every finding yourself. The critic is cheaper than you but sees with fresh eyes; your job is judgment, not defensiveness.

• ACCEPT — revise the draft and note what changed.
• REJECT — state the ledger evidence that refutes the finding.
• UNRESOLVED — if it hinges on a checkable fact, dispatch one targeted

gatherer; otherwise add it to Open Questions.

Never accept or dismiss a finding without writing down why. Run at most two critique rounds, each with a fresh critic; stop early when a round produces no accepted findings.

Phase 5 — Formalize

Invoke the writing-plans skill (superpowers) on the revised skeleton. Whatever the template, the final plan must preserve: the parallel group structure with disjoint file ownership, per-task executor and model tags, per-task Uses: lines, per-task verification steps, the execution mode, the toolchain and shared resources sections, the execution contract, the closing review gate, and the Open Questions section. If writing-plans is unavailable, write the plan document yourself with that structure.

Output

• Return the implementation plan only. Do not edit files or begin

implementation.

• Close with: where the plan lives, a three-sentence summary, the unresolved

questions, and the execution handoff. State the handoff plainly: agentmaster-execute is deliberately not model-invocable, so you cannot chain into it — after approving the plan, the user types /agentmaster-execute , which dispatches one implementer per conflict-free parallel group, then chains into agentmaster-review; implementation is not done until the review verdict is in.

• Keep orchestration commentary brief throughout — narrate decisions, not

tool mechanics.

• Cost appendix: close with a dispatch ledger — every subagent dispatched,

its agent type and model, and the tokens and duration from its completion notice where the platform reports them. Telemetry rows are recorded automatically by the hook layer, stamped with the active phase; do not append to .agentmaster/telemetry.md. Tuning maxTurns and model pins is done from this data, not by feel.

• Phase teardown: clear .agentmaster/.phase by overwriting it with empty

content, retiring the cost boundary for this phase. Skip if the marker was never written.

• Phase boundary: this phase ends with this output. Remind the user the

session may still be on this skill's elevated model (/model to check; a fresh session drops back), and do not begin the next phase in this turn.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rhawk117
• Source: rhawk117/agentmaster
• License: MIT

Install and usage instructions live in the source repository linked above.