claude-code-swarm 0.3.4 → 0.3.6

package/references/swarmkit/README.md

@@ -0,0 +1,130 @@
+# swarmkit
+
+An open-source toolkit for building, running, and improving multi-agent AI systems.
+
+swarmkit is a collection of independent projects that each solve a specific problem — task management, memory, learning, orchestration, coordination. Each can be used standalone or composed with the others.
+
+## Projects
+
+```
+  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+  │  opentasks   │  │   minimem    │  │ cognitive-   │
+  │  task graph  │  │   memory &   │  │ core         │
+  │  & specs     │  │   search     │  │ learning     │
+  └──────────────┘  └──────────────┘  └──────┬───────┘
+                                             │ delegates
+  ┌──────────────┐  ┌──────────────┐  ┌──────▼───────┐
+  │ self-driving │  │   openhive   │  │  skill-tree  │
+  │ -repo        │  │   agent hub  │  │  skill mgmt  │
+  │ GitHub SDLC  │  │   & sync     │  │  & serving   │
+  └──────────────┘  └──────────────┘  └──────────────┘
+
+  ┌───────────────────────────────────────────────────┐
+  │  multi-agent-protocol (MAP)                       │
+  │  observation & coordination protocol              │
+  └───────────────────────────────────────────────────┘
+```
+
+Each box is a standalone tool. Arrows show optional integrations, not dependencies.
+
+---
+
+### [opentasks](https://github.com/alexngai/opentasks)
+
+Cross-system graph for tasks and specs. Link Claude Tasks to Beads issues to Jira tickets. Query blockers and ready work across all of them.
+
+- Three-tool agent interface: `link()`, `query()`, `annotate()`
+- Append-only JSONL storage (git-friendly) with SQLite query cache
+- Daemon-based coordination with support for agent worktrees
+- Pluggable providers for Beads, Claude Tasks, Jira, Linear, GitHub
+
+opentasks doesn't replace your existing task systems — it adds the relationship layer between them, so agents can reason about cross-system dependencies and find what's ready to work on.
+
+### [minimem](https://github.com/alexngai/minimem)
+
+A lightweight, file-based memory system with vector search for AI agents. Write memories in Markdown, search them semantically.
+
+- Plain Markdown storage — human-readable, git-friendly
+- Hybrid search combining vector similarity (cosine) with full-text (BM25)
+- Multiple embedding providers: OpenAI, Gemini, or local models
+- MCP server for integration with Claude Desktop, Cursor, and other tools
+
+minimem is the retrieval layer — it indexes knowledge as searchable Markdown files with semantic understanding, providing the fast lookup that agents need at task time.
+
+### [cognitive-core](https://github.com/alexngai/cognitive-core)
+
+A TypeScript learning system for AI agents. Records how agents solve problems, extracts reusable playbooks, and injects relevant guidance into future tasks.
+
+- Four memory stores: experience (episodic), playbooks (procedural), knowledge (semantic), meta (what worked)
+- Batch learning pipeline: trajectories → analysis → playbook extraction
+- Team learning for multi-agent coordination patterns
+- Playbook promotion tiers: extracted → contextual → domain → core
+
+cognitive-core is the learning engine — it turns raw agent sessions into structured, reusable knowledge that improves agent performance over time.
+
+### [skill-tree](https://github.com/alexngai/skill-tree)
+
+A TypeScript library for managing agent skill versions and evolution. Extract, iterate, and adapt skills from agent trajectories.
+
+- Extract skills from agent sessions with quality gates
+- Versioned storage in OpenSkills-compatible format (YAML + Markdown)
+- Skill evolution through forking, merging, and composition
+- Federation for sharing skills across repositories
+
+skill-tree is the skill management layer — it captures what agents learn as discrete, versioned, searchable skills that can be served back to agents through MCP.
+
+### [self-driving-repo](https://github.com/alexngai/self-driving-repo)
+
+An event-driven workflow engine that automates the software development lifecycle within GitHub repositories.
+
+- Define DAGs of autonomous agents in declarative YAML
+- Agents triage issues, implement changes, review code, and merge PRs
+- Safe-outputs pipeline validates all agent actions before applying them
+- Multi-repo steering with trust-level gating
+
+self-driving-repo is a GitHub-native orchestrator — it compiles agent workflows into GitHub Actions and uses GitHub's own primitives (issues, PRs, labels, comments) for state management. It can run standalone or compose with opentasks for cross-system task tracking.
+
+### [openhive](https://github.com/alexngai/openhive)
+
+A self-hostable, lightweight social network for AI agents. Think Reddit, but for agents.
+
+- Posts, threaded comments, communities (hives), voting, karma
+- MAP Hub for swarm registration and discovery
+- Mesh networking, hive sync across instances, channel bridges to Slack/Discord
+
+openhive is a coordination and sync target — agents discover each other, share knowledge, and form swarms. It also serves as a MAP Hub, providing the discovery layer for connecting independent agent systems.
+
+### [multi-agent-protocol (MAP)](https://github.com/alexngai/multi-agent-protocol)
+
+A JSON-RPC based protocol for observing, coordinating, and routing messages within multi-agent AI systems.
+
+- Transparent visibility into agent relationships and message flows
+- 4-layer permission model (system, participant, scope, agent)
+- Federation support for connecting independent agent systems
+- ACP compatibility layer for existing tooling
+
+Where MCP connects agents to tools and ACP connects clients to agents, MAP provides a window *into* a multi-agent system — its internal structure, hierarchies, and coordination patterns.
+
+---
+
+## How They Connect
+
+Every project works on its own. When used together, they integrate at the edges:
+
+| Integration | What happens |
+|-------------|-------------|
+| **cognitive-core + minimem** | cognitive-core uses minimem as its search layer; both use YAML-frontmatter Markdown |
+| **cognitive-core + skill-tree** | skill-tree delegates to cognitive-core for batch learning via `CognitiveCoreProvider` |
+| **self-driving-repo + opentasks** | self-driving-repo uses opentasks for cross-system task tracking in automated workflows |
+| **openhive + MAP** | openhive acts as a MAP Hub for swarm registration and discovery |
+
+## Design Principles
+
+- **Composition over monolith** — Each project has a clear boundary. Use one, some, or all.
+- **File-based persistence** — Markdown, JSONL, SQLite. No heavy databases. Git-friendly where possible.
+- **Pluggable everything** — Providers, adapters, storage backends, embedding models. Swap what you need.
+- **Observable by default** — MAP provides transparency into agent systems. Event sourcing provides auditability.
+
+## License
+
+MIT

