spec-dispatch

name	spec-dispatch
description	Turn a spec, PRD, or vague ambition into a runnable bd issue board with sprints, fan-out, cross-repo gates, and specialist orchestration — without over-engineering the plan itself. Ponytail-first: the plan is only as big as it has to be. Use when the user says "plan this", "spec-dispatch", "prd-to-plan", pastes a PRD/roadmap, links a design doc, or when a new audit/report/spec lands and needs decomposition across one or more xtrm repos. Also use when a task spans ≥2 repos, ≥3 sprints, or would benefit from parallel lanes but the user hasn't yet decided the shape.
priority	normal
disable-model-invocation	true

/spec-dispatch — spec → runnable board

You just got a PRD, plan, audit report, roadmap, or vague ambition. Turn it into a bd board that a coordinator + 3 panes can execute — without invalidating ponytail by writing a giant plan document.

When this fires

• /spec-dispatch — user typed it explicitly
• User pastes a spec / PRD / audit report / design doc
• User says "plan this", "break this down", "how do we ship this", "let's plan the X epic"
• New markdown at docs/design/*.md or docs/plans/*.md lands and user wants it decomposed
• A task obviously spans ≥2 xtrm repos (core, xtmux, specialists) or ≥3 sprints

Workflow

Follow in order. Skip steps only when the input clearly doesn't require them.

1. Ground the input

• If user pasted inline, use it as-is
• If user gave a path, read only what you need — for docs >1000 lines use ctx_execute_file to extract headings + work-package IDs; don't dump bytes into context
• If the doc is unclear or contradicts recent PRs, ask one clarifying question before scoping (never two)

2. Recent-work ack (mandatory)

Before scoping anything, orient to what shipped recently in each affected repo:

gh pr list --state=merged --limit 15
git log --oneline -20

Note if a recent PR already did what the spec is asking. If yes → STOP and surface to user before continuing.

3. Understand complexity & scope

Split the input into:

• Audit-closure vs new-feature (Track A vs Track B) — never mix in one epic; user's earlier firewall preferences apply
• Per-repo lanes — which of ~/dev/core, ~/dev/xtmux, ~/dev/specialists (or wherever) is touched
• Cross-repo release gates — any change that requires atomic multi-repo release?
• Work-package IDs — if the spec already has them (MSG-01, PACKAGE-A, etc.), respect them

4. Adversarial pre-plan audit (only for large/multi-repo)

If the plan spans ≥2 repos or has ≥10 work packages: spawn 2–3 general-purpose audit helpers before creating any beads. One per repo. Each answers, per claim:

• still-current? — is the claim true against HEAD, or has a recent PR fixed it?
• implementable-as-described? — are the proposed files/seams correct? missing coupling?
• ponytail-verdict — accept / simplify-how / cut. Reject new abstractions with one caller, per-caller patches when a shared guard works, "quarantine" over "delete", daemons where a periodic reconciler exists, prose complexity dressed as design

Prefer sequential dispatch (one helper at a time) unless user opts into parallel — helper reports are the base for the fan-out plan.

5. Decide fan-out & sprint subdivision

Write a compact epic-head at docs/design/<slug>-epic-plan.md:

• Track split (if applicable)
• Audit-informed deltas (helpers override the spec)
• Sprints with per-lane task lists
• Fan-out helpers per sprint (coordinator + panes + specialists)
• Cross-repo release gates
• DoD per sprint

Keep it under ~300 lines. Anything longer = ceremony creeping back.

6. Materialize bd board

Via /planning skill or direct bd create script:

• One umbrella epic; one child epic per sprint; tasks under sprint epics
• Group by "would-ship-together" PR boundary — 1 bead per PR, not 1 bead per file
• Fill 7-section contract (PROBLEM / SUCCESS / SCOPE / NON_GOALS / CONSTRAINTS / VALIDATION / OUTPUT) — see /planning
• Wire deps: blocks only for hard sequencing; validates / discovered-from / caused-by otherwise
• Cross-repo gates → bd dep add <A> <B> --type blocks between concrete task beads
• Placeholder epics for deferred programs (child of umbrella, no grandchildren)

Batch-create via a scratchpad script using bd create --silent --stdin — single tool call, one long script, IDs captured to /tmp/bd-created/ids.txt.

7. Cross-cutting rules

Append to the umbrella epic:

• Help-surface parity — CLI code changes ship with --help update in same PR
• Skill drift — any changed CLI flag with a corresponding .xtrm/skills/default/**/SKILL.md mention: update or file follow-up
• Bead assignee auto-populate — when xt pi/claude --bead <id> is used

Append explicit help-surface / assignee checkboxes to individual beads only when they concretely touch that surface.

8. Handoff

• Show board tree (bd list --parent <umbrella>)
• Show first claimable (bd ready --limit 3)
• Report specialist load per sprint (count of dispatches, not tasks)
• Note anything uncommitted (epic-head doc, source PRD) so user commits before starting

