claude-code-swarm 0.3.3 → 0.3.5

package/references/skill-tree/skills/skill-writer/references/patterns.md

@@ -0,0 +1,210 @@
+# Skill Implementation Patterns
+
+These patterns emerged from skills created by early adopters and Anthropic's internal teams. Choose the approach that fits the skill's workflow.
+
+## Choosing an Approach: Problem-First vs. Tool-First
+
+- **Problem-first**: "I need to set up a project workspace" - The skill orchestrates the right tool calls in the right sequence. Users describe outcomes; the skill handles the tools.
+- **Tool-first**: "I have Notion MCP connected" - The skill teaches Claude optimal workflows and best practices. Users have access; the skill provides expertise.
+
+Most skills lean one direction. Knowing which framing fits helps choose the right pattern.
+
+---
+
+## Pattern 1: Sequential Workflow Orchestration
+
+**Use when:** Multi-step processes must happen in a specific order.
+
+```markdown
+## Workflow: Onboard New Customer
+
+### Step 1: Create Account
+Call MCP tool: `create_customer`
+Parameters: name, email, company
+
+### Step 2: Setup Payment
+Call MCP tool: `setup_payment_method`
+Wait for: payment method verification
+
+### Step 3: Create Subscription
+Call MCP tool: `create_subscription`
+Parameters: plan_id, customer_id (from Step 1)
+
+### Step 4: Send Welcome Email
+Call MCP tool: `send_email`
+Template: welcome_email_template
+```
+
+**Key techniques:**
+- Explicit step ordering with numbered steps
+- Dependencies between steps clearly noted
+- Validation at each stage
+- Rollback instructions for failures
+
+---
+
+## Pattern 2: Multi-MCP Coordination
+
+**Use when:** Workflows span multiple services.
+
+```markdown
+### Phase 1: Design Export (Figma MCP)
+1. Export design assets from Figma
+2. Generate design specifications
+3. Create asset manifest
+
+### Phase 2: Asset Storage (Drive MCP)
+1. Create project folder in Drive
+2. Upload all assets
+3. Generate shareable links
+
+### Phase 3: Task Creation (Linear MCP)
+1. Create development tasks
+2. Attach asset links to tasks
+3. Assign to engineering team
+
+### Phase 4: Notification (Slack MCP)
+1. Post handoff summary to #engineering
+2. Include asset links and task references
+```
+
+**Key techniques:**
+- Clear phase separation with service labels
+- Data passing between MCPs (outputs from Phase 1 feed Phase 2)
+- Validation before moving to next phase
+- Centralized error handling
+
+---
+
+## Pattern 3: Iterative Refinement
+
+**Use when:** Output quality improves with iteration.
+
+```markdown
+## Iterative Report Creation
+
+### Initial Draft
+1. Fetch data via MCP
+2. Generate first draft report
+3. Save to temporary file
+
+### Quality Check
+1. Run validation script: `scripts/check_report.py`
+2. Identify issues:
+   - Missing sections
+   - Inconsistent formatting
+   - Data validation errors
+
+### Refinement Loop
+1. Address each identified issue
+2. Regenerate affected sections
+3. Re-validate
+4. Repeat until quality threshold met
+
+### Finalization
+1. Apply final formatting
+2. Generate summary
+3. Save final version
+```
+
+**Key techniques:**
+- Explicit quality criteria defining "done"
+- Validation scripts for deterministic checks
+- Clear stopping conditions to prevent infinite loops
+- Separation between draft and final stages
+
+---
+
+## Pattern 4: Context-Aware Tool Selection
+
+**Use when:** Same outcome can be achieved with different tools depending on context.
+
+```markdown
+## Smart File Storage
+
+### Decision Tree
+1. Check file type and size
+2. Determine best storage location:
+   - Large files (>10MB): Use cloud storage MCP
+   - Collaborative docs: Use Notion/Docs MCP
+   - Code files: Use GitHub MCP
+   - Temporary files: Use local storage
+
+### Execute Storage
+Based on decision:
+- Call appropriate MCP tool
+- Apply service-specific metadata
+- Generate access link
+
+### Provide Context to User
+Explain why that storage location was chosen
+```
+
+**Key techniques:**
+- Clear decision criteria with thresholds
+- Fallback options when primary choice unavailable
+- Transparency about choices made
+- Each branch has complete instructions
+
+---
+
+## Pattern 5: Domain-Specific Intelligence
+
+**Use when:** The skill adds specialized knowledge beyond tool access.
+
+```markdown
+## Payment Processing with Compliance
+
+### Before Processing (Compliance Check)
+1. Fetch transaction details via MCP
+2. Apply compliance rules:
+   - Check sanctions lists
+   - Verify jurisdiction allowances
+   - Assess risk level
+3. Document compliance decision
+
+### Processing
+IF compliance passed:
+- Call payment processing MCP tool
+- Apply appropriate fraud checks
+- Process transaction
+ELSE:
+- Flag for review
+- Create compliance case
+
+### Audit Trail
+- Log all compliance checks
+- Record processing decisions
+- Generate audit report
+```
+
+**Key techniques:**
+- Domain expertise embedded directly in logic
+- Compliance/validation before action (gate pattern)
+- Comprehensive audit documentation
+- Clear governance and conditional branching
+
+---
+
+## Anti-Patterns to Avoid
+
+### Vague Instructions
+```markdown
+# Bad
+Validate the data before proceeding.
+
+# Good
+Run `python scripts/validate.py --input {filename}` to check data format.
+If validation fails, common issues include:
+- Missing required fields (add them to the CSV)
+- Invalid date formats (use YYYY-MM-DD)
+```
+
+### Missing Error Handling
+Every skill should handle the most common failure modes. If a tool call can fail, include what to do when it does.
+
+### Overloaded SKILL.md
+If SKILL.md exceeds 5,000 words, move detailed content to `references/`. A bloated SKILL.md degrades response quality when loaded alongside other skills.
+
+### Assumed Exclusivity
+Never write instructions that assume the skill is the only one loaded. Other skills may be active simultaneously.

