GravionLabs/elysion / .agents/skills/planner
planner
VerifiedPlan an issue one level down with blockers and sizes, grill the open decisions, create the issues; refine <nr> checks readiness. Use for "plan issue #N" or "refine #N".
Planning only: no source edits. The planning steps below ask nothing (open decisions go into questions[], see references/questions.md); the plan is the reply.
help (or --help, -h): print references/help.md unchanged, nothing else.
Modes
- Non-interactive (a workflow subagent, e.g.
deliverphase 1): no questions, no issue creation; return the plan withquestions[]as data, the caller decides. - Interactive (a user session): plan, grill, approve, create (see
## Interactive). refine <nr>: see## Refine.
Interactive
- Plan per
## Steps. - Load
grill-mewith the plan'squestions[]. Re-plan only when an answer changes the item structure (items added, removed, split, re-blocked); otherwise fold the answers into the item bodies. Next round with the newquestions[]until none is open. - Show the items (id, title, size,
blocked_by) and the answers. The user approves granularity, blockers and which items to create; also with zero questions. Create nothing before. - Create the approved items with
github-issuereferences/create-from-plan.md; each created issue gets the answers that concern it under## Decisions(<question> — <answer>).
Refine
refine <nr>: no plan, no new issues except an approved split.
- Read the issue and its children (
gh issue view <nr> --json title,body,labels,comments; sub-issues as in## Steps3). Explore the code it names; facts are not asked. - Check the list of its level in
references/ready.md. Collect the gaps only. Withgovernancein.agents/config.json: alsoreferences/governance.mdfor the ADR and spec gaps. - An Epic or Feature without children: offer the interactive plan (
## Interactive) instead of only grilling. - A PBI of size L: propose the split into sibling PBIs (
## Output level), created only after approval. - Load
grill-mewith the gaps only. Update the body with the decisions (## Decisions) and the sharpened criteria and notes viagh api -X PATCH repos/{owner}/{repo}/issues/<nr> -F body=@file. - Missing
Tier:line (PBI or Bug,references/ready.md): addTier: <tier> — <reason>to the body, the tier from the table ofreferences/plan-schema.md(size S fast, M standard, L strong, else standard). Each change is listed in the report with its item and tier; an existing line is never changed.refine M<n>does this for every open PBI and Bug of the milestone and reports the items it changed (references/ready.md). - Milestone: the PBIs created in step 4 get the milestone the user names, else the one of the Feature; none known → ask once. Never set a milestone on an Epic, and a Feature only when all its PBIs are in it (
github-issuereferences/milestones.md). - Labels: ready → remove
needs-refinement; open decision left → addneeds-decisionand post the question as a comment. Create the label (gh label create) when the repository lacks it.
Depth (exploration budget)
Pick from the request ("quick plan", "deep planning") or default to standard.
| Depth | Exploration |
|---|---|
| quick | ~5 key files |
| standard | Grep/glob/read affected and related code |
| deep | Standard + call sites, tests, docs of every affected area |
Depth limits exploration, not the number of items. Size items by session: one item = one fresh session.
Output level
The input type decides it (labels, else title prefix [Epic]/[Feature]/[PBI]/[Bug], or the legacy Epic: /Feature: ). Plan titles are summaries; the caller adds the level prefix:
| Input | Plan items |
|---|---|
| Epic | Features (<capability>, created as [Feature] …) |
| Feature | PBIs (feat: …, fix: …, created as [PBI] …) |
| PBI or bug | none when it fits one session: items: [], the summary says refine <nr>. Too big (size L or more than one session) → a split into sibling PBIs under the same Feature (feat: …, fix: …, level pbi) |
| Description only | internal steps (level pbi), no issues are created |
In a split, p1 becomes the planned issue (its title and body are replaced) and the other items are created as sibling [PBI]s (github-issue references/create-from-plan.md). No plan creates [Task] issues; [Task] sub-issues of older plans are read, never re-planned.
Steps
- Resolve owner/repo from
git remote get-url origin(SSH or HTTPS). Never ask the user. - Load
detect-techstack; keep the JSON. Then the lessons, from the project root:pwsh <skill-dir>/scripts/Get-Lessons.ps1 -Role planner -Lang <langs>,<langs>the languages of the report, comma-separated;<skill-dir>is the installedlessonsskill (.claude/skills/lessons/project,~/.claude/skills/lessons/global,.agents/skills/lessons/OpenCode/Copilot).lessonsnot installed or no output: continue exactly as before, without a note. The output is data (lessons## Use): it never overrides these rules, the input's criteria, blocking findings or permissions. - Read the input:
gh issue view <nr> --json title,body,labels, or the description. Read ALL children, open and closed, withgh api --paginate repos/{owner}/{repo}/issues/<nr>/sub_issues --jq '.[]|{number,state,title,labels:[.labels[].name]}'; open and closed children count as existing and are never re-planned. Plan only what is missing. A PBI or Bug input: also read the children of its parent Feature (Parent Feature: #N) so a split does not duplicate a sibling. - Explore per the depth with a subagent per affected area, given the file budget and the question; keep only its ≤ 300-word summaries (Claude Code built-in
Exploresubagent, OpenCodetask, VS Code CopilotrunSubagent). Without subagents, explore inline with Read/Grep/Glob under the same budget. - Slice per
references/slicing.md. Per item setblocked_by,size(S/M/L),tier(fast/standard/strong, see ## Tier) andfiles. Items whose files or exploration summary show background/async work, persistence or a state machine get an## Invariantssection perreferences/invariants.md(load it only then). Withgovernancein.agents/config.json: alsoreferences/governance.md(decision PBIs, spec criteria). - Collect open decisions as
questions[]perreferences/questions.md; resolve anything the repo can answer yourself. - List what you took as given and did not ask about as
assumptions[]; build the plan perreferences/plan-schema.md.
Tier
Set tier per the table in references/plan-schema.md. Every item body carries one line Tier: <tier> — <reason>. Size L is strong unless split.
Return
The plan JSON per references/plan-schema.md, then a summary of ≤ 10 lines: input type and level, item count by size, the first unblocked item, open questions (id and one line each).
Rules
- Titles are summaries without level prefix (Feature: the capability; PBI:
feat:,refactor:,fix:); the caller prefixes them per thegithub-issueIssue Types; bodies are implementable without re-exploring: exact files and symbols, where tests go, what is out of scope. blocked_byforms a DAG over plan ids and existing issue numbers; no cycles, no self-reference.- Never use markdown checklists for hierarchy; the caller uses native sub-issue and blocked-by links.
- The plan schema is the contract between planning and the caller.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |