agentleFS
chuckplayerchuckplayer/claude-agent-pack/skills/plan/SKILL.md

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

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-incSkill

    heartmula

    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-ywSkill

    webhook-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-incSkill

    minecraft-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-chenSkill

    touchdesigner-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

  • gaebalaiSkill

    codex-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

  • ibahgatSkill

    context-optimize

    Improve context efficiency and cache stability for long or complex sessions.

    Also in 3 projects that use this

  • +3 more from math-inc

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
  1. Distinctive:

    If unclear, ask: "Do you have a plan already, or do you need one decomposed first?"

    line 16
  2. Distinctive:

    Pass the plan path as a discrete argument: Never interpolate it into a longer shell string and never build a command around it.

    line 66
  3. Very specific:

    If tech-lead's output ends with an ## Obsidian sync request section, handle it per step 6 before moving on.

    line 101
  4. Distinctive:

    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 …

    line 150
  5. Very specific:

    If its output ends with an ## Obsidian sync request section, handle it per step 6.

    line 175
  6. Distinctive:

    If the decision is architectural, irreversible, or spans multiple systems, continue to step 4 for a cross-model check before asking the …

    line 179
  7. Distinctive:

    Ask: "Proceed with the original plan, revise it, or abandon it?"

    line 192
  8. Distinctive:

    If proceeding, note which concerns (from either devils-advocate or codex-reviewer) were accepted as known risks vs.

    line 193
  9. Distinctive:

    If the user is ready to implement:

    line 197
  10. Distinctive:

    If the user wants to revise the plan first, loop back to step 2, 3, or 4 as needed.

    line 202
  11. Very specific:

    Check $env:OBSIDIAN_VAULT_PATH.

    line 210
  12. Very specific:

    If obsidian-writer errors or the vault directory is missing, continue — the project's memory/ file is the authoritative record.

    line 220
  13. Distinctive:

    Over-planning paralysis: If the user keeps asking for "one more round" of devils-advocate without moving toward implementation, surface the …

    line 225
  14. Distinctive:

    tech-lead and devils-advocate disagree: When this happens, present both positions clearly and ask the user to decide.

    line 226
  15. Distinctive:

    Skipping plan when the task is genuinely ambiguous: If a task description is vague and the user says "just implement it," recommend a quick …

    line 229
  16. Distinctive:

    Plan becomes stale mid-implementation: If the user pauses mid-/implement and comes back with changed requirements, return to /plan to …

    line 230

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md step 2), and it stays a read: planning against an item must not move it. State advancement belongs to /implement step 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. /plan with a plain description is the common case and acquires no tracker dependency — the same property that keeps /implement working 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.md value the host repository controls, which makes an interpolated path a command-substitution risk rather than a style question; {{AGENT_PACK_REFS}}/plan-gate.md documents 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 bash is not on the shell's PATH, use the Bash tool rather than skipping the step — the same rule /implement step 5c applies to scripts/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 Read the file and use Edit — never a whole-file Write. 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:

  1. Present the key concerns raised clearly.
  2. 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.
  3. 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:

  1. Present its synthesis alongside devils-advocate's findings — call out agreement, divergence, and any new concerns it surfaced.
  2. Ask: "Proceed with the original plan, revise it, or abandon it?"
  3. 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 /implement and pass the finalized plan plus any risk notes from steps 3–4.
  • If a plan file was written, pass its plan_id and path explicitly. /implement adopts 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:

  1. Check $env:OBSIDIAN_VAULT_PATH. If empty, skip silently — do not tell the user.
  2. For each memory file listed in that section, dispatch obsidian-writer with:
    • write_mode: "capture"
    • vault_path: OBSIDIAN_VAULT_PATH
    • projects_folder: OBSIDIAN_PROJECTS_FOLDER (empty string if unset)
    • project: basename of the project directory
    • title: the description given on that file's line
    • body: full content of the memory file (frontmatter + body)
    • timestamp: current datetime in YYYY-MM-DDThh:mm format

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.
  • codex CLI 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 /hotfix or /refactor run, 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.