@icex-labs/icex-flow 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +316 -52
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,91 +4,209 @@
4
4
 
5
5
  > JSON decides. LLM executes. Every time, the same way.
6
6
 
7
+ [![npm](https://img.shields.io/npm/v/@icex-labs/icex-flow)](https://www.npmjs.com/package/@icex-labs/icex-flow)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9
+
7
10
  ## The Problem
8
11
 
9
- AI agents (OpenClaw, Claude Code, etc.) make freestyle decisions about:
10
- - Which agent handles a task → **random routing**
11
- - What context to inject **forgotten rules, missed files**
12
- - What steps to follow **different path every run**
13
- - Whether to verify results **lies about success**
12
+ AI agents (OpenClaw, Claude Code, Codex, etc.) make freestyle decisions about:
13
+
14
+ - **Which agent handles a task** — random routing, inconsistent delegation
15
+ - **What context to inject** forgotten rules, missed project docs
16
+ - **What steps to follow** different execution path every run
17
+ - **Whether to verify results** — agents lie about success
18
+
19
+ When your agent forgets to read the deployment rules and pushes untested code to production, that's not an AI problem — that's a **process problem**.
14
20
 
15
21
  ## The Solution
16
22
 
17
23
  `icex-flow` replaces LLM judgment with structured JSON definitions:
18
24
 
19
- | Component | What it does | LLM decides? |
20
- |-----------|-------------|:---:|
21
- | **Routes** (`routes.json`) | Maps tasks → agents + workflows | No |
22
- | **Context** (`context.manifest.json`) | Lists files to inject per step | No |
23
- | **Workflows** (`*.flow.json`) | Defines steps + verification | No |
24
- | **Verification** (built-in) | Checks step completion | No |
25
+ ```
26
+ Task arrives → routes.json picks the agent + workflow
27
+ context.manifest.json injects the right files
28
+ workflow.flow.json defines exact steps
29
+ Each step is verified before proceeding
30
+ ```
25
31
 
26
32
  The LLM still does the intelligent work (writing code, analyzing problems). It just doesn't decide the **process**.
27
33
 
34
+ | Component | What it controls | LLM freestyle? |
35
+ |-----------|-----------------|:-:|
36
+ | `routes.json` | Task → agent + workflow | No |
37
+ | `context.manifest.json` | Files injected per step | No |
38
+ | `*.flow.json` | Step sequence + verification | No |
39
+ | `knowledge.json` | Persistent project knowledge | No |
40
+ | `PROJECT.md` | Auto-generated project context | No |
41
+
28
42
  ## Install
29
43
 
30
44
  ```bash
31
- npm install -g icex-flow
45
+ npm install -g @icex-labs/icex-flow
32
46
  ```
33
47
 
48
+ Requires Node.js >= 18.
49
+
34
50
  ## Quick Start
35
51
 
52
+ ### 1. Initialize in your project
53
+
36
54
  ```bash
37
- # Initialize in your project
55
+ cd my-project
38
56
  icex-flow init
57
+ ```
39
58
 
40
- # Edit the generated files
41
- vim .icex-flow/routes.json
42
- vim .icex-flow/context.manifest.json
43
- vim .icex-flow/workflows/dev-chain.flow.json
59
+ `init` auto-detects your project:
44
60
 
45
- # Validate
46
- icex-flow validate
61
+ - **Language** — Python, Node.js, Go, Java, Rust, etc.
62
+ - **Frameworks** — monorepo structure, microservices
63
+ - **CI/CD** — GitHub Actions, GitLab CI
64
+ - **Deployment** — Helm, Docker Compose, Kubernetes
65
+ - **Database** — Liquibase migrations, Prisma, etc.
66
+ - **Preset** — auto-selects from `microservice`, `monorepo`, `frontend`, `library`, `data-pipeline`, or `generic`
47
67
 
48
- # Route a task
49
- icex-flow route "fix the login bug" --labels bug
50
- # → Agent: dev, Workflow: dev-chain, Confidence: keyword
68
+ This generates a `.icex-flow/` directory with routes, context manifest, and workflow definitions — pre-configured for your stack.
51
69
 
52
- # Generate execution plan
53
- icex-flow plan dev-chain --input '{"issue_number":"42","branch_name":"fix/login","pr_title":"Fix login bug"}'
54
- # → Step-by-step plan with resolved commands and verification
70
+ ### 2. Teach it what can't be auto-detected
71
+
72
+ ```bash
73
+ icex-flow learn "production cluster is u9 at 192.168.1.200" --category environment
74
+ icex-flow learn "never push directly to main branch" --category safety
75
+ icex-flow learn "signal-runner feeds quant-bridge via Redis" --category architecture
76
+ ```
55
77
 
56
- # Assemble context for a step
78
+ Knowledge is persisted in `.icex-flow/knowledge.json` — survives agent restarts, session resets, and redeployments.
79
+
80
+ ### 3. Generate project context
81
+
82
+ ```bash
83
+ icex-flow generate
84
+ ```
85
+
86
+ Produces `.icex-flow/context/L1-project/PROJECT.md` — a complete project knowledge document combining auto-detected facts + learned knowledge. Agents get this injected automatically so they never start from zero.
87
+
88
+ ### 4. Use it
89
+
90
+ ```bash
91
+ # Route a task to the right agent + workflow
92
+ icex-flow route "fix the login bug" --labels bug
93
+ # → { agent: "dev", workflow: "dev-chain", confidence: "keyword" }
94
+
95
+ # Assemble context for a specific step
57
96
  icex-flow context dev-chain --step implement
58
- # → Concatenated content of all required files
97
+ # → Concatenated content of all required files (rules, docs, API refs)
98
+
99
+ # Generate a deterministic execution plan
100
+ icex-flow plan dev-chain --input '{"issue_number":"42","branch_name":"fix/login","pr_title":"Fix login"}'
101
+ # → Step-by-step plan with resolved commands and verification checks
102
+
103
+ # Verify a step completed successfully
104
+ icex-flow verify --command "gh pr view 42 --json state -q '.state'" --expect "MERGED"
105
+ # → ✅ PASS or ❌ FAIL
59
106
  ```
60
107
 
61
108
  ## Commands
62
109
 
63
110
  | Command | Description |
64
111
  |---------|-------------|
65
- | `icex-flow init [dir]` | Scaffold `.icex-flow/` with templates |
112
+ | `icex-flow init [dir]` | Auto-detect project + scaffold `.icex-flow/` |
66
113
  | `icex-flow validate [dir]` | Validate all JSON definitions |
67
- | `icex-flow route "<task>"` | Route task to agent + workflow |
114
+ | `icex-flow route "<task>"` | Route task agent + workflow |
68
115
  | `icex-flow plan <workflow>` | Generate deterministic execution plan |
69
116
  | `icex-flow context [workflow]` | Assemble context from manifest |
70
117
  | `icex-flow verify --command "..."` | Run step verification |
71
118
  | `icex-flow list` | List workflows and routes |
119
+ | `icex-flow generate [dir]` | Auto-generate PROJECT.md from detection + knowledge |
120
+ | `icex-flow learn "<fact>"` | Add persistent knowledge |
121
+ | `icex-flow learn --list` | List all learned knowledge |
122
+ | `icex-flow learn --remove <id>` | Remove a knowledge entry |
123
+ | `icex-flow projects [list\|add\|remove]` | Manage project registry |
72
124
 
73
- ## Workflow Definition
125
+ ## Directory Structure
74
126
 
75
- A workflow is a JSON file defining a deterministic sequence of steps:
127
+ After `icex-flow init`, your project gets:
128
+
129
+ ```
130
+ .icex-flow/
131
+ ├── routes.json # Task routing rules
132
+ ├── context.manifest.json # What files to inject, per workflow/step
133
+ ├── knowledge.json # Persistent learned knowledge
134
+ ├── context/
135
+ │ ├── L0-global/ # Always injected (all workflows)
136
+ │ │ ├── workflow-rules.md # Dev process rules
137
+ │ │ └── soul.md # Agent identity
138
+ │ ├── L1-project/ # Injected for project-specific workflows
139
+ │ │ └── PROJECT.md # Auto-generated project overview
140
+ │ └── L2-reference/ # Injected on-demand per step
141
+ │ └── api-docs.md # API reference, etc.
142
+ └── workflows/
143
+ ├── dev-chain.flow.json # Development pipeline
144
+ ├── deploy.flow.json # Deployment pipeline
145
+ └── db-migration.flow.json # Database change pipeline
146
+ ```
147
+
148
+ ### Context Layers
149
+
150
+ | Layer | Purpose | When injected |
151
+ |-------|---------|---------------|
152
+ | **L0-global** | Universal rules (coding standards, safety, identity) | Every workflow, every step |
153
+ | **L1-project** | Project architecture, environments, services | Per-workflow |
154
+ | **L2-reference** | API docs, tool guides, detailed specs | Per-step (to save tokens) |
155
+
156
+ Files in these directories can be actual files or symlinks to files elsewhere in your project.
157
+
158
+ ## Routing
159
+
160
+ `routes.json` maps tasks to agents and workflows using labels and keywords:
161
+
162
+ ```json
163
+ {
164
+ "version": "1.0.0",
165
+ "default_agent": "main",
166
+ "default_workflow": "default",
167
+ "routes": [
168
+ {
169
+ "match": { "labels": ["auto-ok"] },
170
+ "workflow": "dev-chain",
171
+ "agent": "dev",
172
+ "priority": 10
173
+ },
174
+ {
175
+ "match": { "keywords": ["deploy", "rollout", "k3d"] },
176
+ "workflow": "deploy",
177
+ "agent": "ops",
178
+ "priority": 5
179
+ }
180
+ ]
181
+ }
182
+ ```
183
+
184
+ **Priority** — higher number wins when multiple routes match.
185
+
186
+ **Matching** — `labels` requires exact match; `keywords` matches against the task description (case-insensitive substring).
187
+
188
+ **Fallback** — if no route matches, uses `default_agent` + `default_workflow`.
189
+
190
+ ## Workflows
191
+
192
+ A workflow defines a deterministic sequence of steps:
76
193
 
77
194
  ```json
78
195
  {
79
196
  "name": "dev-chain",
80
197
  "version": "1.0.0",
81
- "description": "Issue → Code → Test → PR → Merge",
198
+ "description": "Issue → Code → Test → PR → Merge → Deploy → Notify",
82
199
  "inputs": {
83
200
  "issue_number": { "type": "string", "required": true },
84
- "branch_name": { "type": "string", "required": true }
201
+ "branch_name": { "type": "string", "required": true },
202
+ "repo": { "type": "string", "default": "my-org/my-repo" }
85
203
  },
86
204
  "steps": [
87
205
  {
88
206
  "id": "create-branch",
89
207
  "name": "Create Feature Branch",
90
208
  "action": "shell",
91
- "command": "git checkout -b {{branch_name}}",
209
+ "command": "git checkout -b {{branch_name}} && git push -u origin {{branch_name}}",
92
210
  "verify": {
93
211
  "command": "git branch --show-current",
94
212
  "expect": "{{branch_name}}"
@@ -100,22 +218,55 @@ A workflow is a JSON file defining a deterministic sequence of steps:
100
218
  "action": "agent",
101
219
  "agent": "dev-coder",
102
220
  "timeout": 600,
103
- "input": "Implement issue #{{issue_number}}",
221
+ "input": "Implement issue #{{issue_number}} on branch {{branch_name}}. Run tests.",
104
222
  "verify": {
105
223
  "command": "pytest tests/ -v",
106
224
  "expect_exit": 0
107
225
  }
226
+ },
227
+ {
228
+ "id": "wait-ci",
229
+ "name": "Wait for CI",
230
+ "action": "gate",
231
+ "verify": {
232
+ "command": "gh pr checks {{branch_name}} --json state -q '.[].state' | sort -u",
233
+ "expect": "SUCCESS",
234
+ "retry": 12,
235
+ "retry_delay": 30
236
+ }
237
+ },
238
+ {
239
+ "id": "notify",
240
+ "name": "Notify Completion",
241
+ "action": "notify",
242
+ "channels": ["telegram:notify"],
243
+ "message": "✅ PR merged for issue #{{issue_number}}"
108
244
  }
109
- ]
245
+ ],
246
+ "on_failure": {
247
+ "action": "notify",
248
+ "channels": ["telegram:notify"],
249
+ "message": "❌ Failed at step '{{failed_step}}' for issue #{{issue_number}}: {{error}}"
250
+ }
110
251
  }
111
252
  ```
112
253
 
113
254
  ### Step Types
114
255
 
115
- - **`shell`** Run a command. Optionally capture output.
116
- - **`agent`** — Spawn a subagent with input and timeout.
117
- - **`notify`** Send notifications to channels.
118
- - **`gate`** Wait for a condition (with retries).
256
+ | Action | Purpose | Required Fields |
257
+ |--------|---------|-----------------|
258
+ | `shell` | Run a shell command | `command` |
259
+ | `agent` | Spawn a subagent | `agent`, `input`, `timeout` |
260
+ | `notify` | Send notifications | `channels`, `message` |
261
+ | `gate` | Wait for a condition with retries | `verify` (with `retry` + `retry_delay`) |
262
+
263
+ ### Variables
264
+
265
+ Use `{{variable_name}}` in any string field. Variables come from:
266
+
267
+ 1. **Workflow inputs** — defined in the `inputs` section
268
+ 2. **`--input` flag** — JSON passed to `icex-flow plan`
269
+ 3. **Step capture** — `"capture": "pr_url"` saves a step's stdout as a variable for later steps
119
270
 
120
271
  ### Verification
121
272
 
@@ -124,35 +275,148 @@ Every step can have a `verify` block:
124
275
  ```json
125
276
  {
126
277
  "verify": {
127
- "command": "gh pr checks main --json state",
128
- "expect": "SUCCESS",
129
- "retry": 10,
130
- "retry_delay": 30
278
+ "command": "gh pr view 42 --json state -q '.state'",
279
+ "expect": "MERGED",
280
+ "retry": 5,
281
+ "retry_delay": 10
131
282
  }
132
283
  }
133
284
  ```
134
285
 
135
- Verification runs after each step. If it fails, the workflow stops.
286
+ - `expect` output must contain this string
287
+ - `expect_exit` — command must exit with this code
288
+ - `retry` / `retry_delay` — retry N times with delay (seconds) between attempts
289
+ - If verification fails after all retries → workflow stops, `on_failure` fires
290
+
291
+ ## Knowledge System
292
+
293
+ Agents lose context on restart. `icex-flow learn` gives them persistent memory:
294
+
295
+ ```bash
296
+ # Add knowledge with categories
297
+ icex-flow learn "k3d is dev environment, U9 is production" --category environment
298
+ icex-flow learn "quant-bridge connects IBKR TWS via socat relay" --category architecture
299
+ icex-flow learn "never kubectl apply on production without approval" --category safety
300
+
301
+ # List what the project knows
302
+ icex-flow learn --list
303
+
304
+ # Remove outdated knowledge
305
+ icex-flow learn --remove <id>
306
+ ```
307
+
308
+ ### Categories
309
+
310
+ | Category | Purpose |
311
+ |----------|---------|
312
+ | `environment` | Clusters, servers, IPs, namespaces |
313
+ | `architecture` | Services, data flow, dependencies |
314
+ | `safety` | Rules, constraints, things to never do |
315
+ | `workflow` | Process overrides, special handling |
316
+ | `custom` | Anything else |
317
+
318
+ Knowledge is stored in `.icex-flow/knowledge.json` and merged into `PROJECT.md` when you run `icex-flow generate`.
319
+
320
+ ## Project Registry
321
+
322
+ When you `init` a project, it's registered in `~/.icex-flow/projects.json`. This lets agents find all configured projects:
323
+
324
+ ```bash
325
+ icex-flow projects list # Show all registered projects
326
+ icex-flow projects add /path # Register a project manually
327
+ icex-flow projects remove /path # Unregister a project
328
+ ```
136
329
 
137
- ## Platform Support
330
+ ## Platform Integration
138
331
 
139
- | Platform | Status | Integration |
140
- |----------|--------|------------|
141
- | **OpenClaw** | ✅ Supported | SKILL.md included, install as skill |
142
- | **Claude Code** | 🔜 Planned | Programmatic API via `import { routeTask } from 'icex-flow'` |
332
+ ### OpenClaw
143
333
 
144
- ## Programmatic API
334
+ icex-flow ships with a `SKILL.md` — drop it into your skills directory:
335
+
336
+ ```bash
337
+ # Option 1: Symlink to installed package
338
+ ln -s $(npm root -g)/@icex-labs/icex-flow ~/.openclaw/workspace/skills/icex-flow
339
+
340
+ # Option 2: Copy SKILL.md only
341
+ cp $(npm root -g)/@icex-labs/icex-flow/SKILL.md ~/.openclaw/workspace/skills/icex-flow/
342
+ ```
343
+
344
+ The skill teaches agents to use `icex-flow route → context → plan → verify` instead of freestyle execution. OpenClaw adapter is included at `src/adapters/openclaw.ts`.
345
+
346
+ ### Claude Code
347
+
348
+ Use the programmatic API in your CLAUDE.md or custom tools:
145
349
 
146
350
  ```typescript
147
- import { routeTask, planWorkflow, assembleContext, verifyStep } from 'icex-flow';
351
+ import { routeTask, planWorkflow, assembleContext, verifyStep } from '@icex-labs/icex-flow';
148
352
 
353
+ // Route
149
354
  const result = routeTask(routesConfig, { description: "fix login bug", labels: ["bug"] });
150
355
  // → { agent: "dev", workflow: "dev-chain", confidence: "keyword" }
151
356
 
357
+ // Plan
152
358
  const plan = planWorkflow(workflowDef, { issue_number: "42", branch_name: "fix/login" });
153
359
  // → { steps: [...], variables: {...} }
154
360
  ```
155
361
 
362
+ Or use the CLI in your CLAUDE.md instructions:
363
+
364
+ ```markdown
365
+ ## Task Execution
366
+ Before starting any task, run `icex-flow route "<task>"` to determine the correct workflow.
367
+ Follow the plan from `icex-flow plan <workflow>` exactly — do not skip steps.
368
+ ```
369
+
370
+ ## Example: Full Dev Pipeline
371
+
372
+ Here's what happens when an agent receives "fix issue #42":
373
+
374
+ ```
375
+ 1. icex-flow route "fix issue #42" --labels auto-ok
376
+ → agent: dev, workflow: dev-chain
377
+
378
+ 2. icex-flow context dev-chain --step implement
379
+ → Injects: workflow rules + project architecture + API docs
380
+
381
+ 3. icex-flow plan dev-chain --input '{"issue_number":"42","branch_name":"fix/42-login-bug"}'
382
+ → 7-step plan:
383
+ Step 1: Lock issue (add in-progress label)
384
+ Step 2: Create branch (git checkout -b)
385
+ Step 3: Implement (spawn dev-coder agent, 600s timeout)
386
+ Step 4: Create PR (gh pr create)
387
+ Step 5: Wait CI (gate with 12 retries × 30s)
388
+ Step 6: Merge PR (squash merge)
389
+ Step 7: Notify (Telegram message)
390
+
391
+ 4. Agent executes each step, running icex-flow verify after each one.
392
+ If any step fails → on_failure notification fires, workflow stops.
393
+ ```
394
+
395
+ **Same input, same output. Every time.**
396
+
397
+ ## Why Not Just Prompt Better?
398
+
399
+ Prompting works for simple tasks. For multi-step pipelines, it breaks down:
400
+
401
+ | Approach | Works for | Fails at |
402
+ |----------|-----------|----------|
403
+ | Detailed prompts | Simple tasks | Agent still forgets steps under load |
404
+ | System instructions | Setting tone/rules | Can't enforce step ordering |
405
+ | CLAUDE.md / AGENTS.md | Conventions | Agent reads selectively |
406
+ | **icex-flow** | **Multi-step pipelines** | — |
407
+
408
+ icex-flow doesn't replace prompting — it handles the structural parts (routing, ordering, verification) so the LLM can focus on the creative parts (writing code, solving problems).
409
+
410
+ ## Contributing
411
+
412
+ ```bash
413
+ git clone https://github.com/icex-labs/icex-flow.git
414
+ cd icex-flow
415
+ npm install
416
+ npm run build
417
+ npm link # for local testing
418
+ ```
419
+
156
420
  ## License
157
421
 
158
422
  MIT — [icex-labs](https://github.com/icex-labs)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@icex-labs/icex-flow",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Deterministic agent workflow orchestration — eliminate randomness in AI agent pipelines",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",