poly-weaver 0.2.5
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.
- package/README.md +388 -0
- package/dist/agents/implementors/adapter.d.ts +18 -0
- package/dist/agents/implementors/adapter.d.ts.map +1 -0
- package/dist/agents/implementors/adapter.js +36 -0
- package/dist/agents/implementors/adapter.js.map +1 -0
- package/dist/agents/implementors/dsl.d.ts +11 -0
- package/dist/agents/implementors/dsl.d.ts.map +1 -0
- package/dist/agents/implementors/dsl.js +9 -0
- package/dist/agents/implementors/dsl.js.map +1 -0
- package/dist/agents/implementors/handler.d.ts +10 -0
- package/dist/agents/implementors/handler.d.ts.map +1 -0
- package/dist/agents/implementors/handler.js +55 -0
- package/dist/agents/implementors/handler.js.map +1 -0
- package/dist/agents/implementors/index.d.ts +10 -0
- package/dist/agents/implementors/index.d.ts.map +1 -0
- package/dist/agents/implementors/index.js +21 -0
- package/dist/agents/implementors/index.js.map +1 -0
- package/dist/agents/implementors/prompts.d.ts +20 -0
- package/dist/agents/implementors/prompts.d.ts.map +1 -0
- package/dist/agents/implementors/prompts.js +72 -0
- package/dist/agents/implementors/prompts.js.map +1 -0
- package/dist/agents/implementors/types.d.ts +24 -0
- package/dist/agents/implementors/types.d.ts.map +1 -0
- package/dist/agents/implementors/types.js +2 -0
- package/dist/agents/implementors/types.js.map +1 -0
- package/dist/agents/index.d.ts +12 -0
- package/dist/agents/index.d.ts.map +1 -0
- package/dist/agents/index.js +25 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/planners/adapter.d.ts +22 -0
- package/dist/agents/planners/adapter.d.ts.map +1 -0
- package/dist/agents/planners/adapter.js +67 -0
- package/dist/agents/planners/adapter.js.map +1 -0
- package/dist/agents/planners/dsl.d.ts +13 -0
- package/dist/agents/planners/dsl.d.ts.map +1 -0
- package/dist/agents/planners/dsl.js +9 -0
- package/dist/agents/planners/dsl.js.map +1 -0
- package/dist/agents/planners/handler.d.ts +9 -0
- package/dist/agents/planners/handler.d.ts.map +1 -0
- package/dist/agents/planners/handler.js +86 -0
- package/dist/agents/planners/handler.js.map +1 -0
- package/dist/agents/planners/index.d.ts +10 -0
- package/dist/agents/planners/index.d.ts.map +1 -0
- package/dist/agents/planners/index.js +21 -0
- package/dist/agents/planners/index.js.map +1 -0
- package/dist/agents/planners/prompts.d.ts +30 -0
- package/dist/agents/planners/prompts.d.ts.map +1 -0
- package/dist/agents/planners/prompts.js +153 -0
- package/dist/agents/planners/prompts.js.map +1 -0
- package/dist/agents/planners/types.d.ts +37 -0
- package/dist/agents/planners/types.d.ts.map +1 -0
- package/dist/agents/planners/types.js +2 -0
- package/dist/agents/planners/types.js.map +1 -0
- package/dist/agents/registry.d.ts +29 -0
- package/dist/agents/registry.d.ts.map +1 -0
- package/dist/agents/registry.js +44 -0
- package/dist/agents/registry.js.map +1 -0
- package/dist/agents/reviewers/adapter.d.ts +10 -0
- package/dist/agents/reviewers/adapter.d.ts.map +1 -0
- package/dist/agents/reviewers/adapter.js +35 -0
- package/dist/agents/reviewers/adapter.js.map +1 -0
- package/dist/agents/reviewers/dsl.d.ts +12 -0
- package/dist/agents/reviewers/dsl.d.ts.map +1 -0
- package/dist/agents/reviewers/dsl.js +9 -0
- package/dist/agents/reviewers/dsl.js.map +1 -0
- package/dist/agents/reviewers/handler.d.ts +8 -0
- package/dist/agents/reviewers/handler.d.ts.map +1 -0
- package/dist/agents/reviewers/handler.js +48 -0
- package/dist/agents/reviewers/handler.js.map +1 -0
- package/dist/agents/reviewers/index.d.ts +10 -0
- package/dist/agents/reviewers/index.d.ts.map +1 -0
- package/dist/agents/reviewers/index.js +33 -0
- package/dist/agents/reviewers/index.js.map +1 -0
- package/dist/agents/reviewers/prompts.d.ts +25 -0
- package/dist/agents/reviewers/prompts.d.ts.map +1 -0
- package/dist/agents/reviewers/prompts.js +143 -0
- package/dist/agents/reviewers/prompts.js.map +1 -0
- package/dist/agents/reviewers/types.d.ts +35 -0
- package/dist/agents/reviewers/types.d.ts.map +1 -0
- package/dist/agents/reviewers/types.js +10 -0
- package/dist/agents/reviewers/types.js.map +1 -0
- package/dist/agents/runner.d.ts +62 -0
- package/dist/agents/runner.d.ts.map +1 -0
- package/dist/agents/runner.js +136 -0
- package/dist/agents/runner.js.map +1 -0
- package/dist/agents/simplifiers/adapter.d.ts +12 -0
- package/dist/agents/simplifiers/adapter.d.ts.map +1 -0
- package/dist/agents/simplifiers/adapter.js +27 -0
- package/dist/agents/simplifiers/adapter.js.map +1 -0
- package/dist/agents/simplifiers/dsl.d.ts +11 -0
- package/dist/agents/simplifiers/dsl.d.ts.map +1 -0
- package/dist/agents/simplifiers/dsl.js +9 -0
- package/dist/agents/simplifiers/dsl.js.map +1 -0
- package/dist/agents/simplifiers/handler.d.ts +9 -0
- package/dist/agents/simplifiers/handler.d.ts.map +1 -0
- package/dist/agents/simplifiers/handler.js +39 -0
- package/dist/agents/simplifiers/handler.js.map +1 -0
- package/dist/agents/simplifiers/index.d.ts +10 -0
- package/dist/agents/simplifiers/index.d.ts.map +1 -0
- package/dist/agents/simplifiers/index.js +20 -0
- package/dist/agents/simplifiers/index.js.map +1 -0
- package/dist/agents/simplifiers/prompts.d.ts +11 -0
- package/dist/agents/simplifiers/prompts.d.ts.map +1 -0
- package/dist/agents/simplifiers/prompts.js +24 -0
- package/dist/agents/simplifiers/prompts.js.map +1 -0
- package/dist/agents/simplifiers/types.d.ts +15 -0
- package/dist/agents/simplifiers/types.d.ts.map +1 -0
- package/dist/agents/simplifiers/types.js +2 -0
- package/dist/agents/simplifiers/types.js.map +1 -0
- package/dist/agents/whip-hint.d.ts +23 -0
- package/dist/agents/whip-hint.d.ts.map +1 -0
- package/dist/agents/whip-hint.js +41 -0
- package/dist/agents/whip-hint.js.map +1 -0
- package/dist/ansi.d.ts +39 -0
- package/dist/ansi.d.ts.map +1 -0
- package/dist/ansi.js +158 -0
- package/dist/ansi.js.map +1 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +309 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +41 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +55 -0
- package/dist/config.js.map +1 -0
- package/dist/dsl.d.ts +25 -0
- package/dist/dsl.d.ts.map +1 -0
- package/dist/dsl.js +16 -0
- package/dist/dsl.js.map +1 -0
- package/dist/flow/artifacts.d.ts +13 -0
- package/dist/flow/artifacts.d.ts.map +1 -0
- package/dist/flow/artifacts.js +27 -0
- package/dist/flow/artifacts.js.map +1 -0
- package/dist/flow/built-in/default.d.ts +15 -0
- package/dist/flow/built-in/default.d.ts.map +1 -0
- package/dist/flow/built-in/default.js +123 -0
- package/dist/flow/built-in/default.js.map +1 -0
- package/dist/flow/built-in/default.ts +152 -0
- package/dist/flow/built-in/why-so-serious.d.ts +15 -0
- package/dist/flow/built-in/why-so-serious.d.ts.map +1 -0
- package/dist/flow/built-in/why-so-serious.js +147 -0
- package/dist/flow/built-in/why-so-serious.js.map +1 -0
- package/dist/flow/custom/AUTHORING.md +558 -0
- package/dist/flow/custom/index.d.ts +3 -0
- package/dist/flow/custom/index.d.ts.map +1 -0
- package/dist/flow/custom/index.js +2 -0
- package/dist/flow/custom/index.js.map +1 -0
- package/dist/flow/custom/load.d.ts +19 -0
- package/dist/flow/custom/load.d.ts.map +1 -0
- package/dist/flow/custom/load.js +117 -0
- package/dist/flow/custom/load.js.map +1 -0
- package/dist/flow/diagram.d.ts +37 -0
- package/dist/flow/diagram.d.ts.map +1 -0
- package/dist/flow/diagram.js +596 -0
- package/dist/flow/diagram.js.map +1 -0
- package/dist/flow/dsl.d.ts +65 -0
- package/dist/flow/dsl.d.ts.map +1 -0
- package/dist/flow/dsl.js +210 -0
- package/dist/flow/dsl.js.map +1 -0
- package/dist/flow/executor.d.ts +22 -0
- package/dist/flow/executor.d.ts.map +1 -0
- package/dist/flow/executor.js +185 -0
- package/dist/flow/executor.js.map +1 -0
- package/dist/flow/index.d.ts +16 -0
- package/dist/flow/index.d.ts.map +1 -0
- package/dist/flow/index.js +12 -0
- package/dist/flow/index.js.map +1 -0
- package/dist/flow/inspect.d.ts +21 -0
- package/dist/flow/inspect.d.ts.map +1 -0
- package/dist/flow/inspect.js +54 -0
- package/dist/flow/inspect.js.map +1 -0
- package/dist/flow/neighbors.d.ts +10 -0
- package/dist/flow/neighbors.d.ts.map +1 -0
- package/dist/flow/neighbors.js +48 -0
- package/dist/flow/neighbors.js.map +1 -0
- package/dist/flow/params.d.ts +21 -0
- package/dist/flow/params.d.ts.map +1 -0
- package/dist/flow/params.js +44 -0
- package/dist/flow/params.js.map +1 -0
- package/dist/flow/types.d.ts +159 -0
- package/dist/flow/types.d.ts.map +1 -0
- package/dist/flow/types.js +33 -0
- package/dist/flow/types.js.map +1 -0
- package/dist/flow-editor/index.d.ts +9 -0
- package/dist/flow-editor/index.d.ts.map +1 -0
- package/dist/flow-editor/index.js +6 -0
- package/dist/flow-editor/index.js.map +1 -0
- package/dist/flow-editor/llm.d.ts +33 -0
- package/dist/flow-editor/llm.d.ts.map +1 -0
- package/dist/flow-editor/llm.js +137 -0
- package/dist/flow-editor/llm.js.map +1 -0
- package/dist/flow-editor/names.d.ts +5 -0
- package/dist/flow-editor/names.d.ts.map +1 -0
- package/dist/flow-editor/names.js +21 -0
- package/dist/flow-editor/names.js.map +1 -0
- package/dist/flow-editor/save.d.ts +59 -0
- package/dist/flow-editor/save.d.ts.map +1 -0
- package/dist/flow-editor/save.js +143 -0
- package/dist/flow-editor/save.js.map +1 -0
- package/dist/flow-editor/tui.d.ts +56 -0
- package/dist/flow-editor/tui.d.ts.map +1 -0
- package/dist/flow-editor/tui.js +628 -0
- package/dist/flow-editor/tui.js.map +1 -0
- package/dist/flow-editor/validate.d.ts +39 -0
- package/dist/flow-editor/validate.d.ts.map +1 -0
- package/dist/flow-editor/validate.js +192 -0
- package/dist/flow-editor/validate.js.map +1 -0
- package/dist/git-info.d.ts +6 -0
- package/dist/git-info.d.ts.map +1 -0
- package/dist/git-info.js +26 -0
- package/dist/git-info.js.map +1 -0
- package/dist/orchestrator.d.ts +55 -0
- package/dist/orchestrator.d.ts.map +1 -0
- package/dist/orchestrator.js +240 -0
- package/dist/orchestrator.js.map +1 -0
- package/dist/preflight.d.ts +30 -0
- package/dist/preflight.d.ts.map +1 -0
- package/dist/preflight.js +107 -0
- package/dist/preflight.js.map +1 -0
- package/dist/preview-panel.d.ts +87 -0
- package/dist/preview-panel.d.ts.map +1 -0
- package/dist/preview-panel.js +418 -0
- package/dist/preview-panel.js.map +1 -0
- package/dist/prompts.d.ts +34 -0
- package/dist/prompts.d.ts.map +1 -0
- package/dist/prompts.js +67 -0
- package/dist/prompts.js.map +1 -0
- package/dist/providers/base-completion.d.ts +56 -0
- package/dist/providers/base-completion.d.ts.map +1 -0
- package/dist/providers/base-completion.js +111 -0
- package/dist/providers/base-completion.js.map +1 -0
- package/dist/providers/claude/completion.d.ts +28 -0
- package/dist/providers/claude/completion.d.ts.map +1 -0
- package/dist/providers/claude/completion.js +103 -0
- package/dist/providers/claude/completion.js.map +1 -0
- package/dist/providers/claude/index.d.ts +2 -0
- package/dist/providers/claude/index.d.ts.map +1 -0
- package/dist/providers/claude/index.js +2 -0
- package/dist/providers/claude/index.js.map +1 -0
- package/dist/providers/claude/session.d.ts +55 -0
- package/dist/providers/claude/session.d.ts.map +1 -0
- package/dist/providers/claude/session.js +172 -0
- package/dist/providers/claude/session.js.map +1 -0
- package/dist/providers/claude/strategy.d.ts +14 -0
- package/dist/providers/claude/strategy.d.ts.map +1 -0
- package/dist/providers/claude/strategy.js +38 -0
- package/dist/providers/claude/strategy.js.map +1 -0
- package/dist/providers/codex/completion.d.ts +21 -0
- package/dist/providers/codex/completion.d.ts.map +1 -0
- package/dist/providers/codex/completion.js +63 -0
- package/dist/providers/codex/completion.js.map +1 -0
- package/dist/providers/codex/index.d.ts +2 -0
- package/dist/providers/codex/index.d.ts.map +1 -0
- package/dist/providers/codex/index.js +2 -0
- package/dist/providers/codex/index.js.map +1 -0
- package/dist/providers/codex/session.d.ts +46 -0
- package/dist/providers/codex/session.d.ts.map +1 -0
- package/dist/providers/codex/session.js +151 -0
- package/dist/providers/codex/session.js.map +1 -0
- package/dist/providers/codex/strategy.d.ts +14 -0
- package/dist/providers/codex/strategy.d.ts.map +1 -0
- package/dist/providers/codex/strategy.js +41 -0
- package/dist/providers/codex/strategy.js.map +1 -0
- package/dist/providers/copilot/completion.d.ts +22 -0
- package/dist/providers/copilot/completion.d.ts.map +1 -0
- package/dist/providers/copilot/completion.js +65 -0
- package/dist/providers/copilot/completion.js.map +1 -0
- package/dist/providers/copilot/index.d.ts +2 -0
- package/dist/providers/copilot/index.d.ts.map +1 -0
- package/dist/providers/copilot/index.js +2 -0
- package/dist/providers/copilot/index.js.map +1 -0
- package/dist/providers/copilot/session.d.ts +39 -0
- package/dist/providers/copilot/session.d.ts.map +1 -0
- package/dist/providers/copilot/session.js +185 -0
- package/dist/providers/copilot/session.js.map +1 -0
- package/dist/providers/copilot/strategy.d.ts +14 -0
- package/dist/providers/copilot/strategy.d.ts.map +1 -0
- package/dist/providers/copilot/strategy.js +48 -0
- package/dist/providers/copilot/strategy.js.map +1 -0
- package/dist/providers/index.d.ts +8 -0
- package/dist/providers/index.d.ts.map +1 -0
- package/dist/providers/index.js +6 -0
- package/dist/providers/index.js.map +1 -0
- package/dist/providers/invoke.d.ts +14 -0
- package/dist/providers/invoke.d.ts.map +1 -0
- package/dist/providers/invoke.js +55 -0
- package/dist/providers/invoke.js.map +1 -0
- package/dist/providers/path-utils.d.ts +7 -0
- package/dist/providers/path-utils.d.ts.map +1 -0
- package/dist/providers/path-utils.js +9 -0
- package/dist/providers/path-utils.js.map +1 -0
- package/dist/providers/prompt-file.d.ts +8 -0
- package/dist/providers/prompt-file.d.ts.map +1 -0
- package/dist/providers/prompt-file.js +17 -0
- package/dist/providers/prompt-file.js.map +1 -0
- package/dist/providers/registry.d.ts +17 -0
- package/dist/providers/registry.d.ts.map +1 -0
- package/dist/providers/registry.js +49 -0
- package/dist/providers/registry.js.map +1 -0
- package/dist/providers/types.d.ts +145 -0
- package/dist/providers/types.d.ts.map +1 -0
- package/dist/providers/types.js +5 -0
- package/dist/providers/types.js.map +1 -0
- package/dist/providers/version.d.ts +11 -0
- package/dist/providers/version.d.ts.map +1 -0
- package/dist/providers/version.js +31 -0
- package/dist/providers/version.js.map +1 -0
- package/dist/pty/exit.d.ts +12 -0
- package/dist/pty/exit.d.ts.map +1 -0
- package/dist/pty/exit.js +43 -0
- package/dist/pty/exit.js.map +1 -0
- package/dist/pty/spawn.d.ts +20 -0
- package/dist/pty/spawn.d.ts.map +1 -0
- package/dist/pty/spawn.js +163 -0
- package/dist/pty/spawn.js.map +1 -0
- package/dist/pty/types.d.ts +44 -0
- package/dist/pty/types.d.ts.map +1 -0
- package/dist/pty/types.js +2 -0
- package/dist/pty/types.js.map +1 -0
- package/dist/session/dir.d.ts +19 -0
- package/dist/session/dir.d.ts.map +1 -0
- package/dist/session/dir.js +31 -0
- package/dist/session/dir.js.map +1 -0
- package/dist/session/locator.d.ts +28 -0
- package/dist/session/locator.d.ts.map +1 -0
- package/dist/session/locator.js +88 -0
- package/dist/session/locator.js.map +1 -0
- package/dist/session/reader.d.ts +12 -0
- package/dist/session/reader.d.ts.map +1 -0
- package/dist/session/reader.js +94 -0
- package/dist/session/reader.js.map +1 -0
- package/dist/startup-tui.d.ts +75 -0
- package/dist/startup-tui.d.ts.map +1 -0
- package/dist/startup-tui.js +504 -0
- package/dist/startup-tui.js.map +1 -0
- package/dist/status-bar.d.ts +29 -0
- package/dist/status-bar.d.ts.map +1 -0
- package/dist/status-bar.js +135 -0
- package/dist/status-bar.js.map +1 -0
- package/dist/terminal-input.d.ts +51 -0
- package/dist/terminal-input.d.ts.map +1 -0
- package/dist/terminal-input.js +212 -0
- package/dist/terminal-input.js.map +1 -0
- package/dist/user/dsl.d.ts +13 -0
- package/dist/user/dsl.d.ts.map +1 -0
- package/dist/user/dsl.js +19 -0
- package/dist/user/dsl.js.map +1 -0
- package/dist/user/handler.d.ts +16 -0
- package/dist/user/handler.d.ts.map +1 -0
- package/dist/user/handler.js +49 -0
- package/dist/user/handler.js.map +1 -0
- package/dist/user/index.d.ts +5 -0
- package/dist/user/index.d.ts.map +1 -0
- package/dist/user/index.js +4 -0
- package/dist/user/index.js.map +1 -0
- package/dist/user/prompt.d.ts +86 -0
- package/dist/user/prompt.d.ts.map +1 -0
- package/dist/user/prompt.js +320 -0
- package/dist/user/prompt.js.map +1 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +4 -0
- package/dist/version.js.map +1 -0
- package/package.json +50 -0
- package/schemas/review-verdict.json +41 -0
|
@@ -0,0 +1,558 @@
|
|
|
1
|
+
# Custom Flow Authoring Guide
|
|
2
|
+
|
|
3
|
+
This is the reference for creating and editing poly-weaver custom flow templates. A flow template defines the sequence of agent and user steps that poly-weaver executes for a task.
|
|
4
|
+
|
|
5
|
+
## 1. Essentials
|
|
6
|
+
|
|
7
|
+
- **Where**: `~/.poly-weaver/flows/*.mjs` (or `*.js`)
|
|
8
|
+
- **Export**: `export default function(dsl) { ... }` or `export function createTemplate(dsl) { ... }`
|
|
9
|
+
- **Must return**: `{ name: string, params: FlowParam[], build(values): FlowDefinition }`
|
|
10
|
+
- **Helpers**: always use `plan()`, `review()`, `implement()`, `simplify()`, or `user()` — never `agentStep()` directly
|
|
11
|
+
- **Finalize**: `build()` must return the result of `defineFlow(name, steps)`
|
|
12
|
+
|
|
13
|
+
Minimal example:
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
export default function (dsl) {
|
|
17
|
+
const { defineFlow, loop, artifactData, plan, review, TASK } = dsl;
|
|
18
|
+
|
|
19
|
+
return {
|
|
20
|
+
name: "my-flow",
|
|
21
|
+
params: [
|
|
22
|
+
{ key: "planner", type: "driver", role: "planner", label: "Planner", default: "claude" },
|
|
23
|
+
{ key: "reviewer", type: "driver", role: "reviewer", label: "Reviewer", default: "codex" },
|
|
24
|
+
{ key: "maxIterations", type: "number", label: "Max Iterations", default: 5, min: 1, max: 50 },
|
|
25
|
+
],
|
|
26
|
+
|
|
27
|
+
build(values) {
|
|
28
|
+
return defineFlow("my-flow", [
|
|
29
|
+
loop(values.maxIterations, artifactData("verdict", "approved"), [
|
|
30
|
+
plan({
|
|
31
|
+
driver: values.planner,
|
|
32
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
33
|
+
writes: { plan: "plan" },
|
|
34
|
+
}),
|
|
35
|
+
review({
|
|
36
|
+
driver: values.reviewer,
|
|
37
|
+
variant: "plan",
|
|
38
|
+
reads: { task: TASK, plan: "plan" },
|
|
39
|
+
writes: { verdict: "verdict" },
|
|
40
|
+
}),
|
|
41
|
+
]),
|
|
42
|
+
]);
|
|
43
|
+
},
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 2. DSL Helper Defaults
|
|
49
|
+
|
|
50
|
+
Every helper supplies defaults for optional fields. When you omit an option, the default below applies. When you set an option explicitly, your value wins.
|
|
51
|
+
|
|
52
|
+
| Helper | `phaseLabel` | `reads` | `writes` | `feedbackToTask` | ID prefix | Notes |
|
|
53
|
+
|--------|-------------|---------|----------|-------------------|-----------|-------|
|
|
54
|
+
| `plan(opts)` | `"📝 Planning..."` | **required** | **required** | `false` | `plan` | |
|
|
55
|
+
| `review(opts)` | `"🔍 Reviewing Plan..."` | **required** | **required** | `false` | `review` | When `variant` is `"impl"`: `"🔍 Reviewing Impl..."` |
|
|
56
|
+
| `implement(opts)` | `"🔨 Implementing..."` | **required** | `{}` | `false` | `implement` | |
|
|
57
|
+
| `simplify(opts)` | `"✨ Simplifying..."` | `{}` (hardcoded) | **required** | `false` | `simplify` | `reads` cannot be overridden — simplifier inspects the working directory directly |
|
|
58
|
+
| `user(label, opts?)` | `"👤 User Review..."` | `{ display: "plan" }` | `{}` | `true` | `user-${label}` | `label` is a semantic name (e.g. `"user:feedback"`) |
|
|
59
|
+
|
|
60
|
+
**ID generation**: `defineFlow()` auto-assigns IDs using the prefix — first occurrence gets the bare prefix (e.g. `plan`), subsequent get a numeric suffix (e.g. `plan-2`). You can override with `id`.
|
|
61
|
+
|
|
62
|
+
## 3. How To Edit Common Requests
|
|
63
|
+
|
|
64
|
+
### Change all phase labels
|
|
65
|
+
|
|
66
|
+
Set `phaseLabel` explicitly on every step. Helpers only inject their default when you omit it.
|
|
67
|
+
|
|
68
|
+
```js
|
|
69
|
+
// Before (uses default "📝 Planning...")
|
|
70
|
+
plan({ driver: d, reads: { task: TASK }, writes: { plan: "plan" } })
|
|
71
|
+
|
|
72
|
+
// After
|
|
73
|
+
plan({ driver: d, reads: { task: TASK }, writes: { plan: "plan" }, phaseLabel: "Step 1: Plan" })
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
To change every label in a flow, add `phaseLabel` to every `plan()`, `review()`, `implement()`, `simplify()`, and `user()` call. Steps that already have an explicit `phaseLabel` keep it unless you change it.
|
|
77
|
+
|
|
78
|
+
### Change only review-plan vs review-impl labels
|
|
79
|
+
|
|
80
|
+
`review()` chooses its default label based on `variant`:
|
|
81
|
+
- `variant: "plan"` (or omitted) → `"🔍 Reviewing Plan..."`
|
|
82
|
+
- `variant: "impl"` → `"🔍 Reviewing Impl..."`
|
|
83
|
+
|
|
84
|
+
To override one without affecting the other, set `phaseLabel` on the specific `review()` call:
|
|
85
|
+
|
|
86
|
+
```js
|
|
87
|
+
review({ driver: d, variant: "plan", phaseLabel: "Checking Plan...", reads: {...}, writes: {...} })
|
|
88
|
+
// The variant: "impl" review() elsewhere keeps its default
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Use loop-aware labels with `cyclePhase()`
|
|
92
|
+
|
|
93
|
+
Show one label on the first iteration and a different label on subsequent iterations:
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
// Before (static label)
|
|
97
|
+
plan({ driver: d, phaseLabel: "📝 Planning...", reads: {...}, writes: {...} })
|
|
98
|
+
|
|
99
|
+
// After (revision-aware)
|
|
100
|
+
plan({ driver: d, phaseLabel: cyclePhase("📝 Planning...", "✏️ Revising Plan..."), reads: {...}, writes: {...} })
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`cyclePhase()` must be inside a `loop()`. It auto-binds to the containing loop.
|
|
104
|
+
|
|
105
|
+
### Change the default display artifact for `user()`
|
|
106
|
+
|
|
107
|
+
By default, `user()` reads `{ display: "plan" }`. Override `reads` to show a different artifact:
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
// Before (shows the plan)
|
|
111
|
+
user("user:feedback", { writes: { verdict: "verdict" } })
|
|
112
|
+
|
|
113
|
+
// After (shows the implementation verdict)
|
|
114
|
+
user("user:feedback", { reads: { display: "impl-verdict" }, writes: { verdict: "verdict" } })
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Adjust loop counts
|
|
118
|
+
|
|
119
|
+
Loop counts come from template params. Change the param default, or add a new param:
|
|
120
|
+
|
|
121
|
+
```js
|
|
122
|
+
params: [
|
|
123
|
+
{ key: "maxIterations", type: "number", label: "Max Iterations", default: 10, min: 1, max: 50 },
|
|
124
|
+
],
|
|
125
|
+
build(values) {
|
|
126
|
+
return defineFlow("my-flow", [
|
|
127
|
+
loop(values.maxIterations, artifactData("verdict", "approved"), [ ... ]),
|
|
128
|
+
]);
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Preserve explicit overrides
|
|
133
|
+
|
|
134
|
+
When editing a flow, check whether a step already has an explicit option before applying a blanket change. For example, if a `plan()` already has `phaseLabel: cyclePhase(...)`, replacing it with a static string removes the loop-aware behavior.
|
|
135
|
+
|
|
136
|
+
## 4. FlowDSL Object
|
|
137
|
+
|
|
138
|
+
The `dsl` object passed to your factory provides:
|
|
139
|
+
|
|
140
|
+
| Function | Purpose |
|
|
141
|
+
|----------|---------|
|
|
142
|
+
| `defineFlow(name, steps)` | Finalize a flow definition |
|
|
143
|
+
| `loop(max, until, steps, opts?)` | Create a loop step |
|
|
144
|
+
| `plan(opts)` | Create a planner agent step |
|
|
145
|
+
| `review(opts)` | Create a reviewer agent step |
|
|
146
|
+
| `implement(opts)` | Create an implementor agent step |
|
|
147
|
+
| `simplify(opts)` | Create a simplifier agent step |
|
|
148
|
+
| `user(label, opts?)` | Create a user interaction step |
|
|
149
|
+
| `artifactData(artifactName, field, expected?)` | Structured predicate on artifact data |
|
|
150
|
+
| `ctxField(field, op, value)` | Structured predicate on context fields |
|
|
151
|
+
| `cyclePhase(first, subsequent)` | Loop-aware phase label |
|
|
152
|
+
| `predicateLabel(pred)` | Convert structured predicate to display label |
|
|
153
|
+
| `TASK` | Well-known artifact name (`"task"`) for the user's task description |
|
|
154
|
+
|
|
155
|
+
> **Note**: `agentStep` is intentionally excluded. It is the low-level builder that role-specific helpers wrap. Only built-in roles have registered handlers — always use `plan()`, `review()`, `implement()`, `simplify()`, or `user()`.
|
|
156
|
+
|
|
157
|
+
## 5. Step Builder Signatures
|
|
158
|
+
|
|
159
|
+
### `plan(opts)` → `AgentStep`
|
|
160
|
+
|
|
161
|
+
```js
|
|
162
|
+
plan({
|
|
163
|
+
driver: string, // required — driver name from param value
|
|
164
|
+
reads: Record<string, string>, // required — input artifact mapping
|
|
165
|
+
writes: Record<string, string>, // required — output artifact mapping
|
|
166
|
+
id?: string,
|
|
167
|
+
feedbackToTask?: boolean, // default: false
|
|
168
|
+
when?: WhenCondition, // conditional execution
|
|
169
|
+
whenLabel?: string, // display label for when condition
|
|
170
|
+
phaseLabel?: PhaseLabelSpec, // default: "📝 Planning..."
|
|
171
|
+
})
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### `review(opts)` → `AgentStep`
|
|
175
|
+
|
|
176
|
+
```js
|
|
177
|
+
review({
|
|
178
|
+
driver: string, // required
|
|
179
|
+
reads: Record<string, string>, // required
|
|
180
|
+
writes: Record<string, string>, // required
|
|
181
|
+
id?: string,
|
|
182
|
+
variant?: string, // differentiates review context (e.g. "plan", "impl")
|
|
183
|
+
feedbackToTask?: boolean, // default: false
|
|
184
|
+
phaseLabel?: PhaseLabelSpec, // default: varies by variant (see §2)
|
|
185
|
+
})
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### `implement(opts)` → `AgentStep`
|
|
189
|
+
|
|
190
|
+
```js
|
|
191
|
+
implement({
|
|
192
|
+
driver: string, // required
|
|
193
|
+
reads: Record<string, string>, // required
|
|
194
|
+
writes?: Record<string, string>, // default: {}
|
|
195
|
+
id?: string,
|
|
196
|
+
feedbackToTask?: boolean, // default: false
|
|
197
|
+
phaseLabel?: PhaseLabelSpec, // default: "🔨 Implementing..."
|
|
198
|
+
})
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### `simplify(opts)` → `AgentStep`
|
|
202
|
+
|
|
203
|
+
```js
|
|
204
|
+
simplify({
|
|
205
|
+
driver: string, // required
|
|
206
|
+
writes: Record<string, string>, // required
|
|
207
|
+
id?: string,
|
|
208
|
+
feedbackToTask?: boolean, // default: false
|
|
209
|
+
when?: WhenCondition,
|
|
210
|
+
phaseLabel?: PhaseLabelSpec, // default: "✨ Simplifying..."
|
|
211
|
+
})
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`reads` is always `{}` (hardcoded) — the simplifier inspects the working directory directly.
|
|
215
|
+
|
|
216
|
+
### `user(label, opts?)` → `UserStep`
|
|
217
|
+
|
|
218
|
+
```js
|
|
219
|
+
user("user:feedback", {
|
|
220
|
+
id?: string,
|
|
221
|
+
when?: WhenCondition,
|
|
222
|
+
whenLabel?: string,
|
|
223
|
+
reads?: Record<string, string>, // default: { display: "plan" }
|
|
224
|
+
writes?: Record<string, string>, // default: {}
|
|
225
|
+
feedbackToTask?: boolean, // default: true
|
|
226
|
+
breakOnAccept?: boolean, // exits containing loop on accept
|
|
227
|
+
phaseLabel?: PhaseLabelSpec, // default: "👤 User Review..."
|
|
228
|
+
})
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
The `label` argument is a semantic name used for ID generation (e.g. `"user:feedback"`, `"user:approval"`).
|
|
232
|
+
|
|
233
|
+
## 6. `loop(max, until, steps, opts?)` → `LoopStep`
|
|
234
|
+
|
|
235
|
+
```js
|
|
236
|
+
loop(maxIterations, untilCondition, stepsArray, {
|
|
237
|
+
onExhausted?: UserStep, // runs when max reached without until becoming true
|
|
238
|
+
untilLabel?: string, // display label override for until condition
|
|
239
|
+
})
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
- `max`: maximum iterations (`Infinity` for uncapped)
|
|
243
|
+
- `until`: predicate or lambda — loop exits when truthy
|
|
244
|
+
- `steps`: array of `FlowStep` (agent, user, or nested loop)
|
|
245
|
+
- `onExhausted`: optional user step that runs when the loop hits `max` without `until` becoming true. If the user rejects, the loop restarts with a fresh iteration budget.
|
|
246
|
+
|
|
247
|
+
## 7. Predicates
|
|
248
|
+
|
|
249
|
+
### `artifactData(artifactName, field, expected?)` — structured
|
|
250
|
+
|
|
251
|
+
Checks `artifacts.getData(artifactName)[field] === expected`. Default `expected` is `true`.
|
|
252
|
+
|
|
253
|
+
```js
|
|
254
|
+
artifactData("verdict", "approved") // verdict.approved === true
|
|
255
|
+
artifactData("verdict", "status", "closed") // verdict.status === "closed"
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Auto-generated labels: `"verdict.approved"`, `"verdict.status=closed"`.
|
|
259
|
+
|
|
260
|
+
### `ctxField(field, op, value)` — structured
|
|
261
|
+
|
|
262
|
+
Checks the loop-local cycle iteration. Currently only `field: "iteration"` is supported.
|
|
263
|
+
|
|
264
|
+
```js
|
|
265
|
+
ctxField("iteration", "!=", 1) // skip on first iteration
|
|
266
|
+
ctxField("iteration", ">", 3) // only after 3rd iteration
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Operators: `"=="`, `"!="`, `"<"`, `">"`, `"<="`, `">="`.
|
|
270
|
+
|
|
271
|
+
Auto-generated labels: `"iter≠1"`, `"iter>3"`.
|
|
272
|
+
|
|
273
|
+
Automatically bound to the containing loop — no loop ID needed.
|
|
274
|
+
|
|
275
|
+
### Lambda predicates `(ctx) => boolean` — escape hatch
|
|
276
|
+
|
|
277
|
+
Full access to `ctx.artifacts` for advanced conditions. No auto-label — use `whenLabel` or `untilLabel` overrides.
|
|
278
|
+
|
|
279
|
+
```js
|
|
280
|
+
when: (ctx) => {
|
|
281
|
+
const data = ctx.artifacts.getData("impl-verdict");
|
|
282
|
+
return data != null && Array.isArray(data.issues) && data.issues.length > 2;
|
|
283
|
+
},
|
|
284
|
+
whenLabel: "impl-verdict.issues>2",
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### `predicateLabel(pred)` → `string`
|
|
288
|
+
|
|
289
|
+
Converts a structured predicate into its human-readable label string. Useful when writing a lambda `whenLabel` that should match the auto-generated format.
|
|
290
|
+
|
|
291
|
+
| Input | Output |
|
|
292
|
+
|-------|--------|
|
|
293
|
+
| `artifactData("verdict", "approved")` | `"verdict.approved"` |
|
|
294
|
+
| `artifactData("verdict", "status", "closed")` | `"verdict.status=closed"` |
|
|
295
|
+
| `ctxField("iteration", "!=", 1)` | `"iter≠1"` |
|
|
296
|
+
| `ctxField("iteration", ">=", 3)` | `"iter≥3"` |
|
|
297
|
+
|
|
298
|
+
## 8. `reads` & `writes` (Artifact Routing)
|
|
299
|
+
|
|
300
|
+
Steps declare which artifacts they consume (`reads`) and produce (`writes`).
|
|
301
|
+
|
|
302
|
+
- **Keys** are semantic names (handler-facing): `"task"`, `"plan"`, `"verdict"`, `"revisePlan"`
|
|
303
|
+
- **Values** are artifact store names: `TASK`, `"plan"`, `"verdict"`, `"impl-verdict"`, `"revise-plan"`
|
|
304
|
+
- Multiple steps can share artifact names (last writer wins)
|
|
305
|
+
- `TASK` is a well-known constant (`"task"`) pre-seeded with the user's task description
|
|
306
|
+
|
|
307
|
+
```js
|
|
308
|
+
plan({
|
|
309
|
+
driver: plannerDriver,
|
|
310
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
311
|
+
writes: { plan: "plan" },
|
|
312
|
+
})
|
|
313
|
+
review({
|
|
314
|
+
driver: reviewerDriver,
|
|
315
|
+
variant: "plan",
|
|
316
|
+
reads: { task: TASK, plan: "plan" },
|
|
317
|
+
writes: { verdict: "verdict" },
|
|
318
|
+
})
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
## 9. Phase Labels
|
|
322
|
+
|
|
323
|
+
Phase labels control the status bar display during step execution.
|
|
324
|
+
|
|
325
|
+
- **Static string**: `phaseLabel: "🔨 Implementing..."`
|
|
326
|
+
- **`cyclePhase(first, subsequent)`**: shows `first` on cycle 1, `subsequent` on cycle 2+ within the containing loop. Must be inside a loop.
|
|
327
|
+
- **Lambda**: `(ctx) => string` for fully dynamic labels.
|
|
328
|
+
|
|
329
|
+
## 10. Other Step Options
|
|
330
|
+
|
|
331
|
+
- **`variant?: string`** — differentiates handlers for the same role (e.g. `"plan"` vs `"impl"` for reviewer)
|
|
332
|
+
- **`feedbackToTask: boolean`** — whether the step's output is appended to the task artifact on loop retry
|
|
333
|
+
- **`breakOnAccept: boolean`** (user only) — exits the containing loop when the user accepts
|
|
334
|
+
- **`when`** — conditional step execution (step is skipped when predicate returns false)
|
|
335
|
+
|
|
336
|
+
## 11. Parameters (`FlowParam`)
|
|
337
|
+
|
|
338
|
+
Three param types. All share `key`, `label`, and optional `description`.
|
|
339
|
+
|
|
340
|
+
### `DriverFlowParam`
|
|
341
|
+
|
|
342
|
+
```js
|
|
343
|
+
{ type: "driver", key: "planner", label: "Planner", role: "planner", default: "claude", description?: "..." }
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
- `role`: `"planner"` | `"reviewer"` | `"implementor"` | `"simplifier"`
|
|
347
|
+
- `default`: `"claude"` | `"codex"` | `"copilot"`
|
|
348
|
+
|
|
349
|
+
### `NumberFlowParam`
|
|
350
|
+
|
|
351
|
+
```js
|
|
352
|
+
{ type: "number", key: "maxIterations", label: "Max Iterations", default: 5, min?: 1, max?: 50 }
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### `BooleanFlowParam`
|
|
356
|
+
|
|
357
|
+
```js
|
|
358
|
+
{ type: "boolean", key: "auto", label: "Auto Mode", default: false, description?: "..." }
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
## 12. FlowTemplate Return Shape
|
|
362
|
+
|
|
363
|
+
```js
|
|
364
|
+
{
|
|
365
|
+
name: string, // unique template identifier
|
|
366
|
+
params: FlowParam[], // user-configurable parameters
|
|
367
|
+
build(values): FlowDefinition // values: resolved param values
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
`build()` receives a `FlowParamValues` object — a record mapping each param `key` to its resolved value (from CLI flags, TUI input, or defaults). It must return the result of `defineFlow()`.
|
|
372
|
+
|
|
373
|
+
## 13. File Loading Rules
|
|
374
|
+
|
|
375
|
+
- **Directory**: `~/.poly-weaver/flows/`
|
|
376
|
+
- **Extensions**: `*.mjs` or `*.js`
|
|
377
|
+
- **Shadowing protection**: custom names cannot match built-in names (`"default"`, `"why-so-serious"`)
|
|
378
|
+
- **Uniqueness**: template names must be globally unique across all custom flow files; duplicates are skipped (first-loaded wins)
|
|
379
|
+
- **Error handling**: errors are collected per-file, not fatal — other flows still load
|
|
380
|
+
|
|
381
|
+
## 14. `StepContext` in Lambda Predicates
|
|
382
|
+
|
|
383
|
+
When writing lambda predicates or phase-label lambdas, you receive `ctx`. The usable surface:
|
|
384
|
+
|
|
385
|
+
| Method | Returns | Purpose |
|
|
386
|
+
|--------|---------|---------|
|
|
387
|
+
| `ctx.artifacts.getData(name)` | parsed object or `undefined` | Structured data from an artifact |
|
|
388
|
+
| `ctx.artifacts.getText(name)` | string or `undefined` | Human-readable text from an artifact |
|
|
389
|
+
| `ctx.artifacts.set(name, { data?, text?, file?, meta? })` | void | Write or clear an artifact |
|
|
390
|
+
|
|
391
|
+
For iteration-based conditions, use the structured `ctxField("iteration", op, value)` predicate rather than accessing loop internals directly.
|
|
392
|
+
|
|
393
|
+
## 15. Patterns & Tips
|
|
394
|
+
|
|
395
|
+
### Uncapped user-driven loop
|
|
396
|
+
Use `Infinity` + `() => false` for the outer loop, and `breakOnAccept: true` on a user step to let the user decide when to exit:
|
|
397
|
+
```js
|
|
398
|
+
loop(Infinity, () => false, [
|
|
399
|
+
// ... agent steps ...
|
|
400
|
+
user("approval", { breakOnAccept: true, writes: { verdict: "verdict" } }),
|
|
401
|
+
])
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
### Skip a step on first iteration
|
|
405
|
+
```js
|
|
406
|
+
plan({
|
|
407
|
+
driver: plannerDriver,
|
|
408
|
+
when: ctxField("iteration", "!=", 1),
|
|
409
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
410
|
+
writes: { plan: "plan" },
|
|
411
|
+
})
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Artifact naming conventions
|
|
415
|
+
- `"verdict"` — plan review verdict
|
|
416
|
+
- `"impl-verdict"` — implementation review verdict (avoids collision with plan verdict)
|
|
417
|
+
- `"plan"` — the plan artifact
|
|
418
|
+
- Use distinct artifact names for different phases to prevent data bleed between loops
|
|
419
|
+
|
|
420
|
+
### Conditional steps with lambdas
|
|
421
|
+
For complex conditions that structured predicates cannot express, use a lambda with `whenLabel`:
|
|
422
|
+
```js
|
|
423
|
+
plan({
|
|
424
|
+
when: (ctx) => {
|
|
425
|
+
const data = ctx.artifacts.getData("impl-verdict");
|
|
426
|
+
return data != null && Array.isArray(data.issues) && data.issues.length > 2;
|
|
427
|
+
},
|
|
428
|
+
whenLabel: "impl-verdict.issues>2",
|
|
429
|
+
driver: plannerDriver,
|
|
430
|
+
reads: { task: "plan", verdict: "impl-verdict" },
|
|
431
|
+
writes: { plan: "revise-plan" },
|
|
432
|
+
})
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
### Cleaning up stale artifacts in lambdas
|
|
436
|
+
If a conditional step writes an artifact that downstream steps read, clear the artifact in the false branch to avoid stale data:
|
|
437
|
+
```js
|
|
438
|
+
when: (ctx) => {
|
|
439
|
+
const data = ctx.artifacts.getData("impl-verdict");
|
|
440
|
+
const exceeds = data != null && Array.isArray(data.issues) && data.issues.length > 2;
|
|
441
|
+
if (!exceeds) {
|
|
442
|
+
ctx.artifacts.set("revise-plan", {}); // clear stale artifact
|
|
443
|
+
}
|
|
444
|
+
return exceeds;
|
|
445
|
+
},
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
### Post-loop steps
|
|
449
|
+
Steps can appear outside loops as sequential top-level steps:
|
|
450
|
+
```js
|
|
451
|
+
return defineFlow("my-flow", [
|
|
452
|
+
loop(maxPlan, artifactData("verdict", "approved"), [ ... ]),
|
|
453
|
+
simplify({ driver: simplifierDriver, writes: { plan: "simplify-plan" } }),
|
|
454
|
+
implement({ driver: implementorDriver, reads: { plan: "simplify-plan" } }),
|
|
455
|
+
]);
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
## Appendix: Built-in `default` Flow
|
|
459
|
+
|
|
460
|
+
The built-in default flow demonstrates the interactive two-layered loop pattern. Key editing implications are noted inline.
|
|
461
|
+
|
|
462
|
+
```js
|
|
463
|
+
build(values) {
|
|
464
|
+
const maxPlan = values.maxIterations;
|
|
465
|
+
const maxImpl = values.maxImplIterations;
|
|
466
|
+
const isPlanOnly = values.planOnly;
|
|
467
|
+
const isAuto = values.auto;
|
|
468
|
+
|
|
469
|
+
const plannerDriver = values.planner;
|
|
470
|
+
const reviewerDriver = values.reviewer;
|
|
471
|
+
const implementorDriver = values.implementor;
|
|
472
|
+
|
|
473
|
+
const steps = [];
|
|
474
|
+
|
|
475
|
+
if (isAuto) {
|
|
476
|
+
// Auto mode: flat plan→review loop, no user interaction
|
|
477
|
+
steps.push(
|
|
478
|
+
loop(maxPlan, artifactData("verdict", "approved"), [
|
|
479
|
+
plan({
|
|
480
|
+
driver: plannerDriver,
|
|
481
|
+
phaseLabel: cyclePhase("📝 Planning...", "✏️ Revising Plan..."),
|
|
482
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
483
|
+
writes: { plan: "plan" },
|
|
484
|
+
}),
|
|
485
|
+
review({
|
|
486
|
+
driver: reviewerDriver,
|
|
487
|
+
variant: "plan",
|
|
488
|
+
reads: { task: TASK, plan: "plan" },
|
|
489
|
+
writes: { verdict: "verdict" },
|
|
490
|
+
}),
|
|
491
|
+
]),
|
|
492
|
+
);
|
|
493
|
+
} else {
|
|
494
|
+
// Interactive mode: outer uncapped user loop + inner capped agent review loop
|
|
495
|
+
steps.push(
|
|
496
|
+
loop(Infinity, () => false, [
|
|
497
|
+
plan({
|
|
498
|
+
driver: plannerDriver,
|
|
499
|
+
// NOTE: cyclePhase binds to the outer loop here
|
|
500
|
+
phaseLabel: cyclePhase("📝 Planning...", "✏️ Addressing Feedback..."),
|
|
501
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
502
|
+
writes: { plan: "plan" },
|
|
503
|
+
}),
|
|
504
|
+
user("user:feedback", {
|
|
505
|
+
writes: { verdict: "verdict" },
|
|
506
|
+
}),
|
|
507
|
+
loop(maxPlan, artifactData("verdict", "approved"), [
|
|
508
|
+
plan({
|
|
509
|
+
driver: plannerDriver,
|
|
510
|
+
when: ctxField("iteration", "!=", 1), // skip 1st iter — plan exists from outer loop
|
|
511
|
+
phaseLabel: "✏️ Revising Plan...",
|
|
512
|
+
reads: { task: TASK, verdict: "verdict" },
|
|
513
|
+
writes: { plan: "plan" },
|
|
514
|
+
}),
|
|
515
|
+
review({
|
|
516
|
+
driver: reviewerDriver,
|
|
517
|
+
variant: "plan",
|
|
518
|
+
reads: { task: TASK, plan: "plan" },
|
|
519
|
+
writes: { verdict: "verdict" },
|
|
520
|
+
}),
|
|
521
|
+
]),
|
|
522
|
+
user("user:approval", {
|
|
523
|
+
breakOnAccept: true, // exits outer loop on accept
|
|
524
|
+
writes: { verdict: "verdict" },
|
|
525
|
+
}),
|
|
526
|
+
]),
|
|
527
|
+
);
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
// Implementation loop (same for auto and interactive)
|
|
531
|
+
if (!isPlanOnly) {
|
|
532
|
+
const implVerdict = "impl-verdict";
|
|
533
|
+
steps.push(
|
|
534
|
+
loop(maxImpl, artifactData(implVerdict, "approved"), [
|
|
535
|
+
implement({
|
|
536
|
+
driver: implementorDriver,
|
|
537
|
+
phaseLabel: cyclePhase("🔨 Implementing...", "✏️ Revising Impl..."),
|
|
538
|
+
reads: { plan: "plan", verdict: implVerdict },
|
|
539
|
+
}),
|
|
540
|
+
review({
|
|
541
|
+
driver: reviewerDriver,
|
|
542
|
+
variant: "impl",
|
|
543
|
+
reads: { task: TASK, plan: "plan" },
|
|
544
|
+
writes: { verdict: implVerdict },
|
|
545
|
+
}),
|
|
546
|
+
]),
|
|
547
|
+
);
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
return defineFlow("default", steps);
|
|
551
|
+
}
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
**Key patterns**:
|
|
555
|
+
- Outer loop uses `Infinity` + `() => false` — exits only via `breakOnAccept` on the user step.
|
|
556
|
+
- Inner loop is capped by `maxPlan`, exits when `artifactData("verdict", "approved")` is true.
|
|
557
|
+
- `ctxField("iteration", "!=", 1)` on the inner plan step skips it on the first inner iteration (a plan already exists from the outer loop).
|
|
558
|
+
- Implementation loop uses `"impl-verdict"` to avoid collision with `"verdict"`.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/flow/custom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9F,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/flow/custom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { FlowTemplate } from "../types.js";
|
|
2
|
+
export interface LoadError {
|
|
3
|
+
file: string;
|
|
4
|
+
message: string;
|
|
5
|
+
}
|
|
6
|
+
export interface LoadResult {
|
|
7
|
+
templates: FlowTemplate[];
|
|
8
|
+
errors: LoadError[];
|
|
9
|
+
}
|
|
10
|
+
export interface AllFlowsResult extends LoadResult {
|
|
11
|
+
builtinCount: number;
|
|
12
|
+
customDir: string;
|
|
13
|
+
}
|
|
14
|
+
export declare function loadBuiltinFlows(): Promise<FlowTemplate[]>;
|
|
15
|
+
export declare function validateTemplate(template: unknown, file: string): FlowTemplate;
|
|
16
|
+
export declare function loadCustomFlows(dir?: string): Promise<LoadResult>;
|
|
17
|
+
/** Load all flows: built-in (from package) + custom (from user dir). */
|
|
18
|
+
export declare function loadAllFlows(customDir?: string): Promise<AllFlowsResult>;
|
|
19
|
+
//# sourceMappingURL=load.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/flow/custom/load.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAYhE;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAe9E;AAED,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqDvE;AAID,wEAAwE;AACxE,wBAAsB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAwB9E"}
|