From session-orchestrator
Produces bite-sized, executable implementation plans from PRDs or design specs. Each plan includes per-task Files blocks, complete code per step, and exact verification commands, rejecting placeholders like TBD or TODO.
How this skill is triggered — by the user, by Claude, or both
Slash command
/session-orchestrator:write-executable-planinheritThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Bite-sized plans for parallel agents. No placeholders. No vague steps.
Bite-sized plans for parallel agents. No placeholders. No vague steps.
/plan feature exists but you need a step-by-step implementation plan/brainstorm design is approved and you want to skip the PRD layer/brainstorm instead)/debug instead)Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
Accept ONE of the following inputs (in order of preference):
docs/prd/YYYY-MM-DD-<feature>.md produced by /plan featuredocs/specs/YYYY-MM-DD-<slug>-design.md produced by /brainstormIf no source is provided and $ARGUMENTS is empty, ask via AUQ:
AskUserQuestion({
questions: [{
question: "Which source should this plan be based on?",
header: "Plan Source",
options: [
{ label: "Existing PRD (Recommended)", description: "Point me to docs/prd/YYYY-MM-DD-<feature>.md — most precise decomposition." },
{ label: "Design spec from /brainstorm", description: "Point me to docs/specs/YYYY-MM-DD-<slug>-design.md — skips formal PRD." },
{ label: "Describe inline", description: "Paste or describe the feature — I will ask follow-up questions before planning." }
],
multiSelect: false
}]
})
Read the source file and extract:
Break the source into Tasks. Each Task MUST satisfy all of these constraints:
code-implementer, test-writer), not "the team"Before writing Tasks, output a brief decomposition plan in plain text:
## Decomposition (draft)
- Task 1: <title> — <owner> — ~<N> min — Files: <list>
- Task 2: <title> — <owner> — ~<N> min — Files: <list>
...
If any task's file set overlaps another, surface the conflict and resolve it before writing Steps.
Each Task gets exactly 5 steps in this order. All 5 steps are mandatory.
EARS seam: If the source PRD/spec carries an ## Acceptance Criteria (EARS) (or ## 3.A) section, apply the EARS→vitest 1:1 mapping below to emit per-clause test stubs. If no EARS section is present, fall back to manual derivation from prose.
| EARS pattern | vitest construct | example skeleton |
|---|---|---|
| Ubiquitous ("The S shall R.") | invariant it() — no setup branching | it('S shall R', () => { /* assert invariant */ }) |
| State-driven ("While P, the S shall R.") | describe() for state context, nested it() for assertion | describe('while P', () => { it('S shall R', () => { /* enter P; expect R */ }) }) |
| Event-driven ("When T, the S shall R.") | arrange/trigger/expect inside it() | it('when T, S shall R', () => { /* arrange; trigger T; expect R */ }) |
| Optional feature ("Where F, the S shall R.") | it.skipIf(!F) (vitest conditional) | it.skipIf(!F)('where F, S shall R', () => { /* expect R */ }) |
| Unwanted behaviour ("If C, then the S shall R.") | error-path it() with negative assertion or toThrow() | it('if C, then S shall R', () => { /* induce C; expect R */ }) |
Reference test exemplifying this pattern: tests/lib/wave-executor/persona-gate-hook.test.mjs (shipped at #481).
Follow .claude/rules/testing.md § "Test Quality — False-Positive Prevention": one meaningful assertion per it, behaviour not implementation, no branching, hardcoded expected values.
Provide:
// ..., no placeholders, no // implement laterThe test MUST fail before Step 3 is applied. If the behavior already exists and cannot fail, pick a harder assertion or a new edge case.
Provide:
npm test -- tests/unit/my-module.test.mjs)Provide:
Create: or Modify:// add appropriate logic, no // similar to above, no ...Provide:
Provide:
type(scope): subjectBefore writing the plan to disk, scan every Step in every Task for forbidden strings. Any match is a rejection — fix before writing.
Forbidden strings (case-insensitive):
| Pattern | Why forbidden |
|---|---|
TBD, TODO, FIXME, XXX | Deferred decisions defeat the plan's purpose |
add appropriate error handling | Vague — specify the exact error type and handling code |
add error handling | Same — write the catch block |
similar to Task N, same as above, like Task N | Forces the executor to cross-reference; defeats file-disjoint execution |
etc. | Incomplete enumeration — list every item |
[fill in], <placeholder>, <YOUR_VALUE> | Template leftovers — fill them in |
... inside a code block | Ellipsis in implementation code means incomplete code |
Prose ellipsis (e.g., "Phase 1... Phase 2...") is acceptable. Only code-block ellipsis is forbidden.
Any hit → surface to user via AUQ:
AskUserQuestion({
questions: [{
question: "The placeholder linter found forbidden strings in the draft plan:\n\n[list each hit with Task number, Step number, and matched text]\n\nHow do you want to proceed?",
header: "Placeholder Linter",
options: [
{ label: "Fix automatically (Recommended)", description: "I will resolve each hit by filling in the missing specifics before writing the plan." },
{ label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail." }
],
multiSelect: false
}]
})
Fix all hits before Phase 5.
Ensure the target directory exists:
mkdir -p docs/plans
Generate today's date via date +%Y-%m-%d. Derive <feature-slug> from the feature title (lowercase, hyphens, no special characters, max 40 characters).
Write to: docs/plans/YYYY-MM-DD-<feature-slug>.md
Use the template in plan-template.md (same directory as this SKILL.md) as the structural guide. Fill every slot. The written plan must:
# Plan: <feature title> and a Source: / Created: / Status: draft header block## Files section listing all Create / Modify / Test paths across all Tasks## Task N: <title> section per Task, each with its per-task ### Files block and Steps 1-5Present the plan path and task count to the user via AUQ:
AskUserQuestion({
questions: [{
question: "Executable plan written to docs/plans/YYYY-MM-DD-<slug>.md ([N] tasks, ~[total] min estimated).\n\nHow do you want to execute it?",
header: "Plan Hand-off",
options: [
{ label: "Dispatch via wave-executor (Recommended)", description: "Parallel agents execute all tasks simultaneously. Fastest for file-disjoint tasks." },
{ label: "Execute coordinator-direct", description: "One task at a time in this session. Safer for tasks with shared state." },
{ label: "Revise the plan first", description: "I have feedback — describe what to change and I will update the plan." },
{ label: "Done for now", description: "Keep the plan as a reference; no immediate execution." }
],
multiSelect: false
}]
})
If the user selects "Revise the plan first", incorporate the feedback, update the plan file, re-run the Phase 4 linter, and re-present Phase 6.
If the user selects "Dispatch via wave-executor", hand off to skills/wave-executor/SKILL.md with the plan path as input.
feat(core): update things is not acceptable; the scope and subject must be derivable from the Task's file set without reading the diffskills/plan/SKILL.md — produces the PRD this skill consumesskills/brainstorm/SKILL.md — alternative source (design spec)skills/wave-executor/SKILL.md — consumes the plan for parallel execution.claude/rules/testing.md § "Test Quality — False-Positive Prevention" — test conventions to follow in Step 1skills/write-executable-plan/plan-template.md — structural template used in Phase 5npx claudepluginhub kanevry/session-orchestrator --plugin session-orchestratorConverts an approved spec into a TDD-structured implementation plan with exact file paths, full code snippets, and explicit commit boundaries. Invoke after the user approves a spec and before any implementation begins.
Writes detailed implementation plans from specs for multi-step tasks before coding, with file structure maps, TDD bite-sized steps, and markdown tracking format.