package/references/skill-tree/skills/skill-writer/references/quality-checklist.md

@@ -0,0 +1,123 @@
+# Skill Quality Checklist
+
+Use this checklist to validate a skill before and after deployment.
+
+---
+
+## Before Starting
+
+- [ ] Identified 2-3 concrete use cases with triggers, steps, and expected results
+- [ ] Determined skill category (Document/Asset Creation, Workflow Automation, MCP Enhancement)
+- [ ] Identified required tools (built-in capabilities or MCP servers)
+- [ ] Planned folder structure (references/, scripts/, assets/ as needed)
+- [ ] Reviewed example skills for inspiration
+
+## File Structure
+
+- [ ] Folder named in kebab-case (no spaces, underscores, or capitals)
+- [ ] `SKILL.md` file exists with exact spelling (case-sensitive)
+- [ ] No `README.md` inside the skill folder
+- [ ] Scripts are executable and tested independently
+- [ ] References are markdown, well-organized
+
+## YAML Frontmatter
+
+- [ ] Wrapped in `---` delimiters (both opening and closing)
+- [ ] `name` field: kebab-case, matches folder name
+- [ ] `name` does not use "claude" or "anthropic" prefix
+- [ ] `description` field present and under 1024 characters
+- [ ] Description includes WHAT the skill does
+- [ ] Description includes WHEN to use it (trigger phrases)
+- [ ] Description mentions relevant file types (if applicable)
+- [ ] No XML angle brackets (`<` or `>`) anywhere in frontmatter
+- [ ] No unclosed quotes in YAML values
+- [ ] Optional fields (license, compatibility, metadata) properly formatted
+
+## Instructions Body
+
+- [ ] Written in imperative/infinitive form (not second person)
+- [ ] Instructions are specific and actionable (not vague)
+- [ ] Exact commands, parameters, and expected outputs included
+- [ ] Critical instructions appear at the top
+- [ ] Uses headings, bullet points, and numbered lists for scanability
+- [ ] Error handling included for common failure modes
+- [ ] Examples provided for primary use cases
+- [ ] References to bundled files use correct relative paths
+- [ ] SKILL.md is under 5,000 words
+- [ ] Detailed documentation moved to `references/`
+
+## Triggering
+
+- [ ] Triggers on obvious task descriptions
+- [ ] Triggers on paraphrased requests
+- [ ] Triggers on domain-specific terminology
+- [ ] Does NOT trigger on unrelated topics
+- [ ] Does NOT conflict with other skills' trigger domains
+- [ ] Negative triggers included if overtriggering is a risk
+
+## Functional Quality
+
+- [ ] Primary use cases produce correct outputs
+- [ ] API/MCP calls succeed without errors
+- [ ] Error handling produces helpful guidance
+- [ ] Edge cases are addressed or documented
+- [ ] Consistent results across multiple runs of the same request
+- [ ] Works without user needing to redirect or clarify
+
+## Performance
+
+- [ ] Completes workflows in a reasonable number of tool calls
+- [ ] No unnecessary back-and-forth with the user
+- [ ] Token usage is reasonable (compare with vs. without skill)
+- [ ] Response quality is not degraded by large context
+
+## Distribution (if sharing)
+
+- [ ] Skill folder compresses cleanly as .zip
+- [ ] Installation instructions are clear
+- [ ] Dependencies documented in `compatibility` field
+- [ ] License specified if open-source
+- [ ] Version tracked in `metadata.version`
+
+---
+
+## Common Issues and Fixes
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| Skill never triggers | Description too vague or missing trigger phrases | Add specific user phrases and keywords |
+| Skill triggers too often | Description too broad | Add negative triggers, narrow scope |
+| Claude ignores instructions | Instructions too verbose or buried | Move critical instructions to top, use headers |
+| Inconsistent results | Ambiguous language | Replace vague prose with specific commands |
+| Slow responses | SKILL.md too large | Move content to references/, stay under 5K words |
+| Upload fails | Naming or formatting error | Check SKILL.md spelling, YAML delimiters, kebab-case |
+
+## Debugging Trigger Issues
+
+Ask Claude: "When would you use the [skill-name] skill?"
+
+Claude will quote the description back. Compare against expected triggers and adjust the description accordingly.
+
+For skills that should NOT trigger on certain queries, add explicit exclusions:
+
+```yaml
+description: Advanced data analysis for CSV files. Use for
+  statistical modeling, regression, clustering. Do NOT use for
+  simple data exploration (use data-viz skill instead).
+```
+
+## Iteration Signals
+
+**Undertriggering** (skill doesn't load when it should):
+- Add more trigger phrases, synonyms, and technical terms
+- Include common misspellings or alternative phrasings
+
+**Overtriggering** (skill loads for irrelevant queries):
+- Add "Do NOT use for..." clauses
+- Narrow the domain with more specific language
+- Differentiate from adjacent skills explicitly
+
+**Execution failures** (skill loads but produces poor results):
+- Add validation gates before critical operations
+- Include rollback instructions
+- Bundle validation scripts for deterministic checks

package/references/skill-tree/test/run-all.ts

@@ -0,0 +1,106 @@
+/**
+ * Run all tests
+ */
+
+import { spawn } from "child_process";
+import * as path from "path";
+
+const testFiles = [
+  "semver.test.ts",
+  "adapters.test.ts",
+  "extraction.test.ts",
+  "storage.test.ts",
+  "lineage.test.ts",
+  "skill-bank.test.ts",
+  "matching.test.ts",
+  "batch.test.ts",
+  "composer.test.ts",
+  "merge.test.ts",
+  "hooks.test.ts",
+  "sqlite.test.ts",
+  "metrics.test.ts",
+  "agents.test.ts",
+  "validation.test.ts",
+    "import.test.ts",
+  "sqlite-indexer.test.ts",
+  // New integration tests
+  "config.test.ts",
+  "services-indexer.test.ts",
+  "services-sync.test.ts",
+  "skillbank-events.test.ts",
+  "integration.test.ts",
+  // Serving layer
+  "serving.test.ts",
+];
+
+async function runTest(
+  file: string,
+): Promise<{ file: string; passed: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const testPath = path.join(process.cwd(), "test", file);
+    const proc = spawn("npx", ["tsx", testPath], {
+      stdio: ["inherit", "pipe", "pipe"],
+      shell: true,
+    });
+
+    let output = "";
+
+    proc.stdout?.on("data", (data) => {
+      output += data.toString();
+      process.stdout.write(data);
+    });
+
+    proc.stderr?.on("data", (data) => {
+      output += data.toString();
+      process.stderr.write(data);
+    });
+
+    proc.on("close", (code) => {
+      resolve({
+        file,
+        passed: code === 0,
+        output,
+      });
+    });
+  });
+}
+
+async function main() {
+  console.log("=".repeat(60));
+  console.log("Running all tests");
+  console.log("=".repeat(60));
+
+  const results: { file: string; passed: boolean }[] = [];
+
+  for (const file of testFiles) {
+    console.log(`\n${"─".repeat(60)}`);
+    console.log(`Running: ${file}`);
+    console.log("─".repeat(60));
+
+    const result = await runTest(file);
+    results.push({ file: result.file, passed: result.passed });
+  }
+
+  // Summary
+  console.log("\n" + "=".repeat(60));
+  console.log("TEST SUMMARY");
+  console.log("=".repeat(60));
+
+  const passed = results.filter((r) => r.passed);
+  const failed = results.filter((r) => !r.passed);
+
+  for (const result of results) {
+    const status = result.passed ? "✓" : "✗";
+    console.log(`  ${status} ${result.file}`);
+  }
+
+  console.log("─".repeat(60));
+  console.log(`Total: ${results.length} test files`);
+  console.log(`Passed: ${passed.length}`);
+  console.log(`Failed: ${failed.length}`);
+  console.log("=".repeat(60));
+
+  process.exit(failed.length > 0 ? 1 : 0);
+}
+
+main();

