claude-code-swarm 0.3.3 → 0.3.5

package/references/skill-tree/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "skill-tree",
+  "version": "0.1.5",
+  "description": "Library for managing agent skill versions and evolution - extract, iterate, and adapt skills from agent trajectories",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "skill-tree": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:legacy": "tsx test/run-all.ts",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch && git push && git push --tags",
+    "version:minor": "npm version minor && git push && git push --tags",
+    "version:major": "npm version major && git push && git push --tags"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "llm",
+    "versioning",
+    "extraction",
+    "trajectory",
+    "claude",
+    "skill-tree"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexngai/skill-tree.git"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.10",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.6.2",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "simple-git": "^3.30.0"
+  }
+}

package/references/skill-tree/plan.md

@@ -0,0 +1,78 @@
+# Materialization Gaps — Implementation Plan
+
+## Gap 1: `skill-tree materialize` CLI command
+**File:** `src/cli/commands/materialize.ts`
+
+Add a standalone CLI command for one-shot materialization:
+```
+skill-tree materialize [--paths .claude/skills,.agent/skills] [--agents-md ./AGENTS.md] [--format xml]
+```
+- Creates a temporary SkillBank, runs `Materializer.initialize()`, then shuts down
+- Useful for CI, scripting, and manual invocation outside the programmatic API
+
+## Gap 2: Config file integration
+**Files:** `src/config/types.ts`
+
+Add `materialization` section to `SkillTreeConfig` and `DEFAULT_CONFIG`:
+```yaml
+materialization:
+  enabled: false
+  symlink_paths: []
+  agents_md_path: ""
+  agents_md_format: xml
+  debounce_ms: 500
+```
+Add to `PartialSkillTreeConfig` as well.
+
+## Gap 3: CLI `createSkillBankFromOptions` reads materialization config
+**File:** `src/cli/utils/skillbank.ts`
+
+Update `createSkillBankFromOptions` to:
+- Load the global config (already loaded in cli/index.ts)
+- If `config.materialization.enabled`, pass `MaterializationConfig` to the SkillBank constructor
+- This makes all CLI commands (save, import, delete) trigger materialization automatically
+
+## Gap 4: AGENTS.md sync coordination
+**File:** `src/materialization/materializer.ts`
+
+The existing `sync` command writes full AGENTS.md. Materializer uses markers. These already don't conflict because:
+- Materializer writes within `<!-- SKILLTREE_START/END -->` markers
+- If no markers exist, it appends
+
+But we should add a check: if `sync` command is used, warn if materialization is also enabled for the same path. Add a note in the `materialize` command help text.
+
+## Gap 5: Copy mode (alternative to symlinks)
+**Files:** `src/types.ts`, `src/materialization/materializer.ts`
+
+Add `mode: 'symlink' | 'copy'` to `MaterializationConfig` (default: `'symlink'`).
+- `'symlink'`: current behavior
+- `'copy'`: copies the skill directory instead of symlinking. On changes, copies are refreshed. On delete, copies are removed.
+
+## Gap 6: File watcher mode
+**File:** `src/materialization/materializer.ts`
+
+Add `watch()` / `unwatch()` methods to Materializer:
+- Uses `fs.watch()` on `.skilltree/skills/` to detect file changes
+- On change, re-reads the skill from storage and updates symlinks/copies + AGENTS.md
+- Debounced to avoid rapid-fire events
+
+## Gap 7: Fuzzy `read` command
+**File:** `src/cli/commands/read.ts`
+
+Enhance `read` to fall back to search when exact ID match fails:
+- First try `getSkill(name)` (exact)
+- If not found, try `searchSkills(name)` and use first result
+- Print a note like `(matched: actual-skill-id)` so the agent knows what was resolved
+
+## File Summary
+
+| Action | File |
+|--------|------|
+| New    | `src/cli/commands/materialize.ts` |
+| Edit   | `src/config/types.ts` — add materialization section |
+| Edit   | `src/cli/utils/skillbank.ts` — read materialization config |
+| Edit   | `src/cli/index.ts` — register materialize command |
+| Edit   | `src/types.ts` — add `mode` field to MaterializationConfig |
+| Edit   | `src/materialization/materializer.ts` — copy mode + watcher |
+| Edit   | `src/cli/commands/read.ts` — fuzzy search fallback |
+| Edit   | `test/materialization.test.ts` — new tests for copy, watcher, fuzzy |

