@icex-labs/icex-flow 0.3.0

package/dist/src/utils.js

@@ -0,0 +1,65 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function resolveTemplate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+}
+export function readFileSafe(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export function loadJson(path) {
+    const abs = resolve(path);
+    if (!existsSync(abs)) {
+        throw new Error(`File not found: ${abs}`);
+    }
+    const raw = readFileSync(abs, 'utf-8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON in ${abs}: ${e.message}`);
+    }
+}
+export function parseFlags(args) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            const key = args[i].slice(2);
+            if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+                flags[key] = args[i + 1];
+                i++;
+            }
+            else {
+                flags[key] = 'true';
+            }
+        }
+        else {
+            positional.push(args[i]);
+        }
+    }
+    return { positional, flags };
+}
+export function formatTable(rows, headers) {
+    const allRows = headers ? [headers, ...rows] : rows;
+    const cols = allRows[0]?.length ?? 0;
+    const widths = [];
+    for (let c = 0; c < cols; c++) {
+        widths[c] = Math.max(...allRows.map((r) => (r[c] ?? '').length));
+    }
+    const lines = [];
+    for (let i = 0; i < allRows.length; i++) {
+        const row = allRows[i];
+        const line = row.map((cell, c) => cell.padEnd(widths[c])).join('  ');
+        lines.push(line);
+        if (i === 0 && headers) {
+            lines.push(widths.map((w) => '─'.repeat(w)).join('──'));
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@icex-labs/icex-flow",
+  "version": "0.3.0",
+  "description": "Deterministic agent workflow orchestration — eliminate randomness in AI agent pipelines",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "icex-flow": "bin/icex-flow.mjs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "echo 'no tests yet'",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "schemas/",
+    "templates/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "workflow",
+    "orchestration",
+    "deterministic",
+    "openclaw",
+    "claude-code",
+    "pipeline"
+  ],
+  "author": "icex-labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icex-labs/icex-flow.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/schemas/context.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://icex.dev/schemas/context.schema.json",
+  "title": "icex-flow Context Manifest",
+  "type": "object",
+  "required": ["version", "global"],
+  "properties": {
+    "version": { "type": "string" },
+    "base_dir": { "type": "string" },
+    "global": {
+      "type": "object",
+      "required": ["always_inject"],
+      "properties": {
+        "always_inject": { "type": "array", "items": { "type": "string" } },
+        "inject_if_exists": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "workflows": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "always_inject": { "type": "array", "items": { "type": "string" } },
+          "inject_if_exists": { "type": "array", "items": { "type": "string" } },
+          "steps": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "inject": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/routes.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://icex.dev/schemas/routes.schema.json",
+  "title": "icex-flow Routes Configuration",
+  "type": "object",
+  "required": ["version", "default_agent", "routes"],
+  "properties": {
+    "version": { "type": "string" },
+    "default_agent": { "type": "string" },
+    "default_workflow": { "type": "string" },
+    "routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["match", "workflow", "agent"],
+        "properties": {
+          "match": {
+            "type": "object",
+            "properties": {
+              "labels": { "type": "array", "items": { "type": "string" } },
+              "keywords": { "type": "array", "items": { "type": "string" } },
+              "channel": { "type": "string" },
+              "sender": { "type": "string" }
+            }
+          },
+          "workflow": { "type": "string" },
+          "agent": { "type": "string" },
+          "priority": { "type": "integer" }
+        }
+      }
+    }
+  }
+}

package/schemas/workflow.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://icex.dev/schemas/workflow.schema.json",
+  "title": "icex-flow Workflow Definition",
+  "type": "object",
+  "required": ["name", "version", "steps"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "triggers": {
+      "type": "object",
+      "properties": {
+        "labels": { "type": "array", "items": { "type": "string" } },
+        "keywords": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "context": {
+      "type": "object",
+      "properties": {
+        "always": { "type": "array", "items": { "type": "string" } },
+        "per_step": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array", "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": { "enum": ["string", "number", "boolean"] },
+          "required": { "type": "boolean" },
+          "default": {},
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "action"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "action": { "enum": ["shell", "agent", "notify", "gate"] },
+          "command": { "type": "string" },
+          "agent": { "type": "string" },
+          "timeout": { "type": "number", "minimum": 1 },
+          "input": { "type": "string" },
+          "channels": { "type": "array", "items": { "type": "string" } },
+          "message": { "type": "string" },
+          "capture": { "type": "string" },
+          "condition": { "type": "string" },
+          "verify": {
+            "type": "object",
+            "required": ["command"],
+            "properties": {
+              "command": { "type": "string" },
+              "expect": { "type": "string" },
+              "expect_exit": { "type": "integer" },
+              "retry": { "type": "integer", "minimum": 0 },
+              "retry_delay": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "on_failure": {
+      "type": "object",
+      "properties": {
+        "action": { "enum": ["notify", "rollback"] },
+        "channels": { "type": "array", "items": { "type": "string" } },
+        "message": { "type": "string" },
+        "rollback_steps": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/templates/context.manifest.json

@@ -0,0 +1,21 @@
+{
+  "version": "1.0.0",
+  "base_dir": ".",
+  "global": {
+    "always_inject": [
+      "context/L0-global/"
+    ],
+    "inject_if_exists": []
+  },
+  "workflows": {
+    "dev-chain": {
+      "always_inject": [
+        "context/L1-project/"
+      ],
+      "inject_if_exists": [
+        "context/L2-reference/"
+      ],
+      "steps": {}
+    }
+  }
+}

package/templates/dev-chain.flow.json

@@ -0,0 +1,112 @@
+{
+  "name": "dev-chain",
+  "version": "1.0.0",
+  "description": "Issue → Branch → Implement → Test → PR → Merge → Deploy → Notify",
+  "triggers": {
+    "labels": ["auto-ok", "bug", "feature", "enhancement"],
+    "keywords": ["implement", "fix", "add", "refactor", "build"]
+  },
+  "context": {
+    "always": ["WORKFLOW_AUTO.md", "agents/dev/DEV_RULES.md"],
+    "per_step": {
+      "implement": ["src/", "tests/"],
+      "deploy": ["gitops-config/"]
+    }
+  },
+  "inputs": {
+    "issue_number": {
+      "type": "string",
+      "required": true,
+      "description": "GitHub issue number"
+    },
+    "branch_name": {
+      "type": "string",
+      "required": true,
+      "description": "Feature branch name (e.g. fix/login-bug)"
+    },
+    "repo": {
+      "type": "string",
+      "default": "netralis-inc/netralis-quant",
+      "description": "GitHub repo"
+    },
+    "pr_title": {
+      "type": "string",
+      "required": true,
+      "description": "Pull request title"
+    }
+  },
+  "steps": [
+    {
+      "id": "lock-issue",
+      "name": "Lock Issue",
+      "action": "shell",
+      "command": "gh issue edit {{issue_number}} --add-label in-progress --repo {{repo}}",
+      "verify": {
+        "command": "gh issue view {{issue_number}} --repo {{repo}} --json labels -q '.labels[].name'",
+        "expect": "in-progress"
+      }
+    },
+    {
+      "id": "create-branch",
+      "name": "Create Feature Branch",
+      "action": "shell",
+      "command": "git checkout -b {{branch_name}} && git push -u origin {{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 the changes described in issue #{{issue_number}}. Branch: {{branch_name}}. Run tests before committing.",
+      "verify": {
+        "command": "python -m pytest tests/ -v --tb=short",
+        "expect_exit": 0
+      }
+    },
+    {
+      "id": "create-pr",
+      "name": "Create Pull Request",
+      "action": "shell",
+      "command": "gh pr create --base main --head {{branch_name}} --title '{{pr_title}}' --body 'Closes #{{issue_number}}' --repo {{repo}}",
+      "capture": "pr_url"
+    },
+    {
+      "id": "wait-ci",
+      "name": "Wait for CI",
+      "action": "gate",
+      "verify": {
+        "command": "gh pr checks {{branch_name}} --repo {{repo}} --json state -q '.[].state' | sort -u | grep -v SUCCESS | wc -l | tr -d ' '",
+        "expect": "0",
+        "retry": 12,
+        "retry_delay": 30
+      }
+    },
+    {
+      "id": "merge-pr",
+      "name": "Merge PR",
+      "action": "shell",
+      "command": "gh pr merge {{branch_name}} --squash --delete-branch --repo {{repo}}",
+      "verify": {
+        "command": "gh pr view {{branch_name}} --repo {{repo}} --json state -q '.state'",
+        "expect": "MERGED"
+      }
+    },
+    {
+      "id": "notify",
+      "name": "Notify Completion",
+      "action": "notify",
+      "channels": ["telegram:notify"],
+      "message": "✅ dev-chain complete: {{pr_title}} (issue #{{issue_number}}) merged"
+    }
+  ],
+  "on_failure": {
+    "action": "notify",
+    "channels": ["telegram:notify"],
+    "message": "❌ dev-chain failed at step '{{failed_step}}' for issue #{{issue_number}}: {{error}}"
+  }
+}

package/templates/routes.json

@@ -0,0 +1,37 @@
+{
+  "version": "1.0.0",
+  "default_agent": "main",
+  "default_workflow": "default",
+  "routes": [
+    {
+      "match": { "labels": ["auto-ok"] },
+      "workflow": "dev-chain",
+      "agent": "dev",
+      "priority": 10
+    },
+    {
+      "match": { "keywords": ["implement", "fix", "bug", "feature", "refactor", "add"] },
+      "workflow": "dev-chain",
+      "agent": "dev",
+      "priority": 5
+    },
+    {
+      "match": { "keywords": ["deploy", "rollout", "k3d", "u9", "cluster", "helm", "argocd"] },
+      "workflow": "deploy",
+      "agent": "ops",
+      "priority": 5
+    },
+    {
+      "match": { "keywords": ["architecture", "design", "rfc", "adr", "review", "strategy"] },
+      "workflow": "review",
+      "agent": "arch",
+      "priority": 5
+    },
+    {
+      "match": { "keywords": ["test", "validate", "qa", "regression", "lint", "coverage"] },
+      "workflow": "test-suite",
+      "agent": "qa",
+      "priority": 5
+    }
+  ]
+}