plan
Skill8 starsChanged 35 days agoMITView on GitHub
Decompose a complex task using tech-lead and optionally pressure-test the plan using devils-advocate before implementation begins. Use when the task is ambiguous, spans multiple concerns, or when the user wants to stress-test an existing proposal before committing. Trigger this when someone says: how should I approach this, plan this out, I am not sure how to do this, think through this with me, is this a good approach, pressure-test my plan, help me design this. Do NOT use when the task is already well-scoped — go straight to /implement instead.
184 other projects use a version of this.
Adopted by
Most recently taken up by
- FAHTHIZ/oasistheir own version, first seen Nov 16, 2026
- ansvisor/ansvisortheir own version, first seen Nov 15, 2026
- felipefontoura/claude-sdd-kittheir own version, first seen Nov 15, 2026
- SireJeff/k0ntexttheir own version, first seen Nov 15, 2026
- yagizdo/quivertheir own version, first seen Nov 15, 2026
- metaspartan/cybaratheir own version, first seen Nov 15, 2026
Used with
Projects with it also use heartmula, webhook-subscriptions and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
math-incSkillheartmula
Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support.
Also in 9 projects that use this
Tommy-ywSkillwebhook-subscriptions
Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.
Also in 5 projects that use this
math-incSkillminecraft-modpack-server
Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts.
Also in 5 projects that use this
john-data-chenSkilltouchdesigner-mcp
Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.
Also in 6 projects that use this
gaebalaiSkillcodex-system
PROACTIVELY consult Codex CLI, your highly capable supporter with exceptional reasoning and task completion abilities. Codex is a trusted expert you should ALWAYS consult BEFORE making decisions on: design choices, implementation approaches, debugging strategies, refactoring plans, or any non-trivial problem. When uncertain, consult Codex. Don't hesitate - Codex provides better analysis. Explicit triggers: "think deeper", "analyze", "second opinion", "consult codex".
Also in 3 projects that use this
ibahgatSkillcontext-optimize
Improve context efficiency and cache stability for long or complex sessions.
Also in 3 projects that use this
- +3 more from math-inc
Other versions184 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 184
- Yeachan-Heo/oh-my-codex★ 34ksame name
- crbnos/carbon★ 2.8ksame name
- graphistry/pygraphistry★ 2.6ksame name
- zereight/gitlab-mcp★ 2.1ksame name
- math-inc/OpenGauss★ 1.3ksame name
- kdlbs/kandev★ 1.1ksame name
- suboss87/FDEOps★ 940same name
- codewithmukesh/dotnet-claude-kit★ 808same name
- witnesstodark/mr-mak-workspace★ 800same name
- loongclaw-ai/loongclaw★ 640same name
174 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- backlogSkill
- conventionsSkill
- debugSkill
- devops-azureSkill
- devops-githubSkill
- devopsSkill
- hotfixSkill
- implementSkill
- interview-meSkill
- lint-agentsSkill
- memory-auditSkill
- memory-querySkill
- obsidian-briefSkill
- obsidian-captureSkill
- obsidian-dailySkill
- obsidian-recapSkill
- obsidian-searchSkill
- obsidianSkill
- onboardSkill
- pack-reviewSkill
- refactorSkill
- repo-mapSkill
- review-prSkill
- scaffoldSkill
- setup-projectSkill
- smellSkill
- spec-intakeSkill
- system-checkSkill
- whatSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 12 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 168 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
If unclear, ask: "Do you have a plan already, or do you need one decomposed first?"
- Distinctive: line 66
Pass the plan path as a discrete argument: Never interpolate it into a longer shell string and never build a command around it.
- Very specific: line 101
If tech-lead's output ends with an ## Obsidian sync request section, handle it per step 6 before moving on.
- Distinctive: line 150
Never dispatch a second writer while a first holds the file: Do not run a tech-lead revision and a devils-advocate audit in parallel, and …
- Very specific: line 175
If its output ends with an ## Obsidian sync request section, handle it per step 6.
- Distinctive: line 179
If the decision is architectural, irreversible, or spans multiple systems, continue to step 4 for a cross-model check before asking the …
- Distinctive: line 192
Ask: "Proceed with the original plan, revise it, or abandon it?"
- Distinctive: line 193
If proceeding, note which concerns (from either devils-advocate or codex-reviewer) were accepted as known risks vs.
- Distinctive: line 197
If the user is ready to implement:
- Distinctive: line 202
If the user wants to revise the plan first, loop back to step 2, 3, or 4 as needed.
- Very specific: line 210
Check $env:OBSIDIAN_VAULT_PATH.
- Very specific: line 220
If obsidian-writer errors or the vault directory is missing, continue — the project's memory/ file is the authoritative record.
- Distinctive: line 225
Over-planning paralysis: If the user keeps asking for "one more round" of devils-advocate without moving toward implementation, surface the …
- Distinctive: line 226
tech-lead and devils-advocate disagree: When this happens, present both positions clearly and ask the user to decide.
- Distinctive: line 229
Skipping plan when the task is genuinely ambiguous: If a task description is vague and the user says "just implement it," recommend a quick …
- Distinctive: line 230
Plan becomes stale mid-implementation: If the user pauses mid-/implement and comes back with changed requirements, return to /plan to …
“Common” is measured: kept by at least 6 in 10 of the 168 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plan
Decompose or challenge a task before implementation begins.
1. Determine what the user needs
- "I have a task I don't know how to approach" → decompose with tech-lead (step 2)
- "I have a plan I want to pressure-test" → challenge with devils-advocate (step 3)
- "Both" → run tech-lead first (step 2), then devils-advocate on the result (step 3)
If unclear, ask: "Do you have a plan already, or do you need one decomposed first?"
2. tech-lead — task decomposition (if needed)
Invoke tech-lead with the full task description. Pass any constraints, related files, or architectural context. tech-lead reads memory/architecture/repo-map.md (if present) to accelerate routing and blast-radius assessment — if you already know the repo structure has changed a lot recently, suggest /repo-map refresh first so the plan is built against an accurate map.
If the user named an Azure DevOps work item, pass its id and tell tech-lead to record it as work_item: in the plan's frontmatter. Asking "plan 12345" already works — you read the item and hand its title and acceptance criteria to tech-lead as the task description — but without the key the id does not survive into the plan, so /implement has to be given it again and a plan and the item it was planned from stay unrelated files. One key removes that.
- You do the read, not tech-lead — it holds no
Bash. Resolving the item is an ID-scoped read needing only the org (skills/devops-azure/SKILL.mdstep 2), and it stays a read: planning against an item must not move it. State advancement belongs to/implementstep 1a, after that run's branch check. - Pass the id, not just the item text. Including the title and criteria in the task description is what makes the plan useful; recording the id is what makes it reachable.
- Omit it entirely when there is no work item.
/planwith a plain description is the common case and acquires no tracker dependency — the same property that keeps/implementworking with no tracker at all. - A work item id is not a pull request id; this key holds the work item id only.
Instruct tech-lead to write a plan file, and pass it the resolved plan directory. tech-lead writes a plan file only when told to, so this instruction is what creates the artifact. Resolve the directory first:
grep -m1 '^- \*\*Plan directory:\*\*' docs/CONVENTIONS.md 2>/dev/null | sed 's/^.*\*\*Plan directory:\*\*[[:space:]]*//'Fall back to docs/plans when that returns nothing, or when the value fails any condition in the
table in {{AGENT_PACK_REFS}}/plan-directory-guard.md (if that path is relative, prefix it with the
project root) — read that table rather than working from a list here. It is the single authority on what
is rejected, and a copy in this file would go stale the first time it grows a row. If that file cannot be
read, use docs/plans and ignore the configured value. Pass the resolved directory and the current
branch name in the dispatch prompt.
If tech-lead declines a plan-file dispatch — creating a plan or revising one — because a reference it
needs is unreadable, stop. That covers any reference it names: the directory guard, the plan-file
authoring rules, the bar-soundness table, or the plan gate. Report which path failed and that the pack's
installed references are missing or out of date (re-run the pack's install.sh). Do not re-dispatch — a
second dispatch cannot fix a missing file — and do not write or edit the plan yourself in its place: that
would skip the directory guard and the rules the plan is checked against. A refusal leaves no plan to lint
and no revision to confirm, so the lint step below and the post-audit revision rules do not apply to it.
tech-lead re-applies that guard to whatever it receives, so the two checks are genuinely redundant — but do not rely on that as a reason to skip this one. Resolving here is what lets you tell the user why their configured directory was rejected; tech-lead's copy is a backstop, not a substitute.
Note the resulting plan_id from tech-lead's output — step 5 hands it forward.
Then validate the plan's structure before presenting it. This is a blocking gate, and it is the coordinating session's job — merge-reviewer deliberately does not run it:
bash scripts/lint-plans.sh docs/plans/<plan-id>.md- Pass the plan path as a discrete argument. Never interpolate it into a longer shell string and
never build a command around it. The directory half comes from a
docs/CONVENTIONS.mdvalue the host repository controls, which makes an interpolated path a command-substitution risk rather than a style question;{{AGENT_PACK_REFS}}/plan-gate.mddocuments that reasoning in full (if that path is relative, prefix it with the project root). - Pass only the plan this run produced. The script never globs the plan directory, for the same
reason consumption is opt-in: a glob would validate and report on a plan belonging to unrelated work.
The long-form plan-spine rules are in
{{AGENT_PACK_REFS}}/orchestration-rules.md("Plan spine"); if that path is relative, prefix it with the project root. Read it only if a rule here is unclear -- nothing in this step depends on it, so an unreadable file is not a reason to stop. - On a machine where
bashis not on the shell's PATH, use the Bash tool rather than skipping the step — the same rule/implementstep 5c applies toscripts/lint-agents.sh.
A non-zero exit blocks. Missing frontmatter keys, a missing ## Acceptance bars or
## Deviations, duplicate bar ids, an untyped Evidence: line, or a Gated: field with no Cost:
line all mean the plan cannot be enforced by merge-reviewer's gate 4a. Route the named failure back to
tech-lead and re-run until it exits 0 — unless tech-lead refused the dispatch because a reference was
unreadable (see above), in which case stop, and likewise stop if a route-back is itself refused. Every one of these is something the plan's author can fix
before any pipeline starts, which is exactly why the check belongs here and not at the end.
One output line is not a failure: [--] ## Deviations still holds its sentinel is correct at this
point — that section is filled in at /implement step 10, not now.
A PASS is not a reviewed plan. The script checks structure and makes no claim about truth. Whether
a bar's evidence proves anything, and whether a stated Cost: is accurate, is step 3's job and the
bar-soundness table's.
The tech-lead will:
- Identify which specialist agents are needed
- Determine the correct invocation order (sequential vs. parallel)
- Surface whether devils-advocate should run before implementation
- Produce a step-by-step plan with rationale for each step
Present the plan clearly to the user. If it introduces a new pattern, a new dependency, or an irreversible architectural change, recommend running step 3 before proceeding.
If tech-lead's output ends with an ## Obsidian sync request section, handle it per step 6 before moving on.
3. devils-advocate — pressure-test (if warranted)
Invoke devils-advocate with:
- The full plan or proposal
- Any alternatives already considered and why they were rejected
- Any constraints, requirements, or deadlines that shaped the decision
The devils-advocate will surface unconsidered alternatives, challenge hidden assumptions, and identify risks.
If a plan file was written in step 2, tell devils-advocate to pressure-test its acceptance bars
in the file, editing it in place. Pass the plan path. It already holds Write, and this is the
only check on bar quality anywhere in the pipeline — tech-lead writes the bars and is the agent
whose work they measure, so unreviewed bars tend toward the unfalsifiable. Specifically ask it to
flag any bar whose Evidence: line names something that cannot actually be produced.
Expect a ## Challenge section appended to the plan. devils-advocate is required to persist its
narrative findings there before composing its reply, because an agent that goes idle without
reporting otherwise takes its judgement with it. Treat that section as expected output, not drift.
It does not substitute for the report: if the plan gained a ## Challenge section and no report
arrived, the stage did not complete — re-request once, and if that is also silent, say so in the
record rather than reading the artifact as a verdict.
In the same pass, ask it to flag non-falsifiable entries in ## Calls made for you. A stated
call is only enforceable downstream if it names a concrete artifact someone could look up — a
dependency, a file or directory, a type or endpoint, a specific value. A call naming only a quality
("keep it maintainable") or a pattern ("use the repository pattern") has no lookup target, so
merge-reviewer's Tier 3 skips it by construction and it silently enforces nothing. Have
devils-advocate either sharpen such a call into a checkable form or say plainly that it is
documentation for the human rather than an enforceable decision. Gate coverage is a direct function
of how well these are written, and this pass is the only place it gets checked.
If devils-advocate edited the plan file, re-run scripts/lint-plans.sh on it — same command and
same blocking rule as step 2. This is not redundant with the step 2 run: devils-advocate edits bars in
place, so it can sharpen a vague bar into a gated one and introduce a Gated: field with no Cost:
line, which is a row-6 failure that did not exist when step 2 passed. Also confirm it left the
## Deviations sentinel alone; it is instructed not to touch it, and the script reports which state
that section is in.
One writer at a time, and the statement you owe if you revise
The plan file has exactly one writer at any moment, and a revision after an audit is the transition
that has actually failed. On 2026-08-05 tech-lead and devils-advocate held the same plan
concurrently. tech-lead's whole-file Write was composed from a snapshot taken before the audit, and
three of devils-advocate's clauses vanished silently. Nothing mechanical can see a lost clause — it
surfaced only because merge-reviewer asked devils-advocate to vouch for the current plan and got an
honest "I cannot." That was luck, not a step.
- Never dispatch a second writer while a first holds the file. Do not run a tech-lead revision and a devils-advocate audit in parallel, and do not dispatch either while the other has not reported. Sequential is not a preference here; it is the entire control.
- A revision dispatch happens only after devils-advocate has reported, and the dispatch tells
tech-lead to
Readthe file and useEdit— never a whole-fileWrite. Both agents carry that rule (tech-lead in{{AGENT_PACK_REFS}}/plan-file-authoring.md, which it reads for any plan-file dispatch, devils-advocate in its own file); stating it in the dispatch is what makes it available at the moment it applies. - After any post-audit revision, re-ask devils-advocate to confirm its edits survived. Pass the plan path and ask it to check the file as it now stands, by substance rather than wording. The re-ask only works because the auditor wrote a memory file — a later dispatch of it does not carry the audit transcript, so without that artifact the only honest answer is "I cannot". Established 2026-08-06. Treat the memory write and the re-ask as one mechanism: if the audit produced no memory file, expect "I cannot confirm" and record it as such rather than reading it as a pass.
Then state one of exactly two things in your own output:
devils-advocate re-confirmed its edits survived.
No post-audit revision occurred.
An absent statement is not the second one. Same rule as an engineer's Departures from stated calls:
line, for the same reason: silence and a clean result are indistinguishable, and only one of them is
evidence.
If its output ends with an ## Obsidian sync request section, handle it per step 6.
After it completes:
- Present the key concerns raised clearly.
- If the decision is architectural, irreversible, or spans multiple systems, continue to step 4 for a cross-model check before asking the user to decide.
- Otherwise ask: "Proceed with the original plan, revise it, or abandon it?" and note which concerns were accepted as known risks vs. resolved.
4. codex-reviewer — cross-model second opinion (if warranted)
Invoke when the decision is architectural, irreversible, or spans multiple systems, and the codex CLI is available and authenticated. Skip silently (do not block on it) if codex is not installed — this step is advisory, not required.
Invoke codex-reviewer with:
- The full plan or proposal
- The concerns devils-advocate already raised (so it isn't duplicating ground already covered)
After it completes:
- Present its synthesis alongside devils-advocate's findings — call out agreement, divergence, and any new concerns it surfaced.
- Ask: "Proceed with the original plan, revise it, or abandon it?"
- If proceeding, note which concerns (from either devils-advocate or codex-reviewer) were accepted as known risks vs. resolved.
5. Hand off to implementation
If the user is ready to implement:
- Invoke
/implementand pass the finalized plan plus any risk notes from steps 3–4. - If a plan file was written, pass its
plan_idand path explicitly./implementadopts a plan only when handed one — it never searches a directory — so omitting the id means it will re-plan from scratch and write a second plan file for the same work. - If the user wants to revise the plan first, loop back to step 2, 3, or 4 as needed.
6. Obsidian sync requests
tech-lead and devils-advocate write memory files but cannot reach the vault themselves —
neither grants Bash or Agent. When either one ends its output with an
## Obsidian sync request section, you own the dispatch:
- Check
$env:OBSIDIAN_VAULT_PATH. If empty, skip silently — do not tell the user. - For each memory file listed in that section, dispatch obsidian-writer with:
write_mode:"capture"vault_path:OBSIDIAN_VAULT_PATHprojects_folder:OBSIDIAN_PROJECTS_FOLDER(empty string if unset)project: basename of the project directorytitle: the description given on that file's linebody: full content of the memory file (frontmatter + body)timestamp: current datetime inYYYY-MM-DDThh:mmformat
If obsidian-writer errors or the vault directory is missing, continue — the project's
memory/ file is the authoritative record. Do not fail the plan over a failed sync.
Gotchas
- Over-planning paralysis: If the user keeps asking for "one more round" of devils-advocate without moving toward implementation, surface the pattern and ask directly: "Are there unresolved concerns keeping you from proceeding, or is this ready to implement?" Planning is a means, not an end.
- tech-lead and devils-advocate disagree: When this happens, present both positions clearly and ask the user to decide. Do not pick one silently. The user owns the architectural decision.
- devils-advocate and codex-reviewer disagree: Same rule applies — present both perspectives and let the user decide. Do not treat codex-reviewer as a tiebreaker.
codexCLI not installed or not authenticated: Skip step 4 without asking — it's advisory only, and a missing/broken CLI shouldn't block planning. Mention the skip briefly so the user knows it wasn't silently forgotten.- Skipping plan when the task is genuinely ambiguous: If a task description is vague and the user says "just implement it," recommend a quick tech-lead decomposition first. A few minutes of planning prevents hours of rework from misunderstood requirements.
- Plan becomes stale mid-implementation: If the user pauses mid-/implement and comes back with changed requirements, return to /plan to re-decompose rather than patching the original plan. Stale plans cause the pipeline to route incorrectly.
- A plan whose work is never implemented just stays in the tree. That is harmless and needs no cleanup. Nothing globs the plan directory: consumption is opt-in, so a downstream stage acts on a plan only when a skill hands it a specific
plan_id. An unimplemented plan cannot be picked up by an unrelated/hotfixor/refactorrun, and it is not committed until some run commits it. Mention it to the user so they know it is there, then leave it alone.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

