From zsl
Fan out the unblocked [AFK] sub-tasks of a parent (PRD) issue into parallel /tdd sub-agents in worktrees. Sub-agents commit but do NOT push; the orchestrator merges every slice branch onto the PRD branch in wave order with --no-ff, then opens a single integration PR. AFK-only — [HITL] slices are skipped. PR-style repos only.
npx claudepluginhub zunosmartlabs/zsl-superpowersThis skill uses the workspace's default tool permissions.
Fan out the unblocked **[AFK]** sub-tasks of a parent issue into parallel `/tdd` sub-agents. Each sub-agent runs `/tdd <num> --no-ship` in its own worktree, committing locally but never pushing. The orchestrator merges every slice branch onto the parent's PRD branch (which doubles as the integration branch) in wave order with `--no-ff`, then opens a single integration PR.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Fan out the unblocked [AFK] sub-tasks of a parent issue into parallel /tdd sub-agents. Each sub-agent runs /tdd <num> --no-ship in its own worktree, committing locally but never pushing. The orchestrator merges every slice branch onto the parent's PRD branch (which doubles as the integration branch) in wave order with --no-ff, then opens a single integration PR.
[HITL] slices are filtered out — they require human interaction and must be run via /tdd directly. PR-style repos only — direct-push fanouts merge straight to main without consolidation.
Each push to a feature branch triggers CI workflows. With N sub-issues = N PRs you'd pay N × M CI runs over the life of a fanout. Staging slice work locally and pushing one consolidated branch costs one CI run. Trade-offs: one PR is a single review surface (no per-slice review granularity), and merge conflicts surface during local integration rather than during PR review. Both are acceptable when the wave model from /to-issues asserts same-wave slices are disjoint.
/tdd-parallel <parent-issue> [--max N]
<parent-issue> — the parent (PRD) issue whose unblocked AFK sub-tasks should be fanned out.--max N — concurrency cap within a wave. Default 2.Sub-agents spawned by this skill operate AFK. They make reasonable decisions and finish — they do not return mid-flight to ask routine questions. They escalate (return early with a question) only when they hit:
When an agent escalates, the orchestrator relays the question to the user and resumes the agent via SendMessage with the user's answer. Anything that would routinely need human input mid-flight isn't AFK and shouldn't be in the fanout — it belongs as an [HITL] slice.
Three phases. 1a refuses on failure; 1b cleans up silently and continues; 1c either creates or adopts the PRD branch.
Refuse with a clear error message if any of these fail.
docs/agents/ship-style.md exists and says PR-style. Direct-push fanouts are unsupported — they'd land slices on main directly without consolidation, defeating the point.docs/agents/issue-tracker.md exists.docs/agents/triage-labels.md exists.Append .worktrees/ to the repo root .gitignore if not already present.
Scan .worktrees/*. For each entry whose name matches <num>-<slug>:
git -C .worktrees/<dir> status --porcelain is non-empty — uncommitted changes; the user should investigate.git worktree remove .worktrees/<num>-<slug> (no --force)git branch -d tdd/<num>-<slug> (no -D)git branch -d refuses because the branch isn't fully merged, skip and log — never -D automatically.Print a one-block summary: cleaned, skipped — open, skipped — uncommitted, skipped — unmerged branch. Do not refuse on any skip.
The PRD branch doubles as the integration branch — sub-task branches will be merged onto it, and it gets pushed once at the end as the integration PR's source.
git fetch origin.git status --porcelain non-empty) or HEAD is detached.main: create the PRD branch and switch to it.
feature/<parent-num>-<slug>. Slug is kebab-case of the parent issue title, max 40 chars.git checkout -b feature/<parent-num>-<slug> from main's tip.main branch: treat it as the PRD branch. Do not switch, do not auto-rebase against main — the user owns its relationship to main.After 1c the orchestrator is on the PRD branch with a clean working tree.
Using docs/agents/issue-tracker.md conventions, fetch the parent issue's sub-issues. Keep only those that are:
[AFK] ([HITL] filtered out)ready-for-agent labelFor each surviving slice, parse the ## Blocked by section to extract referenced issue numbers. Build the dependency graph in memory.
Maintain orchestrator state across iterations:
merged — set of sub-task issue numbers whose branches have been merged onto the PRD branch.attempted — set of sub-task issue numbers we've spawned an agent for.A slice is unblocked when every issue in its Blocked by section is in merged. (Issue closure is irrelevant in this architecture — sub-issues never close mid-fanout because they're never pushed.)
Pick all unblocked, not-yet-attempted slices, sorted by issue number, capped by --max.
If the picked set is empty:
merged covers every discovered slice → fanout complete. Go to step 4.Blocked by, a slice depending on an issue outside this fanout, or a reference to a non-existent issue. Stop.Print buckets:
/tdd <num> directly in a normal session.Blocked by references it's still waiting on.Confirm with the user before proceeding.
For each selected slice, derive:
tdd/<num>-<slug>..worktrees/<num>-<slug>/.Then:
git worktree add .worktrees/<num>-<slug> -b tdd/<num>-<slug> HEAD — HEAD is the PRD branch's current tip, so the slice inherits any prior waves' merges.-b.Agent({
description: "TDD <num>",
subagent_type: "general-purpose",
run_in_background: true,
name: "tdd-<num>",
prompt: <see template below>
})
Sub-agent prompt template:
You are running AFK as part of a /tdd-parallel fanout.
First action: cd <ABSOLUTE-PATH-TO-WORKTREE>
Then run: /tdd <num> --no-ship
You operate under the AFK contract:
- Make reasonable decisions and finish without coming back to ask routine questions.
- Escalate (return early with a question) ONLY for: destructive ops needing confirmation per auto mode rules, missing access/credentials, or genuine architectural ambiguity that would change a public contract.
- Be specific about what you need if you do escalate.
When done, report: branch name, last commit sha, the slice issue number you worked on (so the orchestrator can map slice → issue), and a one-paragraph summary of changes. Do NOT push. Do NOT open a PR.
Add each spawned issue number to attempted. Pass the absolute worktree path in the prompt — the sub-agent's first action must be to cd there before doing anything else, so its Bash CWD lands in the right worktree for the remainder of its session.
Process completion notifications as they arrive. For each completing agent:
SendMessage({ to: "tdd-<num>", message: <user's answer> }). Do not proceed until the agent returns properly.Wait until all agents in the current wave have completed normally before moving to merge. (Halts in 3d cancel the rest — see "Halt semantics" below.)
The orchestrator is on the PRD branch. Merge each of the wave's slice branches in order — by letter for lettered slices (1a, 1b, 1c), by issue number otherwise. For each:
git merge --no-ff tdd/<num>-<slug> -m "Merge slice [AFK] <wave><letter> — <slice-title> (#<num>)".make lint test if a Makefile exposes them; otherwise infer from repo conventions). On pass, git add the resolved files and git commit --no-edit to complete the merge, then continue to the next branch.git merge --abort — the user inspects in place) and halt with hybrid RCA. Stop.merged. Continue to the next branch.Go back to 3a. Newly-unblocked slices (whose Blocked by references are now all in merged) become the next wave's candidates.
After all discovered slices are merged:
git push -u origin <prd-branch>.gh pr create \
--title "<parent-title> (#<parent-num>)" \
--base main \
--body "<see template>"
PR body template:
## Summary
<one-line, parsed from the parent issue's `## Solution` section if present; otherwise the parent's title>
## Slices integrated
In wave order, oldest first:
- `[AFK] 1 — Slice 1 title` — #N
- `[AFK] 2a — Slice 2a title` — #N
- `[AFK] 2b — Slice 2b title` — #N
- `[AFK] 3 — Slice 3 title` — #N
## Closes
Closes #<parent>
Closes #<sub-issue-1>
Closes #<sub-issue-2>
...
---
Integrated by `/tdd-parallel` across <N> waves.
docs/agents/project-board.md exists). Bulk-move the parent issue and every merged sub-issue's project card from "In progress" to the option mapped to "PR opened" (typically In review) via updateProjectV2ItemFieldValue. Use the same lookup-then-update procedure documented in triage/SKILL.md step 6. This step is mandatory when the file exists — do not treat it as optional. If an individual update fails, log the failure and continue with the rest of the items; only abort if every update fails (that would indicate a credential or project-id problem worth surfacing).When the integration PR merges, GitHub's auto-close workflow closes every Closes #N issue and lands each card on Done.
Print a final summary:
/tdd <num> directly).The orchestrator session can now be closed. Slice worktrees and branches remain on disk; pre-flight 1b will sweep them on the next /tdd-parallel run, or you can clean them sooner by hand.
Three failure paths halt the run, all with the same shape: print a hybrid RCA, leave state inspectable, stop. The orchestrator does not attempt resume — the user takes over from the halted state.
git merge --no-ff conflicted and the orchestrator's auto-resolve attempt couldn't produce a clean, lint+test-passing merge. The merge is left in its conflicted state on the PRD branch.When a halt fires while other agents are still in flight, the orchestrator waits for those agents to return (so it can capture their state in the RCA), then halts. It does not cancel them mid-flight — let them either complete or escalate, and surface their final state.
Every halt produces a structured RCA followed by an LLM-generated Possible interpretation paragraph. The structured part is deterministic, gathered via git and gh. The interpretation reads those facts and proposes the most likely cause — treat the facts as authoritative and the interpretation as a hint.
Common header (all halt types):
Agent failure (3d):
/tdd red-green-refactor failed / unknown.cd <agent-worktree> to inspect, retry by re-running /tdd <num> manually, or amend the slice's brief and re-run /tdd-parallel.Unresolvable merge conflict (3e):
git diff --check).same-wave overlap (both slices in wave N — indicates /to-issues mis-sliced), cross-wave drift (downstream slice rebased onto an upstream wave that touched the same area), or unknown.Blocked by references each slice declared (helps spot a missing dependency that should have serialised them)./tdd-parallel again to continue.Zero-progress (3a):
Blocked by references each is waiting on.cycle (other un-attempted siblings forming a cycle), external (issue outside the parent's sub-tree), unresolvable (non-existent issue number).Blocked by sections in the issue tracker to break the cycle / reference the right issue / drop the external dep, then re-run /tdd-parallel.The framework auto-cleans nothing during the run. After the integration PR merges:
git worktree remove .worktrees/<num>-<slug> for each slice.git branch -d tdd/<num>-<slug> (force with -D only if upstream branch was force-pushed).Pre-flight 1b sweeps these on the next /tdd-parallel run, so manual cleanup is optional unless you want the disk space back sooner.
/tdd-parallel after switching their ship-style.md to PR-style for the duration, or run individual /tdd sessions in parallel by hand.