package/references/skill-tree/test/utils.ts

@@ -0,0 +1,128 @@
+/**
+ * Test utilities and helpers
+ */
+
+// Simple test runner
+let passed = 0;
+let failed = 0;
+let currentSuite = '';
+
+export function suite(name: string) {
+  currentSuite = name;
+  console.log(`\n${name}`);
+}
+
+export function test(name: string, fn: () => void | Promise<void>) {
+  const run = async () => {
+    try {
+      await fn();
+      passed++;
+      console.log(`  ✓ ${name}`);
+    } catch (error) {
+      failed++;
+      console.log(`  ✗ ${name}`);
+      console.log(`    ${error instanceof Error ? error.message : error}`);
+    }
+  };
+  return run();
+}
+
+export function assertEqual<T>(actual: T, expected: T, message?: string) {
+  const actualStr = JSON.stringify(actual);
+  const expectedStr = JSON.stringify(expected);
+  if (actualStr !== expectedStr) {
+    throw new Error(message || `Expected ${expectedStr}, got ${actualStr}`);
+  }
+}
+
+export function assertDeepEqual<T>(actual: T, expected: T, message?: string) {
+  assertEqual(actual, expected, message);
+}
+
+export function assertTrue(condition: boolean, message?: string) {
+  if (!condition) {
+    throw new Error(message || 'Expected true, got false');
+  }
+}
+
+export function assertFalse(condition: boolean, message?: string) {
+  if (condition) {
+    throw new Error(message || 'Expected false, got true');
+  }
+}
+
+export function assertNull(value: unknown, message?: string) {
+  if (value !== null) {
+    throw new Error(message || `Expected null, got ${JSON.stringify(value)}`);
+  }
+}
+
+export function assertNotNull<T>(value: T | null | undefined, message?: string): asserts value is T {
+  if (value === null || value === undefined) {
+    throw new Error(message || 'Expected non-null value');
+  }
+}
+
+export function assertThrows(fn: () => void, message?: string) {
+  let threw = false;
+  try {
+    fn();
+  } catch {
+    threw = true;
+  }
+  if (!threw) {
+    throw new Error(message || 'Expected function to throw');
+  }
+}
+
+export async function assertThrowsAsync(fn: () => Promise<void>, message?: string) {
+  let threw = false;
+  try {
+    await fn();
+  } catch {
+    threw = true;
+  }
+  if (!threw) {
+    throw new Error(message || 'Expected async function to throw');
+  }
+}
+
+export function assertContains(str: string, substr: string, message?: string) {
+  if (!str.includes(substr)) {
+    throw new Error(message || `Expected "${str}" to contain "${substr}"`);
+  }
+}
+
+export function assertArrayLength<T>(arr: T[], length: number, message?: string) {
+  if (arr.length !== length) {
+    throw new Error(message || `Expected array length ${length}, got ${arr.length}`);
+  }
+}
+
+export function assertGreaterThan(actual: number, expected: number, message?: string) {
+  if (actual <= expected) {
+    throw new Error(message || `Expected ${actual} > ${expected}`);
+  }
+}
+
+export function assertLessThan(actual: number, expected: number, message?: string) {
+  if (actual >= expected) {
+    throw new Error(message || `Expected ${actual} < ${expected}`);
+  }
+}
+
+export function getResults() {
+  return { passed, failed };
+}
+
+export function printSummary() {
+  console.log(`\n${'='.repeat(40)}`);
+  console.log(`${passed} passed, ${failed} failed`);
+  console.log(`${'='.repeat(40)}\n`);
+  return failed;
+}
+
+export function resetCounters() {
+  passed = 0;
+  failed = 0;
+}

