plan
Use when breaking down a Beat change spec into tasks — not for spec creation or implementation
How do I install this agent skill?
npx skills add https://github.com/kirkchen/beat --skill planIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The 'plan' skill is a development workflow tool designed to decompose feature specifications into actionable implementation tasks. It utilizes Git for version control and workspace isolation, incorporates multi-role reviews via sub-agents, and includes bundled Node.js scripts for artifact validation. No malicious behaviors or security vulnerabilities were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Plan the execution — read spec artifacts, review from multiple perspectives, then generate tasks.md.
<decision_boundary>
Use for:
- Breaking down spec artifacts into implementation tasks (tasks.md)
- Multi-role review of an execution plan before implementation
- Re-generating or updating tasks for an existing change
NOT for:
- Creating spec artifacts like proposal, gherkin, or design.md (use
/beat:design) - Exploring ideas or investigating a problem (use
/beat:explore) - Implementing code (use
/beat:apply) - Verifying implementation (use
/beat:verify)
</decision_boundary>
<HARD-GATE> Before writing any files: you MUST invoke superpowers:using-git-worktrees. You MUST invoke superpowers:writing-plans to generate tasks. Do NOT write tasks inline. writing-plans IS the task creation process. This applies regardless of change complexity or time pressure.You MUST have at least one spec artifact done (gherkin or proposal) before proceeding. Do NOT create tasks from a description alone — spec artifacts are the input.
When the multi-role review rejects an alternative with a load-bearing reason
that would otherwise have to be re-litigated by future reviewers: you MUST
run the three-condition ADR gate (see references/adr-format.md) and offer
to record an ADR. User may decline.
If a prerequisite skill is unavailable (not installed), continue with fallback — but NEVER skip because you judged it unnecessary. </HARD-GATE>
Prerequisites (invoke before proceeding)
| Superpower | When | Priority |
|---|---|---|
| using-git-worktrees | Before first file write | MUST |
| writing-plans | When creating tasks | MUST |
If a superpower is unavailable (skill not installed), skip and continue.
Unattended mode
When the invocation carries --unattended, nobody can answer during the run: follow references/unattended-mode.md. Without it this skill is interactive, whatever the environment looks like. Every AskUserQuestion in this skill becomes a default (recorded in beat/changes/<name>/decisions/assumed.md), a decision brief (references/decision-brief.md, blocked-on: decision), or an environmental stop (blocked-on: env). The per-skill table in that reference says which. For plan specifically: use the suggested review roles; a review finding that changes what gets built becomes a brief, one that only reshapes tasks is applied and noted.
Rationalization Prevention
| Thought | Reality |
|---|---|
| "I don't need a worktree, design already committed the artifacts" | Design may not have run, or the worktree may not exist yet. using-git-worktrees is idempotent — if already isolated, it detects and continues. |
| "This change is simple enough to write tasks inline" | Simple changes finish writing-plans quickly. Complex changes need it most. There is no middle ground where skipping helps. |
| "I already understand the scope from the proposal/gherkin" | Understanding scope ≠ properly decomposed tasks. writing-plans catches scope gaps you haven't noticed. |
| "The user wants speed, invoking superpowers will slow us down" | Skipping prerequisites produces lower-quality tasks that cause rework during apply. |
| "The spec artifacts are clear enough, review is overkill" | Review catches blind spots that the spec author can't see. The more obvious the spec seems, the more likely assumptions are hiding. |
| "I'll skip review for this small change" | Small changes still get the test coverage check — the preset decides how many roles, never whether to review. minimal/technical means one role, not zero. |
| "The review rejected option X — let's just note it in tasks.md" | If the rejection reason is load-bearing for future reviewers, it'll be re-litigated. Run the ADR gate; if all three conditions hold, write the ADR. |
Red Flags — STOP if you catch yourself:
- Writing any file before invoking using-git-worktrees
- Writing
- [ ]task checkboxes without having invoked writing-plans - Creating tasks without reading spec artifacts first
- Thinking "review isn't needed for this particular change"
- Skipping a MUST prerequisite and planning to "compensate" later
- Proceeding without at least one spec artifact (gherkin or proposal) being done
- Merging a review rejection into tasks.md without checking whether it qualifies as an ADR
Process Flow
digraph plan {
"Select change" [shape=box];
"Invoke using-git-worktrees" [shape=box, style=bold];
"Read spec artifacts" [shape=box];
"Check readiness" [shape=diamond];
"STOP: need spec first" [shape=box, style=dashed];
"Preset minimal/technical?" [shape=diamond];
"Test-coverage role only" [shape=box];
"Assess complexity" [shape=box];
"Suggest review roles" [shape=box];
"User confirms roles" [shape=box];
"Invoke writing-plans" [shape=box, style=bold];
"Generate initial tasks.md" [shape=box];
"Role count?" [shape=diamond];
"Single review agent\n(all roles)" [shape=box, style=bold];
"Parallel review agents\n(1 per role)" [shape=box, style=bold];
"Merge findings +\nupdate tasks.md" [shape=box];
"Advance to implement" [shape=box, label="Advance to implement\n(forward only)"];
"Show summary" [shape=doublecircle];
"Select change" -> "Invoke using-git-worktrees";
"Invoke using-git-worktrees" -> "Read spec artifacts";
"Read spec artifacts" -> "Check readiness";
"Check readiness" -> "STOP: need spec first" [label="no spec done"];
"Check readiness" -> "Preset minimal/technical?" [label="spec ready"];
"Preset minimal/technical?" -> "Test-coverage role only" [label="yes"];
"Preset minimal/technical?" -> "Assess complexity" [label="no"];
"Test-coverage role only" -> "Invoke writing-plans";
"Assess complexity" -> "Suggest review roles";
"Suggest review roles" -> "User confirms roles";
"User confirms roles" -> "Invoke writing-plans";
"Invoke writing-plans" -> "Generate initial tasks.md";
"Generate initial tasks.md" -> "Role count?";
"Role count?" -> "Single review agent\n(all roles)" [label="1-2 roles"];
"Role count?" -> "Parallel review agents\n(1 per role)" [label="3+ roles"];
"Single review agent\n(all roles)" -> "Merge findings +\nupdate tasks.md";
"Parallel review agents\n(1 per role)" -> "Merge findings +\nupdate tasks.md";
"Merge findings +\nupdate tasks.md" -> "Advance to implement";
"Advance to implement" -> "Commit tasks";
"Commit tasks" [shape=box];
"Commit tasks" -> "Show summary";
}
Input: Optionally specify a change name. If omitted, infer from context or prompt. --unattended switches on unattended mode (above).
Steps
-
Select the change
If no name provided:
- Look for
beat/changes/directories (excludingarchive/) - If only one exists, use it (announce: "Using change: <name>")
- If multiple exist, use AskUserQuestion tool to let user select
- Look for
-
Ensure worktree isolation
Invoke
using-git-worktreesbefore reading or writing any files. If already in a worktree (e.g., from design), it detects and continues. -
Read spec artifacts and verify readiness
Read
status.yaml(schema:references/status-schema.md).Check that either:
gherkinhasstatus: done→ Gherkin-drivengherkinhasstatus: skippedANDproposalhasstatus: done→ Proposal-driven
If neither condition is met: "Spec artifacts are required before task breakdown. Run
/beat:designfirst." STOP.If
status.yamlhassource: distill: warn — "This is a distill change; it describes current behavior, so there is nothing to plan. The intended flow is/beat:verify→/beat:archive." Use AskUserQuestion tool to confirm before proceeding.If
tasksalready hasstatus: done: "Tasks already exist. Re-running will regenerate tasks.md." Confirm with user before proceeding.Read all available artifacts:
proposal.md(if exists)features/*.feature(all files, if gherkin is done)design.md(if exists)
Read
beat/config.yamlif it exists (schema:references/config-schema.md). Uselanguagefor output language, injectcontext, and applyrules.tasksas additional constraints. -
Assess change complexity and suggest review roles
Preset
minimalortechnical(fromstatus.yaml): the review is the Test coverage role alone. Say so in one line, skip the AskUserQuestion below, and go to step 5. The user can still ask for more roles;/beat:applyupgrades the preset if the change turns out bigger.Otherwise, evaluate complexity based on:
- Number of feature files and scenarios
- Number of components/services mentioned in design.md
- Whether
@e2escenarios exist (implies integration surface) - Whether design.md mentions external dependencies, DB changes, or API changes
Suggest review roles based on complexity:
Use AskUserQuestion tool (unattended: take the suggested roles, record in
assumed.md):"Based on the spec artifacts, I suggest the following review perspectives: [dynamically selected roles with rationale]
Adjust, add, remove, or confirm?"
Role selection guidance:
Signal Suggested role Always included Test coverage: Are all scenarios covered? Any gaps? @e2escenarios presentIntegration: Are integration boundaries identified? design.md mentions API/DB changes Architecture: Is the design consistent with existing patterns? proposal.md mentions user-facing changes User experience: Does the plan match user expectations? design.md mentions auth/data/external APIs Security: Are there security considerations? High scenario count (>5) or multiple features Scope: Is the decomposition granular enough? Test coverage is always included. Other roles are suggested dynamically. The user can add custom roles (e.g., "performance", "accessibility") or remove suggested ones.
-
Generate initial tasks via writing-plans
Invoke
superpowers:writing-plans. Pass the completed artifacts (proposal, gherkin, design) as context.The output of writing-plans becomes the initial tasks.md — do NOT generate tasks.md yourself.
If writing-plans is unavailable (not installed), create tasks.md as fallback with notice:
<!-- Generated without writing-plans. Consider re-running with superpowers plugin. -->Task Decomposition Principles — if writing-plans output violates any principle, decompose further before saving tasks.md:
- Single concern: one component, service, or API endpoint per task. "Build X and integrate into Y" = two tasks.
- ~200 LOC cap: each task produces ~200 lines of new code (excluding tests). More = too many responsibilities.
- 2-3 files max: each task touches at most 2-3 source files. More = crossing concern boundaries.
- Independently verifiable: can run tests after completing without depending on later tasks.
- "And then" test: if a task description needs "and then", split it.
- Exception: project initialization/scaffolding tasks may exceed file limits while maintaining single concern.
Quality Principles header — insert the following block between the tasks.md header and the first
### Task:## Quality Principles **Testing:** Tests verify behavior (return values, state changes, responses), not wiring. If the main assertion is `toHaveBeenCalledWith`, rewrite to assert on the function's output. **Code:** No single new file exceeds ~300 lines. If it grows past that, split into focused sub-modules.Verification steps — layer them per the default in
references/check-layering.md: each task's verification runs only the tests that task affects; the full suite runs at change wrap-up (/beat:verify; the e2e suite also at the end of/beat:apply) and in CI, never per task. When the project'sCLAUDE.md/AGENTS.mddefines its own test layering, use the project's commands and layering instead.Save the initial tasks.md to
beat/changes/<name>/tasks.md. -
Dispatch review agents
Read
review-subagent-prompt.mdfor the subagent prompt template.Dispatch strategy based on confirmed role count:
- 1–2 roles: Single Agent (subagent_type:
general-purpose, told to edit nothing) with all confirmed roles. Build one prompt containing all roles and their focus areas. - 3+ roles: One Agent (subagent_type:
general-purpose, told to edit nothing) per role, dispatched in parallel. Each agent receives ONLY its own role and focus area — no knowledge of other roles.
Every agent receives:
- All spec artifacts (proposal, gherkin, design)
- The initial tasks.md
Do NOT pass conversation history or session context to any agent.
Why parallel at 3+: A single agent reviewing from many perspectives simultaneously loses depth and independence — findings from one role bias another. Independent agents give genuine blind-spot coverage. At 1–2 roles the overhead isn't worth the split.
Fallback: If any agent fails or returns empty, proceed with findings from the others. If ALL fail, use initial tasks.md as-is. Show notice: "Review could not be completed — tasks.md was not reviewed. Consider re-running
/beat:plan." - 1–2 roles: Single Agent (subagent_type:
-
Merge findings and update tasks.md
Collect findings from all review agents. If parallel agents were used:
- Deduplicate findings that identify the same issue from different roles
- When findings conflict, prefer the more conservative recommendation
ADR gate on rejected alternatives — scan the review output for cases where an alternative approach was considered and rejected with a load-bearing reason (i.e. a reason a future reviewer would want to know about to avoid re-suggesting the same thing). For each, run the three conditions from
references/adr-format.md:- Hard to reverse?
- Surprising without context?
- Result of a real trade-off?
If all three hold, use AskUserQuestion tool: "Review rejected '<alt>' because '<reason>' — record as ADR?" On Yes, follow "Before writing an ADR" in
references/adr-format.md(apply configrules.adr; use the project'sdocs/adr/TEMPLATE.mdif it exists, otherwise Beat's front-matter template withsource: beat/changes/<name>), write the ADR underdocs/adr/, increment numbering, cross-reference fromtasks.mdordesign.mdas appropriate. On No, continue. Step 8 commits the ADR together with tasks.md.Read
beat/changes/<name>/tasks.md, then use the Edit tool to apply:- Add missing tasks or steps identified by the review
- Split tasks that the review flagged as too broad
- Add test coverage notes where the review found gaps
- Reorder tasks if the review identified dependency issues
Show the user a brief summary of what changed:
## Review Applied - [Role]: <what was changed> - [Role]: <what was changed> ...Update
status.yaml: settasksto{ status: done }, and set phase toimplementwhen it is earlier than that. Phase only moves forward: a re-run on a change already inimplementor later leaves phase where it is. Then runnode <skill-dir>/scripts/validate-beat.mjs --file beat/changes/<name>/status.yaml(seereferences/lint-tools.md) and fix anything it reports. -
Commit
In unattended mode, first read
beat/changes/<name>/decisions/sensitive.md; when it saysyes, write the plan brief (references/decision-brief.md"Plan brief") tobeat/changes/<name>/decisions/P1.mdnow, so the commit below carries it and the handoff reportsdirty: no.Commit tasks.md, updated status.yaml, and every living-documentation file this run wrote — an ADR recorded at the review's ADR gate (plus any ADR index the project keeps under
docs/adr/) belongs in the same commit as the tasks it came from:git add beat/changes/<name>/ git add docs/adr/NNNN-<slug>.md # only if this run wrote an ADR, by file name git add docs/adr/<index-file> # only if the project keeps an ADR index there and this run updated it git commitStage files by name, never
docs/adr/as a directory: a path is staged whengit statusshows it and this run wrote it; a path modified by the user outside this run stays unstaged.Use a descriptive message, e.g. "plan(<name>): add task breakdown".
## Plan Complete: <change-name> Tasks: N tasks in tasks.md Review: [list of roles that reviewed] Changes from review: [count of modifications] Ready for implementation! Run `/beat:apply` to start.Then end with the handoff block from
references/handoff-report.md(next: /beat:apply <name>). Readbeat/changes/<name>/decisions/sensitive.mdand repeat its verdict assensitive: yes|noin the block (nowhen the file is absent). In unattended mode, when it saysyes, print the plan brief written todecisions/P1.mdbefore the commit (step 8) above the block; the handoff staysblocked-on: none, and whether to stop before apply is the caller's decision. A decision brief, when written, is printed above the block withblocked-on: decision,decision: D<n>andnextpointing back at this command.
Guardrails
- NEVER proceed without at least one spec artifact (gherkin or proposal) being done
- NEVER write tasks inline — always use writing-plans (or fallback with notice)
- Review is part of the process, not optional — but depth scales with complexity
- Test coverage review is always included regardless of complexity
- Apply review findings directly to tasks.md, not as a separate report
- If review reveals spec-level issues (missing scenarios, design gaps), surface them to the user rather than silently compensating in tasks (unattended: a brief when it changes what gets built)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/kirkchen/beat/plan">View plan on skillZs</a>