master-plan skill
✓ VerifiedCreates structured, verifiable plans for multi-step features, migrations, or multi-PR programs by breaking work into units with specific checks.
- GitHub stars
- 113
- Files
- 2
- Last commit
- Nov 1, 2026
- License
- MIT
- Allowed tools
- —
What does the master-plan skill do?
master-plan creates structured, verifiable plans for multi-step features, migrations, or multi-PR programs by breaking work into units with specific checks.
Summary generated from the skill's SKILL.md.
About the master-plan skill
Developers planning complex software changes use master-plan to transform vague requirements into structured, verifiable roadmaps. This skill is designed for multi-step features, large migrations, or multi-PR programs that require breaking work into discrete, testable units. Instead of writing code, the agent produces a written Markdown plan that serves as a checklist for owners and an audit trail for operators.
When an agent identifies a task that cannot be completed in one or two files, it loads this skill to generate either a unit plan or a multi-PR program plan. For smaller tasks, it creates a unit plan detailing goals, file paths, dependencies, and specific checks. For larger programs, it coordinates subagents like Toph to explore different areas and produces a comprehensive skeleton. The process relies on tools like seismic-sense for surveying code, tea-time for prose, and a specific check script located at ../../tools/check-plan.mjs to validate the plan structure before execution begins.
What an agent can do with it
- 1Deconstruct a large migrationBreak a complex system migration into a sequence of verifiable units that leave the system working at every step.
- 2Coordinate multi-PR development programsOrganize a series of pull requests into a structured program with specific execution skills and verification rules.
- 3Validate plan integrity automaticallyEnsure a written plan meets all structural requirements by running a dedicated validation script.
- 4Establish rigorous verification standardsDefine mandatory live, regression, and performance checks for every pull request in a program.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the master-plan skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the master-plan skill in Plugin
/plugin marketplace add tmcfarlane/team-avatar /plugin install team-avatar@team-avatar
Install the master-plan skill in Claude Code
~/.claude/skills/master-plan/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan ~/.claude/skills/master-planInstall the master-plan skill in Claude Code (project)
.claude/skills/master-plan/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan .claude/skills/master-planInstall the master-plan skill in Codex
~/.agents/skills/master-plan/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan ~/.agents/skills/master-planInstall the master-plan skill in Gemini CLI
~/.gemini/skills/master-plan/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan ~/.gemini/skills/master-planInstall the master-plan skill in Claude.ai
npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan master-plan && zip -r master-plan.zip master-plan # claude.ai → Customize → Skills → + → Create skill → Upload a skill → master-plan.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachabletmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan is public and reachablegithub.com/tmcfarlane/team-avatar/tree/HEAD/plugins/team-ava ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-01github.com/tmcfarlane/team-avatar/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 94 linesgithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
SKILL.md
View on GitHubSokka's master plan
Sokka has no bending. He wins with a plan, a map, and a willingness to throw the plan out when the ground changes. A plan is worth writing only if each step can be checked.
On Codex, read avatar-mode/references/codex.md for tool equivalents.
You own the plan, not the code. The plan is a checklist an owner runs box by box and the operator audits from the evidence. The plan is the deliverable. Do not implement.
Pick the size
- One or two files with an obvious approach. Skip the plan. Say so and stop.
- One PR with several steps. Write a unit plan. Follow Unit plan.
- Several phases or several PRs. Write a program plan. Follow Multi-PR program.
Unit plan
- State the outcome. One sentence on what the user can do when this is done, and one sentence on what the next maintainer inherits.
- Survey the ground. Run
seismic-senseover every area the work touches. List the callers, the data shapes, and the tests that exist today. No plan rests on unread code. - Name the data shape. Write the core types, states, and ownership the work introduces or changes. If there are two plausible designs, run
war-roombefore going further. - Cut the work into units. Each unit is one reviewable change that leaves the system working. For each unit write:
- Goal. What changes, in one line.
- Files. The paths it touches.
- Check. The command, test, or observation that proves it. A check you cannot name means the unit is too vague.
- Depends on. The units that must land first.
- Order for proof. Subtraction first (dead code, stale paths), then scaffolding, then behavior. A failing test lands before the fix it proves. Units with disjoint files can run in parallel. Units that write the same file run one after another.
- Mark the risks. Name the step most likely to fail, how you will know early, and what you will do instead. Name any irreversible step so it waits for the human.
- Write it down. Save the plan as Markdown beside the work (for example
docs/plans/<slug>.md, or a scratch file for short work). Usetea-timefor the prose. - Hand it to Appa. Execution follows
steady-flight. When a unit's check fails in a way the plan did not predict, stop and revise the plan rather than improvising around it.
# <Outcome in a few words>
Outcome: <what the user can do>
Inherits: <what the maintainer gets>
Data shape: <types, states, ownership>
## Units
1. <Goal>
Files: <paths>
Check: <command or observation>
Depends on: <none | unit numbers>
## Risks
- <risk>: <early signal>, <fallback>
Multi-PR program
-
Settle open questions by prototype before you write. Run
scouting-flightfor each one. Keep the branch, the SHA, and the screenshots for Appendix A. Ask the operator only about a product or preference call that no run can settle, and give options with your recommendation (Never Block on the Human, Fire infour-elements). -
Explore in subagents. Dispatch Toph (
subagent_type: "team-avatar:toph") on Toph's model from the avatar-setup sheet, one per area, so the bulk stays out of your context. Pick each dispatch's reasoning effort for the job asavatar-modedescribes. Each returns file pointers, conventions, test commands, and entry points. No inlined dumps. When you are yourself a subagent, do this exploration yourself, one area after another. -
Fill the skeleton. Copy the skeleton in references/plan-skeleton.md into the plan file and fill every placeholder. Keep every heading and every sub-block in the order shown.
- Unless the operator names a path, write the file under the agent store,
${CLAUDE_CONFIG_DIR:-~/.claude}/orchestrate/<slug>/docs/on Claude Code or${CODEX_HOME:-~/.codex}/orchestrate/<slug>/docs/on Codex. - One section per PR. One PR is one change with its own evidence (Sequence Work into Verifiable Units, Fire in
four-elements). - Name the execution skill in How to read this. A queue of independent PRs takes
full-patrol, where each owner drives its PR to merge-ready and the operator clicks every merge. A queue delivered as one linear stack the operator lands takesshield-wall. Follow the choice rule inshield-wallwhen the two are close. A standing program takeskyoshi-command. - The execution skill owns base selection, topology changes, and merge authority. Do not copy its rebase steps into the plan.
- Unless the operator names a path, write the file under the agent store,
-
Write it clean. Write under
tea-time. The body is one document type, a how-to. Appendices hold explanation and reference. Each heading states the task or the finding. No long dashes. No mid-sentence colons. -
Run the check script. From the plugin root, run the shared plan checker on the plan file. From this skill's folder its path is
../../tools/check-plan.mjs.node <plugin root>/tools/check-plan.mjs <plan.md>It prints one line per PR section with its box counts, then
<n> PR sections, <m> problems, and exits 1 when any problem remains. Fix every line it prints to stderr and rerun until it reports 0 problems (Encode Lessons in Structure, Fire infour-elements). -
Hand back. Post the plan path and the script's output, then stop. Execution starts on the operator's explicit go, under the execution skill the plan names.
Verification rule
Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked. That sentence is the verification rule, and every verification block opens with it.
- Live block. Mandatory. Ten lanes on Suki's model at the PR head drive the real surface through its driver skill, per
kyoshi-formation. Each lane is one box with a concrete scenario, the screenshot it saves, and its pass predicate. - Regression lane against trunk. One lane runs the same load-bearing scenario on trunk and head. If trunk does not have the feature, the lane records that fact and gates the behavior the diff adds plus the end state the user waits for. It never invents a trunk result.
- Perf block. The gate is dual-sided. Trunk and head must both produce the named metric. If trunk lacks the feature, also isolate the work the diff adds and set an absolute budget for that work plus the end-to-end state the user waits for. Do not claim a ratio between unlike scenarios. The block names the metric, the interleaved probe, the trunk baseline measured first, and the rule with the number that fails.
- Review gate. A PR that changes an interaction is review-gated. The operator reviews it in chat with screenshots and a video before merge. A PR that changes no interaction writes
**Review gate.** None. <PR id> is not review-gated.and no boxes under it.
Driver skill
Pick the driver for each surface and put the resolved skill path or the exact commands in each live lane's boot recipe. Use the project's own verification skill when it has one (see vital-signs to create one). Native mobile uses whatever simulator-driving skill the repo has. A PR that touches two surfaces gets lanes on both. A surface with no driver skill is a risk in Appendix C, and its live block still names how each lane drives it.
Rules
- A unit without a check is not a unit. Split it or name the check.
- Do not plan past what you have read. Mark unknowns as unknowns and schedule the investigation as its own unit.
- Keep the plan shorter than the change it describes.
Reply
- Unit plan. The plan path, the units in order, and the riskiest step.
- Program plan. The plan path, the PR ids with their dependencies and the review-gated set, what the prototypes proved and what stays unproven, and the check script's output.
Files in this skill
2master-plan skill questions
How do I install the master-plan skill in Claude Code?
Run npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/master-plan ~/.claude/skills/master-plan. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the master-plan skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What should I do if a task is very small?
If the work involves only one or two files with an obvious approach, skip the plan and state that you are skipping it.
How do I ensure a unit of work is valid?
Every unit must include a specific goal, the files it touches, its dependencies, and a check consisting of a command, test, or observation that proves it.
What is the verification rule for a PR?
A PR is only verified when its unit, live, and perf boxes are all checked.