cognitive-core 0.0.2 → 0.1.2

package/references/skill-tree/.sudocode/specs.jsonl

@@ -0,0 +1 @@
+{"id":"s-70no","uuid":"2070edd2-fb8a-42a2-af93-b8951ab8fa16","title":"Skill Graph Serving Layer","file_path":"specs/s-70no_skill_graph_serving_layer.md","content":"# Skill Graph Serving Layer\n\n## Overview\n\nAdd a serving layer to skill-tree that enables **dynamic skill loadouts** with **mid-session adjustability**. Skills can be selected based on task, project context, semantic matching, or explicit configuration. Both external orchestrators and agents can control the loadout.\n\n## Problem\n\nCurrently, serving skills to an agent requires either:\n1. Loading the entire skill library upfront (context explosion)\n2. Manually configuring which skills to include (inflexible)\n\nNeither approach supports dynamic, context-aware skill selection or mid-session adjustments.\n\n## Solution\n\nImplement a **loadout-based serving model** with two layers:\n\n1. **Loadout Layer**: Which skills are available to the agent\n2. **Expansion Layer**: Of available skills, which are showing full content vs summaries\n\nKey capabilities:\n- **Flexible selection**: Task-based, project-based, profile-based, semantic, dependency-graph\n- **Mid-session adjustable**: Loadouts can change during a session\n- **Dual control**: Both orchestrator (external) and agent (internal) can modify loadouts\n- **Progressive disclosure**: Skills start collapsed, expand on demand\n- **Context-aware**: Auto-suggest skills based on current task/errors\n\n## Reference: OpenSkills Patterns\n\nThis design adopts compatible patterns from [OpenSkills](https://github.com/numman-ali/openskills):\n\n- **SKILL.md format**: Skills stored as markdown with YAML frontmatter\n- **AGENTS.md XML format**: `<available_skills>` block for system prompt rendering\n- **Progressive disclosure**: Summaries visible, full content on demand\n- **CLI-style reads**: Explicit skill loading (we add MCP on top)\n\nKey difference: OpenSkills is stateless (no expansion tracking). We add stateful loadout management.\n\n## Core Types\n\n### LoadoutCriteria\n\nFlexible criteria for selecting skills into a loadout:\n\n```typescript\ninterface LoadoutCriteria {\n  // === Explicit Selection ===\n  include?: string[];              // Always include these skill IDs\n  exclude?: string[];              // Never include these\n  \n  // === Filter-Based ===\n  tags?: string[];                 // Match any of these tags\n  tagsAll?: string[];              // Must have ALL these tags\n  status?: SkillStatus[];          // Filter by status (default: ['active'])\n  minSuccessRate?: number;         // Quality threshold (0-1)\n  author?: string;                 // Filter by author\n  \n  // === Semantic/Context-Based ===\n  taskDescription?: string;        // Semantic match to task\n  problemContext?: string;         // Current problem being solved\n  errorContext?: string;           // Error message to match\n  keywords?: string[];             // Keyword triggers\n  \n  // === Project-Based ===\n  projectType?: string;            // \"python\", \"typescript\", \"rust\", etc.\n  filePatterns?: string[];         // Glob patterns of files in scope\n  frameworks?: string[];           // Detected frameworks\n  \n  // === Relationship-Based ===\n  rootSkills?: string[];           // Start here, traverse relationships\n  includeDependencies?: boolean;   // Follow 'depends_on' edges\n  includeRelated?: boolean;        // Include 'related' skills\n  depth?: number;                  // Max traversal depth (default: 2)\n  \n  // === Limits ===\n  maxSkills?: number;              // Cap on loadout size\n  maxTokens?: number;              // Context budget (estimated)\n  priorityOrder?: 'relevance' | 'usage' | 'successRate' | 'recent';\n  \n  // === Merge Behavior ===\n  mode?: 'replace' | 'merge' | 'subtract';  // How to apply to current state\n}\n```\n\n### LoadoutState\n\nCurrent state of what's loaded for an agent:\n\n```typescript\ntype SkillState = 'available' | 'expanded' | 'pending';\n\ninterface LoadoutState {\n  /** Skills available to the agent (summaries visible) */\n  available: Map<string, Skill>;\n  \n  /** Skills with full content expanded */\n  expanded: Set<string>;\n  \n  /** Skills requested by agent, pending orchestrator approval */\n  pending: Set<string>;\n  \n  /** How this loadout was created */\n  source: LoadoutSource;\n  \n  /** When the loadout was last modified */\n  updatedAt: Date;\n}\n\ninterface LoadoutSource {\n  type: 'criteria' | 'profile' | 'task' | 'project' | 'manual';\n  criteria?: LoadoutCriteria;\n  profileName?: string;\n  taskDescription?: string;\n  projectPath?: string;\n}\n```\n\n### Skill Extension\n\nExtend existing `Skill` interface in `src/types.ts`:\n\n```typescript\ninterface Skill {\n  // ... existing fields\n  \n  serving?: {\n    /** Short summary for collapsed view (defaults to description) */\n    summary?: string;\n    \n    /** Estimated token count for context budgeting */\n    tokenEstimate?: number;\n    \n    /** Auto-expand triggers */\n    autoExpand?: ExpandTrigger[];\n    \n    /** Group ID for batch expansion */\n    expansionGroup?: string;\n  };\n}\n\ninterface ExpandTrigger {\n  on: 'use' | 'mention' | 'error-match' | 'file-match' | 'explicit';\n  conditions?: {\n    keywords?: string[];\n    errorPatterns?: string[];\n    filePatterns?: string[];\n  };\n}\n```\n\n## Core Components\n\n### 1. LoadoutCompiler (`src/serving/loadout-compiler.ts`)\n\nCompiles skills from criteria using multiple selection strategies:\n\n```typescript\ninterface LoadoutCompilerConfig {\n  defaultMaxSkills?: number;       // Default: 15\n  defaultStatus?: SkillStatus[];   // Default: ['active']\n  semanticThreshold?: number;      // Default: 0.6\n}\n\nclass LoadoutCompiler {\n  constructor(\n    private skillBank: SkillBank,\n    private config?: LoadoutCompilerConfig\n  ) {}\n\n  /**\n   * Compile from flexible criteria (main entry point)\n   */\n  async compile(criteria: LoadoutCriteria): Promise<Skill[]> {\n    let candidates = await this.skillBank.listSkills({ \n      status: criteria.status ?? ['active'] \n    });\n    \n    // Apply filters in priority order\n    candidates = this.applyExplicitFilters(candidates, criteria);\n    candidates = this.applyTagFilters(candidates, criteria);\n    candidates = this.applyQualityFilters(candidates, criteria);\n    candidates = await this.applySemanticFilters(candidates, criteria);\n    candidates = await this.applyRelationshipFilters(candidates, criteria);\n    candidates = this.applyLimits(candidates, criteria);\n    \n    return candidates;\n  }\n\n  /**\n   * Compile for a specific task (semantic matching)\n   */\n  async compileForTask(taskDescription: string): Promise<Skill[]>;\n\n  /**\n   * Compile by analyzing a project directory\n   */\n  async compileForProject(projectPath: string): Promise<Skill[]>;\n\n  /**\n   * Compile from a named profile\n   */\n  async compileFromProfile(profileName: string): Promise<Skill[]>;\n\n  /**\n   * Detect project context from files\n   */\n  async detectProjectContext(projectPath: string): Promise<ProjectContext>;\n}\n\ninterface ProjectContext {\n  type: string;              // \"typescript\", \"python\", etc.\n  frameworks: string[];      // [\"react\", \"express\", ...]\n  patterns: string[];        // File patterns found\n  packageManager?: string;   // \"npm\", \"pip\", etc.\n}\n```\n\n### 2. SkillGraphServer (`src/serving/graph-server.ts`)\n\nMain orchestrator with dual control (orchestrator + agent):\n\n```typescript\ninterface GraphServerConfig {\n  /** SkillBank instance */\n  skillBank: SkillBank;\n  \n  /** Initial loadout criteria (optional) */\n  initialLoadout?: LoadoutCriteria;\n  \n  /** Whether agent can modify loadout */\n  agentCanModify?: boolean;           // Default: true\n  \n  /** Whether agent additions need approval */\n  requireApproval?: boolean;          // Default: false\n  \n  /** Auto-expand skills on first use */\n  autoExpandOnUse?: boolean;          // Default: true\n  \n  /** Max skills in expanded state (context budget) */\n  maxExpanded?: number;               // Default: 5\n  \n  /** Eviction strategy when maxExpanded reached */\n  evictionStrategy?: 'lru' | 'priority' | 'manual';\n  \n  /** Available loadout profiles */\n  profiles?: Record<string, LoadoutCriteria>;\n  \n  /** Persist state across sessions */\n  persistState?: boolean;             // Default: false\n}\n\nclass SkillGraphServer {\n  private state: LoadoutState;\n  private compiler: LoadoutCompiler;\n  \n  constructor(config: GraphServerConfig);\n\n  // =========================================================================\n  // External API (for Orchestrator)\n  // =========================================================================\n\n  /** Set loadout from criteria (replaces current) */\n  async setLoadout(criteria: LoadoutCriteria): Promise<LoadoutState>;\n  \n  /** Set loadout for a specific task */\n  async setLoadoutForTask(taskDescription: string): Promise<LoadoutState>;\n  \n  /** Set loadout based on project analysis */\n  async setLoadoutForProject(projectPath: string): Promise<LoadoutState>;\n  \n  /** Switch to a named profile */\n  async setLoadoutFromProfile(profileName: string): Promise<LoadoutState>;\n  \n  /** Merge additional skills into current loadout */\n  async addSkills(skillIds: string[]): Promise<void>;\n  \n  /** Remove skills from loadout */\n  removeSkills(skillIds: string[]): void;\n  \n  /** Approve pending skill requests from agent */\n  approvePending(skillIds: string[]): void;\n  \n  /** Deny pending skill requests */\n  denyPending(skillIds: string[]): void;\n  \n  /** Get current state */\n  getState(): LoadoutState;\n\n  // =========================================================================\n  // Agent API (exposed via MCP tools)\n  // =========================================================================\n\n  /** Agent requests to change loadout */\n  async agentSetLoadout(criteria: LoadoutCriteria): Promise<LoadoutState | 'denied'>;\n  \n  /** Agent requests additional skills */\n  async agentRequestSkills(skillIds: string[]): Promise<{ added: string[]; pending: string[] }>;\n  \n  /** Agent searches for skills by query */\n  async agentSearchSkills(query: string, limit?: number): Promise<SkillSummary[]>;\n  \n  /** Agent expands a skill to see full content */\n  async agentExpandSkill(skillId: string): Promise<Skill | null>;\n  \n  /** Agent collapses a skill back to summary */\n  agentCollapseSkill(skillId: string): void;\n  \n  /** Agent lists current loadout */\n  agentListLoadout(): LoadoutView;\n  \n  /** Agent switches to a profile */\n  async agentSwitchProfile(profileName: string): Promise<LoadoutState | 'denied'>;\n\n  // =========================================================================\n  // Rendering\n  // =========================================================================\n\n  /** Render current state for system prompt (OpenSkills-compatible XML) */\n  renderSystemPrompt(): string;\n  \n  /** Get MCP tool definitions for current loadout */\n  getMcpTools(): ToolDefinition[];\n  \n  /** Render a single skill's full content */\n  renderSkillContent(skillId: string): string;\n\n  // =========================================================================\n  // Events\n  // =========================================================================\n\n  on(event: 'loadout:changed' | 'skill:expanded' | 'skill:collapsed' | 'pending:added', \n     handler: (data: any) => void): void;\n}\n\ninterface LoadoutView {\n  available: SkillSummary[];\n  pending: string[];\n  profiles: string[];\n}\n\ninterface SkillSummary {\n  id: string;\n  name: string;\n  description: string;\n  expanded: boolean;\n  tags: string[];\n}\n```\n\n### 3. ViewRenderer (`src/serving/view-renderer.ts`)\n\nRenders loadout state for different consumers:\n\n```typescript\nclass ViewRenderer {\n  /**\n   * Render as OpenSkills-compatible XML for system prompt\n   */\n  renderXml(state: LoadoutState): string;\n  \n  /**\n   * Render as Markdown (for debugging/display)\n   */\n  renderMarkdown(state: LoadoutState): string;\n  \n  /**\n   * Render skill in SKILL.md format\n   */\n  renderSkillMd(skill: Skill): string;\n  \n  /**\n   * Estimate token count for current state\n   */\n  estimateTokens(state: LoadoutState): number;\n}\n```\n\nExample XML output (OpenSkills-compatible):\n\n```xml\n<skills_system>\n<usage>\nSkills in your current loadout. Use skill_expand to see full content.\nUse loadout_search to find additional skills. Use loadout_add to request them.\n</usage>\n\n<available_skills>\n<skill id=\"tdd-workflow\" state=\"expanded\">\n  <name>TDD Workflow</name>\n  <description>Test-driven development patterns</description>\n  <content>\n    ## Problem\n    Writing tests after code leads to incomplete coverage...\n    \n    ## Solution\n    1. Write failing test first\n    2. Implement minimal code to pass\n    ...\n  </content>\n</skill>\n\n<skill id=\"security-review\" state=\"available\">\n  <name>Security Review</name>\n  <description>Security vulnerability detection and remediation</description>\n</skill>\n</available_skills>\n\n<pending_requests>\n  <skill id=\"oauth-patterns\">Awaiting approval</skill>\n</pending_requests>\n</skills_system>\n```\n\n### 4. MCP Server (`src/mcp/`)\n\nMCP server with loadout management tools:\n\n#### Loadout Management Tools\n\n| Tool | Description |\n|------|-------------|\n| `loadout_list` | List available skills with expansion state |\n| `loadout_search` | Search for skills to add (semantic) |\n| `loadout_add` | Request skills to be added |\n| `loadout_remove` | Remove skills from loadout |\n| `loadout_profile` | Switch to a named profile |\n| `loadout_set` | Set loadout from criteria (if permitted) |\n\n#### Skill Tools\n\n| Tool | Description |\n|------|-------------|\n| `skill_expand` | Expand a skill to see full content |\n| `skill_collapse` | Collapse back to summary |\n| `skill_use` | Apply/invoke an expanded skill |\n\n#### Dynamic Tools\n\nWhen a skill is expanded, it becomes a callable tool: `skill_{id}`\n\nUsing a skill tool:\n1. Triggers `autoExpandOnUse` for related skills\n2. Records usage for metrics\n3. Returns skill guidance for the agent to follow\n\n#### Tool Definitions\n\n```typescript\n// src/mcp/tools/loadout-tools.ts\n\nconst loadoutListTool: ToolDefinition = {\n  name: 'loadout_list',\n  description: 'List skills in your current loadout with their expansion state',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      filter: { \n        type: 'string', \n        description: 'Optional: filter by \"expanded\", \"available\", or \"pending\"' \n      }\n    }\n  }\n};\n\nconst loadoutSearchTool: ToolDefinition = {\n  name: 'loadout_search',\n  description: 'Search for skills that could help with your current task',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      query: { type: 'string', description: 'What you need help with' },\n      limit: { type: 'number', description: 'Max results (default: 5)' }\n    },\n    required: ['query']\n  }\n};\n\nconst loadoutAddTool: ToolDefinition = {\n  name: 'loadout_add',\n  description: 'Request skills to be added to your loadout',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      skill_ids: { \n        type: 'array', \n        items: { type: 'string' },\n        description: 'Skill IDs to add'\n      }\n    },\n    required: ['skill_ids']\n  }\n};\n\nconst skillExpandTool: ToolDefinition = {\n  name: 'skill_expand',\n  description: 'Expand a skill to see its full content and guidance',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      skill_id: { type: 'string', description: 'ID of skill to expand' }\n    },\n    required: ['skill_id']\n  }\n};\n```\n\n## File Structure\n\n```\nsrc/\n├── serving/                       # NEW\n│   ├── index.ts                   # Public exports\n│   ├── types.ts                   # LoadoutCriteria, LoadoutState, etc.\n│   ├── graph-server.ts            # Main orchestrator\n│   ├── loadout-compiler.ts        # Selection logic\n│   ├── view-renderer.ts           # XML/Markdown rendering\n│   ├── project-detector.ts        # Auto-detect project context\n│   └── profiles/                  # Built-in loadout profiles\n│       ├── index.ts\n│       ├── code-review.ts\n│       ├── implementation.ts\n│       ├── debugging.ts\n│       └── security.ts\n│\n├── mcp/                           # NEW\n│   ├── index.ts                   # Public exports\n│   ├── server.ts                  # MCP server implementation\n│   ├── handlers.ts                # Tool execution handlers\n│   └── tools/\n│       ├── loadout-tools.ts       # Loadout management tools\n│       └── skill-tools.ts         # Skill expand/collapse/use\n│\n├── types.ts                       # EXTEND with Skill.serving\n└── matching/                      # EXISTING (used by compiler)\n```\n\n## Example Flows\n\n### Flow 1: Orchestrator Pre-configures Agent\n\n```typescript\n// Orchestrator spawning an agent for PR review\nconst server = new SkillGraphServer({\n  skillBank,\n  agentCanModify: true,\n  requireApproval: false,\n});\n\n// Set loadout based on task\nawait server.setLoadoutForTask(\"Review PR #123 for security issues and code quality\");\n\n// Get what agent needs\nconst systemPrompt = server.renderSystemPrompt();\nconst tools = server.getMcpTools();\n\n// Spawn agent\nspawnAgent({ systemPrompt, tools });\n```\n\n### Flow 2: Agent Discovers and Adds Skills Mid-Session\n\n```\nUser: Review this code for SQL injection vulnerabilities.\n\nAgent: I should check if there are relevant security skills.\n\n→ loadout_search({ query: \"SQL injection prevention\" })\n← [{ id: \"sql-security\", name: \"SQL Security Patterns\", description: \"...\" }]\n\nAgent: Found one. Let me add it to my loadout.\n\n→ loadout_add({ skill_ids: [\"sql-security\"] })\n← { added: [\"sql-security\"], pending: [] }\n\nAgent: Now let me see the full guidance.\n\n→ skill_expand({ skill_id: \"sql-security\" })\n← { id: \"sql-security\", content: \"## Problem\\nSQL injection occurs when...\" }\n\nAgent: [Applies the skill's guidance to review the code]\n```\n\n### Flow 3: Approval Flow (Controlled Environment)\n\n```typescript\n// Orchestrator requires approval for sensitive skills\nconst server = new SkillGraphServer({\n  skillBank,\n  agentCanModify: true,\n  requireApproval: true,  // Agent must request, human approves\n});\n\n// Agent requests a skill...\n// Tool: loadout_add({ skill_ids: [\"production-deploy\"] })\n// Response: { added: [], pending: [\"production-deploy\"] }\n\n// Agent sees: \"Skill requested, awaiting approval.\"\n\n// Human/orchestrator approves\nserver.approvePending([\"production-deploy\"]);\n\n// Agent can now expand and use it\n```\n\n### Flow 4: Profile Switching\n\n```typescript\n// Define profiles\nconst profiles = {\n  \"code-review\": {\n    tags: [\"review\", \"quality\", \"security\"],\n    maxSkills: 5,\n  },\n  \"implementation\": {\n    rootSkills: [\"tdd-workflow\", \"coding-standards\"],\n    includeDependencies: true,\n    maxSkills: 8,\n  },\n  \"debugging\": {\n    taskDescription: \"diagnose and fix issues\",\n    tags: [\"debugging\", \"logging\"],\n  },\n};\n\nconst server = new SkillGraphServer({ skillBank, profiles });\n\n// Agent can switch profiles mid-session\n// Tool: loadout_profile({ name: \"debugging\" })\n// → Loadout changes to debugging-focused skills\n```\n\n### Flow 5: Project-Based Auto-Configuration\n\n```typescript\n// Analyze project and configure loadout automatically\nawait server.setLoadoutForProject(\"/path/to/project\");\n\n// Detects:\n// - package.json → Node.js\n// - tsconfig.json → TypeScript  \n// - prisma/ → Prisma ORM\n// - .github/workflows/ → CI/CD\n\n// Selects relevant skills:\n// → typescript-patterns, nodejs-backend, prisma-patterns, github-actions\n```\n\n## Configuration Options\n\n### GraphServerConfig\n\n```typescript\ninterface GraphServerConfig {\n  // Core\n  skillBank: SkillBank;\n  initialLoadout?: LoadoutCriteria;\n  \n  // Agent permissions\n  agentCanModify?: boolean;           // Default: true\n  agentCanSetLoadout?: boolean;       // Default: false (can search/add, not replace)\n  agentCanSwitchProfile?: boolean;    // Default: true\n  requireApproval?: boolean;          // Default: false\n  \n  // Expansion behavior\n  autoExpandOnUse?: boolean;          // Default: true\n  autoExpandRelated?: boolean;        // Default: true\n  maxExpanded?: number;               // Default: 5\n  evictionStrategy?: 'lru' | 'priority' | 'manual';\n  \n  // Profiles\n  profiles?: Record<string, LoadoutCriteria>;\n  defaultProfile?: string;\n  \n  // Persistence\n  persistState?: boolean;             // Default: false\n  stateStorage?: StateStorage;        // Custom persistence adapter\n  \n  // Rendering\n  outputFormat?: 'xml' | 'markdown';  // Default: 'xml'\n  includeTokenEstimates?: boolean;    // Default: false\n}\n```\n\n## Built-in Profiles\n\n### code-review\n```typescript\n{\n  tags: [\"review\", \"quality\", \"security\"],\n  taskDescription: \"review code for quality, security, and best practices\",\n  maxSkills: 6,\n  priorityOrder: 'relevance'\n}\n```\n\n### implementation  \n```typescript\n{\n  rootSkills: [\"tdd-workflow\", \"coding-standards\"],\n  includeDependencies: true,\n  tags: [\"development\", \"testing\"],\n  maxSkills: 8\n}\n```\n\n### debugging\n```typescript\n{\n  taskDescription: \"diagnose and fix bugs, analyze errors\",\n  tags: [\"debugging\", \"logging\", \"error-handling\"],\n  maxSkills: 5\n}\n```\n\n### security\n```typescript\n{\n  tags: [\"security\"],\n  tagsAll: [\"security\"],\n  taskDescription: \"security review, vulnerability detection\",\n  maxSkills: 8,\n  minSuccessRate: 0.7\n}\n```\n\n## Success Criteria\n\n- [ ] LoadoutCompiler supports all selection strategies (explicit, tag, semantic, project, relationship)\n- [ ] SkillGraphServer provides both orchestrator API and agent API\n- [ ] Agent can search, add, expand, collapse skills mid-session\n- [ ] Approval flow works when requireApproval=true\n- [ ] Profile switching works mid-session\n- [ ] MCP tools update dynamically (tools/list_changed)\n- [ ] System prompt renders OpenSkills-compatible XML\n- [ ] maxExpanded limit enforced with configurable eviction\n- [ ] Project detection infers relevant skills from codebase\n- [ ] Token estimates available for context budgeting\n\n## Open Questions (Resolved)\n\n1. ~~State persistence~~ → Configurable via `persistState`, default false\n2. ~~Auto-collapse~~ → Use `evictionStrategy` when `maxExpanded` reached\n3. ~~Context budget~~ → `maxExpanded` + `maxTokens` in criteria + token estimates\n\n## Future Enhancements\n\n- **Usage-based learning**: Track which skills are used together, suggest bundles\n- **Adaptive profiles**: Profiles that evolve based on usage patterns\n- **Cross-agent sharing**: Share loadout state between related agents\n- **Skill recommendations**: Proactively suggest skills based on errors/context\n\n## Related\n\n- Existing: `SkillBank`, `SemanticMatcher`, `DependencyGraph`\n- Reference: [OpenSkills](https://github.com/numman-ali/openskills) patterns\n- Integration: `@modelcontextprotocol/sdk` for MCP server\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-01-29 23:37:43","updated_at":"2026-02-03 20:50:05","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["agent-control","architecture","loadout","mcp","serving"]}

package/references/skill-tree/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance for Claude Code when working with this repository.
+
+## Project Overview
+
+**skill-tree** is a TypeScript library for managing agent skill versions and evolution. It extracts, iterates, and adapts skills from agent trajectories, enabling AI agents to build and maintain reusable skill libraries.
+
+## Key Architecture
+
+```
+src/
+├── index.ts              # Main exports
+├── skill-bank.ts         # Main orchestrator (SkillBank class)
+├── types.ts              # Core type definitions
+├── semver.ts             # Semantic versioning utilities
+├── adapters/             # Session format adapters (Claude Code, OpenAI, etc.)
+├── extraction/           # Manual and automatic skill extraction
+├── storage/              # Storage adapters (memory, filesystem, SQLite)
+├── matching/             # Semantic skill matching with embeddings
+├── versioning/           # Lineage tracking and version management
+├── learning/             # Learning providers for skill extraction
+│   ├── types.ts          # LearningProvider interface, candidate types
+│   └── providers/        # Provider implementations
+│       ├── naive.ts      # Simple heuristic-based extraction
+│       └── cognitive-core.ts  # Advanced batch learning via cognitive-core
+├── validation/           # Skill validation and testing
+├── metrics/              # Usage tracking and analytics
+├── hooks/                # Event hooks and activation system
+├── agents/               # AGENTS.md generation and parsing
+├── composition/          # Skill composition and merging
+└── cli/                  # Command-line interface
+```
+
+## Core Concepts
+
+### Skill
+A reusable piece of knowledge with:
+- `problem`: What it solves
+- `triggerConditions`: When to apply
+- `solution`: Step-by-step guidance
+- `verification`: How to verify success
+- Semantic versioning and lineage tracking
+
+### Trajectory
+An agent session parsed into structured turns (user, assistant, tool interactions) with metadata and outcome.
+
+### LearningProvider
+Interface for extracting candidates from trajectories. Two implementations:
+- `NaiveLearningProvider`: Simple, synchronous extraction
+- `CognitiveCoreProvider`: Advanced batch learning with dependency injection
+
+### LearningCandidate
+Extracted knowledge before promotion to a versioned skill. Has kinds: `skill`, `strategy`, `pattern`, `error-fix`.
+
+## Development Commands
+
+```bash
+# Build
+npm run build
+
+# Run all tests
+npm test
+
+# Run specific test file
+npx tsx test/learning.test.ts
+
+# Type check
+npx tsc --noEmit
+```
+
+## Testing Patterns
+
+Tests use a simple test harness in `test/run-all.ts`. Each test file exports tests via `describe()` and `it()` functions.
+
+```typescript
+describe('My Feature', () => {
+  it('does something', () => {
+    // assertions
+  });
+});
+```
+
+Mock factories are used for dependency injection testing, especially for `CognitiveCoreProvider`:
+
+```typescript
+function createMockCognitiveCoreFactory(): CognitiveCoreFactory & MockInspection {
+  // Returns mock implementations with inspection helpers
+}
+```
+
+## CognitiveCoreProvider
+
+This provider integrates with [cognitive-core](./references/cognitive-core/) (Atlas) for advanced learning. Key design decisions:
+
+1. **Dependency Injection**: Uses `CognitiveCoreFactory` interface instead of direct imports to avoid `tsconfig.json` `rootDir` issues and maintain clean separation.
+
+2. **Batch Accumulation**: Accumulates trajectories until `minTrajectories` threshold, then runs batch extraction for cross-trajectory pattern detection.
+
+3. **Trajectory Conversion**: Converts skill-tree `Turn[]` to cognitive-core's ReAct `Step[]` format when `convertToReAct: true`.
+
+4. **Kind Inference**: Automatically determines `LearningKind` from playbook content (error triggers → `error-fix`, strategy keywords → `strategy`, etc.).
+
+5. **Outcome Feedback**: Records success/failure to refine playbook confidence over time.
+
+See `src/learning/providers/README.md` for detailed documentation.
+
+## Important Files
+
+- `src/skill-bank.ts`: Main API entry point
+- `src/learning/types.ts`: Learning interface definitions
+- `src/learning/providers/cognitive-core.ts`: Cognitive-core adapter
+- `test/learning.test.ts`: Comprehensive learning provider tests
+
+## Common Tasks
+
+### Adding a new learning provider
+
+1. Implement `LearningProvider` interface in `src/learning/providers/`
+2. Export from `src/learning/providers/index.ts`
+3. Re-export from `src/learning/index.ts`
+4. Add tests in `test/learning.test.ts`
+
+### Extending CognitiveCoreProvider
+
+The provider uses interface types (`CCPlaybook`, `CCTrajectory`, etc.) that mirror cognitive-core. If cognitive-core adds new fields, update the interfaces in `cognitive-core.ts`.
+
+### Running a subset of tests
+
+```bash
+# Run only learning tests
+npx tsx test/learning.test.ts
+
+# Run with verbose output
+DEBUG=1 npx tsx test/learning.test.ts
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ES modules (`.js` extensions in imports)
+- JSDoc comments for public APIs
+- Interface types preferred over type aliases for extensibility
+- Dependency injection for external integrations
+
+## References
+
+- [cognitive-core (Atlas)](./references/cognitive-core/README.md): External learning engine
+- [OpenSkills](https://github.com/numman-ali/openskills): Skill format inspiration
+- [Claudeception](https://github.com/blader/Claudeception): Quality gates concept

package/references/skill-tree/README.md

@@ -0,0 +1,324 @@
+# skill-tree
+
+A TypeScript library for managing agent skill versions and evolution. Extract, iterate, and adapt skills from agent trajectories.
+
+## Overview
+
+skill-tree helps you build and maintain a library of reusable skills for AI agents by:
+
+- **Extracting skills** from agent sessions/trajectories (manual or automatic)
+- **Storing skills** in a versioned, searchable format (OpenSkills-compatible)
+- **Evolving skills** through versioning, forking, and merging
+- **Quality gates** to ensure extracted skills are reusable and non-trivial
+
+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 } from 'skill-tree';
+
+// Create a skill bank with filesystem storage
+const skillBank = createSkillBank({
+  storage: {
+    type: 'filesystem',
+    basePath: './skills',
+    openSkillsCompatible: true,
+  },
+});
+
+await skillBank.initialize();
+
+// Parse a Claude Code session
+const trajectory = await skillBank.parseSession(sessionContent);
+
+// Extract a skill manually
+const result = await skillBank.extractManual(trajectory, {
+  suggestedName: 'typescript-import-fix',
+  description: 'Fix TypeScript ES module import errors',
+  tags: ['typescript', 'imports'],
+});
+
+if (result.success) {
+  console.log('Extracted skill:', result.skill.name);
+}
+
+// Search for skills
+const skills = await skillBank.searchSkills('typescript error');
+
+// Create a new version
+const updated = await skillBank.createVersion('typescript-import-fix', {
+  solution: 'Updated solution...',
+}, { bumpType: 'minor' });
+```
+
+## Core Concepts
+
+### Skills
+
+A skill represents a reusable piece of knowledge extracted from agent interactions:
+
+```typescript
+interface Skill {
+  id: string;                    // Unique identifier
+  name: string;                  // Human-readable name
+  version: string;               // Semantic version
+  description: string;           // For semantic 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
+  // ... metadata, metrics, lineage
+}
+```
+
+### Trajectories
+
+Agent sessions are parsed into trajectories:
+
+```typescript
+interface Trajectory {
+  sessionId: string;
+  turns: Turn[];       // User/assistant/tool interactions
+  metadata: TrajectoryMetadata;
+  outcome?: TrajectoryOutcome;
+}
+```
+
+### Quality Gates
+
+Extraction includes quality gates (inspired by Claudeception) to ensure skills are:
+
+- **Reusable**: Applicable across multiple future tasks
+- **Non-trivial**: Involves discovery beyond documentation lookup
+- **Specific**: Has clear trigger conditions
+- **Verified**: Solution demonstrably works
+
+## Features
+
+### Session Adapters
+
+Parse different agent session formats:
+
+```typescript
+// Built-in: Claude Code JSONL
+const trajectory = await skillBank.parseSession(jsonlContent);
+
+// Register custom adapters
+skillBank.registerAdapter(myCustomAdapter);
+```
+
+### Extraction Modes
+
+**Manual extraction** with user guidance:
+
+```typescript
+const result = await skillBank.extractManual(trajectory, {
+  turnRange: [5, 15],           // Extract specific turns
+  suggestedName: 'my-skill',
+  tags: ['debugging'],
+});
+```
+
+**Automatic extraction** using LLM:
+
+```typescript
+skillBank.setLLMProvider(myLLMProvider);
+
+const results = await skillBank.extractAutomatic(trajectory, {
+  minConfidence: 0.7,
+});
+```
+
+### Storage
+
+**Filesystem storage** (OpenSkills-compatible):
+
+```typescript
+const skillBank = createSkillBank({
+  storage: {
+    type: 'filesystem',
+    basePath: '~/.skills',
+    openSkillsCompatible: true,  // YAML frontmatter + Markdown
+  },
+});
+```
+
+**Memory storage** (for testing):
+
+```typescript
+const skillBank = 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
+```
+
+### Versioning
+
+Semantic versioning with full lineage tracking:
+
+```typescript
+// Create new version
+const v2 = await skillBank.createVersion('my-skill', updates, {
+  bumpType: 'minor',
+  changelog: 'Added alternative solution',
+});
+
+// Get version history
+const history = await skillBank.getVersionHistory('my-skill');
+
+// Rollback to previous version
+const restored = await skillBank.rollbackSkill('my-skill', '1.0.0');
+
+// Compare versions
+const diff = await skillBank.compareVersions('my-skill', '1.0.0', '2.0.0');
+```
+
+### Skill Evolution
+
+Fork and merge skills:
+
+```typescript
+// Fork for a specialized use case
+const forked = await skillBank.forkSkill('my-skill', {
+  newId: 'my-skill-react',
+  newName: 'My Skill (React variant)',
+  reason: 'Specialized for React projects',
+});
+
+// Merge improvements back
+const merged = await skillBank.lineageTracker.mergeSkill(
+  'my-skill',
+  'my-skill-react',
+  { fields: ['solution', 'examples'] }
+);
+```
+
+### Events
+
+Subscribe to skill bank events:
+
+```typescript
+const unsubscribe = skillBank.on((event) => {
+  switch (event.type) {
+    case 'skill:created':
+      console.log('New skill:', event.skill.name);
+      break;
+    case 'extraction:completed':
+      console.log('Extraction confidence:', event.result.confidence);
+      break;
+  }
+});
+```
+
+## API Reference
+
+### SkillBank
+
+Main orchestrator class.
+
+| Method | Description |
+|--------|-------------|
+| `initialize()` | Initialize storage (required before use) |
+| `parseSession(content, adapter?)` | Parse session into trajectory |
+| `extractManual(trajectory, options?)` | Extract skill with guidance |
+| `extractAutomatic(trajectory, options?)` | Extract skills using LLM |
+| `getSkill(id, version?)` | Get skill by ID |
+| `listSkills(filter?)` | List skills with optional filter |
+| `searchSkills(query)` | Search skills by text |
+| `saveSkill(skill)` | Save or update a skill |
+| `deleteSkill(id, version?)` | Delete a skill |
+| `createVersion(id, updates, options?)` | Create new version |
+| `forkSkill(id, options)` | Fork a skill |
+| `getVersionHistory(id)` | Get version history |
+| `rollbackSkill(id, version)` | Rollback to version |
+| `on(handler)` | Subscribe to events |
+
+### 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.
+
+## Examples
+
+### Basic import fix
+
+**Before:**
+```typescript
+import { helper } from './utils'
+```
+
+**After:**
+```typescript
+import { helper } from './utils.js'
+```
+```
+
+## License
+
+MIT