From dkod-swarm
Use this skill when the user gives Claude a code task that touches more than one symbol — refactors that span multiple functions, multi-step rewrites, or any task where parallelism across symbols would speed up the work. The skill drives the dkod-swarm MCP server's 8 tools (`dkod_plan`, `dkod_execute_begin`, `dkod_write_symbol`, `dkod_execute_complete`, `dkod_commit`, `dkod_pr`, `dkod_status`, `dkod_abort`) to partition the task by call-graph coupling, run N Task subagents in parallel against a single shared worktree, and produce one commit per group plus one GitHub PR. Trigger when (a) the user asks for a refactor that names two or more symbols, (b) the user explicitly asks for "parallel" or "multi-agent" work, (c) a task description contains "and" joining independently-named pieces of code, or (d) the user invokes one of the `/dkod-swarm:` slash commands. Skip when the task is a single-line edit or single-symbol rewrite — the partitioning overhead isn't worth it.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dkod-swarm:dkod-swarmThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Most "let agents work in parallel" approaches fail one of two ways:
Most "let agents work in parallel" approaches fail one of two ways:
auth.rs, agent B owns db.rs. Safe but limits parallelism: real refactors touch overlapping files, so 10 candidate agents collapse to 2-3.dkod-swarm partitions at the symbol level — function, struct, method — not the file level. Two agents rewrite different functions in the same auth.rs simultaneously. AST-aware writes through dkod_write_symbol compose their edits in-place. The partition comes from the call graph, so coupled symbols stay in the same group — correctness preserved, parallelism unlocked.
One worktree. N Task subagents. One commit per group on one dk-branch. One PR.
Trigger on:
login and logout to use passkeys").parse_request AND fix the off-by-one in iter_chunks")./dkod-swarm:plan, /dkod-swarm:execute, or /dkod-swarm:pr.Skip when:
dkod init (no .dkod/config.toml). Tell the user to run dkod init first.Before any tool call, check that the dkod-swarm MCP tools are available. Look for dkod_plan in the tool listing. If absent, the plugin's MCP server didn't start — tell the user:
The dkod-swarm MCP server isn't running. Try
/plugin install dkod-swarm@dkod-swarmto reinstall, or check~/.claude/logs/for stderr from thedkod --mcpinvocation.
Call dkod_plan with:
task_prompt — the user's task description verbatimin_scope — qualified names of every symbol you think the task will touch. Use code search and the user's task description to identify these. Err on the side of inclusion; the partitioner will tell you if any name is unknown.files — Rust source files containing those symbols, relative to the repo roottarget_groups — your best guess at the parallelism degree (2–4 is typical; never above 8)The response is a PlanResponse { groups: Vec<PlanGroup>, warnings, unresolved_edges }. Each PlanGroup is a connected component of the call graph among the in-scope symbols.
Review the partition. If groups.len() is 1, the symbols are too coupled to parallelise — fall back to single-agent execution. If groups.len() >= 2, proceed. If warnings mentions ScopeSymbolUnknown, ask the user which symbol they meant.
Show the partition to the user as a brief table (group id, symbol count, sample names). Wait for confirmation before Phase 2 unless the user invoked /dkod-swarm:execute (which auto-confirms).
Call dkod_execute_begin(task_prompt, groups). The response includes session_id and dk_branch (dk/<session-id>).
The MCP server has now:
dk/<session-id> off main.dkod/sessions/<sid>/active_session so subsequent tool calls know which session they're inFor each group in the partition, dispatch a Task subagent. Use the parallel-executor subagent template (this plugin's agents/parallel-executor.md) or the generic Agent tool.
Each subagent's prompt MUST include:
dkod_write_symbol(group_id, file, qualified_name, new_body) for the edit. DO NOT use raw Edit or Write on those files. Raw Edit / Write is only acceptable for files that are NOT in any partition group (e.g., a genuinely new file you're creating)."group_id from the partition response — the subagent passes it to dkod_write_symbol and to the final dkod_execute_complete call.dkod_execute_complete(group_id, summary) when done, where summary is a one-paragraph description of what changed.Why this enforcement matters: raw Edit bypasses the per-file lock and the AST-merge primitive. Two subagents using raw Edit on the same file will produce a Git conflict at commit time — exactly what dkod-swarm exists to prevent. Always include the enforcement clause.
Wait for every Task subagent to return before Phase 4. The Task tool's natural synchronization handles this — no polling needed.
For each subagent that returned, confirm:
dkod_execute_complete for its groupOptionally call dkod_status to see per-group write counts and confirm everything is in done state.
Call dkod_commit(). The response is CommitResponse { commits_created, dk_branch, commit_shas }. One commit per group with writes; groups that produced no writes are silently skipped.
The dk-branch now has all the work. The session manifest is marked Committed.
Briefly review the diff (git diff main..<dk_branch>) — look for obvious bugs, missing tests, or scope drift. If anything is off, dispatch a fix-up subagent or call dkod_abort to discard the session.
When satisfied, call dkod_pr(title, body):
title — concise, ≤ 70 chars, summarises the user's taskbody — short summary + test-plan checklist (mirror the project's PR-body convention if visible in git log)The response is PrResponse { url, was_existing }. Show the URL to the user. was_existing == true means a PR for dk/<sid> already existed and we returned its URL — that's idempotency, not an error.
After a successful dkod_pr, the active session is cleared. The user may now run dkod_plan again for a new task.
The in-scope symbols are too coupled. Either:
Check its escalation message. Common causes:
dkod_abort, fix the in_scope list, re-plandkod_status for fallback outcomes; the symbol may need a different replacement strategydkod_pr returns Error::VerifyFailedYour verify_cmd (configured in .dkod/config.toml at dkod init time) failed. Read the error's tail field — it's the last 10 lines of stderr from the verify command. Dispatch a fix-up subagent on the dk-branch, then retry dkod_pr.
dkod_pr returns an existing URL with was_existing: trueThis is normal idempotency — a previous run already opened the PR. Just show the URL to the user.
When a fresh Claude session starts in the same repo, the dkod-swarm MCP server's recover() reads .dkod/sessions/ and restores any session in Executing state. Call dkod_status to see what was done; either resume from there, or call dkod_abort to discard.
Edit or Write on a file in any partition group. Use dkod_write_symbol exclusively for those. Raw Edit / Write is acceptable only for files outside every group's symbol set (e.g., a brand-new file).dkod_pr opens the PR; the user (or CI) merges it. Calling git merge directly bypasses the project's review gate.main. Every write happens on dk/<sid>; main is read-only from this skill's perspective.dkod_abort without explicit user confirmation unless verification has failed unrecoverably (e.g., the dk-branch is in a state that cannot be fixed by a fix-up subagent).| Tool | Caller | Purpose |
|---|---|---|
dkod_plan | parent Claude | partition the task by call-graph coupling |
dkod_execute_begin | parent Claude | mint session + dk-branch |
dkod_write_symbol | Task subagent | AST-level symbol replacement (per-file lock) |
dkod_execute_complete | Task subagent | mark group done with summary |
dkod_commit | parent Claude | one commit per group on dk-branch |
dkod_pr | parent Claude | verify, push, open PR (idempotent) |
dkod_status | parent Claude or user | read-only session snapshot |
dkod_abort | parent Claude or user | destroy dk-branch + clear state |
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub dkod-io/dkod-swarm --plugin dkod-swarm