cognitive-core 0.2.1 → 0.2.3

package/references/skill-tree/README.md

@@ -1,372 +0,0 @@
-# skill-tree
-
-A TypeScript library for managing agent skill versions and evolution. Store, version, serve, sync, and federate reusable skills for AI agents.
-
-## Overview
-
-skill-tree helps you build and maintain a library of reusable skills for AI agents by:
-
-- **Storing skills** in a versioned, searchable format (OpenSkills-compatible)
-- **Evolving skills** through versioning, forking, and merging
-- **Serving skills** via dynamic loadouts with expand/collapse, profiles, and token budgeting
-- **Syncing skills** across agents with git-based multi-agent collaboration
-- **Federating skills** across repositories for cross-organization sharing
-
-Inspired by research on skill libraries ([arXiv:2512.17102](https://arxiv.org/abs/2512.17102)), [Claudeception](https://github.com/blader/Claudeception), and [OpenSkills](https://github.com/numman-ali/openskills).
-
-## Installation
-
-```bash
-npm install skill-tree
-```
-
-## Quick Start
-
-```typescript
-import { createSkillBank, type Skill } from 'skill-tree';
-
-// Create a skill bank with filesystem storage
-const bank = createSkillBank({
-  storage: { basePath: './skills' },
-});
-
-await bank.initialize();
-
-// Save a skill
-await bank.saveSkill({
-  id: 'typescript-esm-import-fix',
-  name: 'TypeScript ESM Import Fix',
-  version: '1.0.0',
-  description: 'Fix TypeScript ES module import errors',
-  problem: 'TypeScript with ES modules requires explicit .js extensions',
-  triggerConditions: [{ type: 'error', value: "Cannot find module './utils'" }],
-  solution: 'Add .js extension to all relative imports.',
-  verification: 'Run tsc --noEmit to verify no import errors',
-  examples: [],
-  author: 'me',
-  tags: ['typescript', 'esm'],
-  createdAt: new Date(),
-  updatedAt: new Date(),
-  status: 'active',
-  metrics: { usageCount: 0, successRate: 0, feedbackScores: [] },
-} as Skill);
-
-// Search for skills
-const skills = await bank.searchSkills('typescript');
-
-// Create a new version
-const updated = await bank.createVersion('typescript-esm-import-fix', {
-  solution: 'Add .js extension, or use "moduleResolution": "bundler".',
-}, { bumpType: 'minor' });
-
-await bank.shutdown();
-```
-
-## Core Concepts
-
-### Skills
-
-A skill represents a reusable piece of knowledge:
-
-```typescript
-interface Skill {
-  id: string;                    // Unique identifier
-  name: string;                  // Human-readable name
-  version: string;               // Semantic version
-  description: string;           // For search and matching
-  problem: string;               // What problem this solves
-  triggerConditions: TriggerCondition[];  // When to apply
-  solution: string;              // Step-by-step solution
-  verification: string;          // How to verify it worked
-  examples: SkillExample[];      // Usage examples
-  tags: string[];                // Categorization
-  status: SkillStatus;           // 'draft' | 'active' | 'deprecated' | 'experimental'
-  metrics: SkillMetrics;         // Usage tracking
-  // ... namespace, taxonomy, lineage
-}
-```
-
-### Storage
-
-Two backends:
-
-```typescript
-// Filesystem (JSON source of truth + SQLite cache)
-const bank = createSkillBank({
-  storage: { basePath: './skills' },
-});
-
-// Memory (for testing)
-const bank = createSkillBank({
-  storage: { type: 'memory' },
-});
-```
-
-Skills are stored in the OpenSkills format:
-
-```
-skills/
-├── my-skill/
-│   ├── SKILL.md           # Skill content (YAML + Markdown)
-│   └── .skilltree.json    # Metadata and lineage
-└── .versions/
-    └── my-skill/
-        ├── 1.0.0.json     # Version snapshots
-        └── 1.1.0.json
-```
-
-## Features
-
-### Versioning
-
-Semantic versioning with full lineage tracking:
-
-```typescript
-// Create new version
-const v2 = await bank.createVersion('my-skill', updates, {
-  bumpType: 'minor',
-  changelog: 'Added alternative solution',
-});
-
-// Get version history
-const history = await bank.getVersionHistory('my-skill');
-
-// Rollback to previous version
-const restored = await bank.rollbackSkill('my-skill', '1.0.0');
-
-// Compare versions
-const diff = await bank.compareVersions('my-skill', '1.0.0', '2.0.0');
-
-// Fork for a specialized use case
-const forked = await bank.forkSkill('my-skill', {
-  newId: 'my-skill-react',
-  newName: 'My Skill (React variant)',
-  reason: 'Specialized for React projects',
-});
-```
-
-### Serving Layer
-
-Dynamic skill loadouts for agent context windows:
-
-```typescript
-const { server } = await bank.createServingLayer({
-  maxExpanded: 5,
-});
-
-// Orchestrator sets loadout based on task
-await server.setLoadoutForTask('Fix authentication bug');
-
-// Or use a built-in profile
-await server.setLoadoutFromProfile('debugging');
-
-// Render skills into system prompt
-const prompt = server.renderSystemPrompt();
-
-// Agent-side API
-const view = server.agentListLoadout();
-const skill = server.agentExpandSkill('some-skill-id');
-server.agentCollapseSkill('some-skill-id');
-await server.agentRequestSkills(['another-skill']);
-```
-
-### Multi-Agent Sync
-
-Git-based skill synchronization:
-
-```typescript
-import { createDefaultSyncConfig } from 'skill-tree';
-
-const bank = createSkillBank({
-  storage: { basePath: './skills' },
-  sync: {
-    config: createDefaultSyncConfig({
-      repoUrl: 'git@github.com:org/skills.git',
-      agentId: 'agent-1',
-    }),
-    pullOnInit: true,
-  },
-});
-
-await bank.initialize(); // auto-pulls remote changes
-
-// Manual sync
-await bank.sync.push();
-await bank.sync.pull();
-const status = await bank.sync.status();
-
-await bank.shutdown(); // flushes pending sync
-```
-
-### Federation
-
-Connect independent skill repositories:
-
-```typescript
-// Add a remote
-await bank.federation.addRemote('team', {
-  url: 'git@github.com:org/team-skills.git',
-  access: 'read-write',
-});
-
-// Browse remote skills
-const remoteSkills = await bank.federation.browse('team');
-
-// Import a skill
-const result = await bank.federation.import('team', 'useful-pattern');
-
-// Share a skill
-await bank.federation.share('my-skill', 'team');
-
-// Check for upstream updates
-const updates = await bank.federation.checkUpstream();
-```
-
-### Events
-
-Subscribe to skill bank events:
-
-```typescript
-// Simple synchronous listeners
-const unsubscribe = bank.on((event) => {
-  switch (event.type) {
-    case 'skill:created':
-      console.log('New skill:', event.skill.name);
-      break;
-    case 'skill:updated':
-      console.log('Updated:', event.skill.name, 'from', event.previousVersion);
-      break;
-  }
-});
-
-// Advanced: async hooks with priority and filtering
-bank.getHookRegistry().register({
-  event: 'storage:after-save',
-  handler: async (context) => {
-    console.log('Skill saved to storage');
-  },
-  priority: 'normal',
-});
-```
-
-### AGENTS.md Integration
-
-Bidirectional sync between skill bank and AGENTS.md files:
-
-```typescript
-import { createAgentsSync } from 'skill-tree';
-
-const sync = createAgentsSync(bank.getStorage());
-const result = await sync.sync('./AGENTS.md', {
-  direction: 'bidirectional',
-});
-```
-
-### Namespace Support
-
-Multi-tier skill trees for team environments:
-
-```typescript
-const bank = createSkillBank({
-  storage: { basePath: './skills' },
-  namespace: {
-    agentId: 'agent-1',
-    team: 'frontend',
-    defaultScope: 'personal',
-    defaultVisibility: 'private',
-  },
-});
-
-// List skills by scope
-const personal = await bank.listSkills({ scope: 'personal', owner: 'agent-1' });
-const teamSkills = await bank.listSkills({ scope: 'team', team: 'frontend' });
-```
-
-## API Reference
-
-### SkillBank
-
-Main orchestrator class, created via `createSkillBank(config)`.
-
-| Method | Description |
-|--------|-------------|
-| `initialize()` | Initialize storage, federation, and sync |
-| `shutdown()` | Clean shutdown (flushes sync) |
-| `getSkill(id, version?)` | Get skill by ID |
-| `listSkills(filter?)` | List skills with optional filter |
-| `searchSkills(query)` | Full-text search |
-| `saveSkill(skill)` | Save or update a skill |
-| `deleteSkill(id, version?)` | Delete a skill |
-| `deprecateSkill(id)` | Mark skill as deprecated |
-| `createVersion(id, updates, options?)` | Create new version |
-| `forkSkill(id, options)` | Fork a skill |
-| `getVersionHistory(id)` | Get version history |
-| `getLineage(id)` | Get full lineage |
-| `rollbackSkill(id, version)` | Rollback to version |
-| `compareVersions(id, vA, vB)` | Diff two versions |
-| `on(handler)` | Subscribe to events (returns unsubscribe fn) |
-| `off(handler)` | Unsubscribe from events |
-| `getStats()` | Get skill bank statistics |
-| `exportAll()` | Export all skills |
-| `importSkills(skills)` | Bulk import skills |
-| `createServingLayer(config?)` | Create a SkillGraphServer |
-| `getStorage()` | Access underlying storage adapter |
-| `getHookRegistry()` | Access hook registry |
-| `sync` | SyncManager accessor (throws if not configured) |
-| `federation` | FederationManager accessor (requires basePath) |
-
-### Versioning Utilities
-
-```typescript
-import {
-  parseVersion,
-  compareVersions,
-  bumpVersion,
-  satisfiesRange,
-} from 'skill-tree';
-
-bumpVersion('1.2.3', 'minor');  // '1.3.0'
-satisfiesRange('1.5.0', '^1.2.0');  // true
-```
-
-## Skill Format
-
-Skills use YAML frontmatter + Markdown (OpenSkills-compatible):
-
-```markdown
----
-name: typescript-esm-import-fix
-description: |
-  Fix TypeScript ES module import errors by adding .js extension
-version: 1.0.0
-author: extracted
-status: active
-date: 2024-01-15
-tags:
-  - typescript
-  - esm
-  - imports
----
-
-## Problem
-
-TypeScript with ES modules requires explicit .js extensions in imports.
-
-## Trigger Conditions
-
-- **error**: `Cannot find module './utils'`
-- **pattern**: `import .* from '\./[^']+(?<!\.js)'`
-
-## Solution
-
-1. Add `.js` extension to relative imports
-2. Even for `.ts` files, use `.js` in the import path
-
-## Verification
-
-Run `tsc` and verify no module resolution errors.
-```
-
-## License
-
-MIT

package/references/skill-tree/docs/GAPS_v1.md

@@ -1,221 +0,0 @@
-# Integration Gaps Tracking - v1
-
-This document tracks the remaining work to complete the skill indexer integration as defined in [INTEGRATION_PLAN.md](./INTEGRATION_PLAN.md).
-
-## Status Overview
-
-| Phase | Status | Completion |
-|-------|--------|------------|
-| Phase 1: Import Pipeline | ✅ Complete | 100% |
-| Phase 2: CLI Unification | ✅ Complete | 100% |
-| Phase 3: Unified Storage | ✅ Complete | 100% |
-| Phase 4: Direct Integration | ✅ Complete | 100% |
-| Phase 5: Bidirectional Sync | ✅ Complete | 100% |
-
----
-
-## High Priority Items
-
-### 1. Unified Configuration System
-
-**Status**: ✅ Complete
-
-**Goal**: Single config file for both skill-tree and indexer settings.
-
-**Location**: `~/.skill-tree/config.yaml`
-
-**Tasks**:
-- [x] Create `src/config/` module
-- [x] Define `SkillTreeConfig` interface
-- [x] Implement config file loading with defaults
-- [x] Support environment variable substitution
-- [x] Integrate with CLI global options
-- [x] Integrate with IndexerService
-
-**Files Created**:
-- `src/config/types.ts` - Configuration type definitions
-- `src/config/loader.ts` - Config loading and merging logic
-- `src/config/index.ts` - Module exports
-- `src/cli/commands/config.ts` - CLI config command
-
-**Config Schema**:
-```yaml
-storage:
-  type: sqlite | filesystem | memory
-  path: ~/.skill-tree/skills.db
-
-indexer:
-  github_token: ${GITHUB_TOKEN}
-  anthropic_key: ${ANTHROPIC_API_KEY}
-  sources:
-    - https://github.com/VoltAgent/awesome-agent-skills
-  batch_size: 10
-  min_confidence: 0.7
-
-matching:
-  embedding_model: text-embedding-3-small
-  similarity_threshold: 0.8
-
-sync:
-  auto_check: false
-  check_interval_hours: 24
-  conflict_resolution: prompt
-
-cli:
-  output_format: table
-  color: true
-  quiet: false
-```
-
----
-
-### 2. IndexerService Direct Execution
-
-**Status**: ✅ Complete
-
-**Goal**: CLI commands execute directly instead of delegating to subprocess.
-
-**Tasks**:
-- [x] Update `IndexerService.initialize()` to properly load scraper modules
-- [x] Implement `scrape()` method with actual scraper integration
-- [x] Implement `classify()` method with actual indexer integration
-- [x] Implement `detectRelationships()` method
-- [x] Implement `getTaxonomyTree()` using storage adapter
-- [x] Implement `getStats()` method
-- [x] Update CLI commands to use IndexerService directly
-- [x] Add fallback to subprocess if modules unavailable
-
-**Files Modified**:
-- `src/services/indexer.ts` - Full IndexerService implementation
-- `src/cli/commands/indexer/scrape.ts` - Direct execution with fallback
-- `src/cli/commands/indexer/classify.ts` - Direct execution with fallback
-- `src/cli/commands/indexer/taxonomy.ts` - Direct execution with fallback
-- `src/cli/commands/indexer/relationships.ts` - Direct execution with fallback
-- `src/cli/commands/indexer/stats.ts` - Direct execution with fallback
-
----
-
-## Medium Priority Items
-
-### 3. Direct SkillBank Integration
-
-**Status**: ✅ Complete
-
-**Goal**: IndexerService writes directly to SkillBank, no export/import step.
-
-**Tasks**:
-- [x] Implement `IndexerService.scrapeAndIndex()` method
-- [x] Convert scraped skills on-the-fly using converter
-- [x] Store directly via SkillBank.addSkill()
-- [x] Auto-place in taxonomy after save
-- [x] Update `skill-tree index scrape` to use direct integration
-
-**Files Modified**:
-- `src/services/indexer.ts` - Added `scrapeAndIndex()` method
-- `src/skill-bank.ts` - Added `addSkill()` method with taxonomy placement
-- `src/cli/commands/indexer/scrape.ts` - Added `--import` flag for auto-import
-
-**Workflow After**:
-```bash
-# One command does everything
-skill-tree index scrape https://github.com/org/repo
-# Skills immediately available in skill-tree
-skill-tree list
-```
-
----
-
-### 4. SkillBank Event System
-
-**Status**: ✅ Complete
-
-**Goal**: Event-driven hooks for skill lifecycle.
-
-**Tasks**:
-- [x] Add EventEmitter to SkillBank (already existed via `on()`)
-- [x] Define event types: `skill:created`, `skill:updated`, `skill:deleted`
-- [x] Emit events from `addSkill()`, `updateSkill()`, `deleteSkill()`
-- [x] Hook relationship detection to `skill:created` for imported skills
-- [x] Add `on()` and `off()` methods to SkillBank API
-- [x] Add `onEvent()` for typed event subscriptions
-- [x] Add `getStorage()` for advanced integration
-
-**Files Modified**:
-- `src/skill-bank.ts` - Enhanced event system with `off()`, `onEvent()`, `getStorage()`
-
-**Event Interface**:
-```typescript
-interface SkillEvent {
-  type: 'skill:created' | 'skill:updated' | 'skill:deleted' | 'skill:deprecated';
-  skill: Skill;
-  timestamp: Date;
-  source?: 'manual' | 'imported' | 'extracted';
-}
-```
-
----
-
-## Lower Priority Items
-
-### 5. Bidirectional Sync
-
-**Status**: ✅ Complete
-
-**Goal**: Keep skills in sync with remote sources.
-
-**Tasks**:
-- [x] Create `src/services/sync.ts`
-- [x] Define `SkillSyncState` type
-- [x] Implement `checkForUpdates()` - compare ETags/versions
-- [x] Implement `pullRemoteChanges()` - fetch and merge
-- [x] Implement `detectConflicts()` - local vs remote changes
-- [x] Add `skill-tree index sync` command with options:
-  - [x] `--status` - show sync state
-  - [x] `--pull` - pull remote changes
-  - [x] `--dry-run` - preview changes
-
-**Files Created**:
-- `src/services/sync.ts` - Full SyncService implementation
-
-**Files Modified**:
-- `src/cli/commands/indexer/sync.ts` - Updated with sync status and pull commands
-
-**Note**: SQLite sync_state table not yet added to schema (sync states stored in memory for now). This can be added in a future iteration.
-
----
-
-## Open Questions (Decisions Made)
-
-| Question | Status | Decision |
-|----------|--------|----------|
-| Taxonomy ownership | ✅ Resolved | Preserve original, allow re-classification on demand |
-| Deduplication strategy | ✅ Resolved | Use `externalSource.url` as dedup key |
-| Version conflict resolution | ✅ Resolved | Default to manual, with `--resolve` flag for automation |
-| Namespace separation | ✅ Resolved | Use `source.type` field, no namespace prefix |
-
----
-
-## Success Criteria Checklist
-
-- [x] Single CLI (`skill-tree`) for all operations
-- [x] Single database with skills from all sources
-- [x] Taxonomy browsing works for all skills
-- [x] Relationships detected across indexed and extracted skills
-- [x] Clear provenance tracking (source: extracted vs indexed)
-- [x] Seamless workflow from discovery to usage
-
----
-
-## Change Log
-
-| Date | Change |
-|------|--------|
-| 2025-01-XX | Initial gap analysis created |
-| 2025-01-XX | Phases 1-3 implemented |
-| 2025-01-XX | Tests added (56 tests) |
-| 2025-02-01 | Unified configuration system implemented |
-| 2025-02-01 | IndexerService direct execution implemented |
-| 2025-02-01 | Direct SkillBank integration implemented |
-| 2025-02-01 | SkillBank event system enhanced |
-| 2025-02-01 | Bidirectional sync service implemented |
-| 2025-02-01 | All phases complete |