@icex-labs/icex-flow 0.3.0

package/README.md

@@ -0,0 +1,158 @@
+# icex-flow
+
+**Deterministic agent workflow orchestration.** Eliminate randomness in AI agent pipelines.
+
+> JSON decides. LLM executes. Every time, the same way.
+
+## The Problem
+
+AI agents (OpenClaw, Claude Code, etc.) make freestyle decisions about:
+- Which agent handles a task → **random routing**
+- What context to inject → **forgotten rules, missed files**
+- What steps to follow → **different path every run**
+- Whether to verify results → **lies about success**
+
+## The Solution
+
+`icex-flow` replaces LLM judgment with structured JSON definitions:
+
+| Component | What it does | LLM decides? |
+|-----------|-------------|:---:|
+| **Routes** (`routes.json`) | Maps tasks → agents + workflows | No |
+| **Context** (`context.manifest.json`) | Lists files to inject per step | No |
+| **Workflows** (`*.flow.json`) | Defines steps + verification | No |
+| **Verification** (built-in) | Checks step completion | No |
+
+The LLM still does the intelligent work (writing code, analyzing problems). It just doesn't decide the **process**.
+
+## Install
+
+```bash
+npm install -g icex-flow
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project
+icex-flow init
+
+# Edit the generated files
+vim .icex-flow/routes.json
+vim .icex-flow/context.manifest.json
+vim .icex-flow/workflows/dev-chain.flow.json
+
+# Validate
+icex-flow validate
+
+# Route a task
+icex-flow route "fix the login bug" --labels bug
+# → Agent: dev, Workflow: dev-chain, Confidence: keyword
+
+# Generate execution plan
+icex-flow plan dev-chain --input '{"issue_number":"42","branch_name":"fix/login","pr_title":"Fix login bug"}'
+# → Step-by-step plan with resolved commands and verification
+
+# Assemble context for a step
+icex-flow context dev-chain --step implement
+# → Concatenated content of all required files
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `icex-flow init [dir]` | Scaffold `.icex-flow/` with templates |
+| `icex-flow validate [dir]` | Validate all JSON definitions |
+| `icex-flow route "<task>"` | Route task to agent + workflow |
+| `icex-flow plan <workflow>` | Generate deterministic execution plan |
+| `icex-flow context [workflow]` | Assemble context from manifest |
+| `icex-flow verify --command "..."` | Run step verification |
+| `icex-flow list` | List workflows and routes |
+
+## Workflow Definition
+
+A workflow is a JSON file defining a deterministic sequence of steps:
+
+```json
+{
+  "name": "dev-chain",
+  "version": "1.0.0",
+  "description": "Issue → Code → Test → PR → Merge",
+  "inputs": {
+    "issue_number": { "type": "string", "required": true },
+    "branch_name": { "type": "string", "required": true }
+  },
+  "steps": [
+    {
+      "id": "create-branch",
+      "name": "Create Feature Branch",
+      "action": "shell",
+      "command": "git checkout -b {{branch_name}}",
+      "verify": {
+        "command": "git branch --show-current",
+        "expect": "{{branch_name}}"
+      }
+    },
+    {
+      "id": "implement",
+      "name": "Implement Changes",
+      "action": "agent",
+      "agent": "dev-coder",
+      "timeout": 600,
+      "input": "Implement issue #{{issue_number}}",
+      "verify": {
+        "command": "pytest tests/ -v",
+        "expect_exit": 0
+      }
+    }
+  ]
+}
+```
+
+### Step Types
+
+- **`shell`** — Run a command. Optionally capture output.
+- **`agent`** — Spawn a subagent with input and timeout.
+- **`notify`** — Send notifications to channels.
+- **`gate`** — Wait for a condition (with retries).
+
+### Verification
+
+Every step can have a `verify` block:
+
+```json
+{
+  "verify": {
+    "command": "gh pr checks main --json state",
+    "expect": "SUCCESS",
+    "retry": 10,
+    "retry_delay": 30
+  }
+}
+```
+
+Verification runs after each step. If it fails, the workflow stops.
+
+## Platform Support
+
+| Platform | Status | Integration |
+|----------|--------|------------|
+| **OpenClaw** | ✅ Supported | SKILL.md included, install as skill |
+| **Claude Code** | 🔜 Planned | Programmatic API via `import { routeTask } from 'icex-flow'` |
+
+## Programmatic API
+
+```typescript
+import { routeTask, planWorkflow, assembleContext, verifyStep } from 'icex-flow';
+
+const result = routeTask(routesConfig, { description: "fix login bug", labels: ["bug"] });
+// → { agent: "dev", workflow: "dev-chain", confidence: "keyword" }
+
+const plan = planWorkflow(workflowDef, { issue_number: "42", branch_name: "fix/login" });
+// → { steps: [...], variables: {...} }
+```
+
+## License
+
+MIT — [icex-labs](https://github.com/icex-labs)

package/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: icex-flow
+description: |
+  Deterministic agent workflow orchestration. Use when receiving any task that
+  should be routed to a specific agent or executed as a multi-step workflow.
+  Eliminates LLM freestyle decisions — routing, context assembly, step execution,
+  and verification are all defined in JSON, not left to model judgment.
+  Triggers: receiving a new task, spawning a subagent, executing a dev chain,
+  deploying changes, triaging inbox items, or any multi-step operation.
+metadata:
+  openclaw:
+    emoji: "⚡"
+    requires:
+      bins: ["node"]
+    install:
+      - id: "npm"
+        kind: "npm"
+        package: "icex-flow"
+        bins: ["icex-flow"]
+        label: "Install icex-flow via npm"
+---
+
+# icex-flow — Deterministic Agent Workflows
+
+**Core principle: JSON decides, LLM executes.** No freestyle routing, no ad-hoc context, no skipped steps.
+
+## Quick Reference
+
+```bash
+icex-flow init                          # Scaffold .icex-flow/ directory
+icex-flow validate                      # Validate all definitions
+icex-flow route "<task>" [--labels x]   # Route task → agent + workflow
+icex-flow plan <workflow> --input '{}'  # Generate execution plan
+icex-flow context [workflow] [--step x] # Assemble context from manifest
+icex-flow verify --command "<cmd>"      # Run step verification
+icex-flow list                          # List workflows and routes
+```
+
+## MANDATORY: How to Use in Agent Sessions
+
+When you receive a task, follow this exact sequence. **Do NOT deviate.**
+
+### Step 1: Route
+
+```bash
+icex-flow route "<task description>" --labels "label1,label2"
+```
+
+This returns the **agent** and **workflow** to use. Do NOT choose yourself.
+
+### Step 2: Assemble Context
+
+```bash
+icex-flow context <workflow> --step <current-step>
+```
+
+Read the output. This is the context you MUST inject before executing. Do NOT decide what files to read — the manifest decides.
+
+### Step 3: Plan
+
+```bash
+icex-flow plan <workflow> --input '{"key":"value"}'
+```
+
+This returns a step-by-step execution plan with resolved commands and verification. Follow it **in order**.
+
+### Step 4: Execute Each Step
+
+For each step in the plan:
+1. Execute the action (shell command, spawn agent, send notification)
+2. Run verification: `icex-flow verify --command "<verify_cmd>" --expect "<expected>"`
+3. If verification fails → **STOP**. Do not continue. Report failure.
+4. If verification passes → proceed to next step.
+
+### Step 5: Report
+
+After all steps complete (or on failure), send notifications as defined in the plan.
+
+## File Structure
+
+```
+.icex-flow/
+├── routes.json              # Task → agent + workflow mapping
+├── context.manifest.json    # What files to inject per workflow/step
+└── workflows/
+    ├── dev-chain.flow.json  # Development workflow
+    ├── deploy.flow.json     # Deployment workflow
+    └── *.flow.json          # Custom workflows
+```
+
+## Workflow Definition Format
+
+```json
+{
+  "name": "dev-chain",
+  "version": "1.0.0",
+  "description": "Issue → Code → Test → PR → Merge",
+  "inputs": {
+    "issue_number": { "type": "string", "required": true }
+  },
+  "steps": [
+    {
+      "id": "lock",
+      "name": "Lock Issue",
+      "action": "shell",
+      "command": "gh issue edit {{issue_number}} --add-label in-progress",
+      "verify": {
+        "command": "gh issue view {{issue_number}} --json labels",
+        "expect": "in-progress"
+      }
+    }
+  ]
+}
+```
+
+### Step Actions
+
+| Action | Description | Required Fields |
+|--------|-------------|-----------------|
+| `shell` | Run a shell command | `command` |
+| `agent` | Spawn a subagent | `agent`, `input`, `timeout` |
+| `notify` | Send notification | `channels`, `message` |
+| `gate` | Wait for condition | `verify` (with retries) |
+
+### Variables
+
+Use `{{variable_name}}` in any string field. Variables come from:
+- Workflow `inputs` definitions
+- `--input` JSON passed to `icex-flow plan`
+- `capture` field on previous steps (captures command stdout)
+
+## Anti-Patterns (FORBIDDEN)
+
+| Do NOT | Instead |
+|--------|---------|
+| Choose which agent handles a task | Run `icex-flow route` |
+| Decide what context files to read | Run `icex-flow context` |
+| Skip steps in a workflow | Follow the plan exactly |
+| Skip verification after a step | Always run `icex-flow verify` |
+| Improvise extra steps | Only execute what's in the plan |
+| Report success without verification | Verify first, then report |

package/bin/icex-flow.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/src/cli.js';
+main(process.argv.slice(2));

package/dist/src/adapters/index.d.ts

@@ -0,0 +1 @@
+export { handleTask, getChannelMode, shouldUseIcexFlow, routeViaCLI, planViaCLI } from './openclaw.js';

package/dist/src/adapters/index.js

@@ -0,0 +1,2 @@
+export { handleTask, getChannelMode, shouldUseIcexFlow, routeViaCLI, planViaCLI } from './openclaw.js';
+//# sourceMappingURL=index.js.map

package/dist/src/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/adapters/openclaw.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenClaw adapter for icex-flow
+ * Provides helpers for OpenClaw skills to use icex-flow routing and planning
+ */
+import type { RouteResult, ExecutionPlan } from '../types.js';
+interface OpenClawContext {
+    workspacePath: string;
+    channelId?: string;
+    agentId?: string;
+    sessionKey?: string;
+}
+interface OpenClawTaskInput {
+    description: string;
+    labels?: string[];
+    issueNumber?: string;
+    channelId?: string;
+}
+interface HandleTaskResult {
+    success: boolean;
+    error?: string;
+    route?: RouteResult;
+    plan?: ExecutionPlan;
+    context?: string;
+    configDir?: string;
+}
+export declare function getChannelMode(channelId: string): string;
+export declare function shouldUseIcexFlow(channelId: string): boolean;
+export declare function handleTask(ctx: OpenClawContext, task: OpenClawTaskInput): Promise<HandleTaskResult>;
+export declare function routeViaCLI(description: string, labels?: string[]): string;
+export declare function planViaCLI(workflow: string, input?: Record<string, string>): string;
+export {};

package/dist/src/adapters/openclaw.js

@@ -0,0 +1,118 @@
+/**
+ * OpenClaw adapter for icex-flow
+ * Provides helpers for OpenClaw skills to use icex-flow routing and planning
+ */
+import { routeTask } from '../engine/router.js';
+import { planWorkflow } from '../engine/planner.js';
+import { assembleContext } from '../engine/context.js';
+import { mergeRoutes, mergeWorkflows, mergeContextManifest } from '../engine/config.js';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// Resolve icex-flow config directory
+// Priority: project-specific .icex-flow/ > workspace .icex-flow/ > ~/.icex-flow/
+function resolveConfigDir(workspacePath, projectPath) {
+    const candidates = [
+        projectPath && join(projectPath, '.icex-flow'),
+        join(workspacePath, '.icex-flow'),
+        join(process.env.HOME || '~', '.icex-flow'),
+    ].filter(Boolean);
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('No .icex-flow configuration found. Run: icex-flow init');
+}
+// Channel ID to mode mapping
+const CHANNEL_MODES = {
+    '1477537830053089341': 'dev-execute', // #dev
+    '1477537900437438474': 'dev-execute', // #ops
+    '1477549408487997520': 'dev-execute', // #qa
+    '1477549454339866716': 'dev-discuss', // #arch
+    '1476693934255247545': 'casual', // #general
+    '1477538241233885296': 'read-only', // #notifications
+};
+export function getChannelMode(channelId) {
+    return CHANNEL_MODES[channelId] || 'casual';
+}
+export function shouldUseIcexFlow(channelId) {
+    const mode = getChannelMode(channelId);
+    return mode === 'dev-execute' || mode === 'dev-discuss';
+}
+// Main entry point for OpenClaw skills
+export async function handleTask(ctx, task) {
+    const configDir = resolveConfigDir(ctx.workspacePath);
+    const projectDir = resolve(configDir, '..');
+    // 1. Route the task
+    const routes = mergeRoutes(projectDir);
+    if (!routes) {
+        return {
+            success: false,
+            error: 'No routes configuration found. Run: icex-flow init',
+        };
+    }
+    const routeResult = routeTask(routes, {
+        description: task.description,
+        labels: task.labels,
+        channel: task.channelId,
+    });
+    // 2. Find workflow
+    const allWorkflows = mergeWorkflows(projectDir);
+    const workflow = allWorkflows.find((w) => w.name === routeResult.workflow);
+    if (!workflow) {
+        // Also try loading directly from the workflows directory
+        const workflowPath = join(configDir, 'workflows', `${routeResult.workflow}.flow.json`);
+        if (!existsSync(workflowPath)) {
+            return {
+                success: false,
+                error: `Workflow "${routeResult.workflow}" not found`,
+                route: routeResult,
+            };
+        }
+        const loadedWorkflow = JSON.parse(readFileSync(workflowPath, 'utf-8'));
+        return buildResult(loadedWorkflow, routeResult, task, configDir, projectDir);
+    }
+    return buildResult(workflow, routeResult, task, configDir, projectDir);
+}
+function buildResult(workflow, routeResult, task, configDir, projectDir) {
+    // 3. Generate plan
+    const variables = {};
+    if (task.issueNumber)
+        variables.issue_number = task.issueNumber;
+    if (task.description)
+        variables.task_description = task.description;
+    const plan = planWorkflow(workflow, variables);
+    // 4. Assemble context for the workflow
+    const manifest = mergeContextManifest(projectDir);
+    let context;
+    if (manifest) {
+        try {
+            const firstStepId = plan.steps[0]?.id;
+            context = assembleContext(manifest, projectDir, routeResult.workflow, firstStepId, plan.variables);
+        }
+        catch {
+            // Context assembly is best-effort; don't fail the whole task
+        }
+    }
+    return {
+        success: true,
+        route: routeResult,
+        plan,
+        context,
+        configDir,
+    };
+}
+// CLI wrapper for simple cases
+export function routeViaCLI(description, labels) {
+    const args = [`icex-flow route "${description}"`];
+    if (labels?.length)
+        args.push(`--labels ${labels.join(',')}`);
+    return execSync(args.join(' '), { encoding: 'utf-8' });
+}
+export function planViaCLI(workflow, input) {
+    const args = [`icex-flow plan ${workflow}`];
+    if (input)
+        args.push(`--input '${JSON.stringify(input)}'`);
+    return execSync(args.join(' '), { encoding: 'utf-8' });
+}
+//# sourceMappingURL=openclaw.js.map

package/dist/src/adapters/openclaw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw.js","sourceRoot":"","sources":["../../../src/adapters/openclaw.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): void;

package/dist/src/cli.js

@@ -0,0 +1,95 @@
+import { cmdInit } from './commands/init.js';
+import { cmdValidate } from './commands/validate.js';
+import { cmdRoute } from './commands/route.js';
+import { cmdContext } from './commands/context.js';
+import { cmdPlan } from './commands/plan.js';
+import { cmdList } from './commands/list.js';
+import { cmdVerify } from './commands/verify.js';
+import { cmdProjects } from './commands/projects.js';
+import { cmdGenerate } from './commands/generate.js';
+import { cmdLearn } from './commands/learn.js';
+const VERSION = '0.2.0';
+const HELP = `
+icex-flow v${VERSION} — Deterministic agent workflow orchestration
+
+Usage: icex-flow <command> [options]
+
+Commands:
+  init [dir] [--force]            Initialize .icex-flow/ with smart auto-detection
+  generate [--dir .]              Auto-generate PROJECT.md from scanned project
+  learn "<knowledge>"             Store project knowledge (env, safety, arch)
+  learn --list                    List all stored knowledge
+  learn --remove <id>             Remove a knowledge entry
+  validate [dir] [--global]       Validate all workflow definitions
+  route "<description>" [--labels] Route a task to agent + workflow
+  context [workflow] [--step]     Assemble context from manifest
+  plan <workflow> [--input '{}']  Generate deterministic execution plan
+  list [--dir .]                  List workflows and routes (merged)
+  verify --command "<cmd>"        Run step verification
+  projects [list|add|remove]      Manage registered projects
+
+Options:
+  --dir <path>     Working directory (default: .)
+  --json           Output as JSON
+  --help, -h       Show help
+  --version, -v    Show version
+
+Global Config: ~/.icex-flow/
+  config.json      Global settings
+  projects.json    Registry of all initialized projects
+  context/L0-global/ Global rules shared across all projects
+  workflows/       Global workflow templates (overridable per project)
+
+Examples:
+  icex-flow init
+  icex-flow init --force
+  icex-flow route "fix login bug" --labels bug
+  icex-flow plan dev-chain --input '{"issue_number":"42","branch_name":"fix/login"}'
+  icex-flow context dev-chain --step implement
+  icex-flow verify --command "pytest tests/ -v" --expect-exit 0
+  icex-flow projects
+  icex-flow projects add /path/to/project
+  icex-flow projects remove /path/to/project
+  icex-flow validate --global
+`.trim();
+export function main(args) {
+    const command = args[0];
+    const rest = args.slice(1);
+    switch (command) {
+        case 'init':
+            return cmdInit(rest);
+        case 'generate':
+            return cmdGenerate(rest);
+        case 'learn':
+            return cmdLearn(rest);
+        case 'validate':
+            return cmdValidate(rest);
+        case 'route':
+            return cmdRoute(rest);
+        case 'context':
+            return cmdContext(rest);
+        case 'plan':
+            return cmdPlan(rest);
+        case 'list':
+            return cmdList(rest);
+        case 'verify':
+            return cmdVerify(rest);
+        case 'projects':
+            return cmdProjects(rest);
+        case '--version':
+        case '-v':
+            console.log(`icex-flow v${VERSION}`);
+            return;
+        case '--help':
+        case '-h':
+        case undefined:
+            console.log(HELP);
+            return;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.log('');
+            console.log(HELP);
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,IAAI,GAAG;aACA,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCnB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,IAAI,CAAC,IAAc;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxB,KAAK,SAAS;YACZ,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;YACrC,OAAO;QACT,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV,KAAK,SAAS;YACZ,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO;QACT;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/src/commands/context.d.ts

@@ -0,0 +1 @@
+export declare function cmdContext(args: string[]): void;

package/dist/src/commands/context.js

@@ -0,0 +1,40 @@
+import { join, resolve } from 'node:path';
+import { loadJson, parseFlags } from '../utils.js';
+import { assembleContext, listContextFiles } from '../engine/context.js';
+import { mergeContextManifest } from '../engine/config.js';
+export function cmdContext(args) {
+    const { positional, flags } = parseFlags(args);
+    const workflow = positional[0];
+    const step = flags['step'];
+    const dir = flags['dir'] ?? '.';
+    const dryRun = flags['dry-run'] === 'true';
+    const baseDir = resolve(dir);
+    const manifestPath = join(baseDir, '.icex-flow', 'context.manifest.json');
+    // Try merged manifest (global + project), fall back to project-only
+    let manifest = mergeContextManifest(baseDir);
+    if (!manifest) {
+        manifest = loadJson(manifestPath);
+    }
+    // Parse vars from --var key=value flags
+    const vars = {};
+    if (flags['var']) {
+        for (const pair of flags['var'].split(',')) {
+            const [k, v] = pair.split('=');
+            if (k && v)
+                vars[k] = v;
+        }
+    }
+    if (dryRun) {
+        const files = listContextFiles(manifest, baseDir, workflow, step, vars);
+        console.log('Files to inject:');
+        for (const f of files) {
+            console.log(`  - ${f}`);
+        }
+        console.log(`\nTotal: ${files.length} files`);
+    }
+    else {
+        const output = assembleContext(manifest, baseDir, workflow, step, vars);
+        console.log(output);
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/src/commands/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,uBAAuB,CAAC,CAAC;IAE1E,oEAAoE;IACpE,IAAI,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,QAAQ,CAAkB,YAAY,CAAC,CAAC;IACrD,CAAC;IAED,wCAAwC;IACxC,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACjB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/src/commands/generate.d.ts

@@ -0,0 +1,2 @@
+export declare function runGenerate(dir: string): void;
+export declare function cmdGenerate(args: string[]): void;