hyper-plan
Skill5 starsChanged 48 days agoMITView on GitHub
Use when about to start a non-trivial implementation that needs decomposition before coding. Also when the user invokes /hyperclaude:hyper-plan. Produces an ordered, bite-sized plan in .hyperclaude/plans/ — the input for /hyperclaude:hyper-plan-review and /hyperclaude:hyper-implement.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- 0xdevhero/hypercraft-skillstheir own version, first seen Nov 16, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- 0xdevhero/hypercraft-skills★ 0same name
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 repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cc-changelogSkill
- codex-changelogSkill
- hyper-autoSkill
- hyper-code-reviewSkill
- hyper-docs-loopSkill
- hyper-docs-reviewSkill
- hyper-docs-syncSkill
- hyper-implement-loopSkill
- hyper-implementSkill
- hyper-interviewSkill
- hyper-memorySkill
- hyper-plan-loopSkill
- hyper-plan-reviewSkill
- hyper-recapSkill
- hyper-researchSkill
- hyper-setupSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
If one OR MORE files' frontmatter slug: equals the derived slug (there may be a Codex <ts>-<slug>.md AND a Claude <ts>-<slug>-claude.md …
- Very specific: line 63
Use the Agent tool with subagent_type: hyperclaude:planner, run_in_background: false (Step 4 consumes the returned body inline to detect …
- Very specific: line 121
If $ARGUMENTS includes an explicit .hyperclaude/epics/*.md path before milestone <K>, use it.
- Very specific: line 123
If none exists → tell the user "No epic roadmap found under .hyperclaude/epics/ — run /hyperclaude:hyper-plan <oversized task> first to …
- Very specific: line 127
Read the roadmap with the Read tool.
- Very specific: line 152
Write the planner's response verbatim (no frontmatter) to the M-3 path.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
hyper-plan
Plan generation gate. Dispatches the planner agent to produce a multi-task plan; saves it to .hyperclaude/plans/<YYYYMMDD-HHMM>-<slug>.md. When a recent hyper-research artifact matches, the plan inherits its slug so research → plan → plan-review form a linked trio.
For an oversized task the planner returns an epic roadmap (tier: epic, saved under .hyperclaude/epics/) — a list of ## Milestone N: chunks — instead of one giant detailed plan; the skill then auto-expands Milestone 1 into a runnable detailed plan under .hyperclaude/plans/. Later milestones expand on demand via /hyperclaude:hyper-plan milestone <K> — epic-aware: it reads the roadmap and carries that milestone's Depends on: context into the expansion. This keeps each plan — and each hyper-plan-review — small. Vocabulary: epic → milestone → task (the roadmap is the epic, its chunks are milestones, each milestone expands into a detailed plan of tasks).
When to use
- User typed
/hyperclaude:hyper-plan <task>. - About to start multi-task work; want a plan
/hyperclaude:hyper-plan-reviewcan critique and/hyperclaude:hyper-implementcan execute. - Expanding the next milestone of an existing epic roadmap:
/hyperclaude:hyper-plan milestone <K>(see Milestone expansion).
Skip when:
- The task is one step — dispatch the
implementeragent directly (passrun_in_background: falsefor the result inline). - A recent plan already covers this task.
How to invoke
--resume is not supported (re-plan by running again with a refined task).
Invocation argument: $ARGUMENTS
Step 1 — Resolve mode, task + slug
First, check for milestone-expansion intent. If $ARGUMENTS matches [<epic-roadmap-path>] milestone <K> — the word milestone followed by an integer, optionally preceded by a path to an epic roadmap, with nothing trailing (e.g. milestone 2) — this is a milestone expansion request: follow the Milestone expansion section below and skip the rest of Steps 1–5. (Trailing free text like milestone 2 of the rocket is NOT a match — treat it as a normal task.)
Otherwise, resolve task + slug in priority order:
$ARGUMENTSnon-empty → that is the task. Then, in order:- Derive the canonical slug deterministically (rule below).
- Scan all research files under
.hyperclaude/research/*.md— not just the newest. Read each file's frontmatterslug:field (the canonical key — do not match against the filename, which may have collision suffixes like-2). - If one OR MORE files' frontmatter
slug:equals the derived slug (there may be a Codex<ts>-<slug>.mdAND a Claude<ts>-<slug>-claude.mdpair), treat ALL of them as the linked research artifacts and read ALL of them in Step 3 for context.
This deterministic slug-equality scan is what preserves
research → plan → plan-reviewtraceability even when an unrelated newer research file exists.$ARGUMENTSempty → list research files newest-first:ls -1t .hyperclaude/research/*.md 2>/dev/null | head -1Read the latest file's frontmatter
task:+slug:and use both; that file is itself a linked research artifact for Step 3, even when its slug is empty. If no research file exists, fall back to the user's most recent build/implement intent in this conversation; if none, ask the user and stop.
Slug derivation rule (used in branch 1, and matches what hyper-research writes into the artifact frontmatter): lowercase, ASCII only, alphanumerics + hyphen, first 5 words of the task joined by -. Example: "Add OAuth login to the API" → add-oauth-login-to-the. A task with no ASCII words (e.g. all-Korean) has an empty slug, as the bridge does: skip the branch-1 scan — an empty slug would match every other no-ASCII research artifact — and rely on any research already in this conversation for context.
Step 2 — Resolve plan path
mkdir -p .hyperclaude/plans
date -u +%Y%m%d-%H%MBase path: .hyperclaude/plans/<timestamp>-<slug>.md (<timestamp>.md when the slug is empty). If it exists, append -2, -3, … until free.
Step 3 — Dispatch planner (scope-aware)
Use the Agent tool with subagent_type: hyperclaude:planner, run_in_background: false (Step 4 consumes the returned body inline to detect mode and Write the plan). Prompt MUST include:
- Task — verbatim.
- Research context — full contents of all matched research artifacts inline (there may be a Codex + Claude pair), if any were found in Step 1, each labelled with its exact repo path so the planner can cite it. Do not make the agent re-read them.
- Scope assessment first — before writing, judge the task's size and pick ONE format:
- Fits one cohesive plan (~10 bite-sized tasks or fewer, a single area) → produce the detailed format.
- Oversized (would exceed ~10–12 tasks, or spans multiple independent areas/milestones) → produce the epic roadmap format instead. Do not force a giant detailed plan.
- Detailed format — a multi-task plan with
## Task N: <title>headings. Each task block contains:- Files to create / modify — exact paths.
- Steps —
[ ]-checkboxes, 2–5 minutes each. - Verification — a command to run, or an observable change.
- Commit message — one line, conventional-commits style.
- Epic roadmap format — a
# Epic: <task one-liner>H1, then## Milestone N: <title>headings (1-indexed). Each milestone block has a 1–3 line scope, aDepends on:line (noneorMilestone K), and a rough task-count estimate. NO file paths, NO step checkboxes, NO commit messages — those belong to the per-milestone detailed expansion. - Heading style is the mode signal — the skill detects which format you chose from the headings (
## Task N:= detailed,## Milestone N:= epic roadmap); never mix the two in one reply. - No frontmatter — return the plan body only (planner's default return-body mode);
hyper-planowns the file and adds any frontmatter itself.
The detailed format is what /hyperclaude:hyper-implement consumes; do not produce a flat numbered list.
Step 4 — Write the file(s), branching on detected mode
Detect the planner's chosen mode from its heading style: ## Milestone N: headings present and no ## Task N: → epic roadmap; otherwise → detailed (the default — covers normal plans and any reply lacking milestone headings).
Detailed (the common case): use the Write tool with the planner's response verbatim, saving to the path from Step 2 (no frontmatter). Go to Step 5.
Epic roadmap (oversized task): the roadmap is not executable on its own; persist it under .hyperclaude/epics/, then auto-expand the first milestone into a runnable plan under .hyperclaude/plans/.
Write the roadmap.
mkdir -p .hyperclaude/epics, then Write to.hyperclaude/epics/<timestamp>-<slug>.md(same<timestamp>-<slug>as Step 2; if it exists, append-2,-3, … until free), prepending atier: epicfrontmatter block before the planner's milestone body:--- tier: epic --- <planner milestone body verbatim>The
tier: epicmarker is what makes/hyperclaude:hyper-implementrefuse it — it's a roadmap, not a task plan. Keeping it out of.hyperclaude/plans/also keeps it off hyper-implement's newest-plan auto-pick entirely.- Expand Milestone 1. Dispatch the
planneragain (return-body mode, detailed format),run_in_background: false(the returned body is Written verbatim in item 3). The prompt MUST give Milestone 1's title + scope as the task, the full roadmap as context (so the expansion respects milestone boundaries and dependencies), and any Step 1 research context. Require the## Task N:detailed format. - Write the detailed plan with the planner's response verbatim (no frontmatter) to the Step 2 plans path (
.hyperclaude/plans/<timestamp>-<slug>.md) — the same canonical path the detailed case uses. The roadmap is in.hyperclaude/epics/, so there is no name collision, and the Milestone-1 plan keeps the canonical<slug>— preserving theresearch → plan → plan-reviewshared-slug trace. (Do NOT append-m1: that would leak into the slugslug.mjsextracts and break the shared-slug convention.)
Step 5 — Report
Detailed: tell the user the plan path, whether the slug was reused from research or freshly derived, and the next step (/hyperclaude:hyper-plan-review to critique, /hyperclaude:hyper-implement to execute).
Epic roadmap: tell the user:
- The roadmap path (
.hyperclaude/epics/…,tier: epic, N milestones) — and that/hyperclaude:hyper-implementrefuses it by design. - The expanded Milestone-1 detailed plan path (
.hyperclaude/plans/<timestamp>-<slug>.md, canonical slug) — this is the runnable artifact: critique with/hyperclaude:hyper-plan-review <plan path>, execute with/hyperclaude:hyper-implement <plan path>. - How to proceed to later milestones: run
/hyperclaude:hyper-plan milestone <K>(e.g.milestone 2). This is epic-aware — it reads this roadmap, carries Milestone K'sDepends on:context into the expansion, and writes a detailed plan named from the milestone's own title (see Milestone expansion). The epic linkage lives in the plan's content, not its slug. - Whether the slug was reused from research or freshly derived.
Milestone expansion — /hyperclaude:hyper-plan [<epic-path>] milestone <K>
Expands one milestone of an existing epic roadmap into a runnable detailed plan, carrying the roadmap's dependencies and context. This is what makes a later milestone epic-aware rather than a disconnected re-plan.
M-1 — Resolve the epic roadmap
- If
$ARGUMENTSincludes an explicit.hyperclaude/epics/*.mdpath beforemilestone <K>, use it. - Else auto-pick the newest roadmap:
ls -1t .hyperclaude/epics/*.md 2>/dev/null | head -1. - If none exists → tell the user "No epic roadmap found under
.hyperclaude/epics/— run/hyperclaude:hyper-plan <oversized task>first to create one." STOP.
M-2 — Extract Milestone K
Read the roadmap with the Read tool. Find the ## Milestone <K>: block; capture its title, scope, and Depends on: line. If Milestone K is absent → list the roadmap's available milestone numbers + titles and STOP (ask which one).
M-3 — Resolve the plan path
Derive the plan slug from Milestone K's title using the Step 1 slug rule — NOT the epic slug, NOT a -mK suffix (so slug.mjs is untouched and the plan is a normal one slug-wise; the epic linkage rides in the content). Then:
mkdir -p .hyperclaude/plans
date -u +%Y%m%d-%H%MBase path .hyperclaude/plans/<timestamp>-<milestone-slug>.md; append -2, -3, … if it exists.
M-4 — Dispatch the planner (detailed)
Dispatch hyperclaude:planner (return-body mode, detailed ## Task N: format), run_in_background: false (M-5 Writes the returned body verbatim). The prompt MUST include:
- Task — Milestone K's title + scope, verbatim from the roadmap.
- Epic context — the FULL roadmap body inline, naming the source roadmap path, so the expansion respects
Depends on:ordering and does not duplicate sibling milestones. - Dependency note — call out Milestone K's
Depends on:milestones explicitly; assume those are already implemented (their code is in the tree) — build on them, do not re-create them. - Provenance line — instruct the planner to open the plan body with
> Milestone K of epic: <roadmap path>so the plan is navigable back to its epic (the linkage lives in content, since the slug is the milestone's own). - Detailed format — same
## Task N:block requirements as Step 3's detailed bullets.
M-5 — Write + report
Write the planner's response verbatim (no frontmatter) to the M-3 path. Report: the plan path + its milestone-derived slug, which epic + milestone it expands, the Depends on: milestones it assumes are done, and the next step (/hyperclaude:hyper-plan-review / /hyperclaude:hyper-implement on this plan).
Anti-patterns
- Calling Codex. This skill is Claude-only; the
planneragent does the work. - Inventing a slug when a matching research artifact exists — that breaks trio traceability.
- Writing code in the plan. Names, paths, verifications only — the planner does not write code, tests, or commits; for
hyper-planthe skill owns the Write (the planner only returns the body here). - Forcing a giant detailed plan for an oversized task. Let the planner return an epic roadmap; expand milestones one at a time.
- Feeding a
tier: epicroadmap to/hyperclaude:hyper-implement, or addingtier: epicto a detailed plan. The marker rides only on the roadmap (in.hyperclaude/epics/); you (the skill) author no frontmatter on detailed plans (including the auto-expanded Milestone-1 plan) — a PostToolUse stamp hook later adds only aplugin-versionline, never atier:marker, so a detailed plan never becomes an epic. - Encoding
-mNor the epic slug into a milestone plan's filename. The slug extractor would fold it into the slug and break the shared-slug trace; M1 uses the canonical epic<slug>(auto-expanded with the epic), and M2+ use their own milestone-title slug. - Treating
/hyperclaude:hyper-plan milestone <K>as a fresh unrelated task. It MUST read the epic roadmap and carry Milestone K'sDepends on:context — a disconnected re-plan that loses dependencies is the exact failure this path exists to prevent.
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.

