claude-code-swarm 0.3.6 → 0.3.8

package/references/swarmkit/docs/package-setup-reference.md

@@ -1,519 +0,0 @@
-# Package Setup Reference
-
-How each swarmkit package is installed, initialized, and configured — and where they depend on each other. This document serves as the reference for building `swarmkit init` delegation.
-
----
-
-## Summary Table
-
-| Package | Has Init? | Config Dir | Config Format | Needs API Keys? | Needs Embedding? | Swarmkit Deps |
-|---------|-----------|------------|---------------|-----------------|-------------------|---------------|
-| macro-agent | No (config-driven) | `.multiagent/` | JSON + YAML | No | No | opentasks, MAP SDK |
-| opentasks | `opentasks init` | `.opentasks/` | JSON + JSONL | No | No | None |
-| minimem | `minimem init` | `.minimem/` | JSON | Yes (embedding) | Yes | None |
-| agent-iam | `agent-iam config init` | `~/.agent-credentials/` | JSON | No | No | None |
-| cognitive-core | `cognitive-core init` | `.cognitive-core/` | Programmatic | Yes (embedding) | Yes | None (minimem optional) |
-| skill-tree | `skill-tree config init` | `~/.skill-tree/` | YAML | No | No | cognitive-core |
-| openswarm | No (in-app setup) | `~/.openswarm/` | JSON | No | No | macro-agent, MAP SDK |
-| openhive | `openhive init` (wizard) | `~/.openhive/` | JS/JSON | No | No | openswarm |
-| self-driving-repo | `sdr init` (wizard) | `.self-driving/` | YAML | Yes (Anthropic) | No | None |
-| MAP | No (library) | None | Code-based | No | No | agent-iam (optional) |
-
----
-
-## Per-Package Details
-
-### macro-agent
-
-**Installation:** `npm install -g macro-agent`
-
-**CLI binaries:** `multiagent` (full server), `multiagent-cli` (management)
-
-**Init procedure:** No init command. Configuration-driven bootstrap via config files.
-
-**Config files:**
-- `.multiagent/config.json` — project-level config
-- `~/.multiagent/config.json` — global fallback (lowest priority)
-- `.multiagent/teams/<name>/team.yaml` — team manifests with roles/ and prompts/ subdirs
-
-**Config priority:** env vars > project config > global config
-
-**Key config shape:**
-```json
-{
-  "team": "self-driving",
-  "port": 3001,
-  "host": "localhost",
-  "auth": { "disabled": false, "secret": "..." },
-  "task": {
-    "backend": "opentasks",
-    "opentasks": {
-      "socket_path": "/path/to/socket",
-      "auto_start": true
-    }
-  }
-}
-```
-
-**Key env vars:**
-- `MACRO_TASK_BACKEND` — `memory` or `opentasks` (default: `opentasks`)
-- `OPENTASKS_SOCKET_PATH` — opentasks daemon socket
-- `MACRO_SERVER_SECRET` — auth token
-
-**Dependencies on other packages:**
-- **opentasks** — optional task backend (falls back to in-memory)
-- **@multi-agent-protocol/sdk** — MAP protocol support
-- **openteams** — team YAML parsing
-
-**Integration discovery:**
-- opentasks: via `OPENTASKS_SOCKET_PATH` env var or auto-started daemon
-- No auto-detection of other swarmkit packages
-
-**What swarmkit init could do:**
-1. Create `.multiagent/config.json` with task backend set to `opentasks` if installed
-2. Scaffold a default team template in `.multiagent/teams/default/`
-3. Set `OPENTASKS_SOCKET_PATH` if opentasks is installed
-
----
-
-### opentasks
-
-**Installation:** `npm install -g opentasks`
-
-**CLI binary:** `opentasks`
-
-**Init procedure:** `opentasks init [--name <name>] [--global]`
-
-**What init does:**
-1. Creates `.opentasks/` directory
-2. Generates deterministic location hash from git remote + path
-3. Writes `config.json` with location identity
-4. Creates empty `graph.jsonl` (append-only source of truth)
-5. Creates `.gitignore` (excludes cache.db, daemon.sock, etc.)
-
-**Config files:**
-- `.opentasks/config.json` — location identity + provider config
-- `.opentasks/graph.jsonl` — task graph (git-tracked)
-- `.opentasks/cache.db` — SQLite query cache (gitignored, rebuilt)
-- `~/.opentasks/` — global store
-
-**Config shape:**
-```json
-{
-  "version": "1.0",
-  "location": { "hash": "a1b2c3d4", "uuid": "...", "name": "my-project" },
-  "connections": [],
-  "providers": {
-    "beads": { "enabled": true },
-    "claudeTasks": { "enabled": true }
-  }
-}
-```
-
-**Key env vars:**
-- `OPENTASKS_STORAGE_JSONL_PATH`, `OPENTASKS_STORAGE_SQLITE_PATH`
-- `OPENTASKS_DAEMON_SOCKET_PATH`, `OPENTASKS_DAEMON_AUTO_START`
-- Various `OPENTASKS_PROVIDERS_*` vars
-
-**Dependencies:** None on other swarmkit packages.
-
-**What swarmkit init could do:**
-1. Run `opentasks init --name <project-name>` in project dir
-2. Run `opentasks init --global` for global store if not exists
-3. Connect project store to global store via `opentasks connect`
-
----
-
-### minimem
-
-**Installation:** `npm install -g minimem`
-
-**CLI binary:** `minimem`
-
-**Requirement:** Node 22+ (uses native `node:sqlite`)
-
-**Init procedure:** `minimem init [dir] [--global] [--force]`
-
-**What init does:**
-1. Creates root directory + `memory/` subdirectory + `.minimem/` subdirectory
-2. Creates `MEMORY.md` template file
-3. Creates `.minimem/config.json` with defaults
-4. Creates `.minimem/.gitignore` (excludes index.db)
-
-**Config files:**
-- `.minimem/config.json` — embedding provider, search settings
-- `.minimem/index.db` — SQLite with vector embeddings (gitignored)
-- `MEMORY.md` — template memory file
-
-**Config shape:**
-```json
-{
-  "embedding": { "provider": "auto" },
-  "hybrid": { "enabled": true, "vectorWeight": 0.7, "textWeight": 0.3 },
-  "query": { "maxResults": 10, "minScore": 0.3 }
-}
-```
-
-**Config resolution order:** defaults → global config → XDG global → local config → CLI/env
-
-**Key env vars:**
-- `OPENAI_API_KEY` — OpenAI embeddings
-- `GOOGLE_API_KEY` / `GEMINI_API_KEY` — Gemini embeddings
-- `MEMORY_DIR` — default memory directory
-
-**Embedding provider auto-detection:** Tries OpenAI → Gemini → Local based on available API keys. Falls back to BM25-only.
-
-**Dependencies:** None on other swarmkit packages.
-
-**What swarmkit init could do:**
-1. Run `minimem init` (or `minimem init --global` for global memory)
-2. Set embedding provider in config based on swarmkit's global preference
-3. Pass embedding API key from swarmkit's stored keys
-
----
-
-### agent-iam
-
-**Installation:** `npm install -g agent-iam`
-
-**CLI binary:** `agent-iam`
-
-**Init procedure:** `agent-iam config init <provider>` (per-provider, no wizard)
-
-**Available provider inits:**
-```
-agent-iam config init github --app-id X --installation-id Y --private-key ./key.pem
-agent-iam config init google --client-id X --client-secret Y --refresh-token Z
-agent-iam config init aws --region us-east-1 --role-arn arn:...
-agent-iam config init slack --mode bot --token xoxb-...
-agent-iam apikey add --name openai --provider openai --key sk-...
-```
-
-**Config files:**
-- `~/.agent-credentials/config.json` — provider configs (0600 permissions)
-- `~/.agent-credentials/token_secret` — HMAC signing key (auto-generated)
-
-**Config shape:**
-```json
-{
-  "providers": {
-    "github": { "appId": "...", "installationId": "...", "privateKeyPath": "..." },
-    "apikeys": { "openai": { "providerName": "openai", "apiKey": "sk-..." } }
-  }
-}
-```
-
-**Key env vars:**
-- `AGENT_TOKEN` — serialized agent token for subprocess communication
-
-**Dependencies:** None on other swarmkit packages.
-
-**What swarmkit init could do:**
-1. Check if `~/.agent-credentials/` exists; if not, ensure dir is created
-2. Offer to add API keys already stored in swarmkit as agent-iam API keys
-3. No project-level init needed (global only)
-
----
-
-### cognitive-core
-
-**Installation:** `npm install -g cognitive-core`
-
-**CLI binary:** `cognitive-core`
-
-**Init procedure:** `cognitive-core init [--dir <path>]`
-
-**What init does:**
-1. Creates `.cognitive-core/` directory
-2. Initializes memory system with subdirectories:
-   - `experiences/`, `playbooks/`, `meta-strategies/`, `meta-observations/`
-   - `team-experiences/`, `team-playbooks/`, `role-playbooks/`
-   - Optionally `memory/` with knowledge bank subdirs
-
-**Config:** No config file on disk — config is programmatic via `AtlasConfig` object (Zod-validated). CLI uses defaults.
-
-**Key env vars:**
-- `OPENAI_API_KEY` — if embedding provider is `openai`
-- `VOYAGE_API_KEY` — if embedding provider is `voyage`
-
-**minimem integration:**
-- Checks for `.minimem/` directory and `MEMORY.md` marker
-- If found: nests knowledge files under `memory/knowledge/` (minimem-compatible layout)
-- If not: uses built-in `TextSimilaritySearchProvider`
-- Dynamic import: `import('minimem')` — graceful fallback if not installed
-
-**Dependencies:**
-- **minimem** — optional (detected at runtime via dynamic import)
-- `agent-workspace`, `acp-factory` — runtime dependencies
-
-**What swarmkit init could do:**
-1. Run `cognitive-core init --dir .cognitive-core`
-2. If minimem is installed, ensure `.minimem/` exists first so cognitive-core detects it
-3. Pass embedding provider preference
-
----
-
-### skill-tree
-
-**Installation:** `npm install -g skill-tree`
-
-**CLI binary:** `skill-tree`
-
-**Init procedure:** `skill-tree config init` (creates default config)
-
-**Config files:**
-- `~/.skill-tree/config.yaml` — main config
-- `~/.skill-tree/skills.db` — SQLite database
-
-**Config shape (YAML):**
-```yaml
-storage:
-  type: sqlite
-  path: ~/.skill-tree/skills.db
-indexer:
-  github_token: ${GITHUB_TOKEN}
-  anthropic_key: ${ANTHROPIC_API_KEY}
-matching:
-  embedding_model: text-embedding-3-small
-  similarity_threshold: 0.8
-cli:
-  output_format: table
-  color: true
-```
-
-**Env var substitution:** Supports `${VAR}` syntax in YAML config.
-
-**Key env vars:**
-- `GITHUB_TOKEN` — for indexer/scraper
-- `ANTHROPIC_API_KEY` — for indexer
-- `SKILL_TREE_STORAGE_TYPE`, `SKILL_TREE_STORAGE_PATH`
-
-**cognitive-core integration:**
-- Uses dependency injection via `CognitiveCoreFactory` interface
-- Dynamic import: `await import('cognitive-core')`
-- Provides `CognitiveCoreProvider` as an optional learning provider
-- Falls back to `NaiveLearningProvider` (built-in heuristic)
-
-**Dependencies:**
-- **cognitive-core** — optional (via dynamic import + factory pattern)
-
-**Skill storage format (OpenSkills-compatible):**
-```
-skills/<skill-name>/
-├── SKILL.md           # YAML frontmatter + Markdown
-└── .skilltree.json    # Metadata and lineage
-```
-
-**What swarmkit init could do:**
-1. Run `skill-tree config init` if not already configured
-2. No project-level init needed (global only)
-
----
-
-### openswarm
-
-**Installation:** `npm install -g openswarm`
-
-**CLI binary:** `openswarm` (TUI launcher + server)
-
-**Init procedure:** No init command. TUI has in-app connection setup. Server configured via CLI args/env/config file.
-
-**Config files:**
-- `~/.openswarm/server.json` — server configuration
-- `~/.openswarm/adapters/` — custom adapter directory
-
-**Config priority:** CLI args > env vars > config file > defaults
-
-**Config shape:**
-```json
-{
-  "host": "localhost",
-  "port": 3000,
-  "adapter": { "id": "macro-agent" },
-  "auth": { "mode": "none" },
-  "storage": { "type": "memory" },
-  "logging": { "level": "info" }
-}
-```
-
-**Key env vars:** All prefixed `OPENSWARM_*`:
-- `OPENSWARM_HOST`, `OPENSWARM_PORT`, `OPENSWARM_PROTOCOL`
-- `OPENSWARM_ADAPTER` — adapter ID (default: `macro-agent`)
-- `OPENSWARM_AUTH_MODE` — `none`, `token`, `api-key`
-- `OPENSWARM_STORAGE_TYPE` — `memory`, `file`, `redis`
-- `OPENSWARM_BOOTSTRAP_TOKEN` — base64-encoded bootstrap token (for openhive spawning)
-
-**Dependencies:**
-- **macro-agent** — primary MAP server adapter (wildcard version `*`)
-- **@multi-agent-protocol/sdk** — MAP protocol client
-
-**What swarmkit init could do:**
-1. Create `~/.openswarm/server.json` with defaults
-2. Configure macro-agent adapter if macro-agent is installed
-3. No project-level init needed (global only)
-
----
-
-### openhive
-
-**Installation:** `npm install -g openhive`
-
-**CLI binary:** `openhive`
-
-**Init procedure:** `openhive init` — **full interactive wizard**
-
-**Wizard flow:**
-1. Data directory selection (default: `~/.openhive` or `./.openhive`)
-2. Instance name and port
-3. Registration mode: `open` | `invite` | `manual`
-4. Auth mode: `local` | `token`
-5. Admin key generation (32-char random)
-6. Confirmation and database initialization
-7. Optional auto-start
-
-**Config files:**
-- `{dataDir}/config.js` (or `.json`) — main config
-- `{dataDir}/data/openhive.db` — SQLite database
-- `{dataDir}/uploads/` — file uploads
-- `{dataDir}/.openhive-root` — marker file
-
-**Config discovery:** explicit `--config` > `./openhive.config.js` > `{dataDir}/config.js` > defaults
-
-**Key env vars:** All prefixed `OPENHIVE_*`:
-- `OPENHIVE_HOME` — data directory
-- `OPENHIVE_PORT`, `OPENHIVE_HOST`
-- `OPENHIVE_ADMIN_KEY`, `OPENHIVE_JWT_SECRET`
-- `OPENHIVE_INSTANCE_NAME`, `OPENHIVE_INSTANCE_URL`
-- `OPENHIVE_VERIFICATION` — registration strategy
-- `GITHUB_APP_*` — GitHub App integration vars
-
-**Dependencies:**
-- **openswarm** — for spawning multi-agent instances
-
-**What swarmkit init could do:**
-1. Run `openhive init` (delegates to its interactive wizard)
-2. Or run `openhive init --config-only` for just the config file
-3. Global only — not a project-level tool
-
----
-
-### self-driving-repo
-
-**Installation:** `npm install -g self-driving-repo`
-
-**CLI binaries:** `sdr`, `self-driving`
-
-**Init procedure:** `sdr init` — **interactive 5-phase wizard** or `sdr init -t <template>`
-
-**Templates:** `triage-only`, `full-pipeline`, `pr-review`, `empty`
-
-**Wizard phases:**
-1. Blueprint selection
-2. Entry node definition
-3. Downstream nodes (loop)
-4. Global settings + per-node flow control
-5. Review and write
-
-**Config files:**
-- `.self-driving/config.yml` — main DAG + agent config (YAML)
-- `.self-driving/config.lock.json` — compiled DAG snapshot (generated by `sdr compile`)
-- `.self-driving/prompts/*.md` — Handlebars prompt templates
-- `.github/workflows/sdr-*.yml` — generated GitHub Actions (by `sdr compile`)
-
-**Key env vars:**
-- `ANTHROPIC_API_KEY` — required for claude-code agents
-- `OPENAI_API_KEY` — for codex agents
-- `GEMINI_API_KEY` — for gemini agents
-- `SDR_LOG_LEVEL`, `SDR_LOG_FORMAT`
-
-**Dependencies:** None on other swarmkit packages.
-
-**What swarmkit init could do:**
-1. Run `sdr init` (delegates to its interactive wizard)
-2. Or `sdr init -t <template>` for non-interactive setup
-3. After init, remind to run `sdr compile` and push workflows
-
----
-
-### multi-agent-protocol (MAP)
-
-**Installation:** `npm install @multi-agent-protocol/sdk`
-
-**CLI binary:** None — library only
-
-**Init procedure:** None — programmatic setup only
-
-**Config files:** None created. Configuration is code-based.
-
-**Key exports:**
-- `MAPServer` — server convenience wrapper
-- `ClientConnection`, `AgentConnection`, `GatewayConnection` — connection types
-- `TestServer` — testing utility
-
-**Dependencies:**
-- **agent-iam** — optional, for credential brokering
-
-**What swarmkit init could do:** Nothing — MAP is a library consumed by other packages (macro-agent, openswarm). No user-facing setup.
-
----
-
-## Dependency Graph
-
-```
-openhive
-  └─→ openswarm
-       └─→ macro-agent
-            ├─→ opentasks (optional task backend)
-            └─→ MAP SDK
-                 └─→ agent-iam (optional auth)
-
-cognitive-core
-  └─→ minimem (optional, detected at runtime)
-
-skill-tree
-  └─→ cognitive-core (optional, via factory pattern)
-```
-
-## Init Order (when all packages installed)
-
-Based on dependencies, the correct initialization order is:
-
-1. **Global-only packages first (no project deps):**
-   - `agent-iam` — creates `~/.agent-credentials/`
-   - `skill-tree` — creates `~/.skill-tree/config.yaml`
-   - `openswarm` — creates `~/.openswarm/server.json`
-   - `openhive` — creates `~/.openhive/` (interactive wizard)
-
-2. **Project-level packages (order matters):**
-   1. `opentasks init` — creates `.opentasks/` (no deps)
-   2. `minimem init` — creates `.minimem/` (no deps, but needs embedding config)
-   3. `cognitive-core init` — creates `.cognitive-core/` (detects `.minimem/` if present)
-   4. `macro-agent` config — creates `.multiagent/config.json` (references opentasks socket)
-   5. `self-driving-repo init` — creates `.self-driving/` (independent, but usually a different project type)
-
-## Shared Configuration Needs
-
-**Embedding provider** — consumed by:
-- minimem (config: `embedding.provider`)
-- cognitive-core (programmatic: `AtlasConfig.embedding.provider`)
-- skill-tree (config: `matching.embedding_model`)
-
-**Anthropic API key** — consumed by:
-- self-driving-repo (env: `ANTHROPIC_API_KEY`)
-- Any package running Claude Code agents
-
-**Embedding API key** — consumed by:
-- minimem (env: `OPENAI_API_KEY` / `GEMINI_API_KEY`)
-- cognitive-core (env: same)
-- skill-tree indexer (env: `ANTHROPIC_API_KEY` for classification)
-
-## Delegation Strategy
-
-For each package, swarmkit can either:
-
-| Strategy | When to use | Packages |
-|----------|-------------|----------|
-| **Shell out to CLI** | Package has a working init command | opentasks, minimem, cognitive-core, skill-tree, openhive, self-driving-repo |
-| **Write config directly** | Package has no init but needs config files | macro-agent, openswarm |
-| **Skip** | Library with no user-facing setup | MAP |
-| **Global setup only** | No project-level config | agent-iam, skill-tree, openswarm, openhive |