opencode-swarm-plugin 0.48.1 → 0.50.0
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 +10 -7
- package/bin/swarm-setup-consolidate.test.ts +84 -0
- package/bin/swarm.test.ts +170 -0
- package/bin/swarm.ts +300 -2
- package/bin/test-setup-manual.md +67 -0
- package/dist/bin/swarm.js +110927 -100418
- package/dist/coordinator-guard.d.ts +79 -0
- package/dist/coordinator-guard.d.ts.map +1 -0
- package/dist/examples/plugin-wrapper-template.ts +13 -2
- package/dist/hive.d.ts.map +1 -1
- package/dist/hive.js +5 -4
- package/dist/index.d.ts +18 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +35762 -31538
- package/dist/memory.d.ts.map +1 -1
- package/dist/plugin.js +35396 -31175
- package/dist/query-tools.d.ts +5 -0
- package/dist/query-tools.d.ts.map +1 -1
- package/dist/schemas/cell.d.ts +12 -0
- package/dist/schemas/cell.d.ts.map +1 -1
- package/dist/swarm-insights.d.ts +181 -0
- package/dist/swarm-insights.d.ts.map +1 -1
- package/dist/swarm-orchestrate.d.ts +4 -4
- package/dist/swarm-prompts.d.ts +1 -1
- package/dist/swarm-prompts.d.ts.map +1 -1
- package/dist/swarm-prompts.js +22944 -18766
- package/dist/swarm-strategies.d.ts +1 -1
- package/dist/swarm.d.ts +2 -2
- package/examples/plugin-wrapper-template.ts +13 -2
- package/package.json +2 -2
package/dist/query-tools.d.ts
CHANGED
|
@@ -15,6 +15,11 @@ export interface QueryResult {
|
|
|
15
15
|
executionTimeMs: number;
|
|
16
16
|
}
|
|
17
17
|
export declare const presetQueries: Record<PresetQueryName, string>;
|
|
18
|
+
/**
|
|
19
|
+
* Get database path from project path.
|
|
20
|
+
* Uses global database (~/.config/swarm-tools/swarm.db)
|
|
21
|
+
*/
|
|
22
|
+
export declare function getDbPath(): string;
|
|
18
23
|
/**
|
|
19
24
|
* Execute custom SQL against the events table (low-level).
|
|
20
25
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-tools.d.ts","sourceRoot":"","sources":["../src/query-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"query-tools.d.ts","sourceRoot":"","sources":["../src/query-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD,MAAM,MAAM,eAAe,GACxB,uBAAuB,GACvB,sBAAsB,GACtB,gBAAgB,GAChB,qBAAqB,GACrB,mBAAmB,GACnB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,wBAAwB,GACxB,sBAAsB,CAAC;AAE1B,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACxB;AAMD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAgKzD,CAAC;AAMF;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAeD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CACjC,EAAE,EAAE,eAAe,EACnB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GAChB,OAAO,CAAC,WAAW,CAAC,CAiBtB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACvC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAStB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACpC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,GAAG,EAAE,CAAC,CAIhB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAClC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,EAAE,CAAC,CAIhB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAkEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA2BvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAExD"}
|
package/dist/schemas/cell.d.ts
CHANGED
|
@@ -165,6 +165,12 @@ export declare const CellTreeSchema: z.ZodObject<{
|
|
|
165
165
|
dependencies: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
|
|
166
166
|
estimated_complexity: z.ZodDefault<z.ZodNumber>;
|
|
167
167
|
}, z.core.$strip>>;
|
|
168
|
+
strategy: z.ZodOptional<z.ZodEnum<{
|
|
169
|
+
"file-based": "file-based";
|
|
170
|
+
"feature-based": "feature-based";
|
|
171
|
+
"risk-based": "risk-based";
|
|
172
|
+
"research-based": "research-based";
|
|
173
|
+
}>>;
|
|
168
174
|
}, z.core.$strip>;
|
|
169
175
|
export type CellTree = z.infer<typeof CellTreeSchema>;
|
|
170
176
|
/** Arguments for creating an epic with subtasks */
|
|
@@ -395,6 +401,12 @@ export declare const BeadTreeSchema: z.ZodObject<{
|
|
|
395
401
|
dependencies: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
|
|
396
402
|
estimated_complexity: z.ZodDefault<z.ZodNumber>;
|
|
397
403
|
}, z.core.$strip>>;
|
|
404
|
+
strategy: z.ZodOptional<z.ZodEnum<{
|
|
405
|
+
"file-based": "file-based";
|
|
406
|
+
"feature-based": "feature-based";
|
|
407
|
+
"risk-based": "risk-based";
|
|
408
|
+
"research-based": "research-based";
|
|
409
|
+
}>>;
|
|
398
410
|
}, z.core.$strip>;
|
|
399
411
|
/** @deprecated Use CellTree instead */
|
|
400
412
|
export type BeadTree = CellTree;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../../src/schemas/cell.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,0BAA0B;AAC1B,eAAO,MAAM,gBAAgB;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,uBAAuB;AACvB,eAAO,MAAM,cAAc;;;;;;EAMzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB;;;;;;;;iBAG/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,oCAAoC;AACpC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,oCAAoC;AACpC,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,mCAAmC;AACnC,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,mCAAmC;AACnC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;iBAM9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;iBAc5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,cAAc
|
|
1
|
+
{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../../src/schemas/cell.ts"],"names":[],"mappings":"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"}
|
package/dist/swarm-insights.d.ts
CHANGED
|
@@ -22,6 +22,11 @@ export interface FileInsight {
|
|
|
22
22
|
lastFailure: string | null;
|
|
23
23
|
gotchas: string[];
|
|
24
24
|
}
|
|
25
|
+
export interface FileFailureHistory {
|
|
26
|
+
file: string;
|
|
27
|
+
rejectionCount: number;
|
|
28
|
+
topIssues: string[];
|
|
29
|
+
}
|
|
25
30
|
export interface PatternInsight {
|
|
26
31
|
pattern: string;
|
|
27
32
|
frequency: number;
|
|
@@ -35,6 +40,28 @@ export interface InsightsBundle {
|
|
|
35
40
|
export interface FormatOptions {
|
|
36
41
|
maxTokens?: number;
|
|
37
42
|
}
|
|
43
|
+
export interface RejectionReason {
|
|
44
|
+
category: string;
|
|
45
|
+
count: number;
|
|
46
|
+
percentage: number;
|
|
47
|
+
}
|
|
48
|
+
export interface RejectionAnalytics {
|
|
49
|
+
totalReviews: number;
|
|
50
|
+
approved: number;
|
|
51
|
+
rejected: number;
|
|
52
|
+
approvalRate: number;
|
|
53
|
+
topReasons: RejectionReason[];
|
|
54
|
+
}
|
|
55
|
+
export interface ViolationMetric {
|
|
56
|
+
violationType: string;
|
|
57
|
+
count: number;
|
|
58
|
+
percentage: number;
|
|
59
|
+
}
|
|
60
|
+
export interface ViolationAnalytics {
|
|
61
|
+
totalViolations: number;
|
|
62
|
+
byType: ViolationMetric[];
|
|
63
|
+
violationRate: number;
|
|
64
|
+
}
|
|
38
65
|
/**
|
|
39
66
|
* Get strategy success rates and recommendations for a task.
|
|
40
67
|
*
|
|
@@ -74,6 +101,74 @@ export declare function getStrategyInsights(swarmMail: SwarmMailAdapter, _task:
|
|
|
74
101
|
* ```
|
|
75
102
|
*/
|
|
76
103
|
export declare function getFileInsights(swarmMail: SwarmMailAdapter, files: string[]): Promise<FileInsight[]>;
|
|
104
|
+
/**
|
|
105
|
+
* Get file-specific gotchas from semantic memory (hivemind).
|
|
106
|
+
*
|
|
107
|
+
* Queries semantic memory for learnings related to a specific file.
|
|
108
|
+
* Used in worker prompts to surface historical issues/warnings.
|
|
109
|
+
*
|
|
110
|
+
* Strategy:
|
|
111
|
+
* 1. Query hivemind with file path + "gotcha pitfall warning" keywords
|
|
112
|
+
* 2. Filter results to only include memories that mention the specific file
|
|
113
|
+
* 3. Return top 3 learnings, truncated to ~100 chars each for context efficiency
|
|
114
|
+
*
|
|
115
|
+
* @param _swarmMail - SwarmMail adapter (unused, kept for API consistency)
|
|
116
|
+
* @param file - File path to query learnings for
|
|
117
|
+
* @returns Promise resolving to array of gotcha strings (max 3)
|
|
118
|
+
*
|
|
119
|
+
* @example
|
|
120
|
+
* ```typescript
|
|
121
|
+
* const gotchas = await getFileGotchas(swarmMail, "src/auth.ts");
|
|
122
|
+
* // Returns semantic memory learnings like:
|
|
123
|
+
* // ["OAuth tokens need 5min buffer before expiry to avoid race conditions in src/auth.ts", ...]
|
|
124
|
+
* ```
|
|
125
|
+
*/
|
|
126
|
+
export declare function getFileGotchas(_swarmMail: SwarmMailAdapter, file: string): Promise<string[]>;
|
|
127
|
+
/**
|
|
128
|
+
* Get failure history for specific files from review feedback events.
|
|
129
|
+
*
|
|
130
|
+
* Queries the event store for review_feedback events where status="needs_changes"
|
|
131
|
+
* and aggregates rejection reasons by file. Returns top 3 most common issues per file.
|
|
132
|
+
*
|
|
133
|
+
* @param swarmMail - SwarmMail adapter for database access
|
|
134
|
+
* @param files - Array of file paths to query history for
|
|
135
|
+
* @returns Promise resolving to array of file failure histories with rejection counts and top issues
|
|
136
|
+
*
|
|
137
|
+
* @example
|
|
138
|
+
* ```typescript
|
|
139
|
+
* const history = await getFileFailureHistory(swarmMail, ["src/auth.ts", "src/db.ts"]);
|
|
140
|
+
* // Returns: [
|
|
141
|
+
* // { file: "src/auth.ts", rejectionCount: 3, topIssues: ["Missing null checks", "Forgot rate limiting"] }
|
|
142
|
+
* // ]
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
export declare function getFileFailureHistory(swarmMail: SwarmMailAdapter, files: string[]): Promise<FileFailureHistory[]>;
|
|
146
|
+
/**
|
|
147
|
+
* Get rejection analytics from review feedback events.
|
|
148
|
+
*
|
|
149
|
+
* Analyzes review_feedback events to calculate approval/rejection rates and
|
|
150
|
+
* categorize common rejection reasons. Returns aggregated analytics suitable
|
|
151
|
+
* for the swarm stats --rejections dashboard.
|
|
152
|
+
*
|
|
153
|
+
* @param swarmMail - SwarmMail adapter for database access
|
|
154
|
+
* @returns Promise resolving to rejection analytics with rates and categorized reasons
|
|
155
|
+
*
|
|
156
|
+
* @example
|
|
157
|
+
* ```typescript
|
|
158
|
+
* const analytics = await getRejectionAnalytics(swarmMail);
|
|
159
|
+
* // Returns: {
|
|
160
|
+
* // totalReviews: 449,
|
|
161
|
+
* // approved: 175,
|
|
162
|
+
* // rejected: 274,
|
|
163
|
+
* // approvalRate: 38.97,
|
|
164
|
+
* // topReasons: [
|
|
165
|
+
* // { category: "Missing tests", count: 89, percentage: 32.48 },
|
|
166
|
+
* // { category: "Type errors", count: 67, percentage: 24.45 }
|
|
167
|
+
* // ]
|
|
168
|
+
* // }
|
|
169
|
+
* ```
|
|
170
|
+
*/
|
|
171
|
+
export declare function getRejectionAnalytics(swarmMail: SwarmMailAdapter): Promise<RejectionAnalytics>;
|
|
77
172
|
/**
|
|
78
173
|
* Get common failure patterns and anti-patterns.
|
|
79
174
|
*
|
|
@@ -152,4 +247,90 @@ export declare function getCachedInsights(_swarmMail: SwarmMailAdapter, cacheKey
|
|
|
152
247
|
* ```
|
|
153
248
|
*/
|
|
154
249
|
export declare function clearInsightsCache(): void;
|
|
250
|
+
/**
|
|
251
|
+
* Track a coordinator violation event in the event store.
|
|
252
|
+
*
|
|
253
|
+
* Records when a coordinator attempts forbidden actions (editing files,
|
|
254
|
+
* running tests, reserving files). These events feed violation analytics
|
|
255
|
+
* for swarm health monitoring.
|
|
256
|
+
*
|
|
257
|
+
* @param swarmMail - SwarmMail adapter for database access
|
|
258
|
+
* @param violation - Violation details
|
|
259
|
+
* @returns Promise resolving to event ID
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* ```typescript
|
|
263
|
+
* import { CoordinatorGuardError } from "./coordinator-guard";
|
|
264
|
+
*
|
|
265
|
+
* try {
|
|
266
|
+
* // Coordinator attempts to edit file
|
|
267
|
+
* } catch (error) {
|
|
268
|
+
* if (error instanceof CoordinatorGuardError) {
|
|
269
|
+
* await trackCoordinatorViolation(swarmMail, {
|
|
270
|
+
* project_key: "/abs/path/to/project",
|
|
271
|
+
* session_id: "session-123",
|
|
272
|
+
* epic_id: "mjudv5mwh66",
|
|
273
|
+
* violation_type: error.violationType,
|
|
274
|
+
* payload: error.payload,
|
|
275
|
+
* });
|
|
276
|
+
* }
|
|
277
|
+
* }
|
|
278
|
+
* ```
|
|
279
|
+
*/
|
|
280
|
+
export declare function trackCoordinatorViolation(swarmMail: SwarmMailAdapter, violation: {
|
|
281
|
+
project_key: string;
|
|
282
|
+
session_id: string;
|
|
283
|
+
epic_id: string;
|
|
284
|
+
violation_type: "coordinator_edited_file" | "coordinator_ran_tests" | "coordinator_reserved_files";
|
|
285
|
+
payload: Record<string, unknown>;
|
|
286
|
+
}): Promise<number>;
|
|
287
|
+
/**
|
|
288
|
+
* Get violation analytics from coordinator guard events.
|
|
289
|
+
*
|
|
290
|
+
* Analyzes coordinator_violation events to calculate total violations,
|
|
291
|
+
* breakdown by type, and violation rate relative to total coordination
|
|
292
|
+
* actions. Used in swarm_status output to surface coordinator discipline.
|
|
293
|
+
*
|
|
294
|
+
* @param swarmMail - SwarmMail adapter for database access
|
|
295
|
+
* @param projectKey - Optional project key to filter violations
|
|
296
|
+
* @returns Promise resolving to violation analytics
|
|
297
|
+
*
|
|
298
|
+
* @example
|
|
299
|
+
* ```typescript
|
|
300
|
+
* const analytics = await getViolationAnalytics(swarmMail);
|
|
301
|
+
* // Returns: {
|
|
302
|
+
* // totalViolations: 12,
|
|
303
|
+
* // byType: [
|
|
304
|
+
* // { violationType: "coordinator_edited_file", count: 8, percentage: 66.67 },
|
|
305
|
+
* // { violationType: "coordinator_ran_tests", count: 3, percentage: 25.00 },
|
|
306
|
+
* // { violationType: "coordinator_reserved_files", count: 1, percentage: 8.33 }
|
|
307
|
+
* // ],
|
|
308
|
+
* // violationRate: 2.4 // 12 violations per 500 coordination actions = 2.4%
|
|
309
|
+
* // }
|
|
310
|
+
* ```
|
|
311
|
+
*/
|
|
312
|
+
export declare function getViolationAnalytics(swarmMail: SwarmMailAdapter, projectKey?: string): Promise<ViolationAnalytics>;
|
|
313
|
+
/**
|
|
314
|
+
* Format file failure history as warnings for worker prompts.
|
|
315
|
+
*
|
|
316
|
+
* Produces a concise warning section showing which files have caused
|
|
317
|
+
* previous workers to fail review, with the top issues encountered.
|
|
318
|
+
*
|
|
319
|
+
* Limits output to fit context budget (~300 tokens).
|
|
320
|
+
*
|
|
321
|
+
* @param histories - Array of file failure histories
|
|
322
|
+
* @returns Formatted warning section with emoji header, or empty string if no histories
|
|
323
|
+
*
|
|
324
|
+
* @example
|
|
325
|
+
* ```typescript
|
|
326
|
+
* const histories = [
|
|
327
|
+
* { file: "src/auth.ts", rejectionCount: 3, topIssues: ["Missing null checks", "Forgot rate limiting"] }
|
|
328
|
+
* ];
|
|
329
|
+
* const warnings = formatFileHistoryWarnings(histories);
|
|
330
|
+
* // Returns:
|
|
331
|
+
* // ⚠️ FILE HISTORY WARNINGS:
|
|
332
|
+
* // - src/auth.ts: 3 previous workers rejected for missing null checks, forgot rate limiting
|
|
333
|
+
* ```
|
|
334
|
+
*/
|
|
335
|
+
export declare function formatFileHistoryWarnings(histories: FileFailureHistory[]): string;
|
|
155
336
|
//# sourceMappingURL=swarm-insights.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"swarm-insights.d.ts","sourceRoot":"","sources":["../src/swarm-insights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"swarm-insights.d.ts","sourceRoot":"","sources":["../src/swarm-insights.ts"],"names":[],"mappings":"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"}
|
|
@@ -224,7 +224,7 @@ export declare const swarm_complete: {
|
|
|
224
224
|
files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
225
225
|
skip_verification: z.ZodOptional<z.ZodBoolean>;
|
|
226
226
|
planned_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
227
|
-
start_time: z.
|
|
227
|
+
start_time: z.ZodNumber;
|
|
228
228
|
error_count: z.ZodOptional<z.ZodNumber>;
|
|
229
229
|
retry_count: z.ZodOptional<z.ZodNumber>;
|
|
230
230
|
skip_review: z.ZodOptional<z.ZodBoolean>;
|
|
@@ -234,11 +234,11 @@ export declare const swarm_complete: {
|
|
|
234
234
|
agent_name: string;
|
|
235
235
|
bead_id: string;
|
|
236
236
|
summary: string;
|
|
237
|
+
start_time: number;
|
|
237
238
|
evaluation?: string | undefined;
|
|
238
239
|
files_touched?: string[] | undefined;
|
|
239
240
|
skip_verification?: boolean | undefined;
|
|
240
241
|
planned_files?: string[] | undefined;
|
|
241
|
-
start_time?: number | undefined;
|
|
242
242
|
error_count?: number | undefined;
|
|
243
243
|
retry_count?: number | undefined;
|
|
244
244
|
skip_review?: boolean | undefined;
|
|
@@ -703,7 +703,7 @@ export declare const orchestrateTools: {
|
|
|
703
703
|
files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
704
704
|
skip_verification: z.ZodOptional<z.ZodBoolean>;
|
|
705
705
|
planned_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
706
|
-
start_time: z.
|
|
706
|
+
start_time: z.ZodNumber;
|
|
707
707
|
error_count: z.ZodOptional<z.ZodNumber>;
|
|
708
708
|
retry_count: z.ZodOptional<z.ZodNumber>;
|
|
709
709
|
skip_review: z.ZodOptional<z.ZodBoolean>;
|
|
@@ -713,11 +713,11 @@ export declare const orchestrateTools: {
|
|
|
713
713
|
agent_name: string;
|
|
714
714
|
bead_id: string;
|
|
715
715
|
summary: string;
|
|
716
|
+
start_time: number;
|
|
716
717
|
evaluation?: string | undefined;
|
|
717
718
|
files_touched?: string[] | undefined;
|
|
718
719
|
skip_verification?: boolean | undefined;
|
|
719
720
|
planned_files?: string[] | undefined;
|
|
720
|
-
start_time?: number | undefined;
|
|
721
721
|
error_count?: number | undefined;
|
|
722
722
|
retry_count?: number | undefined;
|
|
723
723
|
skip_review?: boolean | undefined;
|
package/dist/swarm-prompts.d.ts
CHANGED
|
@@ -54,7 +54,7 @@ export declare const SUBTASK_PROMPT_V2 = "You are a swarm agent working on: **{s
|
|
|
54
54
|
* - {task} - The task description from user
|
|
55
55
|
* - {project_path} - Absolute path to project root
|
|
56
56
|
*/
|
|
57
|
-
export declare const COORDINATOR_PROMPT = "You are a swarm coordinator. Your job is to clarify the task, decompose it into cells, and spawn parallel agents.\n\n## Task\n\n{task}\n\n## CRITICAL: Coordinator Role Boundaries\n\n**\u26A0\uFE0F COORDINATORS NEVER EXECUTE WORK DIRECTLY**\n\nYour role is **ONLY** to:\n1. **Clarify** - Ask questions to understand scope\n2. **Decompose** - Break into subtasks with clear boundaries \n3. **Spawn** - Create worker agents for ALL subtasks\n4. **Monitor** - Check progress, unblock, mediate conflicts\n5. **Verify** - Confirm completion, run final checks\n\n**YOU DO NOT:**\n- Read implementation files (only metadata/structure for planning)\n- Edit code directly\n- Run tests yourself (workers run tests)\n- Implement features\n- Fix bugs inline\n- Make \"quick fixes\" yourself\n\n**ALWAYS spawn workers, even for sequential tasks.** Sequential just means spawn them in order and wait for each to complete before spawning the next.\n\n### Why This Matters\n\n| Coordinator Work | Worker Work | Consequence of Mixing |\n|-----------------|-------------|----------------------|\n| Sonnet context ($$$) | Disposable context | Expensive context waste |\n| Long-lived state | Task-scoped state | Context exhaustion |\n| Orchestration concerns | Implementation concerns | Mixed concerns |\n| No checkpoints | Checkpoints enabled | No recovery |\n| No learning signals | Outcomes tracked | No improvement |\n\n## CRITICAL: NEVER Fetch Documentation Directly\n\n**\u26A0\uFE0F COORDINATORS DO NOT CALL RESEARCH TOOLS DIRECTLY**\n\nThe following tools are **FORBIDDEN** for coordinators to call:\n\n- `repo-crawl_file`, `repo-crawl_readme`, `repo-crawl_search`, `repo-crawl_structure`, `repo-crawl_tree`\n- `repo-autopsy_*` (all variants)\n- `webfetch`, `fetch_fetch`\n- `context7_resolve-library-id`, `context7_get-library-docs`\n- `pdf-brain_search`, `pdf-brain_read`\n\n**WHY?** These tools dump massive context that exhausts your expensive Sonnet context. Your job is orchestration, not research.\n\n**INSTEAD:** Use `swarm_spawn_researcher` (see Phase 1.5 below) to spawn a researcher worker who:\n- Fetches documentation in disposable context\n- Stores full details in hivemind\n- Returns a condensed summary for shared_context\n\n## Workflow\n\n### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)\n\n**Before decomposing, clarify the task with the user.**\n\nCheck for flags in the task:\n- `--fast` \u2192 Skip questions, use reasonable defaults\n- `--auto` \u2192 Zero interaction, heuristic decisions\n- `--confirm-only` \u2192 Show plan, get yes/no only\n\n**Default (no flags): Full Socratic Mode**\n\n1. **Analyze task for ambiguity:**\n - Scope unclear? (what's included/excluded)\n - Strategy unclear? (file-based vs feature-based)\n - Dependencies unclear? (what needs to exist first)\n - Success criteria unclear? (how do we know it's done)\n\n2. **If clarification needed, ask ONE question at a time:**\n ```\n The task \"<task>\" needs clarification before I can decompose it.\n\n **Question:** <specific question>\n\n Options:\n a) <option 1> - <tradeoff>\n b) <option 2> - <tradeoff>\n c) <option 3> - <tradeoff>\n\n I'd recommend (b) because <reason>. Which approach?\n ```\n\n3. **Wait for user response before proceeding**\n\n4. **Iterate if needed** (max 2-3 questions)\n\n**Rules:**\n- ONE question at a time - don't overwhelm\n- Offer concrete options - not open-ended\n- Lead with recommendation - save cognitive load\n- Wait for answer - don't assume\n\n### Phase 1: Initialize\n`swarmmail_init(project_path=\"{project_path}\", task_description=\"Swarm: {task}\")`\n\n### Phase 1.5: Research Phase (FOR COMPLEX TASKS)\n\n**\u26A0\uFE0F If the task requires understanding unfamiliar technologies, APIs, or libraries, spawn a researcher FIRST.**\n\n**DO NOT call documentation tools directly.** Instead:\n\n```\n// 1. Spawn researcher with explicit tech stack\nswarm_spawn_researcher(\n research_id=\"research-nextjs-cache-components\",\n epic_id=\"<epic-id>\",\n tech_stack=[\"Next.js 16 Cache Components\", \"React Server Components\"],\n project_path=\"{project_path}\"\n)\n\n// 2. Spawn researcher as Task subagent\nconst researchFindings = await Task(subagent_type=\"swarm-researcher\", prompt=\"<from above>\")\n\n// 3. Researcher returns condensed summary\n// Use this summary in shared_context for workers\n```\n\n**When to spawn a researcher:**\n- Task involves unfamiliar framework versions (e.g., Next.js 16 vs 14)\n- Need to compare installed vs latest library APIs\n- Working with experimental/preview features\n- Need architectural guidance from documentation\n\n**When NOT to spawn a researcher:**\n- Using well-known stable APIs (React hooks, Express middleware)\n- Task is purely refactoring existing code\n- You already have relevant findings from hivemind\n\n**Researcher output:**\n- Full findings stored in hivemind (searchable by future agents)\n- Condensed 3-5 bullet summary returned for shared_context\n\n### Phase 2: Knowledge Gathering (MANDATORY)\n\n**Before decomposing, query ALL knowledge sources:**\n\n```\nhivemind_find(query=\"<task keywords>\", limit=5) # Past learnings\nhivemind_find(query=\"<task description>\", limit=5, collection=\"sessions\") # Similar past tasks \nskills_list() # Available skills\n```\n\nSynthesize findings into shared_context for workers.\n\n### Phase 3: Decompose\n```\nswarm_select_strategy(task=\"<task>\")\nswarm_plan_prompt(task=\"<task>\", context=\"<synthesized knowledge>\")\nswarm_validate_decomposition(response=\"<CellTree JSON>\")\n```\n\n### Phase 4: Create Cells\n`hive_create_epic(epic_title=\"<task>\", subtasks=[...])`\n\n### Phase 5: DO NOT Reserve Files\n\n> **\u26A0\uFE0F Coordinator NEVER reserves files.** Workers reserve their own files.\n> If coordinator reserves, workers get blocked and swarm stalls.\n\n### Phase 6: Spawn Workers for ALL Subtasks (MANDATORY)\n\n> **\u26A0\uFE0F ALWAYS spawn workers, even for sequential tasks.**\n> - Parallel tasks: Spawn ALL in a single message\n> - Sequential tasks: Spawn one, wait for completion, spawn next\n\n**For parallel work:**\n```\n// Single message with multiple Task calls\nswarm_spawn_subtask(bead_id_1, epic_id, title_1, files_1, shared_context, project_path=\"{project_path}\")\nTask(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\nswarm_spawn_subtask(bead_id_2, epic_id, title_2, files_2, shared_context, project_path=\"{project_path}\")\nTask(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n```\n\n**For sequential work:**\n```\n// Spawn worker 1, wait for completion\nswarm_spawn_subtask(bead_id_1, ...)\nconst result1 = await Task(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n\n// THEN spawn worker 2 with context from worker 1\nswarm_spawn_subtask(bead_id_2, ..., shared_context=\"Worker 1 completed: \" + result1)\nconst result2 = await Task(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n```\n\n**NEVER do the work yourself.** Even if it seems faster, spawn a worker.\n\n**IMPORTANT:** Pass `project_path` to `swarm_spawn_subtask` so workers can call `swarmmail_init`.\n\n### Phase 7: MANDATORY Review Loop (NON-NEGOTIABLE)\n\n**\u26A0\uFE0F AFTER EVERY Task() RETURNS, YOU MUST:**\n\n1. **CHECK INBOX** - Worker may have sent messages\n `swarmmail_inbox()`\n `swarmmail_read_message(message_id=N)`\n\n2. **REVIEW WORK** - Generate review with diff\n `swarm_review(project_key, epic_id, task_id, files_touched)`\n\n3. **EVALUATE** - Does it meet epic goals?\n - Fulfills subtask requirements?\n - Serves overall epic goal?\n - Enables downstream tasks?\n - Type safety, no obvious bugs?\n\n4. **SEND FEEDBACK** - Approve or request changes\n `swarm_review_feedback(project_key, task_id, worker_id, status, issues)`\n \n **If approved:**\n - Close cell, spawn next worker\n \n **If needs_changes:**\n - `swarm_review_feedback` returns `retry_context` (NOT sends message - worker is dead)\n - Generate retry prompt: `swarm_spawn_retry(retry_context)`\n - Spawn NEW worker with Task() using retry prompt\n - Max 3 attempts before marking task blocked\n \n **If 3 failures:**\n - Mark task blocked, escalate to human\n\n5. **ONLY THEN** - Spawn next worker or complete\n\n**DO NOT skip this. DO NOT batch reviews. Review EACH worker IMMEDIATELY after return.**\n\n**Intervene if:**\n- Worker blocked >5min \u2192 unblock or reassign\n- File conflicts \u2192 mediate between workers\n- Scope creep \u2192 approve or reject expansion\n- Review fails 3x \u2192 mark task blocked, escalate to human\n\n### Phase 8: Complete\n```\n# After all workers complete and reviews pass:\nhive_sync() # Sync all cells to git\n# Coordinator does NOT call swarm_complete - workers do that\n```\n\n## Strategy Reference\n\n| Strategy | Best For | Keywords |\n| -------------- | ------------------------ | -------------------------------------- |\n| file-based | Refactoring, migrations | refactor, migrate, rename, update all |\n| feature-based | New features | add, implement, build, create, feature |\n| risk-based | Bug fixes, security | fix, bug, security, critical, urgent |\n| research-based | Investigation, discovery | research, investigate, explore, learn |\n\n## Flag Reference\n\n| Flag | Effect |\n|------|--------|\n| `--fast` | Skip Socratic questions, use defaults |\n| `--auto` | Zero interaction, heuristic decisions |\n| `--confirm-only` | Show plan, get yes/no only |\n\nBegin with Phase 0 (Socratic Planning) unless `--fast` or `--auto` flag is present.\n";
|
|
57
|
+
export declare const COORDINATOR_PROMPT = "You are a swarm coordinator. Your job is to clarify the task, decompose it into cells, and spawn parallel agents.\n\n## Task\n\n{task}\n\n## CRITICAL: Coordinator Role Boundaries\n\n**\u26A0\uFE0F COORDINATORS NEVER EXECUTE WORK DIRECTLY**\n\nYour role is **ONLY** to:\n1. **Clarify** - Ask questions to understand scope\n2. **Decompose** - Break into subtasks with clear boundaries \n3. **Spawn** - Create worker agents for ALL subtasks\n4. **Monitor** - Check progress, unblock, mediate conflicts\n5. **Verify** - Confirm completion, run final checks\n\n**YOU DO NOT:**\n- Read implementation files (only metadata/structure for planning)\n- Edit code directly\n- Run tests yourself (workers run tests)\n- Implement features\n- Fix bugs inline\n- Make \"quick fixes\" yourself\n\n**ALWAYS spawn workers, even for sequential tasks.** Sequential just means spawn them in order and wait for each to complete before spawning the next.\n\n### Explicit NEVER Rules (With Examples)\n\n```\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551 \u2551\n\u2551 \u274C COORDINATORS NEVER DO THIS: \u2551\n\u2551 \u2551\n\u2551 - Read implementation files (read(), glob src/**, grep for patterns) \u2551\n\u2551 - Edit code (edit(), write() any .ts/.js/.tsx files) \u2551\n\u2551 - Run tests (bash \"bun test\", \"npm test\", pytest) \u2551\n\u2551 - Implement features (adding functions, components, logic) \u2551\n\u2551 - Fix bugs (changing code to fix errors) \u2551\n\u2551 - Install packages (bash \"bun add\", \"npm install\") \u2551\n\u2551 - Commit changes (bash \"git add\", \"git commit\") \u2551\n\u2551 - Reserve files (swarmmail_reserve - workers do this) \u2551\n\u2551 \u2551\n\u2551 \u2705 COORDINATORS ONLY DO THIS: \u2551\n\u2551 \u2551\n\u2551 - Clarify task scope (ask questions, understand requirements) \u2551\n\u2551 - Read package.json/tsconfig.json for structure (metadata only) \u2551\n\u2551 - Decompose into subtasks (swarm_plan_prompt, validate_decomposition) \u2551\n\u2551 - Spawn workers (swarm_spawn_subtask, Task(subagent_type=\"worker\")) \u2551\n\u2551 - Monitor progress (swarmmail_inbox, swarm_status) \u2551\n\u2551 - Review completed work (swarm_review, swarm_review_feedback) \u2551\n\u2551 - Verify final state (check all workers completed, hive_sync) \u2551\n\u2551 \u2551\n\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n```\n\n**Examples of Violations:**\n\n\u274C **WRONG** - Coordinator reading implementation:\n```\nread(\"src/auth/login.ts\") // NO - spawn worker to analyze\nglob(\"src/components/**/*.tsx\") // NO - spawn worker to inventory\ngrep(pattern=\"export\", include=\"*.ts\") // NO - spawn worker to search\n```\n\n\u274C **WRONG** - Coordinator editing code:\n```\nedit(\"src/types.ts\", ...) // NO - spawn worker to fix\nwrite(\"src/new.ts\", ...) // NO - spawn worker to create\n```\n\n\u274C **WRONG** - Coordinator running tests:\n```\nbash(\"bun test src/auth.test.ts\") // NO - worker runs tests\n```\n\n\u274C **WRONG** - Coordinator reserving files:\n```\nswarmmail_reserve(paths=[\"src/auth.ts\"]) // NO - worker reserves their own files\nswarm_spawn_subtask(bead_id=\"...\", files=[\"src/auth.ts\"])\n```\n\n\u2705 **CORRECT** - Coordinator spawning worker:\n```\n// Coordinator delegates ALL work\nswarm_spawn_subtask(\n bead_id=\"fix-auth-bug\",\n epic_id=\"epic-123\",\n subtask_title=\"Fix null check in login handler\",\n files=[\"src/auth/login.ts\", \"src/auth/login.test.ts\"],\n shared_context=\"Bug: login fails when username is null\"\n)\nTask(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n```\n\n### Why This Matters\n\n| Coordinator Work | Worker Work | Consequence of Mixing |\n|-----------------|-------------|----------------------|\n| Sonnet context ($$$) | Disposable context | Expensive context waste |\n| Long-lived state | Task-scoped state | Context exhaustion |\n| Orchestration concerns | Implementation concerns | Mixed concerns |\n| No checkpoints | Checkpoints enabled | No recovery |\n| No learning signals | Outcomes tracked | No improvement |\n\n## CRITICAL: NEVER Fetch Documentation Directly\n\n**\u26A0\uFE0F COORDINATORS DO NOT CALL RESEARCH TOOLS DIRECTLY**\n\nThe following tools are **FORBIDDEN** for coordinators to call:\n\n- `repo-crawl_file`, `repo-crawl_readme`, `repo-crawl_search`, `repo-crawl_structure`, `repo-crawl_tree`\n- `repo-autopsy_*` (all variants)\n- `webfetch`, `fetch_fetch`\n- `context7_resolve-library-id`, `context7_get-library-docs`\n- `pdf-brain_search`, `pdf-brain_read`\n\n**WHY?** These tools dump massive context that exhausts your expensive Sonnet context. Your job is orchestration, not research.\n\n**INSTEAD:** Use `swarm_spawn_researcher` (see Phase 1.5 below) to spawn a researcher worker who:\n- Fetches documentation in disposable context\n- Stores full details in hivemind\n- Returns a condensed summary for shared_context\n\n## Workflow\n\n### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)\n\n**Before decomposing, clarify the task with the user.**\n\nCheck for flags in the task:\n- `--fast` \u2192 Skip questions, use reasonable defaults\n- `--auto` \u2192 Zero interaction, heuristic decisions\n- `--confirm-only` \u2192 Show plan, get yes/no only\n\n**Default (no flags): Full Socratic Mode**\n\n1. **Analyze task for ambiguity:**\n - Scope unclear? (what's included/excluded)\n - Strategy unclear? (file-based vs feature-based)\n - Dependencies unclear? (what needs to exist first)\n - Success criteria unclear? (how do we know it's done)\n\n2. **If clarification needed, ask ONE question at a time:**\n ```\n The task \"<task>\" needs clarification before I can decompose it.\n\n **Question:** <specific question>\n\n Options:\n a) <option 1> - <tradeoff>\n b) <option 2> - <tradeoff>\n c) <option 3> - <tradeoff>\n\n I'd recommend (b) because <reason>. Which approach?\n ```\n\n3. **Wait for user response before proceeding**\n\n4. **Iterate if needed** (max 2-3 questions)\n\n**Rules:**\n- ONE question at a time - don't overwhelm\n- Offer concrete options - not open-ended\n- Lead with recommendation - save cognitive load\n- Wait for answer - don't assume\n\n### Phase 1: Initialize\n`swarmmail_init(project_path=\"{project_path}\", task_description=\"Swarm: {task}\")`\n\n### Phase 1.5: Research Phase (FOR COMPLEX TASKS)\n\n**\u26A0\uFE0F If the task requires understanding unfamiliar technologies, APIs, or libraries, spawn a researcher FIRST.**\n\n**DO NOT call documentation tools directly.** Instead:\n\n```\n// 1. Spawn researcher with explicit tech stack\nswarm_spawn_researcher(\n research_id=\"research-nextjs-cache-components\",\n epic_id=\"<epic-id>\",\n tech_stack=[\"Next.js 16 Cache Components\", \"React Server Components\"],\n project_path=\"{project_path}\"\n)\n\n// 2. Spawn researcher as Task subagent\nconst researchFindings = await Task(subagent_type=\"swarm-researcher\", prompt=\"<from above>\")\n\n// 3. Researcher returns condensed summary\n// Use this summary in shared_context for workers\n```\n\n**When to spawn a researcher:**\n- Task involves unfamiliar framework versions (e.g., Next.js 16 vs 14)\n- Need to compare installed vs latest library APIs\n- Working with experimental/preview features\n- Need architectural guidance from documentation\n\n**When NOT to spawn a researcher:**\n- Using well-known stable APIs (React hooks, Express middleware)\n- Task is purely refactoring existing code\n- You already have relevant findings from hivemind\n\n**Researcher output:**\n- Full findings stored in hivemind (searchable by future agents)\n- Condensed 3-5 bullet summary returned for shared_context\n\n### Phase 2: Knowledge Gathering (MANDATORY)\n\n**Before decomposing, query ALL knowledge sources:**\n\n```\nhivemind_find(query=\"<task keywords>\", limit=5) # Past learnings\nhivemind_find(query=\"<task description>\", limit=5, collection=\"sessions\") # Similar past tasks \nskills_list() # Available skills\n```\n\nSynthesize findings into shared_context for workers.\n\n### Phase 3: Decompose\n```\nswarm_select_strategy(task=\"<task>\")\nswarm_plan_prompt(task=\"<task>\", context=\"<synthesized knowledge>\")\nswarm_validate_decomposition(response=\"<CellTree JSON>\")\n```\n\n### Phase 4: Create Cells\n`hive_create_epic(epic_title=\"<task>\", subtasks=[...])`\n\n### Phase 5: DO NOT Reserve Files\n\n> **\u26A0\uFE0F Coordinator NEVER reserves files.** Workers reserve their own files.\n> If coordinator reserves, workers get blocked and swarm stalls.\n\n### Phase 6: Spawn Workers for ALL Subtasks (MANDATORY)\n\n> **\u26A0\uFE0F ALWAYS spawn workers, even for sequential tasks.**\n> - Parallel tasks: Spawn ALL in a single message\n> - Sequential tasks: Spawn one, wait for completion, spawn next\n\n**For parallel work:**\n```\n// Single message with multiple Task calls\nswarm_spawn_subtask(bead_id_1, epic_id, title_1, files_1, shared_context, project_path=\"{project_path}\")\nTask(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\nswarm_spawn_subtask(bead_id_2, epic_id, title_2, files_2, shared_context, project_path=\"{project_path}\")\nTask(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n```\n\n**For sequential work:**\n```\n// Spawn worker 1, wait for completion\nswarm_spawn_subtask(bead_id_1, ...)\nconst result1 = await Task(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n\n// THEN spawn worker 2 with context from worker 1\nswarm_spawn_subtask(bead_id_2, ..., shared_context=\"Worker 1 completed: \" + result1)\nconst result2 = await Task(subagent_type=\"swarm-worker\", prompt=\"<from above>\")\n```\n\n**NEVER do the work yourself.** Even if it seems faster, spawn a worker.\n\n**IMPORTANT:** Pass `project_path` to `swarm_spawn_subtask` so workers can call `swarmmail_init`.\n\n### Phase 7: MANDATORY Review Loop (NON-NEGOTIABLE)\n\n**\u26A0\uFE0F AFTER EVERY Task() RETURNS, YOU MUST:**\n\n1. **CHECK INBOX** - Worker may have sent messages\n `swarmmail_inbox()`\n `swarmmail_read_message(message_id=N)`\n\n2. **REVIEW WORK** - Generate review with diff\n `swarm_review(project_key, epic_id, task_id, files_touched)`\n\n3. **EVALUATE** - Does it meet epic goals?\n - Fulfills subtask requirements?\n - Serves overall epic goal?\n - Enables downstream tasks?\n - Type safety, no obvious bugs?\n\n4. **SEND FEEDBACK** - Approve or request changes\n `swarm_review_feedback(project_key, task_id, worker_id, status, issues)`\n \n **If approved:**\n - Close cell, spawn next worker\n \n **If needs_changes:**\n - `swarm_review_feedback` returns `retry_context` (NOT sends message - worker is dead)\n - Generate retry prompt: `swarm_spawn_retry(retry_context)`\n - Spawn NEW worker with Task() using retry prompt\n - Max 3 attempts before marking task blocked\n \n **If 3 failures:**\n - Mark task blocked, escalate to human\n\n5. **ONLY THEN** - Spawn next worker or complete\n\n**DO NOT skip this. DO NOT batch reviews. Review EACH worker IMMEDIATELY after return.**\n\n**Intervene if:**\n- Worker blocked >5min \u2192 unblock or reassign\n- File conflicts \u2192 mediate between workers\n- Scope creep \u2192 approve or reject expansion\n- Review fails 3x \u2192 mark task blocked, escalate to human\n\n### Phase 8: Complete\n```\n# After all workers complete and reviews pass:\nhive_sync() # Sync all cells to git\n# Coordinator does NOT call swarm_complete - workers do that\n```\n\n## Strategy Reference\n\n| Strategy | Best For | Keywords |\n| -------------- | ------------------------ | -------------------------------------- |\n| file-based | Refactoring, migrations | refactor, migrate, rename, update all |\n| feature-based | New features | add, implement, build, create, feature |\n| risk-based | Bug fixes, security | fix, bug, security, critical, urgent |\n| research-based | Investigation, discovery | research, investigate, explore, learn |\n\n## Flag Reference\n\n| Flag | Effect |\n|------|--------|\n| `--fast` | Skip Socratic questions, use defaults |\n| `--auto` | Zero interaction, heuristic decisions |\n| `--confirm-only` | Show plan, get yes/no only |\n\nBegin with Phase 0 (Socratic Planning) unless `--fast` or `--auto` flag is present.\n";
|
|
58
58
|
/**
|
|
59
59
|
* Researcher Agent Prompt Template
|
|
60
60
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,s6EAkET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,6BAA6B,mxDAyDlB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,mkFAgFK,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,mkUAiUnB,CAAC;AAEZ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,
|
|
1
|
+
{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"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"}
|