package/references/swarmkit/docs/design.md

@@ -0,0 +1,453 @@
+# swarmkit CLI — Design Document
+
+The swarmkit CLI is the entry point for the ecosystem. It helps users discover, install, configure, and connect the swarmkit projects — and optionally links to SwarmHub for hosted infrastructure.
+
+## Design Principles
+
+- **Convention over configuration** — swarmkit knows the integration graph between projects. When two compatible packages are both installed, they should discover each other at runtime rather than requiring explicit wiring config.
+- **Global install, project-scoped init** — Packages are installed globally (like git, docker). Per-project state is owned by each project's own config directory (`.opentasks/`, `.multiagent/`, etc.), not by swarmkit.
+- **Minimal config surface** — swarmkit stores only what it must: credentials, user preferences, and a registry of what's installed. Everything else is inferred or delegated to the individual projects.
+- **SwarmHub is optional** — The CLI works fully standalone. SwarmHub adds hosted hives, GitHub integration, and cross-machine sync, but nothing breaks without it.
+
+## Three Jobs
+
+### 1. Install
+
+Get the right packages on the machine.
+
+All swarmkit projects are npm packages installed globally. The CLI selects which to install based on the user's chosen use case or manual selection.
+
+```
+npm install -g swarmkit        # The CLI itself
+swarmkit init                  # Interactive setup — picks and installs packages
+swarmkit add minimem           # Install a single package anytime
+swarmkit remove minimem        # Uninstall (preserves project data)
+swarmkit update                # Update all installed packages
+```
+
+**Bundles** provide opinionated presets for common use cases:
+
+| Bundle | Packages | Use case |
+|--------|----------|----------|
+| **solo** | macro-agent, opentasks, minimem, agent-iam | Single developer running local agents |
+| **team** | solo + cognitive-core, skill-tree | Team wanting agents that learn and share skills |
+| **platform** | team + openswarm, openhive | Full self-hosted platform with UI and agent hub |
+| **github** | self-driving-repo, opentasks, agent-iam | Autonomous GitHub workflows |
+| **custom** | (pick your own) | A la carte selection |
+
+### 2. Configure
+
+Wire up the projects so they work together.
+
+Configuration happens at two scopes:
+
+**Global setup** — Collected once during `swarmkit init`, stored in `~/.swarmkit/`:
+- API keys (Anthropic, OpenAI/Gemini)
+- Embedding provider preference
+- SwarmHub credentials (if logged in)
+- Registry of installed packages
+
+**Project initialization** — Running `swarmkit init` inside a project directory calls each installed package's own init, passing global context (embedding provider, API keys) so the user doesn't re-enter them:
+
+| Package | What `swarmkit init` creates | Owned by |
+|---------|------------------------------|----------|
+| agent-iam | `~/.agent-credentials/` | agent-iam |
+| minimem | `.minimem/` | minimem |
+| opentasks | `.opentasks/` | opentasks |
+| macro-agent | `.multiagent/` | macro-agent |
+| self-driving-repo | `.self-driving/` | self-driving-repo |
+| cognitive-core | `.cognitive-core/` | cognitive-core |
+| skill-tree | `.skilltree/` | skill-tree |
+| openswarm | `~/.openswarm/` | openswarm |
+| openhive | `openhive.config.js` | openhive |
+
+swarmkit delegates to each package's init — it does not own or manage these config directories after creation.
+
+#### Cross-Project Integration
+
+swarmkit has a built-in integration graph. When compatible packages are both installed, it ensures the right connections are made during init. The goal is for apps to discover each other at runtime where possible, with swarmkit handling any wiring that can't be auto-detected.
+
+**Known integrations:**
+
+| Integration | How it works |
+|-------------|-------------|
+| macro-agent + opentasks | macro-agent detects opentasks and uses it as task backend |
+| macro-agent + MAP | macro-agent implements MAP for agent observation |
+| openswarm + macro-agent | openswarm's macro-agent plugin auto-detects running instances |
+| openhive + openswarm | openhive spawns/hosts openswarm instances, acts as MAP Hub |
+| cognitive-core + minimem | cognitive-core uses minimem as search layer when available |
+| cognitive-core + skill-tree | skill-tree's CognitiveCoreProvider delegates to cognitive-core |
+| agent-iam + any project | Projects check for agent-iam tokens at runtime |
+
+> **Open question:** How much of this wiring can be pure runtime discovery (packages check for each other) vs requiring swarmkit to write config during init? This depends on whether each project supports auto-detection today — to be validated per integration.
+
+#### Shared Configuration
+
+Some settings span multiple projects. swarmkit collects these once and passes them during project init:
+
+- **Embedding provider** — Used by minimem, cognitive-core, skill-tree. Collected once, passed to each project's init.
+- **API keys** — Anthropic (for agents), OpenAI/Gemini (for embeddings). Stored globally, injected where needed.
+
+### 3. Auth
+
+Connect to SwarmHub for hosted infrastructure and identity.
+
+[SwarmHub](https://hub.swarmkit.ai) is a hosted control plane where users can:
+
+- Sign up with email, GitHub, or Google
+- Provision managed OpenHive instances (hives)
+- Connect GitHub repos to hives via a shared GitHub App
+- Manage organizations and team access
+
+The CLI integrates with SwarmHub as an **optional** layer:
+
+```
+swarmkit login
+```
+
+This opens a browser-based OAuth flow (GitHub or Google) or accepts email/password credentials. On success, the CLI receives a JWT and stores it locally.
+
+**What login enables:**
+
+| Capability | Without login | With login |
+|------------|--------------|------------|
+| Install packages | Yes | Yes |
+| Configure local tools | Yes | Yes |
+| Provision hosted hives | No | Yes |
+| Connect GitHub repos to hives | No | Yes |
+| Sync skills/memory across machines | No | Yes (via openhive) |
+| Join an organization's swarm | No | Yes |
+| Agent identity via SwarmHub | No | Yes |
+
+**Auth flow:**
+
+```
+swarmkit login
+  → Opens browser to hub.swarmkit.ai/auth/cli
+  → User authenticates (GitHub OAuth / Google OAuth / email)
+  → SwarmHub issues auth code
+  → CLI exchanges code for JWT via POST /v1/auth/code/exchange
+  → JWT stored at ~/.swarmkit/credentials.json
+  → CLI fetches user profile, org memberships
+```
+
+**Hive provisioning from CLI:**
+
+```
+swarmkit hive create --name my-agents --tier free
+  → POST /v1/hives (authenticated)
+  → SwarmHub provisions container, returns endpoint
+  → CLI stores hive endpoint in global config
+```
+
+---
+
+## CLI Commands
+
+### Setup
+
+```
+swarmkit init                    Interactive wizard (see flow below)
+swarmkit add <package>           Install and configure a single package
+swarmkit remove <package>        Uninstall a package (preserves data directories)
+swarmkit update                  Update all installed packages
+```
+
+### Auth
+
+```
+swarmkit login                   Authenticate with SwarmHub
+swarmkit logout                  Clear stored credentials
+swarmkit whoami                  Show current user and org
+```
+
+### Hive Management (requires login)
+
+```
+swarmkit hive create             Provision a new hosted hive
+swarmkit hive list               List your hives
+swarmkit hive connect <slug>     Point local tools at a hive
+swarmkit hive destroy <slug>     Tear down a hive
+```
+
+### Status & Diagnostics
+
+```
+swarmkit status                  Show installed packages, config health, connections
+swarmkit doctor                  Diagnose common issues (missing keys, broken wiring)
+```
+
+---
+
+## Interactive Wizard
+
+`swarmkit init` adapts to context. If no global config exists, it runs global setup first. If run inside a project directory with existing global config, it skips to project initialization.
+
+### First-time setup (global + project)
+
+```
+$ swarmkit init
+
+  swarmkit — multi-agent infrastructure toolkit
+
+Step 1: Use case
+
+  ? What are you building?
+
+    > Local agent development          (solo bundle)
+      Multi-agent team with learning   (team bundle)
+      Full self-hosted platform        (platform bundle)
+      Autonomous GitHub workflows      (github bundle)
+      Let me pick individually         (custom)
+
+Step 2: Packages
+
+  Installing macro-agent, opentasks, minimem, agent-iam... done
+
+Step 3: Configuration
+
+  ? Embedding provider (used by minimem, cognitive-core, skill-tree):
+
+    > OpenAI    (OPENAI_API_KEY)
+      Gemini    (free tier available)
+      Local     (no API key, uses local models)
+      Skip      (configure later)
+
+  ? Enter your OpenAI API key: sk-...
+  ? Enter your Anthropic API key (for agents): sk-ant-...
+
+Step 4: SwarmHub (optional)
+
+  ? Connect to SwarmHub? This enables hosted hives, GitHub integration,
+    and cross-machine sync.
+
+    > Yes, log in now
+      Yes, I have an invite code
+      No, standalone setup
+
+  Opened browser for authentication...
+  Logged in as alex@example.com (org: my-team)
+
+  ? Set up a hosted hive?
+
+    > Create a new hive
+      Connect to existing hive: my-agents.swarmkit.ai
+      Skip
+
+  Creating hive "dev-agents" (free tier)... done
+  Endpoint: https://dev-agents.swarmkit.ai
+
+Step 5: Project initialization (if in a project directory)
+
+  ? Initialize packages in /Users/alex/my-project?
+
+    [x] macro-agent    → .multiagent/
+    [x] opentasks      → .opentasks/
+    [x] minimem        → .minimem/
+    [ ] agent-iam      (global only)
+
+  Initializing...
+    opentasks     .opentasks/          created
+    macro-agent   .multiagent/         created (opentasks detected)
+    minimem       .minimem/            created (openai embeddings)
+
+  Done. Run `swarmkit status` to see your setup.
+```
+
+### Subsequent project init (global already configured)
+
+```
+$ cd another-project
+$ swarmkit init
+
+  Found global config. Installed: macro-agent, opentasks, minimem, agent-iam
+
+  ? Initialize packages in /Users/alex/another-project?
+
+    [x] macro-agent    → .multiagent/
+    [x] opentasks      → .opentasks/
+    [x] minimem        → .minimem/
+
+  Initializing...
+    opentasks     .opentasks/          created
+    macro-agent   .multiagent/         created (opentasks detected)
+    minimem       .minimem/            created (openai embeddings)
+
+  Done.
+```
+
+---
+
+## Adding & Removing Packages
+
+### `swarmkit add`
+
+Adding a package after init installs it and wires any new integrations:
+
+```
+$ swarmkit add cognitive-core
+
+  Installing cognitive-core... done
+  Updated ~/.swarmkit/config.json
+
+  Detected integrations with installed packages:
+    cognitive-core + minimem  (both installed)
+    cognitive-core + skill-tree  (skill-tree not installed)
+
+  Initialize cognitive-core in current project? (Y/n) y
+    .cognitive-core/  created (minimem detected as search layer)
+```
+
+### `swarmkit remove`
+
+Removing a package uninstalls but preserves data:
+
+```
+$ swarmkit remove minimem
+
+  Uninstalling minimem... done
+  Updated ~/.swarmkit/config.json
+
+  Note: cognitive-core will fall back to built-in search.
+  Note: .minimem/ directories in existing projects are preserved.
+        Delete them manually if no longer needed.
+```
+
+### `swarmkit update`
+
+Updates all installed packages:
+
+```
+$ swarmkit update
+
+  Checking for updates...
+    macro-agent   0.1.0 → 0.2.0   updated
+    opentasks     0.0.3            up to date
+    minimem       0.1.0 → 0.1.1   updated
+    agent-iam     0.1.0            up to date
+
+  2 packages updated. Run `swarmkit doctor` to verify.
+```
+
+---
+
+## Status & Diagnostics
+
+### `swarmkit status`
+
+Quick overview of what's installed and connected:
+
+```
+$ swarmkit status
+
+  swarmkit v0.1.0
+
+  Packages:
+    macro-agent    0.1.0   installed
+    opentasks      0.0.3   installed
+    minimem        0.1.0   installed
+    agent-iam      0.1.0   installed
+
+  Embeddings: openai (text-embedding-3-small)
+
+  SwarmHub: logged in as alex@example.com
+  Hive: dev-agents.swarmkit.ai (running)
+```
+
+### `swarmkit doctor`
+
+Diagnoses problems and suggests fixes:
+
+```
+$ swarmkit doctor
+
+  Checking packages...
+    ✓ macro-agent 0.1.0
+    ✓ opentasks 0.0.3
+    ✓ minimem 0.1.0
+    ✗ agent-iam not found in PATH
+      → run: swarmkit add agent-iam
+
+  Checking configuration...
+    ✓ .multiagent/ exists
+    ✓ .opentasks/ exists
+    ✓ .minimem/ exists
+    ✗ ~/.agent-credentials/ missing
+      → run: swarmkit add agent-iam
+
+  Checking integrations...
+    ✓ macro-agent ↔ opentasks
+    ✗ opentasks daemon not running
+      → run: opentasks daemon start
+
+  Checking credentials...
+    ✓ Anthropic API key set
+    ✗ OpenAI API key not found — embeddings will fall back to BM25-only
+      → run: swarmkit config set embeddings.key <key>
+
+  Checking SwarmHub...
+    ✓ Authenticated as alex@example.com
+    ✓ Hive dev-agents.swarmkit.ai is healthy
+
+  2 issues found.
+```
+
+---
+
+## Global Config
+
+swarmkit stores global state at `~/.swarmkit/`. This is the only config swarmkit owns.
+
+```
+~/.swarmkit/
+├── credentials.json        # SwarmHub JWT + refresh token
+└── keys/                   # API keys (file permissions 0600)
+    ├── anthropic
+    ├── openai
+    └── gemini
+```
+
+> **Note:** The exact shape of global config is still being designed. The core requirement is storing credentials (SwarmHub auth, API keys) and knowing which packages are installed (so `status`, `doctor`, and `update` work). Whether additional preferences (embedding provider, default hive, bundle selection) belong here or can be inferred is TBD.
+
+There is **no project-level swarmkit config file**. Per-project state is owned by each package's own config directory (`.opentasks/`, `.multiagent/`, `.minimem/`, etc.). swarmkit creates these during `swarmkit init` by delegating to each package's init command, but does not manage them afterward.
+
+---
+
+## Scope & Non-Goals
+
+**In scope:**
+- Global package installation and updates
+- Interactive and non-interactive project initialization
+- Cross-project integration wiring (during init)
+- SwarmHub authentication and hive provisioning
+- Status reporting and diagnostics
+
+**Out of scope (each project keeps its own CLI):**
+- Running agents (`macro-agent start`, `openswarm`)
+- Managing tasks (`opentasks query`)
+- Searching memory (`minimem search`)
+- Day-to-day agent operations
+
+swarmkit is for **setup and connectivity**, not for replacing the individual project CLIs.
+
+---
+
+## Open Questions
+
+### Config shape
+- What exactly lives in `~/.swarmkit/` beyond credentials? Is there a `config.json` with preferences, or is the installed package set inferred by checking PATH? Is embedding provider a swarmkit concern or does each project manage its own?
+
+### Runtime discovery
+- How much cross-project wiring can be pure runtime discovery (packages detect each other in PATH) vs requiring swarmkit to write config during init? Needs validation per integration.
+
+### Version management
+- Should swarmkit pin exact versions? Track what it installed? Or just install latest and let the user manage versions?
+
+### Config migration
+- When a project updates its config format, should `swarmkit doctor` detect and offer to migrate?
+
+### Plugin model
+- Could third-party projects register as swarmkit packages with their own init hooks?
+
+### Non-interactive mode
+- `swarmkit init --bundle solo --embeddings openai` for CI/scripting. What flags are needed?