cognitive-core 0.2.0 → 0.2.2

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

@@ -1,19 +0,0 @@
-{"id":"i-7bxx","uuid":"ddf991df-120d-46ed-87e0-0f998b7b8e69","title":"Define serving layer types and extend Skill interface","content":"## Overview\n\nCreate the foundational types for the serving layer and extend the existing `Skill` interface with serving-specific fields.\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/types.ts` with:\n  - `LoadoutCriteria` interface (all selection options)\n  - `LoadoutState` interface (available, expanded, pending maps)\n  - `LoadoutSource` interface\n  - `SkillState` type ('available' | 'expanded' | 'pending')\n  - `ExpandTrigger` interface\n  - `SkillSummary` interface\n  - `LoadoutView` interface\n  - `ProjectContext` interface\n  - `GraphServerConfig` interface\n  - `LoadoutCompilerConfig` interface\n\n- [ ] Extend `Skill` interface in `src/types.ts` with `serving?` field:\n  ```typescript\n  serving?: {\n    summary?: string;\n    tokenEstimate?: number;\n    autoExpand?: ExpandTrigger[];\n    expansionGroup?: string;\n  }\n  ```\n\n- [ ] Create `src/serving/index.ts` with public exports\n\n- [ ] Add tests for type compatibility\n\n## Technical Notes\n\n- Types should be exported from both `src/serving/index.ts` and re-exported from `src/index.ts`\n- Ensure backward compatibility - `serving` field is optional on Skill\n- Use strict TypeScript (no `any` types)\n\n## Implements\n\n[[s-70no]] - Core Types section","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:02","updated_at":"2026-02-03 21:48:02","closed_at":"2026-02-03 21:48:02","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7bxx","from_type":"issue","to":"i-22y3","to_type":"issue","type":"blocks"},{"from":"i-7bxx","from_type":"issue","to":"i-3rvm","to_type":"issue","type":"blocks"},{"from":"i-7bxx","from_type":"issue","to":"i-4kr7","to_type":"issue","type":"blocks"},{"from":"i-7bxx","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["foundation","serving","types"]}
-{"id":"i-3rvm","uuid":"5d760085-2e9c-4b6f-a067-10fde8b5f478","title":"Implement LoadoutCompiler with filter strategies","content":"## Overview\n\nCreate the LoadoutCompiler class that selects skills based on flexible criteria. This is the core selection logic for building loadouts.\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/loadout-compiler.ts` with `LoadoutCompiler` class\n\n- [ ] Implement filter methods (applied in order):\n  - `applyExplicitFilters()` - include/exclude by ID\n  - `applyTagFilters()` - tags (any) and tagsAll (all required)\n  - `applyQualityFilters()` - status, minSuccessRate, author\n  - `applySemanticFilters()` - taskDescription, problemContext, errorContext, keywords (uses existing SemanticMatcher)\n  - `applyRelationshipFilters()` - rootSkills, includeDependencies, includeRelated, depth\n  - `applyLimits()` - maxSkills, priorityOrder sorting\n\n- [ ] Implement main entry point:\n  ```typescript\n  async compile(criteria: LoadoutCriteria): Promise<Skill[]>\n  ```\n\n- [ ] Implement convenience methods:\n  - `compileForTask(taskDescription: string)`\n  - `compileFromProfile(profileName: string, profiles: Record<string, LoadoutCriteria>)`\n\n- [ ] Handle merge modes: 'replace', 'merge', 'subtract'\n\n- [ ] Add unit tests for each filter strategy\n\n## Technical Notes\n\n- Reuse existing `SemanticMatcher` for semantic filtering\n- Reuse existing `SkillRelationship` for relationship traversal\n- Filters should be composable and order-independent where possible\n- Empty criteria should return all active skills (up to default limit)\n\n## Implements\n\n[[s-70no]] - LoadoutCompiler section","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:13","updated_at":"2026-02-03 21:53:21","closed_at":"2026-02-03 21:53:21","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3rvm","from_type":"issue","to":"i-1uji","to_type":"issue","type":"blocks"},{"from":"i-3rvm","from_type":"issue","to":"i-22y3","to_type":"issue","type":"blocks"},{"from":"i-3rvm","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["compiler","core","serving"]}
-{"id":"i-1uji","uuid":"2dd56649-7568-49e4-9129-1577ba221ded","title":"Implement ProjectDetector for auto-configuration","content":"## Overview\n\nCreate the ProjectDetector that analyzes a project directory to infer relevant skills based on detected languages, frameworks, and patterns.\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/project-detector.ts` with `ProjectDetector` class\n\n- [ ] Implement `detectProjectContext(projectPath: string): Promise<ProjectContext>`:\n  - Detect project type from manifest files:\n    - `package.json` → Node.js/TypeScript\n    - `pyproject.toml` / `requirements.txt` → Python\n    - `Cargo.toml` → Rust\n    - `go.mod` → Go\n    - `pom.xml` / `build.gradle` → Java\n  - Detect frameworks from dependencies:\n    - React, Vue, Angular, Svelte (frontend)\n    - Express, Fastify, NestJS, Next.js (Node backend)\n    - FastAPI, Django, Flask (Python)\n    - Prisma, TypeORM, Drizzle (ORMs)\n  - Detect patterns from directory structure:\n    - `.github/workflows/` → CI/CD\n    - `docker-compose.yml` → Docker\n    - `terraform/` → Infrastructure\n  - Identify package manager (npm, yarn, pnpm, pip, cargo)\n\n- [ ] Add `compileForProject(projectPath: string)` to LoadoutCompiler that uses ProjectDetector\n\n- [ ] Create mapping from detected context to skill tags/criteria\n\n- [ ] Add tests with mock project structures\n\n## Technical Notes\n\n- Should be fast - only check file existence, don't parse deeply\n- Cache results for same projectPath within a session\n- Handle missing files gracefully (partial detection is fine)\n\n## Implements\n\n[[s-70no]] - Project-Based Auto-Configuration","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:23","updated_at":"2026-02-03 22:05:21","closed_at":"2026-02-03 22:05:21","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1uji","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["auto-config","detection","serving"],"feedback":[{"id":"87b558ac-260d-401c-835a-5a7f1f668c47","from_id":"i-1uji","to_id":"s-70no","feedback_type":"comment","content":"ProjectDetector implemented with comprehensive detection:\n- **Project types**: Node.js, Python, Rust, Go, Java, Kotlin\n- **Node.js frameworks**: React, Next.js, Vue, Nuxt, Angular, Svelte, Express, Fastify, NestJS, Hono, Prisma, Drizzle, TypeORM, Jest, Vitest, Playwright, Cypress\n- **Python frameworks**: FastAPI, Django, Flask, SQLAlchemy, pytest, Pydantic\n- **Patterns**: GitHub Actions, GitLab CI, Docker, Docker Compose, Terraform, Kubernetes\n- **Package managers**: npm, pnpm, yarn, bun (Node.js), pip (Python), cargo (Rust), maven/gradle (Java)\n- Result caching with `clearCache()` method\n- `contextToCriteria()` converts detected context to LoadoutCriteria for automatic skill selection","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:05:17.795Z","updated_at":"2026-02-03T22:05:17.795Z"}]}
-{"id":"i-22y3","uuid":"b0ac9a37-5cfd-4339-a98a-3cf989800adb","title":"Implement SkillGraphServer orchestrator API","content":"## Overview\n\nCreate the main SkillGraphServer class with the orchestrator-facing API for managing loadout state.\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/graph-server.ts` with `SkillGraphServer` class\n\n- [ ] Implement constructor with `GraphServerConfig`:\n  - Initialize LoadoutCompiler\n  - Set up empty LoadoutState\n  - Store config options (agentCanModify, requireApproval, etc.)\n  - Apply initialLoadout if provided\n\n- [ ] Implement orchestrator API methods:\n  - `setLoadout(criteria: LoadoutCriteria): Promise<LoadoutState>` - replace current loadout\n  - `setLoadoutForTask(taskDescription: string): Promise<LoadoutState>`\n  - `setLoadoutForProject(projectPath: string): Promise<LoadoutState>`\n  - `setLoadoutFromProfile(profileName: string): Promise<LoadoutState>`\n  - `addSkills(skillIds: string[]): Promise<void>` - merge into current\n  - `removeSkills(skillIds: string[]): void`\n  - `approvePending(skillIds: string[]): void`\n  - `denyPending(skillIds: string[]): void`\n  - `getState(): LoadoutState`\n\n- [ ] Implement expansion state management:\n  - Track expanded vs available skills\n  - Enforce `maxExpanded` limit\n  - Implement eviction strategies: 'lru', 'priority', 'manual'\n\n- [ ] Implement event emission:\n  - `loadout:changed`\n  - `skill:expanded`\n  - `skill:collapsed`\n  - `pending:added`\n\n- [ ] Add unit tests for state transitions\n\n## Technical Notes\n\n- LoadoutState should use Map for available skills (fast lookup)\n- Use Set for expanded and pending skill IDs\n- Events should be synchronous (no async handlers for now)\n\n## Implements\n\n[[s-70no]] - SkillGraphServer External API section","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:34","updated_at":"2026-02-03 22:42:41","closed_at":"2026-02-03 22:42:41","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-22y3","from_type":"issue","to":"i-2hn5","to_type":"issue","type":"blocks"},{"from":"i-22y3","from_type":"issue","to":"i-63n4","to_type":"issue","type":"blocks"},{"from":"i-22y3","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["orchestrator-api","server","serving"],"feedback":[{"id":"1c5f0d8c-9c88-467b-8379-0633f33db550","from_id":"i-22y3","to_id":"s-70no","feedback_type":"comment","content":"SkillGraphServer implemented with full orchestrator API:\n- **Loadout management**: `setLoadout()`, `setLoadoutForTask()`, `setLoadoutForProject()`, `setLoadoutFromProfile()`\n- **Skill operations**: `addSkills()`, `removeSkills()`, `getState()`\n- **Pending approval**: `approvePending()`, `denyPending()`\n- **Expansion management**: `expandSkill()`, `collapseSkill()`, `recordUsage()` with LRU eviction\n- **Agent API**: `agentRequestSkills()`, `agentRemoveSkills()`, `agentSwitchProfile()`, `agentSetLoadout()`\n- **Rendering**: `renderSystemPrompt()` (XML/Markdown), `estimateTokens()`\n- **Events**: Full event emission for loadout:changed, skill:expanded, skill:collapsed, pending:added/approved/denied\n- **Profiles**: `getProfiles()`, `addProfile()`, runtime profile management\n- **Configuration**: All GraphServerConfig options implemented (permissions, expansion behavior, eviction strategies)","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:42:41.058Z","updated_at":"2026-02-03T22:42:41.058Z"}]}
-{"id":"i-4kr7","uuid":"216f6ba8-23fd-437f-88ab-5a66cd4de688","title":"Implement ViewRenderer for system prompt output","content":"## Overview\n\nCreate the ViewRenderer that renders loadout state into formats consumable by agents (XML, Markdown).\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/view-renderer.ts` with `ViewRenderer` class\n\n- [ ] Implement `renderXml(state: LoadoutState): string`:\n  - OpenSkills-compatible `<skills_system>` wrapper\n  - `<usage>` section with instructions\n  - `<available_skills>` with skill entries\n  - For expanded skills: include full `<content>` block\n  - For available skills: just `<name>` and `<description>`\n  - `<pending_requests>` section if any pending\n\n- [ ] Implement `renderMarkdown(state: LoadoutState): string`:\n  - Human-readable format for debugging\n  - Table of skills with state indicators\n  - Full content for expanded skills\n\n- [ ] Implement `renderSkillMd(skill: Skill): string`:\n  - SKILL.md format with YAML frontmatter\n  - Sections: Problem, Solution, Verification, Examples\n\n- [ ] Implement `estimateTokens(state: LoadoutState): number`:\n  - Use `skill.serving?.tokenEstimate` if available\n  - Fall back to character count / 4 approximation\n  - Sum for all available + expanded content\n\n- [ ] Add `renderSystemPrompt()` method to SkillGraphServer that uses ViewRenderer\n\n## Technical Notes\n\n- XML output should be valid and parseable\n- Escape special characters in skill content\n- Keep summaries short (first sentence of description if no explicit summary)\n\n## Implements\n\n[[s-70no]] - ViewRenderer section and XML output example","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:44","updated_at":"2026-02-03 22:05:21","closed_at":"2026-02-03 22:05:21","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-4kr7","from_type":"issue","to":"i-22y3","to_type":"issue","type":"blocks"},{"from":"i-4kr7","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["rendering","serving","xml"],"feedback":[{"id":"caf8f234-dc5b-4a85-865c-cee1fd0cef38","from_id":"i-4kr7","to_id":"s-70no","feedback_type":"comment","content":"ViewRenderer implemented with full functionality:\n- `renderXml()`: OpenSkills-compatible XML format with progressive disclosure (available vs expanded states)\n- `renderMarkdown()`: Debug-friendly table view with expanded skill details\n- `renderSkillMd()`: SKILL.md format with YAML frontmatter\n- `estimateTokens()`: Token estimation for budget tracking\n- `toSummaries()`: Convert loadout to array of skill summaries\n- Proper XML escaping for special characters\n- Configurable options for token estimates, max summary length, and example inclusion","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:05:17.627Z","updated_at":"2026-02-03T22:05:17.627Z"}]}
-{"id":"i-2hn5","uuid":"03ba9fd4-096e-47ef-8f57-bb6c7454378f","title":"Implement SkillGraphServer agent API methods","content":"## Overview\n\nAdd the agent-facing API methods to SkillGraphServer that will be exposed via MCP tools.\n\n## Acceptance Criteria\n\n- [ ] Add agent API methods to `SkillGraphServer`:\n\n  - `agentSetLoadout(criteria: LoadoutCriteria): Promise<LoadoutState | 'denied'>`\n    - Check `agentCanSetLoadout` config\n    - Return 'denied' if not permitted\n\n  - `agentRequestSkills(skillIds: string[]): Promise<{ added: string[]; pending: string[] }>`\n    - Check `agentCanModify` config\n    - If `requireApproval`: add to pending, return in pending array\n    - If no approval needed: add directly, return in added array\n\n  - `agentSearchSkills(query: string, limit?: number): Promise<SkillSummary[]>`\n    - Use SemanticMatcher to search all skills (not just loadout)\n    - Return summaries with id, name, description, tags\n    - Default limit: 5\n\n  - `agentExpandSkill(skillId: string): Promise<Skill | null>`\n    - Return null if skill not in available set\n    - Add to expanded set\n    - Enforce maxExpanded with eviction\n    - Emit 'skill:expanded' event\n\n  - `agentCollapseSkill(skillId: string): void`\n    - Remove from expanded set\n    - Emit 'skill:collapsed' event\n\n  - `agentListLoadout(): LoadoutView`\n    - Return available skills as SkillSummary[]\n    - Include pending array\n    - Include available profile names\n\n  - `agentSwitchProfile(profileName: string): Promise<LoadoutState | 'denied'>`\n    - Check `agentCanSwitchProfile` config\n    - Apply profile criteria\n\n- [ ] Implement auto-expand on use:\n  - When a skill is \"used\" (via skill tool), expand related skills\n  - Respect `autoExpandRelated` config\n\n- [ ] Add tests for permission checks\n\n## Technical Notes\n\n- All agent methods should respect config permissions\n- 'denied' return should include reason in a real implementation\n- Consider rate limiting for search in future\n\n## Implements\n\n[[s-70no]] - SkillGraphServer Agent API section","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:15:57","updated_at":"2026-02-03 22:44:10","closed_at":"2026-02-03 22:44:10","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-2hn5","from_type":"issue","to":"i-28ae","to_type":"issue","type":"blocks"},{"from":"i-2hn5","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["agent-api","server","serving"],"feedback":[{"id":"a1e368bc-c5b9-461e-83ba-a32940412268","from_id":"i-2hn5","to_id":"s-70no","feedback_type":"comment","content":"Agent API methods implemented and tested:\n- `agentSearchSkills(query, limit)` - text search across all skills by name, description, problem, and tags\n- `agentExpandSkill(skillId)` - expands skill and returns it (or null if not in loadout)\n- `agentCollapseSkill(skillId)` - collapses skill from expanded state\n- `agentListLoadout()` - returns LoadoutView with available summaries, pending skills, and profile names\n- All existing agent methods (agentRequestSkills, agentRemoveSkills, agentSwitchProfile, agentSetLoadout) verified working\n\nNote: Search currently uses simple text matching. Could be enhanced with SemanticMatcher for better relevance when available.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:44:09.794Z","updated_at":"2026-02-03T22:44:09.794Z"}]}
-{"id":"i-28ae","uuid":"f84feff7-4f13-4ce9-a562-e860aa76d341","title":"Create MCP tool definitions for loadout management","content":"## Overview\n\nDefine the MCP tool schemas for loadout and skill management that agents will use.\n\n## Acceptance Criteria\n\n- [ ] Create `src/mcp/tools/loadout-tools.ts` with tool definitions:\n\n  - `loadout_list`: List skills in current loadout\n    - Input: `{ filter?: 'expanded' | 'available' | 'pending' }`\n    - Returns: LoadoutView\n\n  - `loadout_search`: Search for skills to add\n    - Input: `{ query: string, limit?: number }`\n    - Returns: SkillSummary[]\n\n  - `loadout_add`: Request skills to be added\n    - Input: `{ skill_ids: string[] }`\n    - Returns: `{ added: string[], pending: string[] }`\n\n  - `loadout_remove`: Remove skills from loadout\n    - Input: `{ skill_ids: string[] }`\n    - Returns: `{ removed: string[] }`\n\n  - `loadout_profile`: Switch to a named profile\n    - Input: `{ name: string }`\n    - Returns: LoadoutView or error\n\n  - `loadout_set`: Set loadout from criteria (if permitted)\n    - Input: LoadoutCriteria subset\n    - Returns: LoadoutView or 'denied'\n\n- [ ] Create `src/mcp/tools/skill-tools.ts` with tool definitions:\n\n  - `skill_expand`: Expand a skill to see full content\n    - Input: `{ skill_id: string }`\n    - Returns: Full Skill object or error\n\n  - `skill_collapse`: Collapse back to summary\n    - Input: `{ skill_id: string }`\n    - Returns: success boolean\n\n  - `skill_use`: Apply/invoke an expanded skill\n    - Input: `{ skill_id: string }`\n    - Returns: Skill content + triggers related expansion\n\n- [ ] Create `src/mcp/tools/index.ts` exporting all tools\n\n- [ ] Follow MCP ToolDefinition schema (name, description, inputSchema)\n\n## Technical Notes\n\n- Tool descriptions should be clear for LLM consumption\n- Input schemas should use JSON Schema format\n- Keep required fields minimal\n\n## Implements\n\n[[s-70no]] - MCP Tools section","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:16:08","updated_at":"2026-02-03 22:47:23","closed_at":"2026-02-03 22:47:23","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-28ae","from_type":"issue","to":"i-3i0j","to_type":"issue","type":"blocks"},{"from":"i-28ae","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["definitions","mcp","tools"],"feedback":[{"id":"89176b15-58c0-4e7d-958a-5dec5a297e85","from_id":"i-28ae","to_id":"s-70no","feedback_type":"comment","content":"MCP tool definitions implemented:\n\n**Loadout Tools:**\n- `loadout_list` - List skills in current loadout with optional filter\n- `loadout_search` - Search for skills to add (by name, description, tags)\n- `loadout_add` - Request skills to be added to loadout\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- `skill_expand` - Expand skill to see full content\n- `skill_collapse` - Collapse back to summary\n- `skill_use` - Mark skill as being used (triggers auto-expansion)\n- `skill_get` - Get details about a specific skill\n\n**Utilities:**\n- `allTools` - Array of all tool definitions\n- `getToolDefinition(name)` - Get tool by name\n- `getToolNames()` - List all tool names\n\nAll tools follow MCP ToolDefinition schema with name, description, and JSON Schema inputSchema.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:47:22.758Z","updated_at":"2026-02-03T22:47:22.758Z"}]}
-{"id":"i-3i0j","uuid":"b517fb8e-881b-437c-94ce-c3653772229c","title":"Implement MCP server with tool handlers","content":"## Overview\n\nCreate the MCP server implementation that exposes loadout/skill tools and handles dynamic tool registration.\n\n## Acceptance Criteria\n\n- [ ] Create `src/mcp/server.ts` with MCP server setup:\n  - Use `@modelcontextprotocol/sdk` package\n  - Initialize with SkillGraphServer instance\n  - Register static tools (loadout_*, skill_*)\n\n- [ ] Create `src/mcp/handlers.ts` with tool execution handlers:\n  - Map each tool to corresponding SkillGraphServer method\n  - Handle errors gracefully with informative messages\n  - Return properly formatted results\n\n- [ ] Implement dynamic tool registration:\n  - When skill is expanded, register `skill_{id}` tool\n  - When skill is collapsed, unregister the tool\n  - Send `notifications/tools/list_changed` on state changes\n\n- [ ] Add `getMcpTools(): ToolDefinition[]` to SkillGraphServer:\n  - Return static tools + dynamic skill tools\n  - Dynamic tools only for expanded skills\n\n- [ ] Create `src/mcp/index.ts` with public exports:\n  - Export server factory function\n  - Export tool definitions for reference\n\n- [ ] Add integration test for MCP server lifecycle\n\n## Technical Notes\n\n- MCP SDK: `@modelcontextprotocol/sdk`\n- Server should be instantiable (not singleton) for testing\n- Consider stdio and HTTP transports\n- Handle tool not found errors gracefully\n\n## Dependencies\n\n- Requires `@modelcontextprotocol/sdk` package to be added\n\n## Implements\n\n[[s-70no]] - MCP Server section and Dynamic Tools","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:16:18","updated_at":"2026-02-03 22:49:25","closed_at":"2026-02-03 22:49:25","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3i0j","from_type":"issue","to":"i-7xaz","to_type":"issue","type":"blocks"},{"from":"i-3i0j","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["handlers","mcp","server"],"feedback":[{"id":"54f50f1b-1b00-49af-b192-5f428240b4d3","from_id":"i-3i0j","to_id":"s-70no","feedback_type":"comment","content":"MCP server implementation completed:\n\n**Handlers (`src/mcp/handlers.ts`):**\n- `createToolHandlers(server)` - Creates all tool handlers bound to a SkillGraphServer\n- `executeToolCall(handlers, name, args)` - Execute a tool by name\n- Handlers for all 10 tools: loadout_list, loadout_search, loadout_add, loadout_remove, loadout_profile, loadout_set, skill_expand, skill_collapse, skill_use, skill_get\n\n**Server (`src/mcp/server.ts`):**\n- `SkillTreeMcpServer` class wrapping SkillGraphServer\n- `createMcpServer(graphServer, config)` factory function\n- `getServerInfo()` - Returns name and version for MCP initialization\n- `getTools()` - Returns all tools (static + dynamic for expanded skills)\n- `executeTool(name, args)` - Execute tool calls\n- `onToolsChanged(callback)` - Subscribe to tools/list_changed notifications\n- Dynamic tool registration when skills are expanded/collapsed\n\n**Design Notes:**\n- SDK-agnostic: Works without @modelcontextprotocol/sdk dependency\n- Handlers can be used with any MCP server implementation\n- Server provides notification hooks for dynamic tool updates","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:49:25.126Z","updated_at":"2026-02-03T22:49:25.126Z"}]}
-{"id":"i-63n4","uuid":"69bfdf79-0f0b-4e0f-9c31-2b444b7e1a5e","title":"Create built-in loadout profiles","content":"## Overview\n\nCreate the built-in loadout profiles for common use cases: code-review, implementation, debugging, security.\n\n## Acceptance Criteria\n\n- [ ] Create `src/serving/profiles/index.ts` with profile registry\n\n- [ ] Create profile definitions:\n\n  **code-review** (`src/serving/profiles/code-review.ts`):\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** (`src/serving/profiles/implementation.ts`):\n  ```typescript\n  {\n    rootSkills: [\"tdd-workflow\", \"coding-standards\"],\n    includeDependencies: true,\n    tags: [\"development\", \"testing\"],\n    maxSkills: 8\n  }\n  ```\n\n  **debugging** (`src/serving/profiles/debugging.ts`):\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** (`src/serving/profiles/security.ts`):\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- [ ] Export `builtInProfiles: Record<string, LoadoutCriteria>` from profiles/index.ts\n\n- [ ] Integrate with SkillGraphServer:\n  - Merge builtInProfiles with user-provided profiles\n  - Built-in profiles can be overridden\n\n- [ ] Add documentation for each profile\n\n## Technical Notes\n\n- Profiles should be extensible (users can add their own)\n- Profile names should be kebab-case\n- Consider making profiles configurable via file in future\n\n## Implements\n\n[[s-70no]] - Built-in Profiles section","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:16:30","updated_at":"2026-02-03 22:45:41","closed_at":"2026-02-03 22:45:41","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-63n4","from_type":"issue","to":"i-7xaz","to_type":"issue","type":"blocks"},{"from":"i-63n4","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["config","profiles","serving"],"feedback":[{"id":"00914242-42c8-4878-95c5-4dc3d836027f","from_id":"i-63n4","to_id":"s-70no","feedback_type":"comment","content":"Built-in profiles implemented with 8 pre-configured profiles:\n- **code-review**: Quality, security, and best practices review\n- **implementation**: TDD workflow and coding standards\n- **debugging**: Error analysis and troubleshooting\n- **security**: Vulnerability detection and secure coding\n- **testing**: Test patterns and coverage\n- **refactoring**: Code improvement and design patterns\n- **documentation**: Technical writing and API docs\n- **devops**: CI/CD, Docker, and infrastructure\n\nFeatures:\n- Exported from serving module: `builtInProfiles`, `getBuiltInProfile()`, `listBuiltInProfiles()`\n- SkillGraphServer automatically includes built-in profiles\n- User profiles can override built-in profiles with the same name","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T22:45:41.314Z","updated_at":"2026-02-03T22:45:41.314Z"}]}
-{"id":"i-7xaz","uuid":"923b69f0-d0c9-40d7-a46e-3f02e3dd7803","title":"Add serving layer integration tests","content":"## Overview\n\nCreate comprehensive integration tests that verify the serving layer works end-to-end.\n\n## Acceptance Criteria\n\n- [ ] Create `test/serving.test.ts` with integration tests:\n\n  **LoadoutCompiler tests:**\n  - Compile with explicit include/exclude\n  - Compile with tag filters\n  - Compile with semantic task description\n  - Compile with relationship traversal\n  - Compile with limits and priority ordering\n\n  **SkillGraphServer orchestrator API tests:**\n  - setLoadout replaces current state\n  - addSkills merges into current\n  - removeSkills removes from available and expanded\n  - approvePending moves to available\n  - maxExpanded enforces limit with eviction\n\n  **SkillGraphServer agent API tests:**\n  - agentRequestSkills respects requireApproval\n  - agentExpandSkill respects maxExpanded\n  - agentSearchSkills returns relevant results\n  - Permission checks work (agentCanModify, etc.)\n\n  **ViewRenderer tests:**\n  - XML output is valid and parseable\n  - Expanded skills include content\n  - Available skills show summary only\n  - Token estimation is reasonable\n\n  **Profile tests:**\n  - Built-in profiles load correctly\n  - Profile switching works mid-session\n  - Custom profiles override built-in\n\n  **End-to-end flow tests:**\n  - Orchestrator sets loadout → agent searches → agent adds → agent expands\n  - Approval flow: request → pending → approve → available\n  - Project detection → loadout compilation\n\n- [ ] Use mock SkillBank with test skills\n\n- [ ] Verify event emissions\n\n## Technical Notes\n\n- Use existing test harness pattern\n- Create test fixture skills with known tags/relationships\n- Test both happy path and error cases\n\n## Implements\n\n[[s-70no]] - Success Criteria validation","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:16:41","updated_at":"2026-02-03 23:21:52","closed_at":"2026-02-03 23:21:52","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7xaz","from_type":"issue","to":"i-3r3l","to_type":"issue","type":"blocks"},{"from":"i-7xaz","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["integration","serving","testing"],"feedback":[{"id":"f87eaecd-0ef8-4f42-bc25-a583181e473b","from_id":"i-7xaz","to_id":"s-70no","feedback_type":"comment","content":"Integration tests already implemented throughout development (89 tests in test/serving.test.ts):\n\n**LoadoutCompiler tests:** ✅\n- compile with empty criteria, tag filters, tagsAll, minSuccessRate, author\n- relationship traversal with dependencies and depth limits\n- limits (maxSkills, maxTokens, priorityOrder)\n- mergeLoadouts (replace, merge, subtract modes)\n\n**SkillGraphServer orchestrator API tests:** ✅\n- setLoadout, setLoadoutForTask, setLoadoutFromProfile\n- addSkills, removeSkills\n- approvePending, denyPending\n- maxExpanded with LRU eviction\n- auto-expand on use\n\n**SkillGraphServer agent API tests:** ✅\n- agentRequestSkills with requireApproval\n- agentExpandSkill, agentCollapseSkill\n- agentSearchSkills by name, tags, with limit\n- agentListLoadout, agentSetLoadout, agentSwitchProfile\n- Permission checks (agentCanModify, agentCanSetLoadout)\n\n**ViewRenderer tests:** ✅\n- XML output with available/expanded states\n- Markdown output with tables\n- SKILL.md format with YAML frontmatter\n- Token estimation\n\n**Profile tests:** ✅\n- Built-in profiles contain expected profiles\n- Profile switching works\n- User profiles override built-in\n\n**MCP tests:** ✅\n- Tool definitions and schemas\n- Handler execution\n- MCP server with dynamic tools\n- tools/list_changed notifications","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T23:21:52.059Z","updated_at":"2026-02-03T23:21:52.059Z"}]}
-{"id":"i-3r3l","uuid":"3b0f1f04-f9db-4d73-ade8-f95e936fc579","title":"Export serving layer from main package","content":"## Overview\n\nWire up the serving layer exports and update package documentation.\n\n## Acceptance Criteria\n\n- [ ] Update `src/index.ts` to export serving layer:\n  ```typescript\n  export * from './serving/index.js';\n  export * from './mcp/index.js';\n  ```\n\n- [ ] Update `src/serving/index.ts` with all public exports:\n  - Types: LoadoutCriteria, LoadoutState, GraphServerConfig, etc.\n  - Classes: SkillGraphServer, LoadoutCompiler, ViewRenderer, ProjectDetector\n  - Profiles: builtInProfiles\n\n- [ ] Update `src/mcp/index.ts` with public exports:\n  - Server factory\n  - Tool definitions\n  - Types\n\n- [ ] Add `@modelcontextprotocol/sdk` to package.json dependencies\n\n- [ ] Update CLAUDE.md with serving layer documentation:\n  - New file structure\n  - Key classes and their purposes\n  - Example usage\n\n- [ ] Verify TypeScript compilation succeeds\n\n- [ ] Run full test suite\n\n## Technical Notes\n\n- Ensure no circular dependencies\n- Keep exports organized and documented\n- Consider separate entry point for MCP-only usage\n\n## Implements\n\n[[s-70no]] - File Structure section","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-03 21:16:50","updated_at":"2026-02-03 23:22:12","closed_at":"2026-02-03 23:22:12","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3r3l","from_type":"issue","to":"s-70no","to_type":"spec","type":"implements"}],"tags":["documentation","exports","packaging"],"feedback":[{"id":"eafbcc91-5bb1-4947-b6b9-d982c67ed3c8","from_id":"i-3r3l","to_id":"s-70no","feedback_type":"comment","content":"Exports completed throughout implementation:\n\n**src/index.ts exports:** ✅\n- All serving layer types and classes\n- All MCP tools, handlers, and server\n\n**src/serving/index.ts exports:** ✅\n- Types: LoadoutCriteria, LoadoutState, GraphServerConfig, SkillSummary, LoadoutView, ProjectContext, etc.\n- Classes: LoadoutCompiler, ViewRenderer, ProjectDetector, SkillGraphServer\n- Profiles: builtInProfiles, getBuiltInProfile, listBuiltInProfiles, and individual profiles\n\n**src/mcp/index.ts exports:** ✅\n- Tool definitions: all 10 tools\n- Handlers: createToolHandlers, executeToolCall\n- Server: SkillTreeMcpServer, createMcpServer\n\n**Design decision:** @modelcontextprotocol/sdk kept as optional\n- Server implementation is SDK-agnostic\n- Handlers can be used with any MCP server implementation\n- No required dependencies added\n\n**Verification:** ✅\n- All 89 tests pass\n- TypeScript compiles (serving layer only - pre-existing errors in config/loader.ts and services/sync.ts unrelated to this work)","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T23:22:12.154Z","updated_at":"2026-02-03T23:22:12.154Z"}]}
-{"id":"i-1t4g","uuid":"538aae39-ff4e-4fe0-97fa-c5b44314f893","title":"Create loadout state persistence layer","content":"\nCreate `src/serving/state-persistence.ts` that serializes/deserializes `LoadoutState` to/from a JSON file on disk.\n\n## Why\n\n`SkillGraphServer` holds loadout state in memory (Maps, Sets). The MCP server kept a long-lived process, but CLI commands are ephemeral. We need to persist state between CLI invocations so that `loadout add`, `loadout expand`, etc. have continuity.\n\n## What to Build\n\nA `LoadoutStatePersistence` class with:\n\n```typescript\ninterface PersistedLoadoutState {\n  available: Array<{ id: string; skill: Skill }>;  // Map serialized as array\n  expanded: string[];                                // Set serialized as array\n  pending: string[];                                 // Set serialized as array\n  source: LoadoutSource;\n  updatedAt: string;                                 // ISO date string\n}\n\nclass LoadoutStatePersistence {\n  constructor(private filePath: string) {}\n  \n  save(state: LoadoutState): void\n  load(): LoadoutState | null\n  clear(): void\n  exists(): boolean\n}\n```\n\n### Serialization Details\n\n- `LoadoutState.available` is `Map<string, Skill>` -- serialize as array of `{id, skill}` pairs\n- `LoadoutState.expanded` is `Set<string>` -- serialize as `string[]`\n- `LoadoutState.pending` is `Set<string>` -- serialize as `string[]`\n- `LoadoutState.updatedAt` is `Date` -- serialize as ISO string\n- `Skill` objects contain `Date` fields (`createdAt`, `updatedAt`) -- handle date revival on load\n\n### Default File Location\n\nThe state file should be stored at `{skillStoragePath}/.loadout-state.json`. The path is passed into the constructor.\n\n### Error Handling\n\n- `load()` returns `null` if file does not exist or is corrupt (log warning, do not throw)\n- `save()` writes atomically (write to temp file, then rename) to prevent corruption\n- `clear()` deletes the file if it exists\n\n### Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/src/serving/types.ts` lines 113-124 for `LoadoutState` type\n- `/Users/alexngai/GitHub/skill-tree/src/serving/types.ts` lines 97-108 for `LoadoutSource` type\n- `/Users/alexngai/GitHub/skill-tree/src/types.ts` for `Skill` type (has Date fields)\n","status":"open","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:34:39","updated_at":"2026-03-03 22:34:39","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1t4g","from_type":"issue","to":"i-32xq","to_type":"issue","type":"blocks"},{"from":"i-1t4g","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","persistence","serving"]}
-{"id":"i-32xq","uuid":"b10a4a96-016f-4be8-8e2c-c384ea8daa74","title":"Create CLI loadout server factory utility","content":"\nCreate `src/cli/utils/loadout-server.ts` -- a factory that creates a `SkillGraphServer` wired to filesystem storage with state persistence for CLI use.\n\n## Why\n\nEvery loadout CLI subcommand needs to: initialize storage, create a `SkillGraphServer`, load persisted state, perform an operation, then save state. This utility centralizes that boilerplate.\n\n## What to Build\n\n```typescript\ninterface LoadoutServerHandle {\n  server: SkillGraphServer;\n  save(): void;   // Persist current state to disk\n  storage: FilesystemStorageAdapter;\n}\n\ninterface LoadoutServerOptions extends GlobalOptions {\n  maxExpanded?: number;\n  autoExpandOnUse?: boolean;\n}\n\nasync function createLoadoutServer(options: LoadoutServerOptions): Promise<LoadoutServerHandle>\n```\n\n### Implementation Steps\n\n1. Resolve skill path using `resolveSkillPath(options.path)` and `ensureDir()`\n2. Create `FilesystemStorageAdapter({ basePath: skillPath })` and initialize it\n3. Create `SkillGraphServer(storage, config)` with sensible defaults:\n   - `agentCanModify: true`\n   - `agentCanSetLoadout: true` (CLI user is the orchestrator, not an agent)\n   - `agentCanSwitchProfile: true`\n   - `requireApproval: false`\n   - `autoExpandOnUse: options.autoExpandOnUse ?? true`\n   - `autoExpandRelated: false`\n   - `maxExpanded: options.maxExpanded ?? 5`\n4. Initialize the server via `server.initialize()`\n5. Create `LoadoutStatePersistence` with path `{skillPath}/.loadout-state.json`\n6. If persisted state exists, restore it into the server:\n   - Call `server.addSkills()` for available skills\n   - Call `server.expandSkill()` for expanded skills\n   - (Pending skills are edge cases in CLI -- include for completeness)\n7. Return `{ server, save: () => persistence.save(server.getState()), storage }`\n\n### Design Decision: Orchestrator vs Agent API\n\nIn the CLI context, the human IS the orchestrator. The CLI commands should use the **orchestrator API** (`setLoadout`, `addSkills`, `removeSkills`, `expandSkill`, `collapseSkill`) rather than the **agent API** (`agentRequestSkills`, etc.) since there is no approval workflow needed. The `loadout search` command can still use `agentSearchSkills` since it is a read-only query.\n\n### Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/src/cli/utils/skillbank.ts` -- pattern to follow for factory function\n- `/Users/alexngai/GitHub/skill-tree/src/cli/utils/paths.ts` -- `resolveSkillPath`, `ensureDir`\n- `/Users/alexngai/GitHub/skill-tree/src/cli/commands/mcp.ts` -- current server setup to migrate from (lines 32-50)\n- `/Users/alexngai/GitHub/skill-tree/src/serving/graph-server.ts` -- `SkillGraphServer` constructor and API\n","status":"blocked","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:34:57","updated_at":"2026-03-03 22:37:08","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-32xq","from_type":"issue","to":"i-6xvy","to_type":"issue","type":"blocks"},{"from":"i-32xq","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","serving","utility"]}
-{"id":"i-6xvy","uuid":"4301dc22-a75d-4d3c-a4e3-ffe7cd4461bb","title":"Create loadout CLI command group with all subcommands","content":"\nCreate the `loadout` command group under `src/cli/commands/loadout/` with subcommands that replace all 10 MCP tools plus a few convenience commands.\n\n## Files to Create\n\n### `src/cli/commands/loadout/index.ts`\nCommand group container, following the pattern from `src/cli/commands/indexer/index.ts`:\n\n```typescript\nimport { Command } from 'commander';\nimport { listSubcommand } from './list.js';\nimport { searchSubcommand } from './search.js';\n// ... etc\n\nexport const loadoutCommand = new Command('loadout')\n  .description('Manage skill loadout - select, expand, and organize skills for agent use')\n  .addCommand(listSubcommand)\n  .addCommand(searchSubcommand)\n  .addCommand(addSubcommand)\n  .addCommand(removeSubcommand)\n  .addCommand(profileSubcommand)\n  .addCommand(setSubcommand)\n  .addCommand(expandSubcommand)\n  .addCommand(collapseSubcommand)\n  .addCommand(useSubcommand)\n  .addCommand(getSubcommand)\n  .addCommand(renderSubcommand)\n  .addCommand(clearSubcommand);\n```\n\n### Subcommand Files\n\nEach file follows the established pattern from existing commands like `list.ts`, `show.ts`, `search.ts`.\n\n#### `src/cli/commands/loadout/list.ts` -- maps to MCP `loadout_list`\n```\nskill-tree loadout list [--filter <all|expanded|available|pending>] [--json]\n```\n- Calls `server.agentListLoadout()` (returns `LoadoutView`)\n- Formats output showing available skills with expansion state, pending IDs, available profiles\n- JSON mode outputs the raw `LoadoutView` object\n\n#### `src/cli/commands/loadout/search.ts` -- maps to MCP `loadout_search`\n```\nskill-tree loadout search <query> [--limit <n>]\n```\n- Calls `server.agentSearchSkills(query, limit)`\n- Shows results as `SkillSummary[]` with id, name, description, tags\n- Distinct from top-level `skill-tree search` which searches raw storage\n\n#### `src/cli/commands/loadout/add.ts` -- maps to MCP `loadout_add`\n```\nskill-tree loadout add <skill-ids...>\n```\n- Calls `server.addSkills(skillIds)` (orchestrator API, no approval needed)\n- Persists state after mutation\n- Shows confirmation with updated loadout summary\n\n#### `src/cli/commands/loadout/remove.ts` -- maps to MCP `loadout_remove`\n```\nskill-tree loadout remove <skill-ids...>\n```\n- Calls `server.removeSkills(skillIds)`\n- Persists state after mutation\n- Shows confirmation\n\n#### `src/cli/commands/loadout/profile.ts` -- maps to MCP `loadout_profile`\n```\nskill-tree loadout profile <name>\nskill-tree loadout profile --list\n```\n- `--list` flag: calls `server.getProfiles()` and lists all available profiles with descriptions\n- Without `--list`: calls `server.setLoadoutFromProfile(name)`\n- Persists state after switching\n- Shows the new loadout view\n\n#### `src/cli/commands/loadout/set.ts` -- maps to MCP `loadout_set`\n```\nskill-tree loadout set [--tags <tags...>] [--tags-all <tags...>] [--task <description>] [--max-skills <n>]\n```\n- Builds `LoadoutCriteria` from options\n- Calls `server.setLoadout(criteria)`\n- Persists state after mutation\n- Shows the resulting loadout\n\n#### `src/cli/commands/loadout/expand.ts` -- maps to MCP `skill_expand`\n```\nskill-tree loadout expand <skill-id>\n```\n- Calls `server.expandSkill(skillId)`\n- Gets the full skill from `server.getState().available.get(skillId)`\n- Displays full skill content using `formatSkillDetail()` from output utils\n- Persists state\n\n#### `src/cli/commands/loadout/collapse.ts` -- maps to MCP `skill_collapse`\n```\nskill-tree loadout collapse <skill-id>\n```\n- Calls `server.collapseSkill(skillId)`\n- Shows confirmation\n- Persists state\n\n#### `src/cli/commands/loadout/use.ts` -- maps to MCP `skill_use`\n```\nskill-tree loadout use <skill-id>\n```\n- Calls `server.recordUsage(skillId)` (this auto-expands if configured)\n- Gets and displays the skill content\n- Persists state\n\n#### `src/cli/commands/loadout/get.ts` -- maps to MCP `skill_get`\n```\nskill-tree loadout get <skill-id>\n```\n- Checks `server.getState()` for the skill\n- If expanded: shows full detail\n- If available but not expanded: shows summary only (id, name, description, tags)\n- If not in loadout: shows \"not found in loadout\"\n\n#### `src/cli/commands/loadout/render.ts` -- new, exposes `renderSystemPrompt()`\n```\nskill-tree loadout render [--format <xml|markdown>]\n```\n- Calls `server.renderSystemPrompt()` \n- Outputs the rendered content to stdout (useful for piping into agent configs)\n\n#### `src/cli/commands/loadout/clear.ts` -- new convenience command\n```\nskill-tree loadout clear\n```\n- Clears the persisted loadout state file\n- Shows confirmation\n\n## Command Pattern\n\nEach subcommand should follow this pattern:\n\n```typescript\nexport const xxxSubcommand = new Command('xxx')\n  .description('...')\n  .argument(...)  // if needed\n  .option(...)    // if needed\n  .action(async (args, options, command) => {\n    const globalOpts = command.optsWithGlobals() as GlobalOptions;\n    try {\n      const { server, save } = await createLoadoutServer(globalOpts);\n      // ... perform operation ...\n      save();  // if state was mutated\n      // ... format and print output ...\n    } catch (error) {\n      printError((error as Error).message);\n      process.exit(1);\n    }\n  });\n```\n\n## Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/src/cli/commands/indexer/index.ts` -- command group pattern\n- `/Users/alexngai/GitHub/skill-tree/src/cli/commands/config.ts` -- subcommand pattern (inline)\n- `/Users/alexngai/GitHub/skill-tree/src/cli/commands/list.ts` -- standard command pattern\n- `/Users/alexngai/GitHub/skill-tree/src/cli/commands/show.ts` -- detail display pattern\n- `/Users/alexngai/GitHub/skill-tree/src/mcp/handlers.ts` -- exact logic to replicate for each command\n- `/Users/alexngai/GitHub/skill-tree/src/serving/graph-server.ts` -- server API methods\n","status":"blocked","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:35:25","updated_at":"2026-03-03 22:37:09","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-6xvy","from_type":"issue","to":"i-3sx0","to_type":"issue","type":"blocks"},{"from":"i-6xvy","from_type":"issue","to":"i-8ooa","to_type":"issue","type":"blocks"},{"from":"i-6xvy","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","commands","loadout"]}
-{"id":"i-6lva","uuid":"07351672-7121-4210-8ac7-b940f8dba901","title":"Add loadout output formatting helpers","content":"\nAdd formatting functions to `src/cli/utils/output.ts` for displaying loadout-specific data types in the CLI.\n\n## Why\n\nThe existing output utilities format `Skill`, `SkillVersion`, and `SkillBankStats`. The loadout commands need formatters for `LoadoutView`, `SkillSummary`, and search results.\n\n## Functions to Add\n\n### `formatLoadoutView(view: LoadoutView): string`\nFormats the full loadout view for `loadout list`:\n```\nSkill Loadout (3 skills, 1 expanded)\n──────────────────────────────────────────────────\n  [expanded] skill-id-1  Skill Name 1  [tag1, tag2]\n  [available] skill-id-2  Skill Name 2  [tag3]\n  [available] skill-id-3  Skill Name 3  [tag1, tag4]\n\nPending: skill-id-4, skill-id-5\n\nProfiles: code-review, debugging, security, testing, ...\n```\n\nUse chalk coloring consistent with the existing `formatStatus` function:\n- `expanded` state in green\n- `available` state in dim/gray  \n- `pending` in yellow\n\n### `formatSkillSummaryLine(summary: SkillSummary): string`\nSingle-line format for a skill summary:\n```\n  [expanded] skill-id  Skill Name  Short description text  [tag1, tag2]\n```\n\n### `formatSearchResults(results: SkillSummary[], query: string): string`\nFormats search results for `loadout search`:\n```\nResults for \"authentication\" (3 found):\n\n  auth-flow       Authentication Flow     Handle OAuth2 login flows    [auth, security]\n  token-refresh   Token Refresh           Manage JWT token lifecycle   [auth, tokens]\n  session-mgmt    Session Management      Server-side session handling [auth, session]\n```\n\n### `formatProfileList(profiles: string[]): string`\nFormats available profiles for `loadout profile --list`:\n```\nAvailable Profiles:\n  code-review     Code quality, security, and best practices\n  implementation  Writing new code and features\n  debugging       Diagnosing and fixing bugs\n  security        Vulnerability detection and secure coding\n  testing         Writing and maintaining tests\n  refactoring     Improving existing code\n  documentation   Writing and maintaining documentation\n  devops          Infrastructure and deployment\n```\n\n## Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/src/cli/utils/output.ts` -- existing formatting functions to extend\n- `/Users/alexngai/GitHub/skill-tree/src/serving/types.ts` lines 133-156 -- `SkillSummary` and `LoadoutView` types\n- `/Users/alexngai/GitHub/skill-tree/src/serving/profiles/index.ts` -- profile names and descriptions for the profile list formatter\n","status":"open","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:35:43","updated_at":"2026-03-03 22:35:43","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-6lva","from_type":"issue","to":"i-6xvy","to_type":"issue","type":"blocks"},{"from":"i-6lva","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","formatting","output"]}
-{"id":"i-8ooa","uuid":"50f7480b-2f67-46f7-98d6-b81ca42c56c4","title":"Wire loadout command into CLI and remove MCP command","content":"\nUpdate `src/cli/index.ts` to register the new `loadout` command group and remove the `mcp` command.\n\n## Changes to `src/cli/index.ts`\n\n1. Remove the import: `import { mcpCommand } from './commands/mcp.js';`\n2. Remove the registration: `program.addCommand(mcpCommand);`\n3. Add the import: `import { loadoutCommand } from './commands/loadout/index.js';`\n4. Add the registration: `program.addCommand(loadoutCommand);`\n\n## File to Delete\n\n- `src/cli/commands/mcp.ts` -- the entire file is no longer needed\n\n## Key Reference\n\n- `/Users/alexngai/GitHub/skill-tree/src/cli/index.ts` -- lines 26, 60 to modify\n","status":"blocked","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:35:51","updated_at":"2026-03-03 22:37:11","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-8ooa","from_type":"issue","to":"i-4l08","to_type":"issue","type":"blocks"},{"from":"i-8ooa","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","wiring"]}
-{"id":"i-4l08","uuid":"9b4eba35-daab-4be7-809a-7135de8b38f6","title":"Remove MCP module, exports, and tests","content":"\nDelete the `src/mcp/` directory and all references to it throughout the codebase.\n\n## Files to Delete\n\n- `src/mcp/handlers.ts`\n- `src/mcp/index.ts`\n- `src/mcp/server.ts`\n- `src/mcp/tools/index.ts`\n- `src/mcp/tools/loadout-tools.ts`\n- `src/mcp/tools/skill-tools.ts`\n- `test/mcp.test.ts`\n\n## Files to Modify\n\n### `src/index.ts`\n\nRemove the entire MCP export block (lines 386-416):\n\n```typescript\n// DELETE THIS ENTIRE BLOCK:\n// MCP Tools and Server\nexport {\n  // Tool definitions\n  loadoutListTool,\n  loadoutSearchTool,\n  loadoutAddTool,\n  loadoutRemoveTool,\n  loadoutProfileTool,\n  loadoutSetTool,\n  loadoutTools,\n  skillExpandTool,\n  skillCollapseTool,\n  skillUseTool,\n  skillGetTool,\n  skillTools,\n  allTools,\n  getToolDefinition,\n  getToolNames,\n  type ToolDefinition,\n  // Handlers\n  createToolHandlers,\n  executeToolCall,\n  type ToolHandler,\n  type McpToolResult,\n  // Server\n  SkillTreeMcpServer,\n  createMcpServer,\n  type McpServerConfig,\n} from \"./mcp/index.js\";\n```\n\nNote: The `ToolDefinition` type is defined in `src/serving/types.ts` and already exported from `src/serving/index.ts`, so it remains available via the serving export block (line 343: `type ToolDefinition`). However, since it is an MCP-specific concept, consider whether to keep or remove it from `src/serving/types.ts`. The type itself is generic enough to keep -- it describes any tool schema. If removed, it is 12 lines (269-280) in `src/serving/types.ts` and its re-export from `src/serving/index.ts` line 28 and `src/index.ts` line 343 (under the serving section, which is separate from the MCP section being deleted). **Recommendation: keep `ToolDefinition` in serving types for now since it is a generic schema type.**\n\n### `test/serving.test.ts`\n\nRemove the MCP-specific imports (lines 17-26):\n```typescript\n// DELETE these imports:\n  // MCP tools\n  allTools,\n  getToolDefinition,\n  getToolNames,\n  loadoutListTool,\n  skillExpandTool,\n  // MCP handlers and server\n  createToolHandlers,\n  executeToolCall,\n  createMcpServer,\n```\n\nRemove the MCP test sections. These are clearly marked with section headers:\n- Lines ~1634-1659: \"MCP Tools Tests\" section\n- Lines ~1715-1835: \"MCP Handlers Tests\" section  \n- Lines ~1843-1955: \"MCP Server Tests\" section\n- Lines ~1960-2402: Additional handler tests that use `createToolHandlers`\n\nThe non-MCP serving tests (LoadoutCompiler, ViewRenderer, ProjectDetector, SkillGraphServer, Profiles, Events) from lines 1-~1632 should remain intact.\n\n**Careful**: Some later tests (after line 1960) test handler behavior for things like `loadout_list` filters and `skill_expand`/`skill_collapse` interactions. These tests exercise MCP handlers but the underlying logic they test is in `SkillGraphServer` which already has its own test coverage in the earlier sections. Verify no unique business logic coverage is lost -- if so, migrate those test cases to use `SkillGraphServer` methods directly instead of handler wrappers.\n\n### `test/run-all.ts`\n\nThis file does NOT include `mcp.test.ts` (it was not added to the legacy runner). No changes needed here.\n\n## Verification\n\nAfter removal:\n1. `npx tsc --noEmit` should pass (no dangling imports)\n2. `npm test` should pass (no broken test imports)\n3. `npm run build` should succeed\n\n## Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/src/index.ts` -- lines 386-416 to remove\n- `/Users/alexngai/GitHub/skill-tree/src/mcp/` -- 6 files to delete\n- `/Users/alexngai/GitHub/skill-tree/test/mcp.test.ts` -- delete\n- `/Users/alexngai/GitHub/skill-tree/test/serving.test.ts` -- lines 17-26 imports, lines 1634-2402 test sections\n","status":"blocked","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:36:17","updated_at":"2026-03-03 22:37:11","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-4l08","from_type":"issue","to":"i-5bru","to_type":"issue","type":"blocks"},{"from":"i-4l08","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cleanup","mcp-removal"]}
-{"id":"i-3sx0","uuid":"c4e912f5-9910-4478-8b87-691467846650","title":"Write tests for loadout CLI commands and state persistence","content":"\nCreate `test/loadout-cli.test.ts` with comprehensive tests for the new loadout CLI infrastructure.\n\n## Test Sections\n\n### 1. State Persistence Tests\n\n```\ndescribe('LoadoutStatePersistence')\n  - saves and loads state roundtrip (Map/Set serialization)\n  - returns null for missing file\n  - returns null for corrupt JSON (does not throw)\n  - handles Date serialization/deserialization in Skill objects\n  - clear() removes the file\n  - exists() returns correct boolean\n  - atomic write (write to temp, rename)\n```\n\n### 2. Loadout Server Factory Tests\n\n```\ndescribe('createLoadoutServer')\n  - creates server with filesystem storage\n  - loads persisted state on initialization\n  - save() persists current state\n  - works with empty/fresh storage directory\n  - respects maxExpanded option\n```\n\n### 3. Command Logic Tests\n\nTest the core logic of each subcommand by directly using the `SkillGraphServer` API (same way MCP handlers were tested). Use `MemoryStorageAdapter` for speed.\n\n```\ndescribe('loadout list')\n  - lists empty loadout\n  - lists loadout with available and expanded skills\n  - filter=expanded shows only expanded\n  - filter=available shows only non-expanded\n  - filter=pending shows pending skills\n\ndescribe('loadout search')\n  - finds skills matching query\n  - respects limit option\n  - returns empty for no matches\n\ndescribe('loadout add')\n  - adds skills to loadout\n  - adding duplicate is idempotent\n\ndescribe('loadout remove')\n  - removes skills from loadout\n  - removes from expanded set too\n\ndescribe('loadout profile')\n  - switches to named profile\n  - lists available profiles\n  - errors on unknown profile\n\ndescribe('loadout set')\n  - sets loadout from tag criteria\n  - sets loadout from task description\n  - respects max-skills limit\n\ndescribe('loadout expand')\n  - expands skill in loadout\n  - errors for skill not in loadout\n  - evicts LRU when maxExpanded reached\n\ndescribe('loadout collapse')\n  - collapses expanded skill\n  - no-op for already collapsed\n\ndescribe('loadout use')\n  - records usage and auto-expands\n  - returns skill content\n\ndescribe('loadout get')\n  - returns full detail for expanded skill\n  - returns summary for available skill\n  - returns null for skill not in loadout\n\ndescribe('loadout render')\n  - renders XML format\n  - renders markdown format\n\ndescribe('loadout clear')\n  - removes state file\n  - subsequent load returns empty state\n```\n\n### Test Helpers\n\nReuse the `createTestSkill` helper pattern from `test/serving.test.ts` and `test/mcp.test.ts`. Use `MemoryStorageAdapter` for in-memory tests. For persistence tests, use a temp directory (cleaned up in afterEach).\n\n## Key Reference Files\n\n- `/Users/alexngai/GitHub/skill-tree/test/serving.test.ts` -- test patterns and helpers\n- `/Users/alexngai/GitHub/skill-tree/test/mcp.test.ts` -- MCP handler tests to migrate/adapt\n- `/Users/alexngai/GitHub/skill-tree/test/cli.test.ts` -- existing CLI test patterns (if any)\n","status":"blocked","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:36:36","updated_at":"2026-03-03 22:37:12","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3sx0","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["cli","loadout","testing"]}
-{"id":"i-5bru","uuid":"d8752083-9317-47c3-827d-955b5f2fbf5a","title":"Update documentation (CLAUDE.md) for MCP removal and new loadout CLI","content":"\nUpdate `CLAUDE.md` to reflect the removal of MCP and addition of the loadout CLI command group.\n\n## Changes to CLAUDE.md\n\n### Architecture Tree\n\nRemove `src/mcp/` from the tree. Add `loadout/` under `src/cli/commands/`:\n\n```\nsrc/\n├── cli/\n│   ├── commands/\n│   │   ├── loadout/        # NEW: Loadout management commands\n│   │   │   ├── index.ts    # Command group container\n│   │   │   ├── list.ts     # List loadout skills\n│   │   │   ├── search.ts   # Search for skills to add\n│   │   │   ├── add.ts      # Add skills to loadout\n│   │   │   ├── remove.ts   # Remove skills from loadout\n│   │   │   ├── profile.ts  # Switch loadout profile\n│   │   │   ├── set.ts      # Set loadout from criteria\n│   │   │   ├── expand.ts   # Expand skill to full content\n│   │   │   ├── collapse.ts # Collapse skill to summary\n│   │   │   ├── use.ts      # Record skill usage\n│   │   │   ├── get.ts      # Get skill details\n│   │   │   ├── render.ts   # Render loadout as system prompt\n│   │   │   └── clear.ts    # Clear persisted state\n│   │   ├── list.ts, show.ts, search.ts, ...\n│   │   └── indexer/\n│   └── utils/\n│       ├── loadout-server.ts  # NEW: Loadout server factory\n│       ├── output.ts\n│       ├── paths.ts\n│       └── skillbank.ts\n├── serving/\n│   ├── state-persistence.ts   # NEW: Loadout state persistence\n│   └── ...\n```\n\n### Remove MCP References\n\n- Remove `mcp` from the CLI commands list in the Key Architecture section\n- Remove any mention of MCP server or JSON-RPC\n\n### Add Loadout CLI Section\n\nAdd a new section documenting the loadout commands:\n\n```markdown\n## Loadout Management CLI\n\nThe `loadout` command group manages skill loadouts -- curated sets of skills for agent use.\nState is persisted to `{skillPath}/.loadout-state.json` between invocations.\n\n### Commands\n\n```bash\n# View current loadout\nskill-tree loadout list [--filter expanded|available|pending]\n\n# Search for skills to add\nskill-tree loadout search <query> [--limit 5]\n\n# Add/remove skills\nskill-tree loadout add <skill-ids...>\nskill-tree loadout remove <skill-ids...>\n\n# Profile management\nskill-tree loadout profile <name>\nskill-tree loadout profile --list\n\n# Set loadout from criteria\nskill-tree loadout set --tags auth security --max-skills 10\n\n# Expand/collapse individual skills\nskill-tree loadout expand <skill-id>\nskill-tree loadout collapse <skill-id>\n\n# Record skill usage (auto-expands)\nskill-tree loadout use <skill-id>\n\n# Get skill details (respects expansion state)\nskill-tree loadout get <skill-id>\n\n# Render for agent consumption\nskill-tree loadout render [--format xml|markdown]\n\n# Clear persisted state\nskill-tree loadout clear\n```\n```\n\n### Update Important Files\n\nUpdate the Important Files list:\n- Remove any MCP file references\n- Add `src/cli/commands/loadout/index.ts` as the loadout CLI entry point\n- Add `src/serving/state-persistence.ts` as the persistence layer\n\n### Update Common Tasks\n\n- Remove \"Adding MCP tools\" task if present\n- Add a task for \"Adding a loadout subcommand\"\n\n## Key Reference File\n\n- `/Users/alexngai/GitHub/skill-tree/CLAUDE.md` -- the file to update\n","status":"blocked","priority":3,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:36:56","updated_at":"2026-03-03 22:37:12","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-5bru","from_type":"issue","to":"s-7pu7","to_type":"spec","type":"implements"}],"tags":["documentation"]}

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

@@ -1,3 +0,0 @@
-{"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"]}
-{"id":"s-7pu7","uuid":"77b52caa-2dc2-4577-b4f2-c84bbef7e45d","title":"Remove MCP Server and Expose Loadout/Skill Operations via CLI","file_path":"specs/s-7pu7_remove_mcp_server_and_expose_loadout_skill_operati.md","content":"\n## Goal\n\nRemove the `src/mcp/` directory and associated exports, replacing all MCP tool functionality with CLI commands under a new `loadout` command group and `skill` subcommands. The serving layer (`src/serving/`) and its tests remain intact.\n\n## Background\n\nThe MCP server wraps `SkillGraphServer` providing 10 tools via JSON-RPC 2.0:\n- 6 loadout tools: `loadout_list`, `loadout_search`, `loadout_add`, `loadout_remove`, `loadout_profile`, `loadout_set`\n- 4 skill tools: `skill_expand`, `skill_collapse`, `skill_use`, `skill_get`\n\nThese operate on **stateful loadout state** (expand/collapse, add/remove from loadout). The CLI must persist this state between invocations.\n\n## Key Challenge: State Persistence\n\nMCP tools operate on in-memory `SkillGraphServer` state within a long-lived process. CLI commands are stateless invocations. Solution: persist loadout state to a JSON file alongside the skill storage, loading it at command start and saving after mutations.\n\n## What to Remove\n\n1. `src/mcp/` directory (6 files)\n2. `src/cli/commands/mcp.ts`\n3. MCP exports from `src/index.ts` (lines 386-416)\n4. MCP import in `src/cli/index.ts` \n5. `test/mcp.test.ts`\n6. MCP-specific test sections from `test/serving.test.ts` (lines 1634-1955 approximately)\n7. `ToolDefinition` type can remain in `src/serving/types.ts` (it is a generic type used for tool schemas)\n\n## What to Add\n\n### State Persistence Layer\n\nNew file: `src/serving/state-persistence.ts`\n- `LoadoutStatePersistence` class\n- `saveState(state: LoadoutState, filePath: string)`: Serializes Map/Set to JSON\n- `loadState(filePath: string): LoadoutState | null`: Deserializes back\n- Default file location: `{skillPath}/.loadout-state.json`\n\n### CLI Command Group: `loadout`\n\nNew file: `src/cli/commands/loadout/index.ts` - Command group container\n\nSubcommands (each a separate file under `src/cli/commands/loadout/`):\n\n1. **`loadout list`** - maps to `loadout_list`\n   - Options: `--filter <all|expanded|available|pending>`\n   - Displays loadout with expansion status, pending requests, available profiles\n\n2. **`loadout search <query>`** - maps to `loadout_search`\n   - Arguments: `<query>` (required)\n   - Options: `--limit <n>` (default: 5)\n   - Searches all skills, shows results with summary info\n\n3. **`loadout add <skill-ids...>`** - maps to `loadout_add`\n   - Arguments: variadic `<skill-ids...>`\n   - Adds skills to current loadout\n\n4. **`loadout remove <skill-ids...>`** - maps to `loadout_remove`\n   - Arguments: variadic `<skill-ids...>`\n   - Removes skills from loadout\n\n5. **`loadout profile <name>`** - maps to `loadout_profile`\n   - Arguments: `<name>` (required)\n   - Options: `--list` (list available profiles without switching)\n   - Switches loadout to a named profile\n\n6. **`loadout set`** - maps to `loadout_set`\n   - Options: `--tags <tags...>`, `--tags-all <tags...>`, `--task <description>`, `--max-skills <n>`\n   - Sets loadout from criteria\n\n7. **`loadout render`** - maps to `renderSystemPrompt()`\n   - Options: `--format <xml|markdown>` (default: xml)\n   - Renders current loadout as system prompt content\n\n8. **`loadout clear`** - new convenience command\n   - Clears the persisted loadout state\n\n### CLI Subcommands under `skill` (expand existing `show`):\n\nNew file: `src/cli/commands/loadout/skill-ops.ts`\n\nThese are registered as subcommands of the `loadout` group:\n\n9. **`loadout expand <skill-id>`** - maps to `skill_expand`\n   - Expands a skill in the loadout, shows full content\n\n10. **`loadout collapse <skill-id>`** - maps to `skill_collapse`\n    - Collapses a skill back to summary\n\n11. **`loadout use <skill-id>`** - maps to `skill_use`\n    - Records skill usage, auto-expands\n\n12. **`loadout get <skill-id>`** - maps to `skill_get`\n    - Gets skill details (respects expansion state)\n\n### CLI Utility: Server Factory\n\nNew file: `src/cli/utils/loadout-server.ts`\n- `createLoadoutServer(options: GlobalOptions)`: Creates a `SkillGraphServer` with state persistence\n  - Initializes `FilesystemStorageAdapter`\n  - Loads persisted state if it exists\n  - Returns `{ server, save() }` where `save()` persists current state\n\n### Output Formatting\n\nAdd to `src/cli/utils/output.ts`:\n- `formatLoadoutView(view: LoadoutView)`: Formats loadout listing\n- `formatSkillSummary(summary: SkillSummary)`: Formats skill summary line\n- `formatSearchResult(results: SkillSummary[])`: Formats search results\n\n### Tests\n\nNew file: `test/loadout-cli.test.ts`\n- Tests for state persistence (save/load roundtrip)\n- Tests for each CLI subcommand's logic\n- Tests that verify the loadout server factory works correctly\n\n## Implementation Sequence\n\n1. Create state persistence layer\n2. Create loadout server factory utility\n3. Create loadout command group with all subcommands\n4. Add output formatting helpers\n5. Wire up loadout command in CLI index\n6. Remove MCP module, exports, and tests\n7. Clean up serving test (remove MCP sections)\n8. Update CLAUDE.md documentation\n9. Write new tests\n10. Verify build and all tests pass\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:34:24","updated_at":"2026-03-03 22:34:24","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["cli","mcp-removal","refactoring","serving"]}
-{"id":"s-41re","uuid":"3b19887e-c6e3-4d4e-a7a5-9f0230a6c7ff","title":"Refactor storage configuration: rename types, add SQLite to SkillBank, add fallback logic","file_path":"specs/s-41re_refactor_storage_configuration_rename_types_add_sq.md","content":"## Summary\n\nRefactor the storage configuration layer so that:\n1. `'memory'` is removed from user-facing config type unions (but MemoryStorageAdapter remains available for programmatic/test use)\n2. `'filesystem'` is renamed to `'json'` in config type strings\n3. SQLite becomes the primary/default storage and is wired into SkillBankConfig and the SkillBank constructor\n4. Graceful fallback: if `better-sqlite3` fails to load, automatically fall back to the `json` (filesystem) adapter\n5. CLI uses `sqlite` by default\n\n## Motivation\n\nThe current codebase has a fully implemented `SQLiteStorageAdapter` that is never instantiated by `SkillBank`. The global config already defaults to `'sqlite'`, but `SkillBankConfig` only supports `'memory'` and `'filesystem'`. This mismatch means the default config cannot actually be used. The rename of `'filesystem'` to `'json'` clarifies that this is a flat-file format option rather than implying SQLite is not filesystem-based.\n\n## Constraints\n- MemoryStorageAdapter must remain importable and functional for tests\n- The fallback from SQLite to JSON should be graceful (try/catch around dynamic import or instantiation of better-sqlite3)\n- Do not change the actual filesystem adapter's serialization format (still YAML+Markdown SKILL.md files)\n- Minimize test changes -- most tests use MemoryStorageAdapter directly via `{ type: 'memory' }` in SkillBankConfig","priority":1,"archived":0,"archived_at":null,"created_at":"2026-03-03 22:44:00","updated_at":"2026-03-03 22:44:00","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["config","refactor","storage"]}

package/references/skill-tree/CLAUDE.md

@@ -1,126 +0,0 @@
-# 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 provides versioned skill storage, a serving layer for dynamic loadouts, multi-agent sync, and federation across repositories.
-
-## Key Architecture
-
-```
-src/
-├── index.ts              # Main exports (barrel)
-├── skill-bank.ts         # Main orchestrator (SkillBank class)
-├── types.ts              # Core type definitions
-├── adapters/             # Session format adapters (Claude Code, OpenAI, etc.) — standalone utilities, not wired into SkillBank
-├── storage/              # Storage adapters (memory, cached filesystem+SQLite)
-├── versioning/           # Lineage tracking, version management, skill merging
-├── hooks/                # Event hooks and hook registry
-├── agents/               # AGENTS.md generation, parsing, and bidirectional sync
-├── serving/              # Serving layer (loadouts, profiles, token budgeting)
-├── federation/           # Remote repository connections and skill sharing
-├── sync/                 # Git-based multi-agent sync
-├── config/               # Configuration loading
-├── services/             # Indexer and sync services
-├── import/               # Skill import utilities
-└── 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
-
-### SkillBank
-Main orchestrator. Unified interface for CRUD, versioning, serving, sync, and federation. Created via `createSkillBank(config)`.
-
-### SkillGraphServer
-Serving layer created via `bank.createServingLayer()`. Manages dynamic skill loadouts with expand/collapse, profiles, and token budgeting. Has separate orchestrator API and agent API.
-
-### Storage
-Two storage backends:
-- `MemoryStorageAdapter`: In-memory (for testing)
-- `CachedStorageAdapter`: JSON filesystem (source of truth) + SQLite cache (fast queries)
-
-### HookRegistry
-Async event hook system. Two levels:
-- `bank.on(handler)`: Simple synchronous event listeners for `skill:created/updated/deleted/deprecated`
-- `bank.getHookRegistry().register()`: Advanced async hooks with priority, filtering, and storage-level events (`storage:after-save`, `storage:after-delete`)
-
-## SkillBank Public API
-
-```
-Lifecycle:     initialize(), shutdown()
-CRUD:          getSkill(), listSkills(filter), searchSkills(), saveSkill(), deleteSkill(), deprecateSkill()
-Versioning:    createVersion(), forkSkill(), getVersionHistory(), getLineage(), rollbackSkill(), compareVersions()
-Events:        on(), off(), getEventHandlerCount()
-Utilities:     getStats(), exportAll(), importSkills()
-Accessors:     getStorage(), getHookRegistry()
-Serving:       createServingLayer()
-Sync:          sync (getter → SyncManager)
-Federation:    federation (getter → FederationManager)
-```
-
-## Development Commands
-
-```bash
-# Build
-npm run build
-
-# Run all tests
-npm test
-
-# Run specific test file
-npx vitest run test/skill-bank.test.ts
-
-# Type check
-npx tsc --noEmit
-```
-
-## Testing Patterns
-
-Tests use vitest with a custom test harness. Each test file wraps suites in `describe()/it()`:
-
-```typescript
-describe('My Feature', () => {
-  it('passes all tests', async () => {
-    const failed = await runTests();
-    expect(failed).toBe(0);
-  });
-});
-```
-
-Test utilities in `test/utils.ts`: `suite()`, `test()`, `assertEqual()`, `assertTrue()`, `assertNotNull()`, etc.
-
-## Important Files
-
-- `src/skill-bank.ts`: Main API entry point
-- `src/index.ts`: Public barrel exports
-- `src/serving/graph-server.ts`: Serving layer (loadouts, profiles)
-- `src/federation/federation-manager.ts`: Federation orchestrator
-- `src/sync/sync-manager.ts`: Git-based multi-agent sync
-- `src/hooks/registry.ts`: Hook registry for event-driven extensibility
-- `src/storage/cached.ts`: Cached storage adapter (JSON + SQLite)
-
-## 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
-
-## Known Pre-existing Type Errors
-
-`src/config/loader.ts` and `src/services/sync.ts` have type errors that predate recent refactors. These don't affect test runs.
-
-## References
-
-- [OpenSkills](https://github.com/numman-ali/openskills): Skill format inspiration
-- [Claudeception](https://github.com/blader/Claudeception): Quality gates concept