package/references/skill-tree/scraper/README.md

@@ -0,0 +1,123 @@
+# Skills Indexer
+
+AI-powered GitHub skills indexer with hierarchical taxonomy organization.
+
+## Overview
+
+The Skills Indexer discovers, scrapes, and indexes Agent Skills from GitHub repositories. It uses Claude AI to intelligently classify skills into a hierarchical taxonomy, enabling semantic search and discovery.
+
+## Features
+
+- **GitHub Scraping**: Discovers skills from awesome-lists and repositories
+- **AI Classification**: Uses Claude to categorize skills into a hierarchical tree
+- **Multi-path Placement**: Skills can belong to multiple taxonomy categories
+- **Relationship Detection**: Identifies dependencies, alternatives, and extensions
+- **Async Architecture**: Designed for scale with concurrent processing
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your GitHub token and Anthropic API key
+
+# Run database migrations
+npm run db:migrate
+
+# Scrape skills from default sources
+npx skillindexer scrape --discover
+
+# Index unclassified skills
+npx skillindexer index
+
+# Browse the taxonomy
+npx skillindexer tree
+```
+
+## Commands
+
+```bash
+# Scraping
+skillindexer scrape <repo-url>     # Scrape specific repository
+skillindexer scrape --discover     # Scrape from configured sources
+
+# Indexing
+skillindexer index                 # Index all unclassified skills
+skillindexer index --skill <id>    # Re-index specific skill
+
+# Browsing
+skillindexer tree                  # Show full taxonomy tree
+skillindexer tree <path>           # Show subtree (e.g., "Development/Python")
+skillindexer list                  # List all skills
+skillindexer show <skill-id>       # Show skill details
+
+# Search
+skillindexer search <query>        # Keyword search
+
+# Maintenance
+skillindexer stats                 # Show statistics
+skillindexer export --json         # Export database to JSON
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITHUB_TOKEN` | Yes | - | GitHub personal access token |
+| `ANTHROPIC_API_KEY` | Yes | - | Anthropic API key |
+| `SKILLINDEXER_DB_PATH` | No | `./data/skills.db` | SQLite database path |
+| `SKILLINDEXER_CACHE_DIR` | No | `./data/cache` | Cache directory |
+| `SKILLINDEXER_LOG_LEVEL` | No | `info` | Log level (debug/info/warn/error) |
+| `SKILLINDEXER_CLAUDE_MODEL` | No | `claude-sonnet-4-20250514` | Claude model to use |
+
+## Architecture
+
+See [docs/DESIGN.md](docs/DESIGN.md) for detailed architecture documentation.
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│    CLI      │───▶│   Scraper   │───▶│   Indexer   │
+└─────────────┘    └─────────────┘    └─────────────┘
+       │                 │                   │
+       └────────────────────────────────────┘
+                        │
+                        ▼
+               ┌─────────────────┐
+               │  Database       │
+               │  (SQLite/PG)    │
+               └─────────────────┘
+```
+
+## Default Sources
+
+Skills are scraped from:
+
+1. [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) - ~172+ curated skills
+2. [VoltAgent/awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills) - ~700+ community skills
+
+## Development
+
+```bash
+# Watch mode for development
+npm run dev
+
+# Run tests
+npm test
+
+# Type check
+npm run lint
+
+# Database management
+npm run db:generate  # Generate migrations
+npm run db:migrate   # Run migrations
+npm run db:studio    # Open Drizzle Studio
+```
+
+## License
+
+MIT