cognitive-core 0.2.1 → 0.2.3

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

@@ -1,210 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-/**
- * 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

@@ -1,128 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-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,
-  },
-});