macro-agent 0.1.2 → 0.1.4

package/references/openteams/src/template/types.ts

@@ -1,200 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// Team Template Types
-// ─────────────────────────────────────────────────────────────
-// These mirror the macro-agent team template schema.
-// Generic multi-agent fields are top-level; system-specific
-// extensions live under namespaced keys (e.g. macro_agent).
-
-// --- Manifest (team.yaml) ---
-
-export interface TeamManifest {
-  name: string;
-  description?: string;
-  version: number;
-  roles: string[];
-  topology: TopologyConfig;
-  communication?: CommunicationConfig;
-
-  // Extension fields from other systems — stored but not interpreted
-  macro_agent?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-// --- Topology ---
-
-export interface TopologyConfig {
-  root: TopologyNode;
-  companions?: TopologyNode[];
-  spawn_rules?: Record<string, string[]>;
-}
-
-export interface TopologyNode {
-  role: string;
-  prompt?: string; // path to prompt file relative to template dir
-  config?: TopologyNodeConfig;
-}
-
-export interface TopologyNodeConfig {
-  model?: string;
-  [key: string]: unknown;
-}
-
-// --- Communication ---
-
-export interface CommunicationConfig {
-  enforcement?: "strict" | "permissive" | "audit";
-  channels?: Record<string, ChannelDefinition>;
-  subscriptions?: Record<string, SubscriptionEntry[]>;
-  emissions?: Record<string, string[]>;
-  routing?: RoutingConfig;
-}
-
-export interface ChannelDefinition {
-  description?: string;
-  signals: string[];
-}
-
-export interface SubscriptionEntry {
-  channel: string;
-  signals?: string[]; // if omitted, subscribes to all signals in channel
-}
-
-export interface RoutingConfig {
-  status?: "upstream" | "none";
-  peers?: PeerRoute[];
-}
-
-export interface PeerRoute {
-  from: string;
-  to: string;
-  via: "direct" | "topic" | "scope";
-  signals?: string[];
-}
-
-// --- Role Definition (roles/<name>.yaml) ---
-
-export interface RoleDefinition {
-  name: string;
-  extends?: string;
-  display_name?: string;
-  description?: string;
-  capabilities?: string[] | CapabilityComposition;
-  prompt?: string; // path to a single prompt file
-  prompts?: string[]; // ordered list of prompt files (relative to prompts/<role>/)
-
-  // Flat capability composition (alternative to CapabilityComposition inside capabilities).
-  // Only valid when `extends` is set. Mutually exclusive with CapabilityComposition in `capabilities`.
-  capabilities_add?: string[];
-  capabilities_remove?: string[];
-
-  // Extension fields
-  macro_agent?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-export interface CapabilityComposition {
-  add?: string[];
-  remove?: string[];
-}
-
-// --- Prompt Sections ---
-
-export interface PromptSection {
-  /** Filename stem, e.g. "soul", "guidelines", "prompt" */
-  name: string;
-  /** Markdown content of this section */
-  content: string;
-}
-
-export interface ResolvedPrompts {
-  /** The primary prompt content (from prompt.md or the single-file prompt) */
-  primary: string;
-  /** Additional prompt materials, in load order */
-  additional: PromptSection[];
-}
-
-// --- Resolved Template (fully loaded) ---
-
-export interface ResolvedTemplate {
-  manifest: TeamManifest;
-  roles: Map<string, ResolvedRole>;
-  prompts: Map<string, ResolvedPrompts>; // role name → structured prompts
-  mcpServers: Map<string, McpServerEntry[]>; // role name → MCP server entries
-  sourcePath: string;
-}
-
-export interface ResolvedRole {
-  name: string;
-  extends?: string;
-  displayName: string;
-  description: string;
-  capabilities: string[];
-  promptFile?: string;
-  promptFiles?: string[]; // explicit ordering from role YAML
-  raw: RoleDefinition; // original YAML for extension fields
-}
-
-// --- MCP Server Config ---
-
-export interface McpServerEntry {
-  name: string;
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-}
-
-// --- Load Options ---
-
-/**
- * Options for TemplateLoader.load() — all hooks are synchronous.
- */
-export interface LoadOptions {
-  /** Resolve a role that `extends` a name not found in the local roles map. */
-  resolveExternalRole?: (name: string) => ResolvedRole | null;
-  /** Post-process each role after inheritance resolution. */
-  postProcessRole?: (role: ResolvedRole, manifest: TeamManifest) => ResolvedRole;
-  /** Post-process the entire template after loading. */
-  postProcess?: (template: ResolvedTemplate) => ResolvedTemplate;
-}
-
-/**
- * Options for TemplateLoader.loadAsync() — hooks may return Promises.
- */
-export interface AsyncLoadOptions {
-  /** Resolve a role that `extends` a name not found in the local roles map. */
-  resolveExternalRole?: (name: string) => Promise<ResolvedRole | null> | ResolvedRole | null;
-  /** Post-process each role after inheritance resolution. */
-  postProcessRole?: (role: ResolvedRole, manifest: TeamManifest) => Promise<ResolvedRole> | ResolvedRole;
-  /** Post-process the entire template after loading. */
-  postProcess?: (template: ResolvedTemplate) => Promise<ResolvedTemplate> | ResolvedTemplate;
-}
-
-// --- Signal Event (emitted through channels) ---
-
-export interface SignalEvent {
-  id: number;
-  team_name: string;
-  channel: string;
-  signal: string;
-  sender: string;
-  payload: Record<string, unknown>;
-  created_at: string;
-}
-
-export interface SignalEventRow {
-  id: number;
-  team_name: string;
-  channel: string;
-  signal: string;
-  sender: string;
-  payload: string;
-  created_at: string;
-}
-
-export interface EmitSignalOptions {
-  teamName: string;
-  channel: string;
-  signal: string;
-  sender: string;
-  payload?: Record<string, unknown>;
-}

package/references/openteams/src/types.ts

@@ -1,205 +0,0 @@
-// --- Team Types ---
-
-export type EnforcementMode = "strict" | "permissive" | "audit";
-
-export interface Team {
-  name: string;
-  description: string | null;
-  agent_type: string | null;
-  template_name: string | null;
-  template_path: string | null;
-  enforcement: EnforcementMode;
-  created_at: string;
-  status: "active" | "deleted";
-}
-
-export interface CreateTeamOptions {
-  name: string;
-  description?: string;
-  agentType?: string;
-  templateName?: string;
-  templatePath?: string;
-}
-
-// --- Member Types ---
-
-export type MemberStatus = "idle" | "running" | "shutdown";
-
-export interface Member {
-  id: number;
-  team_name: string;
-  agent_name: string;
-  agent_id: string | null;
-  agent_type: string;
-  role: string | null;
-  status: MemberStatus;
-  spawn_prompt: string | null;
-  model: string | null;
-  created_at: string;
-}
-
-// --- Task Types ---
-
-export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
-
-export interface Task {
-  id: number;
-  team_name: string;
-  subject: string;
-  description: string;
-  active_form: string | null;
-  status: TaskStatus;
-  owner: string | null;
-  metadata: Record<string, unknown>;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface TaskRow {
-  id: number;
-  team_name: string;
-  subject: string;
-  description: string;
-  active_form: string | null;
-  status: TaskStatus;
-  owner: string | null;
-  metadata: string;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface CreateTaskOptions {
-  teamName: string;
-  subject: string;
-  description: string;
-  activeForm?: string;
-  blockedBy?: number[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface UpdateTaskOptions {
-  status?: TaskStatus;
-  subject?: string;
-  description?: string;
-  activeForm?: string;
-  owner?: string | null;
-  metadata?: Record<string, unknown>;
-  addBlocks?: number[];
-  addBlockedBy?: number[];
-}
-
-export interface TaskSummary {
-  id: number;
-  subject: string;
-  status: TaskStatus;
-  owner: string | null;
-  blockedBy: number[];
-}
-
-// --- Message Types ---
-
-export type MessageType =
-  | "message"
-  | "broadcast"
-  | "shutdown_request"
-  | "shutdown_response"
-  | "plan_approval_response";
-
-export interface Message {
-  id: number;
-  team_name: string;
-  type: MessageType;
-  sender: string;
-  recipient: string | null;
-  content: string;
-  summary: string | null;
-  request_id: string | null;
-  approve: boolean | null;
-  delivered: boolean;
-  created_at: string;
-}
-
-export interface MessageRow {
-  id: number;
-  team_name: string;
-  type: MessageType;
-  sender: string;
-  recipient: string | null;
-  content: string;
-  summary: string | null;
-  request_id: string | null;
-  approve: number | null;
-  delivered: number;
-  created_at: string;
-}
-
-export interface SendMessageOptions {
-  teamName: string;
-  sender: string;
-  recipient: string;
-  content: string;
-  summary: string;
-}
-
-export interface BroadcastMessageOptions {
-  teamName: string;
-  sender: string;
-  content: string;
-  summary: string;
-}
-
-export interface ShutdownRequestOptions {
-  teamName: string;
-  sender: string;
-  recipient: string;
-  reason?: string;
-}
-
-export interface ShutdownResponseOptions {
-  teamName: string;
-  sender: string;
-  requestId: string;
-  approve: boolean;
-  content?: string;
-}
-
-export interface PlanApprovalResponseOptions {
-  teamName: string;
-  sender: string;
-  recipient: string;
-  requestId: string;
-  approve: boolean;
-  content?: string;
-}
-
-// --- Agent Spawner Types ---
-
-export interface SpawnAgentOptions {
-  name: string;
-  teamName: string;
-  prompt: string;
-  agentType?: string;
-  model?: string;
-  cwd?: string;
-  env?: Record<string, string>;
-  permissionMode?: "auto-approve" | "auto-deny" | "interactive";
-}
-
-export interface AgentUpdate {
-  type: "text" | "tool_call" | "thought" | "error" | "done";
-  content: string;
-}
-
-export interface AgentInstance {
-  id: string;
-  name: string;
-  isRunning(): boolean;
-  sendPrompt(prompt: string): AsyncIterable<AgentUpdate>;
-  shutdown(): Promise<void>;
-}
-
-export interface AgentSpawner {
-  spawn(options: SpawnAgentOptions): Promise<AgentInstance>;
-  shutdown(agentId: string): Promise<void>;
-  list(): AgentInstance[];
-}

package/references/openteams/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "declaration": true,
-    "strict": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "sourceMap": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}

package/references/openteams/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    globals: true,
-    include: ["src/**/*.test.ts"],
-    watch: false,
-  },
-});

package/references/skill-tree/.claude/settings.json

@@ -1,6 +0,0 @@
-{
-    "attribution": {
-    "commit": "",
-    "pr": ""
-  }
-}

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

@@ -1,11 +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"}]}

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

@@ -1 +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"]}