English | 简体中文
Turn ambiguous human goals into an executable, testable, auditable, and deliverable AI-driven software production pipeline (Self-evolving Workflow System).
Swarm Paradigm is not about making AI chat smarter. It is about making AI deliver continuously like an engineering system.
Through layered abstractions of Bee / Honey / Dance / Hive, it breaks complex business workflows into manageable minimal units and executes them end-to-end under human review. In principle, users should be able to get the software they need without seeing any code.
This naming is not marketing. It is a system design metaphor:
- Bee: A single bee focuses on one tiny action, mapped to an atomic capability unit. First make logic run, then evolve it.
- Honey: Standardized output produced by bees, mapped to transferable and reusable data contracts.
- Dance: Bees communicate direction and task signals by dancing, mapped to workflow orchestration and collaboration protocols.
- Hive: The organization and governance center of the colony, mapped to execution runtime and task governance.
- Swarm: Collaborative intelligence rather than monolithic intelligence, mapped to a multi-agent division-of-labor system.
- QueenBee: A special System Bee that manages Dance instance lifecycles: create, destroy, terminate, and query. The name follows the swarm metaphor: the queen does not gather nectar directly, but coordinates the colony.
- Beekeeping: Beekeepers do not produce bees or gather honey. They observe and guide, mapped to "humans only review and correct, not directly write Bee/Honey/Dance."
This naming emphasizes one core idea: complex goals are not completed by one super agent, but by a composable, governable, and auditable collaborative collective.
The following are core project boundaries at MUST level:
-
Bee, Honey, and Dance must be generated by AI
Humans do not directly write these three categories of code/definitions. Humans are responsible only for review, acceptance, and correction (Beekeeping). Every Bee, Honey, and Dance is AI-generated, validated by multiple forms of testing, and continuously evolved after release.
The only exception is MVP 1 (architecture validation), where manually writing Bee, Honey, Dance, and Hive is allowed, but only to validate architecture feasibility. Those artifacts must not enter BeeHub and must not be used as training exemplars for later Skills. -
Skills must be created first, then used to generate artifacts
First solidify "how to do it" (Skill), then execute "what to do" (Bee/Honey/Dance), reducing generation quality variance. -
All execution must be traceable, reviewable, and auditable
Each stage must produce explainable intermediate artifacts and execution records. Audit records can be enabled on demand. By default, concise summaries are retained, and detailed logs are used for debugging and retrospection.
Swarm's standard production path is:
Goal decomposition -> Skill design/selection -> Invoke Skill -> Generate Bee/Honey/Dance -> Hive execution -> Beekeeping
Why Skill-First is required:
- Make implicit experience explicit, reducing randomness from generating from scratch every time
- Control quality drift through skill versioning and regression testing
- Reduce inconsistency risk caused by model variance
- Let teams reuse production methods, not only output files
- Bee generation
- Honey generation
- Dance generation
- Goal decomposition
- Swarm visualization
- Memory palace
- Project management
- Software development
- Code review
- Unit testing
- End-to-end testing
- UI design
A Bee is an AI-generated JS class that performs exactly one atomic function. Key characteristics:
- Supports waiting and suspension (can run asynchronous long workflows)
- No nesting support (Bee must keep atomic responsibility)
- Must output a report on completion or exception
- No cross-task persistent internal state, but it may hold temporary runtime state during a single task execution (for example, waiting for multiple Honey payloads to aggregate). All temporary state must be released after the task ends. Data is injected externally, and outputs are returned via Honey
- Decoupled from external capabilities through interface-based dependency injection
- Must include test classes targeting full test-case coverage (100%)
- Independently versioned and runnable by explicit version
- Every Bee must implement
executereturning a Promise; resolve returns{ resultHoney, reportHoney }, reject returns{ errorHoney, reportHoney }. Hive uses Promise resolve/reject states to drive DanceonSuccess/onFailtransitions
In one sentence: Bee is the smallest production unit that is independently verifiable, replaceable, and evolvable.
Honey is an AI-generated JSON payload and the data carrier for Bee collaboration:
- Types must be explicit
- Supports nesting
- Untyped
Objectis not allowed - Explicit schema-based object structures are allowed
- Used to pass business context and results across steps
Dance is an AI-generated JSON workflow definition describing "who does what and when":
- Defines execution order, parallelism, and asynchronous strategies
- Supports nested Dance composition
- Defines timeout, retry, exception, and rollback strategies
- Defines logging rules, commit rules, and delivery exits
- Every step should include a human-readable description
- Independently versioned and runnable by explicit version
Dance specifies the topological order of Bee types, not concrete instances.
- Bee registration and scheduling
- Dance execution engine
- Maintains active Bee instance tables and routes based on Dance definitions and Honey target identifiers, supporting local execution and remote communication
- Task review and delivery aggregation
- Routes produced Honey to correct Bee instances, supporting sequential delivery of multiple Honey payloads to the same active Bee instance for asynchronous long workflows and multi-round interactions
A coordination layer running on Bun, responsible for:
- Requirement decomposition
- Skill selection and orchestration
- Model and tool scheduling
- webUI
- Converting all Honey and Dance into JS at deployment time, and bundling them with Bees into a single compressed JS file to keep runtime performance overhead near zero
QueenBee responsibilities include:
- Dynamically creating multiple child Dance instances for a parent Dance based on
multiplicity. - Sending
__Terminate__signals to stop specified Dance instances. - Querying status of running Dance instances.
- Recording execution traces with Mock Bees in test mode.
QueenBee itself follows the Bee interface. Its execute accepts ManageDanceHoney, performs management operations, and returns results. It is exposed only to Hive internals and authorized Dances, not to regular Bees.
Design intent: QueenBee centralizes instance-management logic so Dances do not directly manipulate Hive internal APIs, preserving clear responsibility boundaries.
- Share reusable Bees
- Retrieve existing capabilities
- Reduce duplicate build cost
- Use automatic Hive scoring for survival-of-the-fittest (scores combine execution performance, user feedback, and more; users do not need to rate each Bee directly)
To keep paradigm consistency, runtime architecture is defined as:
- Both frontend and backend are written in native JavaScript. The frontend also runs a mini Hive and can execute local Bees directly (for example, form linkage and animation driving), so not all logic must go to the server.
- Frontend Hive and backend Hive exchange Honey via WebSocket only when capability sharing is required. Honey is the unified transport payload.
- Wrap system-native capabilities (for example, crypto, WebRTC, media, file APIs) as System Bees with optional sandbox constraints (recommended for high-risk scenarios; users evaluate risk themselves).
- All capabilities are invoked through a unified Bee interface.
Why this matters:
- Keep execution model consistent (all capabilities are inside Bee workflows)
- Avoid paradigm drift caused by overreliance on mature frameworks
- Make system capabilities testable, auditable, and reviewable like business capabilities
Note: Bee interface specifications are language-agnostic. JavaScript is phase-1 reference implementation, and future extensions can include Python, Rust, and others. Bee implementations in different languages can interoperate through the standard Honey protocol.
- The frontend no longer seeds fake projects from
frontend/project.jsinitialState. - On bootstrap, frontend Hive calls backend
GET /api/projectsand renders real project data. - Backend now derives project list directly from subdirectories under
projects/. - If
projects/has no subdirectories, UI shows an empty project list.
- All user-facing prompt text must come from language packs. Do not hardcode visible strings in Bee/Hive/backend runtime logic.
- Language pack locations:
- Frontend:
frontend/languages/<lang>.json - Backend:
backend/languages/<lang>.json - Language selection:
SWARM_LANGcontrols backend language (for examplezh-CN,en-US).- Frontend uses
projectConfig.i18n.language(defaults tozh-CNin current implementation). - Fallback behavior:
- Try configured language first.
- Fallback to
en-USif missing. - If key is still missing, return the key name to expose missing translation early.
- Key naming convention:
domain.scope.intent, for exampleui.welcome.describe_requirement,errors.backend_request_failed.- Keep keys stable; avoid embedding versions in keys.
- Variable placeholders:
- Use
{{name}}style placeholders. - Rendering code must replace placeholders at runtime (for example
{{detail}},{{project}}). - Frontend/backend consistency:
- Shared semantics should use the same key meaning across frontend and backend.
- Avoid one-off ad hoc key meanings.
- Change management:
- Adding a new visible message requires adding translations in at least
zh-CNanden-US. - PRs should include both key definition and runtime usage changes.
Continuously improve Skill / Bee / Dance under sandboxing, scoring, review, and version control.
Each Bee, Dance, and Skill has a score.
After each execution, evaluate:
- Was execution correct?
- Was the goal achieved?
- Was it efficient?
- Is it reusable?
Evolution is driven by scoring. Final direction is determined by human judgment; automated scoring is an important reference, and human review (Beekeeping) decides whether to adopt new versions.
- BeeHub keeps only Top N Bees
- Low-scoring Bees are automatically eliminated
- Skills are version-scored
This is what real "swarm evolution" means.
- Optional permission tiers (
read/write/network) - Execution quota limits
- Approval mechanism (for high-risk Bees)
Core principle:
Do not let the same LLM act as both developer and examiner.
Support dual-model isolation where Builder and Tester run on different models. Otherwise, it is easy to produce a self-consistent loop where code is wrong, tests are wrong, and everything still passes.
Do not generate Bee first and patch tests later.
Correct order:
Goal -> Honey Schema -> Behavior Contract -> Test Cases -> Bee Implementation
Generate tests before implementation.
This forces Bee to satisfy external contracts, instead of letting tests accommodate Bee.
Use at least three roles:
Builder Agent: generate Bee
Tester Agent: reads only requirements and schema, generates tests
Reviewer Agent: reviews whether Bee and tests are colluding
Key points:
- Tester does not read Bee source to avoid implementation contamination
- Builder does not modify tests
- Reviewer focuses on detecting "fake tests"
This is much more reliable than single-agent self-testing.
Typical example test:
input A, expect output BCoverage is often insufficient.
A better approach is defining properties:
For any input:
- Output must satisfy Honey schema
- Amount cannot be negative
- Total count is conserved
- Length remains unchanged after sort
- Same input should produce consistent results across runs
This is property-based testing.
In JavaScript, you can use:
fast-check
If Bee is "draw cards", property tests may include:
After drawing:
- Hand size increases by count
- Deck size decreases by count
- Total card count is conserved
- If count exceeds deck size, error branch must be triggered
This is far stronger than a few AI-written happy-path tests.
Very useful when exact answers are unknown.
Examples:
Run the same Dance twice with identical input; outputs should match.
Add irrelevant fields to Honey; result should not change.
Swap two dependency-free steps; final result should remain the same.
It tests not "what the answer is," but "whether required relationships hold."
This is especially suitable for AI workflows.
Every human-approved case should be stored as:
Golden Honey
Golden Dance
Expected Report
Then every new Bee / Skill must run these historical samples.
This makes the system more stable over time.
Tests themselves must also be reviewed.
Example TestSuite scoring:
TestScore =
schema coverage
+ boundary coverage
+ exception-path coverage
+ number of property tests
+ number of metamorphic tests
- coupling degree to implementation
In other words:
Tests are also artifacts and must also go through Beekeeping.
This is one of the strongest methods.
Process:
1. Generate Bee
2. Auto-create faulty variants, for example:
- change > to >=
- change + to -
- remove exception checks
- invert conditions
3. Run tests
4. If tests fail to catch injected bugs, tests are weak
If a test suite cannot catch intentionally injected bugs, it is not trustworthy.
In the JavaScript ecosystem, see:
StrykerJS
For critical capabilities, do not rely on only one Bee.
Use:
Candidate Bee: newly generated version
Reference Bee: stable old version / simpler but slower version
Run both with the same inputs and compare outputs.
This is differential testing.
Especially suitable for:
- Data transformation
- Sorting
- Rule calculation
- Game state transitions
- JSON processing
System Bee should not be tested directly against real system commands.
Use:
FakeFileSystem
FakeNetwork
FakeClock
FakeRandom
FakeBrowser
This validates:
- Correct permission usage
- Expected side effects
- Rollback capability
- Privilege overreach
Instead of letting a general LLM write tests directly, encapsulate test generation as a Skill:
skill-generate-test-suite
Inputs:
Goal
Honey Schema
Bee Contract
Risk Level
Expected Invariants
Outputs:
Unit Tests
Property Tests
Mutation Plan
Golden Cases
Audit Checklist
Dance logic errors are more hidden than single-Bee errors, so automated testing is mandatory. Core methods:
- Contract tests + Mock Bees: Replace real Bees with Mock Bees in test mode. Mock Bees must strictly follow Honey Schema and remain behavior-predictable.
- Scenario definitions: Every Dance must include a
{DanceName}.test.dance.jsonfile containing multiple scenarios (input Honey sequences, mock responses, expected execution traces). - Trace assertions: In test mode, Hive records step sequences, child Dance create/destroy events, output Honey, and compares them with expected traces.
- Property testing: Define invariants (for example, "after step A succeeds, B or C must eventually execute"), then validate with randomized inputs.
- Mutation testing: Apply small mutations to Dance definitions (for example, wrong transition target) and verify tests can catch them.
- Golden trace regression: Real executions approved by humans are stored as Golden Trace and must pass after each modification.
Test suites are versioned and scored as part of Beekeeping review.
The traditional "exit when all steps are done" model does not fit asynchronous long workflows (for example, WebSocket connections or UI list items). We introduce:
- Natural completion: A Dance instance ends normally when the final step has no
onSuccesstarget. - Explicit termination: Built-in system Honey
__Terminate__. Any Dance step can usetriggeredBy: "__Terminate__"to handle termination, run cleanup, and finish naturally. Parent Dances can send__Terminate__to child instances via QueenBee. - Timeout termination: Top-level Dance can define
timeout; after timeout, Hive auto-injects__Terminate__. - Cascading termination: When a parent Dance ends, all child instances created by it are terminated by default (disable with
cascadeTermination: false).
Dance steps support foreach-style dynamic instantiation:
{
"id": "spawn-items",
"alias": "item-dance",
"multiplicity": {
"source": "$.items",
"instanceIdTemplate": "item-${item.id}",
"inputTemplate": {
"type": "ItemInitHoney",
"payload": { "id": "${item.id}" }
}
}
}{
"name": "ListRootDance.test",
"forDance": "ListRootDance",
"scenarios": [
{
"description": "Start from empty list; receiving 3 new items should create 3 child instances",
"inputSequence": [
{ "type": "ListDataHoney", "payload": { "items": [] }, "delayMs": 0 },
{ "type": "ListDataHoney", "payload": { "items": ["A", "B", "C"] }, "delayMs": 100 }
],
"mockBeeResponses": {
"diff": {
"onSuccess": {
"resultHoney": {
"type": "DiffResultHoney",
"payload": { "added": ["A", "B", "C"], "removed": [] }
}
}
}
},
"expectedTrace": {
"stepIds": ["compute-diff", "spawn-items", "wait-updates"],
"subDanceInstanceCreations": [
{
"danceName": "ListItemDance",
"instanceId": "item-A",
"input": { "type": "ItemInitHoney", "payload": { "id": "A" } }
},
{ "danceName": "ListItemDance", "instanceId": "item-B" },
{ "danceName": "ListItemDance", "instanceId": "item-C" }
]
}
}
]
}A temporal filter for experience
It answers:
- What have we done before?
- Which attempts succeeded?
- Which attempts failed?
- Which historical fragments should this task learn from?
Essentially:
A structural reasoning network
It answers:
- Dependency relationships between Bee and Skill
- Compatibility between Honey schemas
- Which components can be reused
- Which paths are common combinations
- Memory palace retrieves similar historical tasks and provides:
- Which Skills were used
- Which succeeded or failed
- Common pitfalls
Example:
Current goal: build a card battle system
Memory returns:
- skill-game-logic-v2 (successful)
- skill-battle-engine-v1 had state inconsistency issues
- Knowledge graph retrieves Skill dependency relationships
- Recommends combinations
Example:
graph query:
skill: battle-system
returns:
- required: state-manager
- recommended: event-logger
- incompatible: legacy-action-handler
Avoid blindly redesigning Skill combinations every time
- Memory palace provides historical implementations of similar Bees
- Includes bug cases
Example:
Similar Bee: ModifyAttack
Historical issues:
- forgot to handle negative numbers
- incomplete rollback
- Knowledge graph provides dependent Bees
- Provides schema compatibility relationships
Example:
Bee: ModifyAttack
Dependencies:
- PlayerStateBee
- StatValidationBee
Reduce repeated mistakes and improve reuse
- Memory palace retrieves similar workflows
- Provides execution-path experience
Example:
Similar flow:
- validate -> execute -> commit
- do not write DB before computing logic (historical bug)
- Knowledge graph performs DAG validation
- Checks dependency order
Example:
Bee B must run after Bee A
Honey X is incompatible with Honey Y
Prevent workflow structural errors
Wrong:
store full chat history
Right:
{
"goal": "...",
"skill_used": [...],
"bee_used": [...],
"result": "success | fail",
"failure_reason": "...",
"metrics": {
"time": 1200,
"retry": 2
}
}Memory palace is an experience database, not a chat archive.
Storing only successful cases is a mistake.
Must store:
Failure types:
- schema mismatch
- timeout
- infinite loop
- bad test
- wrong decomposition
Failure is often the highest-value guidance.
Do not rely only on:
embedding similarity
Add:
Score =
semantic similarity
+ skill overlap
+ bee overlap
+ similar error type
+ recency
In early decisions, retrieval should primarily use goal-level semantic matching (lightweight embedding). During execution, inject detailed historical fragments to reduce retrieval noise.
The biggest memory-palace pitfall:
Too many returned items = noise.
Recommended: 3-5, never more than 7.
Skill
Bee
Honey Schema
Dance
Error Type
Test Case
Skill -> uses -> Bee
Bee -> produces -> Honey
Bee -> depends_on -> Bee
Dance -> contains -> Bee
Bee -> failed_with -> Error
Skill -> improved_from -> Skill
Not display, but:
generation constraints
Example:
When generating Bee:
must satisfy schema compatibility in graph
When generating Dance:
must satisfy DAG acyclicity
Memory palace provides candidates.
Knowledge graph filters and constrains.
Example:
Memory palace recommends Bee A, B, C
Knowledge graph finds:
- B conflicts with current system
- A is too old
Final choice: C
- User inputs a business goal (natural language)
- System decomposes and clarifies the goal
- AI creates/selects Skills
- Invoke Skills to generate Bee / Honey / Dance
- Hive executes the workflow and outputs intermediate results
- Human performs Beekeeping (review and correction)
- Deliver final output and persist both graph and memory palace
This project aims to help users with limited software background build usable applications, not to maximize execution performance.
Best suited for:
- Prototype demos
- Concept shaping and product-direction exploration
- Personal application development
- Indie game development
Explicitly out of scope:
- Extreme high-performance computing
- Production-grade hard real-time control systems (LAN demo-level real-time is acceptable)
- Financial core clearing/settlement systems
- Low-level drivers and kernel-level infrastructure
- Enterprise systems requiring very high compliance and availability guarantees
To avoid sinking into low-level complexity too early, Swarm adopts a Skill-First MVP path.
Core principle:
First validate whether Swarm can generate "methods of doing work", then validate whether Swarm can generate "runnable systems."
Goal: build a Skill that can decompose a "text chatroom project" and produce decomposed Dance.
Example input:
I want to build a peer-to-peer text chatroom
Output:
Project Breakdown Dance
Validation points:
- Can the Skill decompose goals stably?
- Can it identify Bee / Honey / Dance / Hive requirements?
- Is the generated Dance detailed, readable, and auditable?
- Can Dance serve as a downstream development blueprint?
- One Dance should map to one business rule or one user action
- All Dances together should cover 100% of business scenarios
- No omissions, no cycles, no ambiguity
Goal: based on MVP 0 Dance, manually implement Bee, Honey, Dance, Hive to verify the architecture can run end-to-end.
Note: manually written Bee/Honey/Dance in this phase are only for prototype validation. They must not enter BeeHub and must not be used as training exemplars for later Skills. They only prove architecture feasibility and do not join production evolution loops.
Typical Bees:
CreateRoomBee
JoinRoomBee
ValidateMessageBee
SendMessageBee
BroadcastMessageBee
LogMessageBee
Typical Honey:
UserHoney
RoomHoney
MessageHoney
ChatEventHoney
ExecutionReportHoney
Typical Dance:
CreateRoomDance
JoinRoomDance
SendMessageDance
BroadcastMessageDance
ChatAuditDance
Hive must validate:
- Bee registration and scheduling
- Honey schema validation
- Dance execution engine
- WebSocket communication
- Execution logs and audit records
- Multiple Honey routings to the same active Bee instance (for example, waiting until all room users are ready)
Validation points:
- Is the Bee interface reasonable?
- Is the Honey data contract stable?
- Can Dance drive complete workflows?
- Can Hive schedule, log, and replay?
- Can WebSocket serve as Honey transport channel?
- Frontend-local Hive and backend Hive collaboration (message Bees local, while broadcasts require backend forwarding)
This phase first proves the architecture can run, then proves AI can generate architecture components.
Goal: use MVP 1 handwritten Bee/Honey/Dance as one-shot exemplars (not committed into formal repository) to build generation Skills.
Suggested split into three Skills:
skill-generate-honey-schema
skill-generate-bee
skill-generate-dance
Inputs:
Goal
Project Breakdown Dance
Existing Bee / Honey / Dance Samples (reference only, not fixed)
Coding Standard
Testing Standard
Outputs:
Generated Honey Schema
Generated Bee Class
Generated Dance Definition
Generated Test Suite
Validation points:
- Can Skills learn patterns from reference exemplars?
- Can they stably generate Bee implementations that satisfy interface specs?
- Can they generate strongly typed Honey schemas?
- Can they generate executable Dance definitions?
- Can they include tests and audit notes?
Goal: use MVP 2 generation Skills to automatically generate a 1v1 peer-to-peer voice chatroom.
Additional typical Bees:
GetUserMediaBee
CreatePeerConnectionBee
CreateOfferBee
CreateAnswerBee
ExchangeIceCandidateBee
AttachAudioStreamBee
Additional typical Honey:
MediaDeviceHoney
PeerConnectionHoney
OfferHoney
AnswerHoney
IceCandidateHoney
AudioStreamHoney
Additional typical Dance:
RequestAudioPermissionDance
CreatePeerConnectionDance
SignalingDance
AttachRemoteAudioDance
EndCallDance
Validation points:
- Can Skills transfer from text chatroom to voice chatroom?
- Do System Bees support optional sandboxing and permission constraints?
- Is asynchronous waiting reliable (for example, ICE candidate aggregation)?
- Can Dance express WebRTC signaling workflows?
- Can Hive record key execution events?
Goal: run a multi-user voice chatroom and demonstrate Swarm capability in complex collaboration scenarios.
Additional typical Bees:
CreateVoiceRoomBee
JoinVoiceRoomBee
PeerConnectionManagerBee
MuteBee
LeaveRoomBee
ReconnectBee
RoomStateSyncBee
Additional typical Honey:
VoiceRoomHoney
ParticipantHoney
PeerMeshHoney
MuteStateHoney
ConnectionStateHoney
RoomEventHoney
Additional typical Dance:
CreateVoiceRoomDance
JoinVoiceRoomDance
PeerMeshSetupDance
MuteParticipantDance
LeaveRoomDance
ReconnectDance
RoomStateSyncDance
Validation points:
- Is multi-Bee collaboration stable (including one instance waiting for many inputs)?
- Is multi-Honey state synchronization clear?
- Does Dance support nesting and complex workflows?
- Can Hive handle multi-task scheduling?
- Are failure recovery and reconnection auditable?
MVP 0: Validate "Can Swarm decompose goals"
MVP 1: Validate "Can Swarm architecture run manually" (handwritten artifacts isolated)
MVP 2: Validate "Can Swarm generate Bee / Honey / Dance"
MVP 3: Validate "Can Swarm control real system capabilities"
MVP 4: Validate "Can Swarm handle complex collaborative systems"
- MemPalace: https://github.com/MemPalace/mempalace
- graphify: https://github.com/safishamsi/graphify
- gbrain (reference): https://github.com/garrytan/gbrain
- gstack (reference): https://github.com/garrytan/gstack
MIT