package/references/skill-tree/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    globals: true,
+    include: ["test/**/*.test.ts"],
+    exclude: ["**/node_modules/**", "**/references/**", "**/scraper/**", "test/all.test.ts"],
+    testTimeout: 60000,
+    hookTimeout: 30000,
+    reporters: ["verbose"],
+    passWithNoTests: false,
+    // Run tests sequentially to avoid state conflicts between test files
+    fileParallelism: false,
+  },
+});

package/references/swarmkit/src/commands/init/phases/configure.ts

@@ -1,5 +1,4 @@
 import { select, password } from "@inquirer/prompts";
-import chalk from "chalk";
 import { readConfig, writeConfig } from "../../../config/global.js";
 import { writeKey } from "../../../config/keys.js";
 import * as ui from "../../../utils/ui.js";
@@ -71,26 +70,5 @@ export async function configureKeys(state: WizardState): Promise<WizardState> {
     }
   }
 
-  // Always ask for Anthropic key (needed for agents)
-  console.log();
-  const hasAnthropicKey = !!process.env["ANTHROPIC_API_KEY"];
-  if (hasAnthropicKey) {
-    ui.info(
-      `Anthropic API key detected from environment ${chalk.dim("(ANTHROPIC_API_KEY)")}`,
-    );
-  } else {
-    const anthropicKey = await password({
-      message: "Anthropic API key (for running agents):",
-      mask: "*",
-    });
-    if (anthropicKey) {
-      updated.apiKeys["anthropic"] = anthropicKey;
-      writeKey("anthropic", anthropicKey);
-      ui.success("Anthropic API key stored");
-    } else {
-      ui.info("Skipped — you can set ANTHROPIC_API_KEY later.");
-    }
-  }
-
   return updated;
 }

