cognitive-core 0.1.0 → 0.2.0

package/references/skill-tree/README.md

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

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