@amitdeshmukh/ax-crew 8.6.0 → 8.7.1

package/.claude/settings.local.json

@@ -5,7 +5,9 @@
       "Bash(git push:*)",
       "Bash(git status:*)",
       "Bash(node:*)",
-      "Bash(npm version:*)"
+      "Bash(npm version:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:tanstack.com)"
     ]
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [8.7.1] - 2026-03-17
+
+### Fixed
+- Skill postinstall now installs to the **project directory** (`.claude/skills/ax-crew/`, `.agents/skills/ax-crew/`) instead of the home directory. Skills are scoped to projects that use ax-crew.
+
+## [8.7.0] - 2026-03-17
+
+### Added
+- **16 Claude Code & Codex skill files** in `src/skills/` — terse, code-first `.md` files covering the full AxCrew API: config, signatures, functions, state, sub-agents, streaming, MCP, metrics, execution modes, code execution, ACE, few-shot, providers, telemetry, and multi-agent patterns.
+- **Postinstall auto-install**: `npm install` copies skill files to `~/.claude/skills/ax-crew/` (individual `.md` files) and `~/.agents/skills/ax-crew/` (combined `SKILL.md` for Codex). Skills are auto-discovered by Claude Code and Codex — no manual setup needed.
+- **Preuninstall cleanup**: `npm uninstall` removes installed skill files.
+- MIT LICENSE file.
+
 ## [8.6.0] - 2026-03-14
 
 ### Added

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Amit Deshmukh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,23 +8,23 @@ AxCrew lets you define a team of AI agents in config and run them together with
 
 ### Why AxCrew
 - **Config-first crews**: Declare agents once; instantiate on demand.
+- **ACE Learning**: Agents learn from human feedback with persistent playbooks.
+- **Sandboxed code execution**: AxJSRuntime with permission controls — data never leaves your environment.
 - **Shared state**: Simple key/value state all agents can read/write.
 - **Sub‑agents and tools**: Compose agents and functions cleanly.
-- **Streaming**: Real‑time token streaming for responsive UX.
 - **MCP**: Connect agents to MCP servers (STDIO, HTTP SSE, Streamable HTTP).
+- **Streaming**: Real‑time token streaming for responsive UX.
 - **Metrics & costs**: Per‑agent and crew snapshots, with estimated USD.
+- **Auto-installs Claude & Codex skills**: `npm install` installs 16 skill files that teach LLMs to build AxCrew agents.
 
 ### Install
-Install this package:
-```bash
-npm install @amitdeshmukh/ax-crew
-```
-AxLLM is a peer dependency, so you will need to install it separately. 
 
 ```bash
-npm install @ax-llm/ax @ax-llm/ax-tools
+npm install @amitdeshmukh/ax-crew @ax-llm/ax @ax-llm/ax-tools
 ```
 