package/references/swarmkit/src/commands/init/phases/global-setup.ts

@@ -11,16 +11,18 @@ import * as ui from "../../../utils/ui.js";
 import type { WizardState } from "../state.js";
 
 /** Global packages in setup order */
-const GLOBAL_SETUP_ORDER = ["skill-tree", "openhive"];
+const GLOBAL_SETUP_ORDER = ["skill-tree", "openhive", "claude-code-swarm"];
 
-export async function initGlobal(state: WizardState): Promise<void> {
+export async function initGlobal(state: WizardState, force = false): Promise<void> {
   const globalPackages = GLOBAL_SETUP_ORDER.filter((pkg) =>
     state.selectedPackages.includes(pkg),
   );
 
   if (globalPackages.length === 0) return;
 
-  const uninitialized = globalPackages.filter((pkg) => !isGlobalInit(pkg));
+  const uninitialized = force
+    ? globalPackages
+    : globalPackages.filter((pkg) => !isGlobalInit(pkg));
 
   if (uninitialized.length === 0) {
     ui.blank();

package/references/swarmkit/src/commands/init/wizard.ts

@@ -67,8 +67,8 @@ async function runFirstTimeSetup(opts?: WizardOptions): Promise<void> {
   // Step 3: Configure (embedding provider, API keys)
   state = await configureKeys(state);
 
-  // Step 4: Global package setup (skill-tree, openhive)
-  await initGlobal(state);
+  // Step 4: Global package setup (skill-tree, openhive, claude-code-swarm)
+  await initGlobal(state, opts?.forceGlobal);
 
   // Step 5: Project init (if in a project directory)
   await initProject(state);