@exellix/ai-tasks 9.0.6 → 9.1.1

package/.docs/skill-library-spec.md

@@ -1,249 +0,0 @@
-# Skillix — Skill Library Spec
-
-**Package:** `@skillices/skillix`  
-**Git org:** `Skillices`  
-**Consumer:** `@woroces/ai-tasks`
-
----
-
-## 1. What Is Skillix
-
-Skillix is the **registry of skill definitions** — every skill that ai-tasks can execute lives here as a **Skillix entry**. Each entry carries the skill's **prompt**, **instructions path**, metadata, and execution defaults.
-
-ai-tasks ships a **built-in default registry**. Upstream packages ("skills packages") published under `@skillices/` can be installed and **merged** into that default, extending the library without forking ai-tasks.
-
----
-
-## 2. Architecture: Default + Upstream Merge
-
-```
-┌──────────────────────────────────┐
-│  @skillices/skillix              │  ← the core library (types, merge, lookup)
-│  exports: types, mergeRegistries │
-│  exports: findSkillix, listKeys  │
-└──────────────────────────────────┘
-
-┌──────────────────────────────────┐
-│  @skillices/skillix-security     │  ← upstream skills package (example)
-│  exports: REGISTRY (partial)     │
-└──────────────────────────────────┘
-
-┌──────────────────────────────────┐
-│  @woroces/ai-tasks               │
-│  • has DEFAULT_REGISTRY (built-in)│
-│  • imports @skillices/skillix     │
-│  • optionally imports upstream    │
-│    skills packages and merges     │
-│  • uses merged registry at runtime│
-└──────────────────────────────────┘
-```
-
-**Flow:**
-
-1. ai-tasks defines `DEFAULT_REGISTRY` — its own built-in skills.
-2. At init, ai-tasks calls `mergeRegistries(DEFAULT_REGISTRY, ...upstreamRegistries)` to produce the **active registry**.
-3. Upstream skills packages are regular npm deps (`@skillices/skillix-security`, `@skillices/skillix-ops`, etc.) that each export a partial registry.
-4. Merge rule: **upstream wins** on key collision (upstream is more specific / fresher). ai-tasks can invert this if needed.
-
----
-
-## 3. Skillix Entry Shape
-
-Every skill in the registry is a `SkillixEntry`:
-
-```ts
-interface SkillixEntry {
-  /** Stable unique id (slug or UUID). */
-  id: string;
-
-  /** Skill key as used in RunTaskRequest.skillKey (e.g. "tasks/security-risk-summary"). */
-  key: string;
-
-  /** Human-readable name. */
-  name: string;
-
-  /** Short description — what this skill does. */
-  description: string;
-
-  /** The prompt template. The actual instructions sent to the LLM. */
-  prompt: string;
-
-  /**
-   * Path to an external instructions file (relative to package root or absolute).
-   * When set, the file content is the prompt; `prompt` field may be empty or a fallback.
-   * Consumer loads the file at runtime or build time.
-   */
-  instructionsPath?: string;
-
-  /** Optional tags for filtering and discovery. */
-  tags?: string[];
-
-  /** Default execution type when request doesn't specify one. */
-  defaultExecutionType?: string;
-
-  /** Optional JSON Schema for task input validation. */
-  inputSchema?: object;
-
-  /** Optional hints for execution bindings (model, db, etc.). */
-  bindingHints?: Record<string, unknown>;
-}
-```
-
-### What matters most
-
-Every skillix entry **must** have either `prompt` (inline) or `instructionsPath` (file reference) — that is the skill's core content. Everything else is metadata and defaults.
-
----
-
-## 4. Package API (`@skillices/skillix`)
-
-### 4.1 Types
-
-```ts
-export type { SkillixEntry };
-export type SkillixRegistry = Record<string, SkillixEntry>;  // keyed by SkillixEntry.key
-```
-
-### 4.2 Registry Operations
-
-```ts
-/** Merge multiple registries. Later registries win on key collision. */
-export function mergeRegistries(...registries: SkillixRegistry[]): SkillixRegistry;
-
-/** Find a skillix entry by key or taskId (normalized lookup). */
-export function findSkillix(key: string, registry: SkillixRegistry): SkillixEntry | undefined;
-
-/** List all keys in a registry. */
-export function listKeys(registry: SkillixRegistry): string[];
-```
-
-### 4.3 Key Normalization
-
-Consumers may pass `"security-risk-summary"` or `"tasks/security-risk-summary"`. `findSkillix` tries:
-1. Exact match on `key`.
-2. Prefixed with `tasks/`.
-3. Prefixed with `skills/`.
-
-First match wins.
-
----
-
-## 5. Upstream Skills Packages
-
-A skills package is any npm package under `@skillices/` that exports a `SkillixRegistry`:
-
-```ts
-// @skillices/skillix-security/index.ts
-import type { SkillixRegistry } from "@skillices/skillix";
-
-export const REGISTRY: SkillixRegistry = {
-  "tasks/security-risk-summary": {
-    id: "security-risk-summary-v1",
-    key: "tasks/security-risk-summary",
-    name: "Security risk summary",
-    description: "Summarize security risks from context.",
-    prompt: "You are a security analyst. Given the following context:\n\n{{context}}\n\nProduce a risk summary...",
-    instructionsPath: "instructions/security-risk-summary.md",
-    tags: ["security", "summary"],
-    defaultExecutionType: "DIRECT",
-  },
-  // ... more entries
-};
-```
-
-That's it — flat registry export, no runtime logic. The package just holds skill definitions.
-
----
-
-## 6. How ai-tasks Uses Skillix
-
-### 6.1 Setup (once, at init)
-
-```ts
-import { mergeRegistries, findSkillix } from "@skillices/skillix";
-import { REGISTRY as securitySkills } from "@skillices/skillix-security"; // upstream
-import { DEFAULT_REGISTRY } from "./skillix/defaults.js"; // built-in
-
-const ACTIVE_REGISTRY = mergeRegistries(DEFAULT_REGISTRY, securitySkills);
-```
-
-### 6.2 At runTask Time
-
-```ts
-const skillix = findSkillix(request.skillKey, ACTIVE_REGISTRY);
-
-if (skillix) {
-  // Apply defaults (request takes precedence)
-  if (!request.executionType && skillix.defaultExecutionType) {
-    request.executionType = skillix.defaultExecutionType;
-  }
-
-  // Resolve prompt: instructionsPath (file) takes priority, fallback to inline prompt
-  const prompt = skillix.instructionsPath
-    ? await loadInstructions(skillix.instructionsPath)
-    : skillix.prompt;
-
-  // Inject prompt into execution context
-  request.context = prompt + (request.context ? "\n\n" + request.context : "");
-}
-
-// Continue with existing runTask flow...
-```
-
-### 6.3 When Skill Not in Registry
-
-No change to current behavior. ai-tasks continues as today — the request is used as-is. Skillix only adds defaults and prompt when the skill is found.
-
----
-
-## 7. Built-In Default Registry in ai-tasks
-
-ai-tasks maintains its own `DEFAULT_REGISTRY` for skills that ship with it:
-
-```
-src/skillix/
-  defaults.ts        ← DEFAULT_REGISTRY
-  instructions/      ← .md files referenced by instructionsPath
-    my-built-in.md
-```
-
-This is not the `@skillices/skillix` package. It's ai-tasks' own set of skillix entries that exist without installing any upstream skills package.
-
----
-
-## 8. Implementation Checklist
-
-### Phase 1: Create `@skillices/skillix`
-
-- [ ] New repo under `Skillices` org.
-- [ ] Export `SkillixEntry`, `SkillixRegistry` types.
-- [ ] Implement `mergeRegistries`, `findSkillix`, `listKeys`.
-- [ ] Key normalization (exact → `tasks/` → `skills/` prefix fallback).
-- [ ] Publish to registry.
-
-### Phase 2: Wire into ai-tasks
-
-- [ ] Add `@skillices/skillix` dependency.
-- [ ] Create `src/skillix/defaults.ts` with `DEFAULT_REGISTRY`.
-- [ ] Create `src/skillix/instructions/` for built-in prompt files.
-- [ ] In `task-sdk.ts`: resolve skillix entry, apply defaults + prompt.
-- [ ] Graceful fallback when skill not in registry.
-
-### Phase 3: First upstream skills package
-
-- [ ] Create `@skillices/skillix-<domain>` (e.g. `skillix-security`).
-- [ ] Export partial `SkillixRegistry` with entries and instruction files.
-- [ ] In ai-tasks: add dep, merge at init.
-
----
-
-## 9. Summary
-
-| Concern | Where |
-|---------|-------|
-| Types + merge + lookup | `@skillices/skillix` |
-| Built-in skills | `ai-tasks/src/skillix/defaults.ts` |
-| Upstream skill definitions | `@skillices/skillix-*` packages |
-| Prompt / instructions | `SkillixEntry.prompt` (inline) or `SkillixEntry.instructionsPath` (file) |
-| Merge strategy | `mergeRegistries()` — later wins, request always overrides |
-| Key resolution | `findSkillix()` — exact, then `tasks/`, then `skills/` prefix |