+This also auto-installs 16 skill files for Claude Code (`~/.claude/skills/ax-crew/`) and Codex (`~/.agents/skills/ax-crew/`).
+
 Requirements: Node.js >= 21.
 
 ### Environment

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "8.6.0",
+  "version": "8.7.1",
   "description": "Build and launch a crew of AI agents with shared state. Built with axllm.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,8 @@
     "node": ">=21.0.0"
   },
   "scripts": {
+    "postinstall": "node scripts/install-skills.mjs",
+    "preuninstall": "node scripts/uninstall-skills.mjs",
     "build": "rm -rf dist && tsc --outDir dist",
     "release": "npm run build && npm publish --access public",
     "test": "vitest run",

package/scripts/install-skills.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script: installs ax-crew skill files for Claude Code and Codex.
+ * Runs automatically on `npm install @amitdeshmukh/ax-crew`.
+ *
+ * Skills are installed to the PROJECT directory (not home dir):
+ * Claude Code: .claude/skills/ax-crew/   (individual .md files)
+ * Codex:       .agents/skills/ax-crew/   (combined SKILL.md)
+ *
+ * The project root is determined by walking up from node_modules
+ * to find the consuming project's root directory.
+ */
+
+import { existsSync, mkdirSync, readdirSync, copyFileSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsSource = join(__dirname, '..', 'src', 'skills');
+
+// Find the project root by walking up from the package's location
+// When installed via npm, we're at <project>/node_modules/@amitdeshmukh/ax-crew/scripts/
+// So project root is 4 levels up. When running locally (dev), use INIT_CWD or cwd.
+function findProjectRoot() {
+  // npm sets INIT_CWD to the directory where `npm install` was run
+  if (process.env.INIT_CWD) {
+    return process.env.INIT_CWD;
+  }
+  // Fallback: walk up from our location past node_modules
+  let dir = resolve(__dirname, '..');
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, 'node_modules'))) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  return process.cwd();
+}
+
+function installSkills() {
+  if (!existsSync(skillsSource)) return;
+
+  const skillFiles = readdirSync(skillsSource).filter(f => f.endsWith('.md')).sort();
+  if (skillFiles.length === 0) return;
+
+  const projectRoot = findProjectRoot();
+
+  // Claude Code: individual skill files in project dir
+  const claudeDir = join(projectRoot, '.claude', 'skills', 'ax-crew');
+  try {
+    mkdirSync(claudeDir, { recursive: true });
+    for (const file of skillFiles) {
+      copyFileSync(join(skillsSource, file), join(claudeDir, file));
+    }
+    console.log(`  ax-crew: installed ${skillFiles.length} skills → ${claudeDir}`);
+  } catch {
+    // Silently skip
+  }
+
+  // Codex: single SKILL.md combining all skills in project dir
+  const codexDir = join(projectRoot, '.agents', 'skills', 'ax-crew');
+  try {
+    mkdirSync(codexDir, { recursive: true });
+
+    let combined = `---\nname: ax-crew\ndescription: Build and manage crews of AI agents with JSON config. Covers AxCrew class, agent config, signatures, functions, state, sub-agents, streaming, MCP, metrics, execution modes, code execution, ACE learning, few-shot, providers, telemetry, and multi-agent patterns.\n---\n\n`;
+
+    for (const file of skillFiles) {
+      const content = readFileSync(join(skillsSource, file), 'utf-8');
+      const body = content.replace(/^---\n[\s\S]*?\n---\n/, '');
+      combined += body.trim() + '\n\n---\n\n';
+    }
+
+    writeFileSync(join(codexDir, 'SKILL.md'), combined.trim());
+    console.log(`  ax-crew: installed combined SKILL.md → ${codexDir}`);
+  } catch {
+    // Silently skip
+  }
+}
+
+installSkills();

package/scripts/uninstall-skills.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+/**
+ * Preuninstall script: removes ax-crew skill files from the project directory.
+ */
+
+import { existsSync, rmSync } from 'fs';
+import { join } from 'path';
+
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+const targets = [
+  join(projectRoot, '.claude', 'skills', 'ax-crew'),
+  join(projectRoot, '.agents', 'skills', 'ax-crew'),
+];
+
+for (const dir of targets) {
+  try {
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true });
+      console.log(`  ax-crew: removed skills from ${dir}`);
+    }
+  } catch {
+    // Silently skip
+  }
+}

package/src/skills/ax-crew-ace.md

