@opencode_weave/weave 0.3.2
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/LICENSE +21 -0
- package/README.md +317 -0
- package/dist/agents/agent-builder.d.ts +10 -0
- package/dist/agents/builtin-agents.d.ts +16 -0
- package/dist/agents/dynamic-prompt-builder.d.ts +29 -0
- package/dist/agents/index.d.ts +8 -0
- package/dist/agents/loom/default.d.ts +2 -0
- package/dist/agents/loom/index.d.ts +2 -0
- package/dist/agents/model-resolution.d.ts +19 -0
- package/dist/agents/pattern/default.d.ts +2 -0
- package/dist/agents/pattern/index.d.ts +2 -0
- package/dist/agents/shuttle/default.d.ts +2 -0
- package/dist/agents/shuttle/index.d.ts +2 -0
- package/dist/agents/spindle/default.d.ts +2 -0
- package/dist/agents/spindle/index.d.ts +2 -0
- package/dist/agents/tapestry/default.d.ts +2 -0
- package/dist/agents/tapestry/index.d.ts +2 -0
- package/dist/agents/thread/default.d.ts +2 -0
- package/dist/agents/thread/index.d.ts +2 -0
- package/dist/agents/types.d.ts +82 -0
- package/dist/agents/warp/default.d.ts +2 -0
- package/dist/agents/warp/index.d.ts +2 -0
- package/dist/agents/weft/default.d.ts +2 -0
- package/dist/agents/weft/index.d.ts +2 -0
- package/dist/config/index.d.ts +3 -0
- package/dist/config/loader.d.ts +2 -0
- package/dist/config/merge.d.ts +3 -0
- package/dist/config/schema.d.ts +162 -0
- package/dist/create-managers.d.ts +18 -0
- package/dist/create-tools.d.ts +16 -0
- package/dist/features/builtin-commands/commands.d.ts +2 -0
- package/dist/features/builtin-commands/index.d.ts +2 -0
- package/dist/features/builtin-commands/templates/start-work.d.ts +1 -0
- package/dist/features/builtin-commands/types.d.ts +16 -0
- package/dist/features/skill-loader/builtin-skills.d.ts +2 -0
- package/dist/features/skill-loader/discovery.d.ts +12 -0
- package/dist/features/skill-loader/index.d.ts +7 -0
- package/dist/features/skill-loader/loader.d.ts +6 -0
- package/dist/features/skill-loader/merger.d.ts +2 -0
- package/dist/features/skill-loader/resolver.d.ts +6 -0
- package/dist/features/skill-loader/types.d.ts +25 -0
- package/dist/features/work-state/constants.d.ts +8 -0
- package/dist/features/work-state/index.d.ts +3 -0
- package/dist/features/work-state/storage.d.ts +38 -0
- package/dist/features/work-state/types.d.ts +27 -0
- package/dist/hooks/context-window-monitor.d.ts +19 -0
- package/dist/hooks/create-hooks.d.ts +32 -0
- package/dist/hooks/first-message-variant.d.ts +5 -0
- package/dist/hooks/index.d.ts +12 -0
- package/dist/hooks/keyword-detector.d.ts +8 -0
- package/dist/hooks/pattern-md-only.d.ts +13 -0
- package/dist/hooks/rules-injector.d.ts +6 -0
- package/dist/hooks/start-work-hook.d.ts +20 -0
- package/dist/hooks/verification-reminder.d.ts +22 -0
- package/dist/hooks/work-continuation.d.ts +17 -0
- package/dist/hooks/write-existing-file-guard.d.ts +14 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +2191 -0
- package/dist/managers/background-manager.d.ts +68 -0
- package/dist/managers/config-handler.d.ts +54 -0
- package/dist/managers/index.d.ts +6 -0
- package/dist/managers/skill-mcp-manager.d.ts +30 -0
- package/dist/plugin/index.d.ts +1 -0
- package/dist/plugin/plugin-interface.d.ts +12 -0
- package/dist/plugin/types.d.ts +5 -0
- package/dist/shared/agent-display-names.d.ts +20 -0
- package/dist/shared/index.d.ts +3 -0
- package/dist/shared/log.d.ts +2 -0
- package/dist/shared/types.d.ts +6 -0
- package/dist/tools/index.d.ts +4 -0
- package/dist/tools/permissions.d.ts +18 -0
- package/dist/tools/registry.d.ts +29 -0
- package/package.json +52 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Weave
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/weave_logo.png" alt="Weave" width="400">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# Weave
|
|
6
|
+
|
|
7
|
+
Weave is a lean OpenCode plugin with multi-agent orchestration. It provides a cohesive framework for weaving agents, tools, and skills into structured workflows. By delegating complex tasks to specialized agents and monitoring execution state through hooks, Weave ensures reliable and efficient project development.
|
|
8
|
+
|
|
9
|
+
## Table of Contents
|
|
10
|
+
|
|
11
|
+
- [Overview](#overview)
|
|
12
|
+
- [Agents](#agents)
|
|
13
|
+
- [Agent Modes](#agent-modes)
|
|
14
|
+
- [Agent Details](#agent-details)
|
|
15
|
+
- [Workflow](#workflow)
|
|
16
|
+
- [When the Full Workflow Is Used](#when-the-full-workflow-is-used)
|
|
17
|
+
- [1. Plan](#1-plan)
|
|
18
|
+
- [2. Review (Optional)](#2-review-optional)
|
|
19
|
+
- [3. Execute](#3-execute)
|
|
20
|
+
- [Resuming Interrupted Work](#resuming-interrupted-work)
|
|
21
|
+
- [Quick Tasks (No Plan Needed)](#quick-tasks-no-plan-needed)
|
|
22
|
+
- [Installation](#installation)
|
|
23
|
+
- [Prerequisites](#prerequisites)
|
|
24
|
+
- [Step 1: Install](#step-1-install)
|
|
25
|
+
- [Step 2: Register in opencode.json](#step-2-register-in-opencodejson)
|
|
26
|
+
- [Step 3: Restart OpenCode](#step-3-restart-opencode)
|
|
27
|
+
- [Troubleshooting](#troubleshooting)
|
|
28
|
+
- [Uninstalling](#uninstalling)
|
|
29
|
+
- [Configuration](#configuration)
|
|
30
|
+
- [Example Configuration](#example-configuration)
|
|
31
|
+
- [Configuration Fields](#configuration-fields)
|
|
32
|
+
- [Features](#features)
|
|
33
|
+
- [Hooks](#hooks)
|
|
34
|
+
- [Skills](#skills)
|
|
35
|
+
- [Background Agents](#background-agents)
|
|
36
|
+
- [Tool Permissions](#tool-permissions)
|
|
37
|
+
- [Development](#development)
|
|
38
|
+
- [License](#license)
|
|
39
|
+
|
|
40
|
+
## Overview
|
|
41
|
+
|
|
42
|
+
- **8 specialized agents** with weaving-themed names designed for specific roles in the development lifecycle.
|
|
43
|
+
- **Category-based task dispatch** to route work to domain-optimized models and configurations.
|
|
44
|
+
- **Skill system** for injecting domain-specific expertise that modifies agent behavior via prompt orchestration.
|
|
45
|
+
- **Background agent management** for parallel asynchronous sub-agent execution with concurrency control.
|
|
46
|
+
- **Context window monitoring** to track token usage and suggest recovery strategies when limits are approached.
|
|
47
|
+
- **Tool permissions** enforced per-agent to ensure safety and prevent unauthorized file modifications.
|
|
48
|
+
- **JSONC configuration** supporting comments and trailing commas with hierarchical user and project-level merging.
|
|
49
|
+
|
|
50
|
+
## Agents
|
|
51
|
+
|
|
52
|
+
| Agent | Role | Mode | Description |
|
|
53
|
+
| :--- | :--- | :--- | :--- |
|
|
54
|
+
| **Loom** | main orchestrator | primary | The central team lead that plans tasks, coordinates work, and delegates to specialized agents. |
|
|
55
|
+
| **Tapestry** | execution orchestrator | primary | Manages todo-list driven execution of multi-step plans, focusing on sequential implementation without subagent spawning. |
|
|
56
|
+
| **Shuttle** | category worker | all | Domain-specific specialist worker with full tool access, dispatched dynamically via the category system. |
|
|
57
|
+
| **Pattern** | strategic planner | subagent | Analyzes requirements and produces detailed implementation plans with research and dependency mapping. |
|
|
58
|
+
| **Thread** | codebase explorer | subagent | Fast, read-only codebase navigation and analysis using grep, glob, and read tools. |
|
|
59
|
+
| **Spindle** | external researcher | subagent | Performs external documentation lookups and reference searches, providing synthesized answers with source citations. |
|
|
60
|
+
| **Weft** | reviewer/auditor | subagent | Reviews completed work and plans with a critical but fair eye, rejecting only for true blocking issues. |
|
|
61
|
+
| **Warp** | security auditor | subagent | Audits code changes for security vulnerabilities and specification compliance with a skeptical bias. |
|
|
62
|
+
|
|
63
|
+
### Agent Modes
|
|
64
|
+
|
|
65
|
+
- `primary`: Respects the user-selected model in the OpenCode UI.
|
|
66
|
+
- `subagent`: Uses its own model or fallback chain, ignoring UI selection for predictable specialization.
|
|
67
|
+
- `all`: Available in both primary and subagent contexts.
|
|
68
|
+
|
|
69
|
+
### Agent Details
|
|
70
|
+
|
|
71
|
+
**Loom** is the central orchestrator and the default entry point for every request. It breaks down complex problems into tasks, decides which agents to delegate to, and tracks progress obsessively via todo lists. Loom never implements code directly — it plans and delegates. For quick fixes it acts immediately; for complex work it kicks off the plan → review → execute workflow.
|
|
72
|
+
|
|
73
|
+
**Pattern** is the strategic planner. When a task requires 5+ steps or involves architectural decisions, Loom delegates to Pattern, which researches the codebase (via Thread) and external docs (via Spindle), then produces a structured implementation plan saved to `.weave/plans/{name}.md`. Plans use `- [ ]` checkboxes for every actionable task. Pattern never writes code — only plans.
|
|
74
|
+
|
|
75
|
+
**Weft** is the reviewer and auditor. It validates plans before execution and reviews completed work after implementation. Weft is approval-biased and only rejects for true blocking issues (max 3 per review). It checks that file references are correct, tasks have sufficient context, implementations match requirements, and no stubs or TODOs are left behind. Weft is read-only.
|
|
76
|
+
|
|
77
|
+
**Warp** is the security and specification compliance auditor. It reviews code changes for security vulnerabilities (injection, auth bypass, token handling, crypto weaknesses) and verifies compliance with standards like OAuth2, OIDC, WebAuthn, and JWT. Warp has a skeptical bias — unlike Weft, it rejects by default when security patterns are detected. It self-triages to fast-exit on non-security changes, and can webfetch RFCs for verification. Warp is read-only.
|
|
78
|
+
|
|
79
|
+
**Tapestry** is the execution engine. Activated by the `/start-work` command, it reads a plan from `.weave/plans/` and works through tasks sequentially — writing code, running commands, verifying output, and marking checkboxes as it goes. Tapestry cannot spawn subagents; it focuses on heads-down implementation. If interrupted, it resumes from the first unchecked task.
|
|
80
|
+
|
|
81
|
+
**Thread** is the fast codebase explorer. Loom delegates to Thread whenever it needs to understand code structure, find files, or answer questions about the repository. Thread uses grep, glob, and read tools with zero creativity (temperature 0.0) to return precise, factual answers with file paths and line numbers. Thread is read-only.
|
|
82
|
+
|
|
83
|
+
**Spindle** is the external researcher. When Loom needs documentation for a library, API reference, or any information outside the codebase, Spindle fetches URLs, reads docs, and synthesizes findings with source citations. Spindle is read-only.
|
|
84
|
+
|
|
85
|
+
**Shuttle** is the domain specialist. When work falls into a specific category (e.g., visual engineering, data processing), Loom dispatches Shuttle with full tool access to execute the task. Shuttle's model and configuration can be overridden per-category for domain-optimized performance.
|
|
86
|
+
|
|
87
|
+
## Workflow
|
|
88
|
+
|
|
89
|
+
Weave uses a structured **Plan → Review → Execute** workflow for complex tasks. Simple requests are handled directly by Loom without the full cycle.
|
|
90
|
+
|
|
91
|
+
### When the Full Workflow Is Used
|
|
92
|
+
|
|
93
|
+
- Tasks requiring 5+ steps or architectural decisions
|
|
94
|
+
- Multi-file refactors or new feature implementations
|
|
95
|
+
- Work that benefits from a reviewable plan before execution
|
|
96
|
+
|
|
97
|
+
### 1. Plan
|
|
98
|
+
|
|
99
|
+
Loom delegates to **Pattern**, which researches the codebase and produces a detailed implementation plan:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
User Request → Loom (assesses complexity) → Pattern (researches + plans)
|
|
103
|
+
↓
|
|
104
|
+
.weave/plans/{name}.md
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The plan includes clear objectives, deliverables, and atomic tasks marked with `- [ ]` checkboxes. Pattern never writes code.
|
|
108
|
+
|
|
109
|
+
### 2. Review (Optional)
|
|
110
|
+
|
|
111
|
+
For high-stakes or complex plans, Loom delegates to **Weft** to validate the plan before execution:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
.weave/plans/{name}.md → Weft (validates) → APPROVE or REJECT
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Weft checks that referenced files exist, tasks have sufficient context, and there are no contradictions. If rejected, issues are sent back to Pattern for revision.
|
|
118
|
+
|
|
119
|
+
### 3. Execute
|
|
120
|
+
|
|
121
|
+
The user runs `/start-work` to begin execution:
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
/start-work [plan-name] → creates .weave/state.json → switches to Tapestry
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Tapestry** reads the plan and executes tasks sequentially:
|
|
128
|
+
|
|
129
|
+
1. Find the first unchecked `- [ ]` task
|
|
130
|
+
2. Implement the task (write code, run commands, create files)
|
|
131
|
+
3. Verify completion (read files, run tests, check acceptance criteria)
|
|
132
|
+
4. Mark the checkbox `- [x]`
|
|
133
|
+
5. Move to the next unchecked task
|
|
134
|
+
6. When all tasks are complete, report a final summary
|
|
135
|
+
|
|
136
|
+
### Resuming Interrupted Work
|
|
137
|
+
|
|
138
|
+
If a session is interrupted, running `/start-work` again resumes from the first unchecked task — no re-planning or restarting. The work state is persisted in `.weave/state.json`, so progress is never lost.
|
|
139
|
+
|
|
140
|
+
### Quick Tasks (No Plan Needed)
|
|
141
|
+
|
|
142
|
+
For simple requests — single-file fixes, quick questions, small edits — Loom handles the work directly or delegates to the appropriate agent without creating a formal plan.
|
|
143
|
+
|
|
144
|
+
## Installation
|
|
145
|
+
|
|
146
|
+
This package is published on [npm](https://www.npmjs.com/package/@opencode_weave/weave).
|
|
147
|
+
|
|
148
|
+
### Prerequisites
|
|
149
|
+
|
|
150
|
+
- [OpenCode](https://opencode.ai)
|
|
151
|
+
- Bun or Node.js
|
|
152
|
+
|
|
153
|
+
### Step 1: Install
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
bun add @opencode_weave/weave
|
|
157
|
+
# or
|
|
158
|
+
npm install @opencode_weave/weave
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Step 2: Register in opencode.json
|
|
162
|
+
|
|
163
|
+
Add the plugin to your `opencode.json` file:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"plugin": ["@opencode_weave/weave"]
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Step 3: Restart OpenCode
|
|
172
|
+
|
|
173
|
+
The plugin loads automatically upon restart and works with zero configuration out of the box.
|
|
174
|
+
|
|
175
|
+
### Troubleshooting
|
|
176
|
+
|
|
177
|
+
| Issue | Solution |
|
|
178
|
+
|-------|----------|
|
|
179
|
+
| `404 Not Found` | Ensure the package name is correct: `@opencode_weave/weave`. |
|
|
180
|
+
| Package not found after publish | npm can take a few minutes to propagate. Wait and retry. |
|
|
181
|
+
|
|
182
|
+
## Uninstalling
|
|
183
|
+
|
|
184
|
+
To fully remove the Weave plugin from your project:
|
|
185
|
+
|
|
186
|
+
### Step 1: Remove from opencode.json
|
|
187
|
+
|
|
188
|
+
Delete the `@opencode_weave/weave` entry from the `plugin` array in your `opencode.json`:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"plugin": []
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Step 2: Uninstall the package
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
bun remove @opencode_weave/weave
|
|
200
|
+
# or
|
|
201
|
+
npm uninstall @opencode_weave/weave
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Step 3: Clean up project artifacts (optional)
|
|
205
|
+
|
|
206
|
+
Weave may have created plan and state files during usage. Remove them if no longer needed:
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
rm -rf .weave/
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
You can also remove any project-level configuration if present:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
rm -f .opencode/weave-opencode.jsonc .opencode/weave-opencode.json
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Step 4: Clean up user-level configuration (optional)
|
|
219
|
+
|
|
220
|
+
If you no longer use Weave in any project, remove the global configuration:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
rm -f ~/.config/opencode/weave-opencode.jsonc ~/.config/opencode/weave-opencode.json
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Configuration
|
|
227
|
+
|
|
228
|
+
Weave searches for configuration files in the following locations, merging them in order (user config → project config → defaults):
|
|
229
|
+
|
|
230
|
+
- **Project**: `.opencode/weave-opencode.jsonc` or `.opencode/weave-opencode.json`
|
|
231
|
+
- **User**: `~/.config/opencode/weave-opencode.jsonc` or `~/.config/opencode/weave-opencode.json`
|
|
232
|
+
|
|
233
|
+
The configuration uses JSONC format, allowing for comments and trailing commas.
|
|
234
|
+
|
|
235
|
+
### Example Configuration
|
|
236
|
+
|
|
237
|
+
```jsonc
|
|
238
|
+
{
|
|
239
|
+
// Override agent models and parameters
|
|
240
|
+
"agents": {
|
|
241
|
+
"loom": {
|
|
242
|
+
"model": "anthropic/claude-3-5-sonnet",
|
|
243
|
+
"temperature": 0.1
|
|
244
|
+
},
|
|
245
|
+
"thread": {
|
|
246
|
+
"model": "openai/gpt-4o-mini"
|
|
247
|
+
}
|
|
248
|
+
},
|
|
249
|
+
// Category-based dispatch overrides
|
|
250
|
+
"categories": {
|
|
251
|
+
"visual-engineering": {
|
|
252
|
+
"model": "google/gemini-2-pro"
|
|
253
|
+
}
|
|
254
|
+
},
|
|
255
|
+
// Selective feature toggling
|
|
256
|
+
"disabled_hooks": [],
|
|
257
|
+
"disabled_agents": [],
|
|
258
|
+
"disabled_tools": [],
|
|
259
|
+
"disabled_skills": [],
|
|
260
|
+
// Background agent concurrency limits
|
|
261
|
+
"background": {
|
|
262
|
+
"defaultConcurrency": 5
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Configuration Fields
|
|
268
|
+
|
|
269
|
+
- `agents` — Override model, temperature, prompt_append, tools, and skills per agent.
|
|
270
|
+
- `categories` — Custom model and tool configurations for category-based dispatch.
|
|
271
|
+
- `disabled_hooks` / `disabled_agents` / `disabled_tools` / `disabled_skills` — Selective feature disabling.
|
|
272
|
+
- `background` — Concurrency limits and timeouts for parallel background agents.
|
|
273
|
+
- `tmux` — Terminal multiplexer layout settings for TUI integration.
|
|
274
|
+
- `skills` — Custom skill discovery paths and recursion settings.
|
|
275
|
+
- `experimental` — Plugin load timeouts and context window threshold adjustments.
|
|
276
|
+
|
|
277
|
+
## Features
|
|
278
|
+
|
|
279
|
+
### Hooks
|
|
280
|
+
|
|
281
|
+
Weave includes 5 built-in hooks that monitor and modify agent behavior:
|
|
282
|
+
|
|
283
|
+
- `context-window-monitor` — Warns when token usage approaches limits and suggests recovery strategies.
|
|
284
|
+
- `write-existing-file-guard` — Tracks file reads to prevent agents from overwriting files they haven't examined.
|
|
285
|
+
- `rules-injector` — Automatically injects contextual rules when agents enter directories containing AGENTS.md.
|
|
286
|
+
- `first-message-variant` — Applies specific prompt variants on session start for consistent behavior.
|
|
287
|
+
- `keyword-detector` — Detects keywords in messages to trigger behavioral changes or agent switches.
|
|
288
|
+
|
|
289
|
+
All hooks are enabled by default and can be disabled via the `disabled_hooks` configuration.
|
|
290
|
+
|
|
291
|
+
### Skills
|
|
292
|
+
|
|
293
|
+
Skills are injectable prompt expertise loaded from markdown files (SKILL.md). They modify agent behavior by prepending domain-specific instructions to the agent's system prompt.
|
|
294
|
+
|
|
295
|
+
Skills are discovered across three scopes:
|
|
296
|
+
- `builtin` — Provided by the Weave plugin.
|
|
297
|
+
- `user` — Located in the user's global configuration directory.
|
|
298
|
+
- `project` — Located in the current project's `.opencode/skills/` directory.
|
|
299
|
+
|
|
300
|
+
### Background Agents
|
|
301
|
+
|
|
302
|
+
Weave supports parallel asynchronous sub-agent management via the BackgroundManager. This allows Loom to spawn multiple agents simultaneously to handle independent tasks, with configurable concurrency limits to manage API rate limits.
|
|
303
|
+
|
|
304
|
+
### Tool Permissions
|
|
305
|
+
|
|
306
|
+
Tool access is controlled per-agent to ensure safety and specialized focus. For example, **Thread** and **Spindle** are strictly read-only; they are denied access to write, edit, and task management tools. These permissions can be customized globally or per-agent in the configuration.
|
|
307
|
+
|
|
308
|
+
## Development
|
|
309
|
+
|
|
310
|
+
- **Build**: `bun run build`
|
|
311
|
+
- **Test**: `bun test`
|
|
312
|
+
- **Typecheck**: `bun run typecheck`
|
|
313
|
+
- **Clean**: `bun run clean`
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
MIT
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { AgentConfig } from "@opencode-ai/sdk";
|
|
2
|
+
import type { AgentSource } from "./types";
|
|
3
|
+
import type { CategoriesConfig } from "../config/schema";
|
|
4
|
+
export type ResolveSkillsFn = (skillNames: string[], disabledSkills?: Set<string>) => string;
|
|
5
|
+
export type BuildAgentOptions = {
|
|
6
|
+
categories?: CategoriesConfig;
|
|
7
|
+
disabledSkills?: Set<string>;
|
|
8
|
+
resolveSkills?: ResolveSkillsFn;
|
|
9
|
+
};
|
|
10
|
+
export declare function buildAgent(source: AgentSource, model: string, options?: BuildAgentOptions): AgentConfig;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { AgentConfig } from "@opencode-ai/sdk";
|
|
2
|
+
import type { AgentPromptMetadata, WeaveAgentName } from "./types";
|
|
3
|
+
import type { CategoriesConfig, AgentOverrideConfig } from "../config/schema";
|
|
4
|
+
import type { ResolveSkillsFn } from "./agent-builder";
|
|
5
|
+
export interface CreateBuiltinAgentsOptions {
|
|
6
|
+
disabledAgents?: string[];
|
|
7
|
+
agentOverrides?: Record<string, AgentOverrideConfig>;
|
|
8
|
+
categories?: CategoriesConfig;
|
|
9
|
+
uiSelectedModel?: string;
|
|
10
|
+
systemDefaultModel?: string;
|
|
11
|
+
availableModels?: Set<string>;
|
|
12
|
+
disabledSkills?: Set<string>;
|
|
13
|
+
resolveSkills?: ResolveSkillsFn;
|
|
14
|
+
}
|
|
15
|
+
export declare const AGENT_METADATA: Record<WeaveAgentName, AgentPromptMetadata>;
|
|
16
|
+
export declare function createBuiltinAgents(options?: CreateBuiltinAgentsOptions): Record<string, AgentConfig>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { AgentPromptMetadata } from "./types";
|
|
2
|
+
export interface AvailableAgent {
|
|
3
|
+
name: string;
|
|
4
|
+
description: string;
|
|
5
|
+
metadata: AgentPromptMetadata;
|
|
6
|
+
}
|
|
7
|
+
export interface AvailableTool {
|
|
8
|
+
name: string;
|
|
9
|
+
category: "lsp" | "ast" | "search" | "session" | "command" | "other";
|
|
10
|
+
}
|
|
11
|
+
export interface AvailableSkill {
|
|
12
|
+
name: string;
|
|
13
|
+
description: string;
|
|
14
|
+
location: "user" | "project" | "builtin";
|
|
15
|
+
}
|
|
16
|
+
export interface AvailableCategory {
|
|
17
|
+
name: string;
|
|
18
|
+
description: string;
|
|
19
|
+
model?: string;
|
|
20
|
+
}
|
|
21
|
+
export declare function categorizeTools(toolNames: string[]): AvailableTool[];
|
|
22
|
+
export declare function buildKeyTriggersSection(agents: AvailableAgent[], _skills?: AvailableSkill[]): string;
|
|
23
|
+
export declare function buildToolSelectionTable(agents: AvailableAgent[], tools?: AvailableTool[], _skills?: AvailableSkill[]): string;
|
|
24
|
+
export declare function buildThreadSection(agents: AvailableAgent[]): string;
|
|
25
|
+
export declare function buildSpindleSection(agents: AvailableAgent[]): string;
|
|
26
|
+
export declare function buildWeftSection(agents: AvailableAgent[]): string;
|
|
27
|
+
export declare function buildWarpSection(agents: AvailableAgent[]): string;
|
|
28
|
+
export declare function buildDelegationTable(agents: AvailableAgent[]): string;
|
|
29
|
+
export declare function buildCategorySkillsDelegationGuide(categories: AvailableCategory[], skills: AvailableSkill[]): string;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export { createBuiltinAgents, AGENT_METADATA } from "./builtin-agents";
|
|
2
|
+
export type { CreateBuiltinAgentsOptions } from "./builtin-agents";
|
|
3
|
+
export { buildAgent } from "./agent-builder";
|
|
4
|
+
export type { BuildAgentOptions, ResolveSkillsFn } from "./agent-builder";
|
|
5
|
+
export { resolveAgentModel, AGENT_MODEL_REQUIREMENTS } from "./model-resolution";
|
|
6
|
+
export * from "./dynamic-prompt-builder";
|
|
7
|
+
export type { AgentMode, AgentFactory, AgentSource, AgentCategory, AgentCost, DelegationTrigger, AgentPromptMetadata, WeaveAgentName, } from "./types";
|
|
8
|
+
export { isFactory, isGptModel } from "./types";
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { AgentMode, WeaveAgentName } from "./types";
|
|
2
|
+
export type FallbackEntry = {
|
|
3
|
+
providers: string[];
|
|
4
|
+
model: string;
|
|
5
|
+
variant?: string;
|
|
6
|
+
};
|
|
7
|
+
export type AgentModelRequirement = {
|
|
8
|
+
fallbackChain: FallbackEntry[];
|
|
9
|
+
};
|
|
10
|
+
export declare const AGENT_MODEL_REQUIREMENTS: Record<WeaveAgentName, AgentModelRequirement>;
|
|
11
|
+
export type ResolveAgentModelOptions = {
|
|
12
|
+
availableModels: Set<string>;
|
|
13
|
+
agentMode: AgentMode;
|
|
14
|
+
uiSelectedModel?: string;
|
|
15
|
+
categoryModel?: string;
|
|
16
|
+
overrideModel?: string;
|
|
17
|
+
systemDefaultModel?: string;
|
|
18
|
+
};
|
|
19
|
+
export declare function resolveAgentModel(agentName: WeaveAgentName, options: ResolveAgentModelOptions): string;
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { AgentConfig } from "@opencode-ai/sdk";
|
|
2
|
+
/**
|
|
3
|
+
* Agent mode determines UI model selection behavior:
|
|
4
|
+
* - "primary": Respects user's UI-selected model (loom, tapestry)
|
|
5
|
+
* - "subagent": Uses own fallback chain, ignores UI selection (pattern, thread, spindle)
|
|
6
|
+
* - "all": Available in both contexts (shuttle)
|
|
7
|
+
*/
|
|
8
|
+
export type AgentMode = "primary" | "subagent" | "all";
|
|
9
|
+
/**
|
|
10
|
+
* Agent factory function with static mode property.
|
|
11
|
+
* Mode is exposed as static property for pre-instantiation access.
|
|
12
|
+
*/
|
|
13
|
+
export type AgentFactory = ((model: string) => AgentConfig) & {
|
|
14
|
+
mode: AgentMode;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* Agent source is either a factory (called with model) or a static config (cloned)
|
|
18
|
+
*/
|
|
19
|
+
export type AgentSource = AgentFactory | AgentConfig;
|
|
20
|
+
/**
|
|
21
|
+
* Agent category for grouping in Loom prompt sections
|
|
22
|
+
*/
|
|
23
|
+
export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility";
|
|
24
|
+
/**
|
|
25
|
+
* Cost classification for Tool Selection table
|
|
26
|
+
*/
|
|
27
|
+
export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE";
|
|
28
|
+
/**
|
|
29
|
+
* Delegation trigger for Loom prompt's Delegation Table
|
|
30
|
+
*/
|
|
31
|
+
export interface DelegationTrigger {
|
|
32
|
+
/** Domain of work (e.g., "Frontend UI/UX") */
|
|
33
|
+
domain: string;
|
|
34
|
+
/** When to delegate (e.g., "Visual changes only...") */
|
|
35
|
+
trigger: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Metadata for generating Loom prompt sections dynamically.
|
|
39
|
+
* Allows adding/removing agents without manually updating the Loom prompt.
|
|
40
|
+
*/
|
|
41
|
+
export interface AgentPromptMetadata {
|
|
42
|
+
/** Category for grouping in prompt sections */
|
|
43
|
+
category: AgentCategory;
|
|
44
|
+
/** Cost classification for Tool Selection table */
|
|
45
|
+
cost: AgentCost;
|
|
46
|
+
/** Domain triggers for Delegation Table */
|
|
47
|
+
triggers: DelegationTrigger[];
|
|
48
|
+
/** When to use this agent (for detailed sections) */
|
|
49
|
+
useWhen?: string[];
|
|
50
|
+
/** When NOT to use this agent */
|
|
51
|
+
avoidWhen?: string[];
|
|
52
|
+
/** Optional dedicated prompt section (markdown) */
|
|
53
|
+
dedicatedSection?: string;
|
|
54
|
+
/** Nickname/alias used in prompt (e.g., "Pattern" instead of "pattern") */
|
|
55
|
+
promptAlias?: string;
|
|
56
|
+
/** Key trigger that should appear in Phase 0 quick checks */
|
|
57
|
+
keyTrigger?: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The 8 built-in Weave agent names
|
|
61
|
+
*/
|
|
62
|
+
export type WeaveAgentName = "loom" | "tapestry" | "shuttle" | "pattern" | "thread" | "spindle" | "weft" | "warp";
|
|
63
|
+
/**
|
|
64
|
+
* Override config for a single agent — all fields optional
|
|
65
|
+
*/
|
|
66
|
+
export type AgentOverrideConfig = Partial<AgentConfig> & {
|
|
67
|
+
prompt_append?: string;
|
|
68
|
+
variant?: string;
|
|
69
|
+
fallback_models?: string | string[];
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* Map of agent name to override config
|
|
73
|
+
*/
|
|
74
|
+
export type AgentOverrides = Partial<Record<WeaveAgentName, AgentOverrideConfig>>;
|
|
75
|
+
/**
|
|
76
|
+
* Returns true if the model string identifies a GPT/OpenAI model.
|
|
77
|
+
*/
|
|
78
|
+
export declare function isGptModel(model: string): boolean;
|
|
79
|
+
/**
|
|
80
|
+
* Type guard: returns true if source is an AgentFactory (callable with .mode).
|
|
81
|
+
*/
|
|
82
|
+
export declare function isFactory(source: AgentSource): source is AgentFactory;
|