@deeflectcom/smart-spawn 1.0.3 → 1.0.4

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/package.json +1 -1
  2. package/skills/smart-spawn/SKILL.md +63 -81
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deeflectcom/smart-spawn",
3
- "version": "1.0.3",
3
+ "version": "1.0.4",
4
4
  "description": "Intelligent sub-agent spawning with automatic model selection for OpenClaw",
5
5
  "main": "index.ts",
6
6
  "type": "module",
package/skills/smart-spawn/SKILL.md CHANGED
@@ -1,114 +1,96 @@
1
1
  ---
2
2
  name: smart-spawn
3
- description: "Intelligent sub-agent spawning with automatic model selection and role composition. Use instead of sessions_spawn for optimal model routing."
3
+ description: "Intelligent sub-agent spawning with automatic model selection. Call smart_spawn → get recommendation → call sessions_spawn with the result."
4
4
  ---
5
5
 
6
6
  # Smart Spawn
7
7
 
8
- Use `smart_spawn` to delegate tasks to sub-agents. It picks the best model and can inject expert role instructions that make cheap models perform like specialists.
8
+ Use `smart_spawn` to pick the best model for a task, then `sessions_spawn` to run it.
9
9
 
10
- ## Flow
11
-
12
- 1. Analyze the task → pick role blocks if relevant
13
- 2. Call `smart_spawn` → get JSON with model + enriched task
14
- 3. Call `sessions_spawn` with the returned values
15
-
16
- ## Modes
17
-
18
- | Mode | When to use |
19
- |------|------------|
20
- | `single` | Default. One optimal model. |
21
- | `collective` | Need diverse perspectives. Spawns N models, you merge results. |
22
- | `cascade` | Cost-sensitive. Cheap model first, escalate to premium if quality is poor. |
23
- | `plan` | Multi-step sequential tasks. Format task as numbered list. |
24
- | `swarm` | Complex tasks with parallel subtasks. API builds a dependency DAG. |
25
-
26
- ## Role Blocks
27
-
28
- Analyze the task and specify blocks that match. **Only include what's clearly relevant — omit if unsure.** Guardrails auto-apply based on persona when not specified.
29
-
30
- ### persona — who the sub-agent is
31
-
32
- **Engineering:** `software-engineer` `frontend-engineer` `backend-engineer` `fullstack-engineer` `devops-engineer` `data-engineer` `mobile-engineer` `systems-engineer` `security-engineer` `ml-engineer` `performance-engineer`
10
+ **Important:** `smart_spawn` is a recommendation tool — it returns a JSON response telling you which model to use. It does NOT spawn agents itself. You MUST call `sessions_spawn` after getting the result.
33
11
 
34
- **Architecture:** `architect` `api-designer` `database-architect`
35
-
36
- **Analysis:** `analyst` `data-analyst` `market-analyst` `financial-analyst`
12
+ ## Flow
37
13
 
38
- **Problem Solving:** `problem-solver` `debugger` `mathematician`
14
+ ```
15
+ 1. Call smart_spawn(task, budget, mode) → returns JSON recommendation
16
+ 2. Call sessions_spawn(task, model, label) → actually runs the sub-agent
17
+ ```
39
18
 
40
- **Content:** `writer` `technical-writer` `copywriter` `editor` `social-media`
19
+ ## Quick Examples
41
20
 
42
- **Product/Business:** `product-manager` `strategist` `ux-researcher` `project-manager`
21
+ ### Single (default)
22
+ ```
23
+ smart_spawn result → { action: "spawn", model: "moonshotai/kimi-k2.5", task: "...", label: "..." }
43
24
 
44
- **Design:** `ui-designer` `brand-designer`
25
+ You do: sessions_spawn(task=result.task, model=result.model, label=result.label)
26
+ ```
45
27
 
46
- **Other:** `sysadmin` `teacher` `legal-analyst` `assistant`
28
+ ### Collective (parallel diverse models)
29
+ ```
30
+ smart_spawn result → { action: "collective", models: [{id, label}, ...], task: "..." }
47
31
 
48
- ### stack — tech expertise (array, max 4)
32
+ You do: for each model → sessions_spawn(task=result.task, model=model.id, label=model.label)
33
+ Then merge the best parts from all results.
34
+ ```
49
35
 
50
- **Frontend:** `react` `nextjs` `vue` `svelte` `angular` `tailwind` `shadcn` `css` `animation` `threejs`
36
+ ### Cascade (cheap first, escalate if needed)
37
+ ```
38
+ smart_spawn result → { action: "cascade", cheapModel: "...", premiumModel: "...", task: "..." }
51
39
 
52
- **Languages:** `typescript` `python` `rust` `go` `java` `csharp` `php` `ruby` `elixir` `swift` `kotlin`
40
+ You do:
41
+ 1. sessions_spawn(task=result.task, model=result.cheapModel)
42
+ 2. Check result quality via sessions_history(sessionKey)
43
+ 3. If quality is poor → sessions_spawn(task=result.task, model=result.premiumModel)
44
+ ```
53
45
 
54
- **Backend:** `nodejs` `fastapi` `django` `flask` `react-native` `flutter`
46
+ ## sessions_spawn Parameters
55
47
 
56
- **Data:** `sql` `postgres` `mysql` `supabase` `prisma` `drizzle` `mongodb` `redis` `elasticsearch` `kafka` `rabbitmq`
48
+ This is the OpenClaw built-in tool you call AFTER smart_spawn:
57
49
 