@@ -0,0 +1,165 @@
+---
+name: ax-crew-ace
+version: __VERSION__
+description: "ACE (Agentic Context Engineering) for AxCrew: feedback loops, online learning, playbook persistence, and optimization."
+tags: [ace, agentic-context-engineering, feedback, learning, playbook, online-update, optimize]
+---
+
+# ACE (Agentic Context Engineering)
+
+ACE enables agents to learn from human feedback at runtime. Feedback is analyzed, categorized into playbook sections, and injected into the agent's system prompt on every subsequent `forward()` call.
+
+## ACEConfig Shape
+
+```ts
+interface ACEConfig {
+  teacher?: {
+    provider?: Provider;
+    providerKeyName?: string;
+    apiURL?: string;
+    ai?: AxModelConfig & { model: string };
+    providerArgs?: Record<string, unknown>;
+  };
+  persistence?: {
+    playbookPath?: string;
+    initialPlaybook?: Record<string, any>;
+    autoPersist?: boolean;
+    onPersist?: (pb: any) => Promise<void> | void;
+    onLoad?: () => Promise<any> | any;
+  };
+  options?: {
+    maxEpochs?: number;
+    allowDynamicSections?: boolean;
+    tokenBudget?: number;
+    reflectorPrompt?: string;
+    curatorPrompt?: string;
+  };
+  metric?: {
+    metricFnName?: string;
+    primaryOutputField?: string;
+  };
+  compileOnStart?: boolean;
+}
+```
+
+## Agent-Level ACE API
+
+```ts
+// StatefulAxAgent methods:
+await agent.initACE(aceConfig);                          // called automatically during addAgent()
+await agent.applyOnlineUpdate({ example, prediction, feedback }); // learn from feedback
+agent.getPlaybook();                                     // returns current ACEPlaybook
+agent.applyPlaybook(playbook);                           // set playbook directly
+await agent.optimizeOffline({ metric, examples });       // offline compilation
+```
+
+## Crew-Level Feedback Routing
+
+```ts
+// AxCrew tracks which agents participated in a task and routes feedback to all of them:
+crew.trackAgentExecution(taskId, agentName, input);      // automatic during forward()
+crew.recordAgentResult(taskId, agentName, result);       // automatic during forward()
+await crew.applyTaskFeedback({ taskId, feedback, strategy: "all" | "primary" | "weighted" });
+crew.getTaskAgentInvolvement(taskId);                    // inspect execution history
+crew.cleanupOldExecutions(maxAgeMs);                     // prevent memory leaks
+```
+
+## Playbook Persistence
+
+Three persistence options (checked in order):
+1. `onLoad` callback -- custom async loader
+2. `initialPlaybook` -- inline playbook object
+3. `playbookPath` -- JSON file on disk (auto-created)
+
+Auto-save: set `autoPersist: true` with `playbookPath` or `onPersist` callback.
+
+## Canonical Pattern
+
+Adapted from `examples/ace-customer-support.ts` -- an agent that learns customer support exception policies from supervisor feedback.
+
+```ts
+import { AxCrew } from "ax-crew";
+import type { AxCrewConfig, Provider } from "ax-crew";
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "SupportAgent",
+      description: "Customer support agent. Follow company policies strictly.",
+      signature: "ticket:string, policies:string[] -> response:string, decision:string",
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-flash-latest", temperature: 0.7 },
+      options: { stream: false },
+      ace: {
+        teacher: {
+          provider: "google-gemini" as Provider,
+          providerKeyName: "GEMINI_API_KEY",
+          ai: { model: "gemini-flash-latest" },
+        },
+        options: { maxEpochs: 1, allowDynamicSections: true },
+        persistence: {
+          playbookPath: "playbooks/support.json",
+          autoPersist: true,
+        },
+        metric: { primaryOutputField: "response" },
+        compileOnStart: false,
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAgentsToCrew(["SupportAgent"]);
+  const agent = crew.agents!.get("SupportAgent")!;
+
+  // Run the agent
+  const result = await agent.forward({
+    ticket: "Customer wants refund on sale item (defective on arrival)",
+    policies: ["No refunds on sale items", "Returns within 30 days only"],
+  });
+
+  console.log(result.response, result.decision);
+
+  // Apply feedback -- agent learns for future calls
+  const taskId = (result as any)._taskId;
+  if (taskId) {
+    await crew.applyTaskFeedback({
+      taskId,
+      feedback: "Defective products must always be refunded regardless of sale status",
+      strategy: "all",
+    });
+  }
+
+  // Or apply directly to agent (without task routing)
+  await (agent as any).applyOnlineUpdate({
+    example: { ticket: "..." },
+    prediction: result,
+    feedback: "Medical emergencies extend the 30-day window to 60 days",
+  });
+
+  // Inspect learned playbook
+  const playbook = (agent as any).getPlaybook();
+  console.log(JSON.stringify(playbook, null, 2));
+
+  crew.cleanupOldExecutions(60000);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT call `initACE()` manually -- it is called automatically when `addAgent()` / `addAgentsToCrew()` detects an `ace` config on the agent.
+- Do NOT set `compileOnStart: true` without providing `examples` and a `metric` -- offline compilation requires both.
+- Do NOT mutate the playbook object directly -- use `applyOnlineUpdate()` or `applyPlaybook()`.
+- Do NOT forget `autoPersist: true` if you want playbook changes saved to disk automatically.
+- Do NOT use `strategy: "weighted"` expecting differentiated weights -- it currently behaves the same as `"all"`.
+
+## References
+
+- [ace-customer-support.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/ace-customer-support.ts)
+- [src/agents/ace.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/ace.ts)
+- [AxACE upstream docs](https://axllm.dev/ace/)

package/src/skills/ax-crew-agent-config.md

@@ -0,0 +1,181 @@
+---
+name: ax-crew-agent-config
+version: __VERSION__
+description: "AgentConfig - agent configuration: provider, signature, model, temperature, definition, prompt, executionMode, axAgentOptions, providerArgs"
+---
+
+# AgentConfig
+
+Every agent in a crew is defined by an `AgentConfig` object inside `AxCrewConfig.crew[]`.
+
+## All Fields
+
+```ts
+interface AgentConfig {
+  // Required
+  name: string;                    // Unique agent name
+  description: string;             // Short description (used as default system prompt)
+  signature: string | AxSignature; // DSPy-style signature, e.g. "query:string -> answer:string"
+  provider: Provider;              // "openai" | "anthropic" | "google-gemini" | "azure-openai" | ...
+  ai: AxModelConfig & {           // Model configuration
+    model: string;                 //   model name (required)
+    temperature?: number;          //   sampling temperature
+    maxTokens?: number;            //   max output tokens
+    stream?: boolean;              //   enable streaming at AI level
+  };
+
+  // Optional
+  providerKeyName?: string;        // Env var name for API key (e.g. "OPENAI_API_KEY")
+  apiURL?: string;                 // Custom API endpoint (e.g. ollama on localhost)
+  providerArgs?: Record<string, unknown>; // Provider-specific args forwarded to Ax factory
+  definition?: string;             // Detailed system prompt (must be >= 100 chars per Ax)
+  prompt?: string;                 // Alias for definition (used if definition is omitted)
+  debug?: boolean;                 // Enable debug logging
+  options?: Partial<AxProgramForwardOptions<any>> & Record<string, any>; // Forward options + provider-specific keys
+  functions?: string[];            // Function names from the registry
+  agents?: string[];               // Sub-agent names (must be added to crew first)
+  examples?: Array<Record<string, any>>; // DSPy few-shot examples
+  mcpServers?: Record<string, MCPTransportConfig>; // MCP server configs
+  executionMode?: "axagent" | "axgen"; // Execution engine (default: "axgen")
+  axAgentOptions?: AxCrewAxAgentOptions; // AxAgent-specific options (only for executionMode: "axagent")
+  ace?: ACEConfig;                 // Optional AxACE optimization config
+}
+```
+
+## Canonical Pattern
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "analyzer",
+      description: "Analyzes user queries and provides structured responses",
+      signature: "userQuery:string -> analysis:string, confidence:number",
+      provider: "anthropic",
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: {
+        model: "claude-sonnet-4-20250514",
+        temperature: 0.5,
+        maxTokens: 2000,
+      },
+      options: { debug: true, stream: false },
+      functions: ["CurrentDateTime"],
+    }
+  ]
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+  const analyzer = crew.agents?.get("analyzer");
+  const result = await analyzer?.forward({ userQuery: "What is quantum computing?" });
+  console.log(result?.analysis, result?.confidence);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Provider Key Pattern
+
+The `providerKeyName` field specifies which environment variable holds the API key. The key is read from `process.env` at agent creation time.
+
+```ts
+{
+  provider: "openai",
+  providerKeyName: "OPENAI_API_KEY",  // reads process.env.OPENAI_API_KEY
+}
+```
+
+## Azure OpenAI Example
+
+Use `providerArgs` for provider-specific configuration:
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "TestAgent",
+      description: "Test Agent for Azure OpenAI",
+      provider: "azure-openai",
+      providerKeyName: "AZURE_OPENAI_API_KEY",
+      signature: "userQuery:string -> answer:string",
+      ai: {
+        model: "gpt-5-mini",
+        temperature: 0,
+        stream: false
+      },
+      providerArgs: {
+        resourceName: "your-resource-name",
+        deploymentName: "your-deployment-name",
+        version: "2025-01-01-preview"
+      },
+      options: { debug: true, stream: false }
+    }
+  ]
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+  const agent = crew.agents?.get("TestAgent");
+  const response = await agent?.forward({ userQuery: "What is the capital of France?" });
+  console.log(response?.answer);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Execution Mode
+
+| Mode | Engine | When to use |
+|---|---|---|
+| `"axgen"` (default) | `AxGen` | Standard prompt-response with tool calling |
+| `"axagent"` | `AxAgent` | Full agent capabilities: RLM, context fields, actor/responder split |
+
+When `executionMode: "axagent"`, use `axAgentOptions` for agent-specific settings:
+
+```ts
+{
+  executionMode: "axagent",
+  axAgentOptions: {
+    contextFields: ["conversationHistory"],
+    // agents: { ... },   // Agent graph config
+    // functions: { ... }, // Function graph config
+    // actorOptions: { description: "..." },
+    // responderOptions: { description: "..." },
+  }
+}
+```
+
+## Signature Format
+
+DSPy-style string signatures with optional field descriptions:
+
+```
+"input1:type, input2:type -> output1:type, output2:type"
+"topic:string \"The topic\" -> article:string \"The written article\""
+"query:string -> results:string[]"
+```
+
+Supported types: `string`, `number`, `boolean`, `string[]`, `number[]`, etc.
+
+## Do Not Generate
+
+- Do NOT omit `name`, `description`, `signature`, `provider`, or `ai.model` -- all are required.
+- Do NOT set `definition` to less than 100 characters if you provide it (Ax enforces this minimum).
+- Do NOT confuse `options.stream` (forward option) with `ai.stream` (AI-level streaming config).
+- Do NOT use `providerArgs` for API keys; use `providerKeyName` instead.
+- Do NOT list sub-agents in `agents` that haven't been added to the crew before the parent agent.
+
+## References
+
+- [basic-researcher-writer.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/basic-researcher-writer.ts)
+- [providerArgs.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/providerArgs.ts)