Skill routing (what to load when)

Situation	Load
Structured bd decomposition after this skill drafts the epic-head	/planning
Companion test/smoke/E2E issues per bead layer	/test-planning
Coordinator + ≥2 panes for parallel lanes	/multiplexing
Dispatch executor/reviewer/debugger/test-runner/security-auditor chains	/using-specialists
Any coding bead — enforce lazy solution	/ponytail:ponytail (auto-active if operator has it on)
Service/project context before scoping	/scope + /using-service-skills
Stress-test the plan for blind spots	/premortem
Underspec'd PRD — needs research first	/deep-research
xtrm workflow / beads gates / hooks	/using-xtrm
PR flow / session close	/xt-end, /xt-merge, /session-close-report

Load skills just before the phase that needs them, not upfront.

Optional: Jira mirror

If the operator uses Jira (Atlassian Rovo MCP connector active — mcp__claude_ai_Atlassian_Rovo__*), mirror the umbrella epic and sprint epics into Jira for operator-facing durability. bd stays the execution truth (claims, deps, memory-acks, KV state); Jira is the human-scan view.

• One Jira issue per bd epic (umbrella + sprint children). Do NOT mirror leaf tasks unless the operator asks — that's ceremony.
• Link each Jira issue to its bd id in the description; put the bd id in a Jira label (e.g. bd:xtrm-wiy5n).
• Dedupe first — mcp__claude_ai_Atlassian_Rovo__searchJiraIssuesUsingJql with labels = "bd:<id>".
• On sprint close, mcp__claude_ai_Atlassian_Rovo__addCommentToJiraIssue with release PR link + smoke evidence.
• Never sync bead notes / KV / memory-ack into Jira — those are execution signals with no operator-scan value.

Ponytail: if the operator hasn't asked for Jira mirroring and no Rovo MCP is available, skip the section entirely. Don't create Jira debt.

Optional: Calendar time-blocking for future work

If work is planned for future dates (release windows, sprint kickoffs, review gates, cross-repo coordination) AND a calendar connector is available (mcp__claude_ai_Google_Calendar__* is the reference; other providers similar), time-block the moments, not the beads.

Date-anchor candidates (block only these):

• Sprint kickoff once dependencies clear
• Coordinated release window
• Smoke-container review checkpoint
• Cross-repo release gate operator sign-off
• External dependency deadline (e.g. an upstream PRD ships)

Ponytail: never one calendar event per bead. Only date-anchored moments. If the operator hasn't asked and no calendar connector is available, skip.

Example (Google Calendar): mcp__claude_ai_Google_Calendar__create_event with title "Sprint 3c release window — <slug>", description linking bd umbrella + release PRs, duration = expected wall-clock (a real block, not a 15-min "for later" placeholder).

Ponytail rules for this skill

• The plan document is not the deliverable — the runnable board is. Keep the doc small.
• Group beads by PR boundary, not by file. 8 small fixes in one PR = one bead with 8 VALIDATION checkboxes, not 8 beads.
• Cross-repo release gate = one blocks edge between the two release beads. No new orchestration layer.
• Adversarial audit is not for every plan. Skip if the input is a straightforward single-repo feature and the operator hasn't asked for it.
• No new bead for tooling meta-work that fits under an existing umbrella claim.
• If the spec is under 30 lines and touches one repo, skip the epic-head doc entirely — go straight to /planning.
• Never invent format when a canonical one exists (xtrm.forensic.v1, existing pollTimer, existing writeUnifiedHandoff seam, etc.).
• Ask user question only when it's genuinely a decision they must make (audit fold-in vs new bead, sprint reshape, release-gate strictness). Never ask "should I proceed" after they said "plan this".

Trigger patterns

When	Do
user pastes PRD / audit / roadmap	ground input → recent-work ack → complexity split
doc is >1000 lines	ctx_execute_file for headings + work-IDs; don't read all bytes
plan spans ≥2 repos or has ≥10 packages	adversarial audit before beads
operator says "no new bead for X"	fold X's scope into an existing bead via bd update --append-notes
bead descriptions balloon past ~80 lines	you're over-planning; cut back
a sprint has >15 tasks	consider splitting the sprint or grouping tasks by PR boundary

Output pattern

Every phase reports to the user in one of these shapes:

• Confirmation of grounding — "Doc is X lines, ~Y is authoritative content, Z is historical" + verified state of affected repos
• Fan-out proposal — table of helpers/lanes/repos + one AskUserQuestion before spawning
• Audit deltas — table: doc-proposal | helper-verdict | action
• Sprint pre-subdivision — code block with sprint tree + fan-out helpers per sprint
• Board materialized — bd list --parent <umbrella> + bd ready --limit 3 + specialist load summary + first claimable

Never wall-of-text between phases. Ask user question only at real decision points.