58
- **APIs:** `graphql` `rest` `grpc` `websocket` `auth` `stripe` `payment-general`
50
+ | Parameter | Required | Description |
51
+ |-----------|----------|-------------|
52
+ | `task` | Yes | The task string (use exactly what smart_spawn returns) |
53
+ | `model` | No | Model ID like `moonshotai/kimi-k2.5` (from smart_spawn result) |
54
+ | `label` | No | Short label for the session |
55
+ | `agentId` | No | Agent ID if using configured agents |
56
+ | `runTimeoutSeconds` | No | Max runtime in seconds (0 = no limit) |
59
57
 
60
- **DevOps:** `docker` `kubernetes` `cicd` `terraform` `aws` `gcp` `nginx` `caddy` `monitoring`
58
+ ## Modes
61
59
 
62
- **AI/ML:** `llm` `rag` `langchain` `fine-tuning` `pytorch` `pandas`
60
+ | Mode | When | What happens |
61
+ |------|------|-------------|
62
+ | `single` | Default — one task, one model | Returns best model for the job |
63
+ | `collective` | Need diverse perspectives | Returns N models from different providers |
64
+ | `cascade` | Budget-conscious | Returns cheap + premium model pair |
65
+ | `plan` | Multi-step sequential work | Returns ordered steps with model per step |
66
+ | `swarm` | Complex parallel work | Returns DAG of tasks with dependencies |
63
67
 
64
- **Web3:** `solidity` `web3-frontend`
68
+ ## Role Blocks (Optional)
65
69
 
66
- **Platforms:** `vercel` `railway` `cloudflare` `firebase` `convex`
70
+ You can hint what kind of expert is needed. **Only include what's clearly relevant — omit if unsure.** The API enriches the task prompt with expert context.
67
71
 
68
- **Other:** `bash` `powershell` `markdown` `astro` `json` `yaml` `regex` `email` `a11y` `seo` `performance` `i18n` `git` `testing` `playwright`
72
+ ### persona — who the sub-agent should be
73
+ `software-engineer` `frontend-engineer` `backend-engineer` `devops-engineer` `data-engineer` `ml-engineer` `architect` `analyst` `writer` `technical-writer` `product-manager` `debugger` `ui-designer` `sysadmin` `assistant`
69
74
 
70
- ### domain — industry (one)
75
+ ### stack — tech expertise (array, max 4)
76
+ `react` `nextjs` `typescript` `python` `rust` `go` `nodejs` `postgres` `redis` `docker` `kubernetes` `aws` `tailwind` `llm` `rag` (and many more)
71
77
 
72
- `fintech` `ecommerce` `saas` `marketplace` `gaming` `crypto` `healthcare` `education` `media` `iot` `logistics` `real-estate` `social-platform` `legal` `developer-tools`
78
+ ### domain — industry context (one)
79
+ `fintech` `saas` `ecommerce` `crypto` `healthcare` `developer-tools` `gaming` `education`
73
80
 
74
81
  ### format — output shape (one)
82
+ `full-implementation` `fix-debug` `refactor` `explain` `review` `planning` `documentation`
75
83
 
76
- `full-implementation` `fix-debug` `refactor` `explain` `review` `comparison` `planning` `documentation` `copywriting` `social-post` `data-report` `migration` `pitch-deck` `project-proposal` `user-story` `email` `legal-doc`
77
-
78
- ### guardrails — quality rules (array, auto-applied if omitted)
79
-
80
- `code` `research` `concise` `security` `production` `accuracy`
81
-
82
- ## Acting on Results
83
-
84
- ### `action: "spawn"` (single/fallback)
85
- ```
86
- sessions_spawn(task: result.task, model: result.model, label: result.label)
87
- ```
88
-
89
- ### `action: "collective"`
90
- Spawn each model, wait for all, merge the best parts:
91
- ```
92
- for model in result.models:
93
- sessions_spawn(task: result.task, model: model.id, label: model.label)
94
- ```
95
-
96
- ### `action: "cascade"`
97
- 1. Spawn `cheapModel` first
98
- 2. Check quality via `sessions_history`
99
- 3. Escalate to `premiumModel` if: incomplete, wrong, vague, or too short for the task
100
- 4. Return whichever result is good
101
-
102
- ### `action: "plan"`
103
- Execute steps sequentially, pass each output as context to the next.
84
+ ## Error Handling
104
85
 
105
- ### `action: "swarm"`
106
- Execute wave-by-wave. Spawn all tasks in a wave in parallel. Pass outputs to dependents in the next wave.
86
+ - If `smart_spawn` fails or times out → fall back to `sessions_spawn` without a model (uses default)
87
+ - If the spawned agent fails → check `sessions_history` for errors, consider retrying with a different budget tier
88
+ - If cascade cheap model produces bad results → escalate to premium (that's the point of cascade)
107
89
 
108
90
  ## Rules
109
91
 
110
- - **Always spawn after smart_spawn returns** — don't just report the recommendation
111
- - Use the exact `model` and `task` strings from the result
112
- - **Don't guess blocks** — if unsure, omit and the task goes raw
113
- - For plan mode, format tasks as numbered lists
114
- - After completion, consider calling `smart_spawn_feedback` with a 1-5 rating
92
+ 1. **Always call sessions_spawn after smart_spawn** — never just report the recommendation
93
+ 2. Use the exact `model` and `task` strings from the result
94
+ 3. **Don't guess role blocks** — if unsure about persona/stack/domain, omit them entirely
95
+ 4. For plan/swarm modes, pass outputs from earlier steps as context to later ones
96
+ 5. After completion, optionally call `smart_spawn_feedback` with a 1-5 rating to improve future picks