agentleFS
AlexanderTarAlexanderTar/swarmrun/skills/swarm-spike/SKILL.md

swarm-spike

Skill2 starsChanged 19 days agoApache-2.0View on GitHub

Spike methodology for a Swarm orchestrator running a spike item — framing, splitting into research sub-questions run by researcher agents, design brainstorming, spec approval per section, and planning into work packages. Use together with the `swarm` skill when your kickoff names this skill (a spike-item orchestrator).

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Follow swarm and swarm-orchestrator for inbox, artifacts, approvals and worktrees.

    line 8

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Turn a spike into an approved, role-assigned plan

Follow swarm and swarm-orchestrator for inbox, artifacts, approvals and worktrees. Use this seven-step method for a feature spike. A debug spike uses superpowers:systematic-debugging for evidence and root cause, may create research tasks, and assigns its fix packages the debug workflow.

  1. Frame the request. Restate the outcome and constraints, and search candidate repositories. The starting repositories are hints: research may use any real Git repository without repository approval. Register a newly found local repository with swarm_repo_register when the plan needs to name it. Once the request is understood, consult the advisor about unknowns and scope.
  2. Deep research. Apply the “understand the idea” phase of superpowers:brainstorming. Split unknowns into 2–5 non-overlapping sub-questions (one for a single fact; three by default). Create a spike task per question with workflow: {"template":"research"} (researchers write notes under $SWARM_HOME/research/<ROOT-KEY>/, never under specs/; only your synthesis goes to specs/) and start each through swarm_workflow start, in parallel within budget. Do at most one extra round for critical gaps. Synthesize an answer-first summary at $SWARM_HOME/specs/<date>-<SPIKE>-research-<slug>.md, call out conflicts, link every claim to a note, register it as a note artifact, and reference it from the spec Context.
  3. Design. Use superpowers:brainstorming with the user: questions, two or three approaches, then section-by-section design. For UI work, create a separate spike task with workflow: {"template":"design-reviewed"}. Its designer makes the design artifact, its ui_reviewer checks it, and the spec Screens section references it. Make that task a dependency of any UI build package.
  4. Spec approval. Register or revise the spec; write each required section's approval prompt as a section brief (lead sentence, then 6–12 short bullets, 1–2000 characters; see Approval summaries in swarm-orchestrator), and ask for native approval at its current hash. Reply with the returned chat_block and end your turn; ask when Swarm sends request_ask. Only Context, Background, Bibliography, References, File list, Files, and Work breakdown are exempt after optional decimal section numbering and case folding. Out of scope, Explicitly out of scope, unknown headings, and headingless sections require approval. Record the advisor's design advice and what changed because of it.
  5. Plan. Use superpowers:writing-plans. Each deliverable gets a workflow, acceptance, verify, and a TDD script: write failing test → run and record red → implement → run and record green → refactor → commit. Write superpowers-sized tasks as units; use swarm-batching to combine three to five related units into one work package. One coder executes its units sequentially and review happens once after the package. Give stories after_tasks reviews when children interact, and give the root an integration workflow. Use dependencies only where one output is needed by another; prefer a pipeline to a barrier. Use the role table in swarm-workflows to assign every role explicitly in the plan. A task's role_hint, if set, agrees with the workflow run role.
  6. Completeness critic. Before plan approval, spawn a reviewer on the spike with the plan path. Ask: “What is missing or wrong: acceptance criteria not covered by any task, tasks that aren't self-contained, missing verify commands, wrong dependencies, split TDD phases, packages that fail the batching test or could be merged, and any task whose workflow roles don't fit its work?” Fold findings in, or record why a finding is inapplicable, and re-register the plan. Resolve the plan-registration warnings shown on the board.
  7. Plan approval and materialize. After all current required spec sections are approved, write the plan's approval prompt as a brief of its delivery packages and verification, in the same Approval summaries shape. Reply with the returned chat_block (it holds both review paths) and end your turn; ask when Swarm sends request_ask. Ask for whole-plan approval at the current revision, then call swarm_materialize. Follow swarm-orchestrator for the hook-backed Claude, Antigravity, Codex, and Grok path and the Cursor and Muse native-tool answer_text report; cancellation submits nothing. The materialized tasks carry resolved workflows, units, verify commands and role hints. Complete the spike after materialization and clean its worktrees through swarm_worktree. A spec section with nothing for the user to review (e.g. "DB models: none") is asked with nothing_to_review: "<one-line reason>" instead of a native question; print the line the result gives you -- never to skip a section that has content.

Report each step's status on every swarm_checkpoint with todos, as the Spikes section of swarm-orchestrator describes.

Bad: make separate “Write failing test”, “Make test pass” and “Review change” tasks. That makes three agents and three review boundaries for one deliverable.

Good: one task with a tdd-reviewed workflow and related units, each with failing test, green implementation and commit steps. The daemon starts one coder for the whole package and runs the reviewer after its verification passes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.