@jhustle44 / jcr-guide-pro
Code Commits Issues Pulls Cloud Agent CI/CD
main
copilot/add-firebase copilot/change-app-name-to-jcrguru copilot/create-zip-file copilot/create-zip-file-again copilot/merge-any-updates main master
md 200 lines 7.67 KB
Rendered Raw
1 ---
2 name: delegation
3 description: Delegate tasks to specialized subagents. Use subagent for synchronous task execution, startAsyncSubagent for background task execution, messageSubagent for async follow-ups, or messageSubagentAndGetResponse for sync follow-ups.
4 ---
5
6 # Delegation Skill
7
8 Delegate tasks to specialized subagents for autonomous execution.
9
10 ## When to Use
11
12 Use this skill when:
13
14 - You need to delegate tasks to run autonomously (especially when you have a session plan)
15 - You have multiple independent tasks that can run in parallel
16
17 ## When NOT to Use
18
19 - Simple tasks that you can complete directly
20 - Tasks that require immediate user interaction
21 - Read-only operations (use ripgrep or glob/read tools instead)
22 - Quick file edits (use edit tool directly)
23 - Analysis, planning, or debugging (e.g. performing code review)
24
25 ## Available Functions
26
27 ### subagent(task, fromPlan, relevantFiles, relevantSkills)
28
29 Launch a subagent to handle a task synchronously. Blocks until the subagent completes and returns the result.
30
31 **Parameters:**
32
33 - `task` (str, required): Task ID from session plan (e.g., "T003") OR brief task description
34 - `fromPlan` (bool, default False): If True, subagent reads full task context from .local/session_plan.md
35 - `relevantFiles` (list[str], optional): File paths the subagent should access
36 - `relevantSkills` (list[str], optional): Paths to all implementation skills you've read. Use the full path from the skills view. Pass every skill with integration details (auth, storage, payments) — not orchestration skills meant for you (design, delegation, react-vite).
37 - `specialization` (str, default "GENERAL"): "GENERAL" or "SMALL_TASK" for quick tasks
38
39 **Returns:** Dict with task results
40
41 ```json
42 {
43 "success": true,
44 "message": "Task summary",
45 "subagentAlias": "subagent_1",
46 "result": "Full task output..."
47 }
48 ```
49
50 **Usage Patterns:**
51
52 **1. From Plan (Recommended when you have a session plan):**
53
54 ```javascript
55 // Reference tasks by ID - subagent reads full context from .local/session_plan.md
56 const result = await subagent({ task: "T003", fromPlan: true });
57 console.log(result); // Always print the result
58 ```
59
60 **2. Direct Task (for ad-hoc tasks without a plan):**
61
62 ```javascript
63 const result = await subagent({
64 task: "Fix the auth bug in src/auth.ts",
65 relevantFiles: ["src/auth.ts"],
66 relevantSkills: [".local/skills/clerk-auth/SKILL.md", ".local/skills/database/SKILL.md"]
67 });
68 console.log(result); // Always print the result
69 ```
70
71 ### startAsyncSubagent(task, fromPlan, relevantFiles, relevantSkills)
72
73 Launch a subagent to handle a task asynchronously in the background. Returns immediately without waiting for completion. Use the `wait_for_background_tasks` tool to collect results later.
74
75 **Parameters:**
76
77 - `task` (str, required): Task ID from session plan (e.g., "T003") OR brief task description
78 - `fromPlan` (bool, default False): If True, subagent reads full task context from .local/session_plan.md
79 - `relevantFiles` (list[str], optional): File paths the subagent should access
80 - `relevantSkills` (list[str], optional): Paths to all implementation skills you've read. Use the full path from the skills view. Pass every skill with integration details (auth, storage, payments) — not orchestration skills meant for you (design, delegation, react-vite).
81 - `specialization` (str, default "GENERAL"): "GENERAL" or "SMALL_TASK" for quick tasks
82
83 **Returns:** Immediately with acknowledgment. Use the `wait_for_background_tasks` tool to collect results.
84
85 **Usage Patterns:**
86
87 **1. From Plan (Recommended when you have a session plan):**
88
89 ```javascript
90 // Reference tasks by ID - no print needed, result comes via wait_for_background_tasks
91 await startAsyncSubagent({ task: "T003", fromPlan: true });
92 ```
93
94 **2. Direct Task (for ad-hoc tasks without a plan):**
95
96 ```javascript
97 await startAsyncSubagent({
98 task: "Fix the auth bug in src/auth.ts",
99 relevantFiles: ["src/auth.ts"],
100 relevantSkills: [".local/skills/clerk-auth/SKILL.md", ".local/skills/database/SKILL.md"]
101 });
102 ```
103
104 **Parallel Execution:**
105
106 ```javascript
107 // Launch independent tasks simultaneously
108 console.log(await startAsyncSubagent({ task: "T002", fromPlan: true }));
109 console.log(await startAsyncSubagent({ task: "T003", fromPlan: true }));
110 console.log(await startAsyncSubagent({ task: "T004", fromPlan: true }));
111 ```
112
113 **Giving Subagents Access to Skills:**
114
115 ```javascript
116 // Pass skill paths from the skills view
117 await startAsyncSubagent({
118 task: "T005",
119 fromPlan: true,
120 relevantSkills: [".local/skills/database/SKILL.md", ".local/skills/clerk-auth/SKILL.md"]
121 });
122 ```
123
124 ### messageSubagent(subagentId, message)
125
126 Send a follow-up message to an existing subagent asynchronously. Returns immediately after the message is delivered. Use this when the subagent should continue in the background.
127
128 **Parameters:**
129
130 - `subagentId` (str, required): Alias returned when the subagent was started
131 - `message` (str, required): Follow-up instruction or clarification for the subagent
132
133 **Returns:** Acknowledgment that the message was sent. The subagent keeps running in the background.
134
135 **Example:**
136
137 ```javascript
138 // Async follow-up: continue background work
139 await messageSubagent({
140 subagentId: "subagent-happy-tiger",
141 message: "After the fix, add regression tests for the auth edge case."
142 });
143 ```
144
145 Use the `wait_for_background_tasks` tool to collect results later.
146
147 ### messageSubagentAndGetResponse(subagentId, message, timeoutSeconds)
148
149 Send a follow-up message to an existing subagent synchronously. Blocks until the subagent completes, times out, or is interrupted.
150
151 **Parameters:**
152
153 - `subagentId` (str, required): Alias returned when the subagent was started
154 - `message` (str, required): Follow-up instruction or clarification for the subagent
155 - `timeoutSeconds` (float, default 300.0): Max time to wait before returning a timeout status
156
157 **Returns:** Dict with `success`, `message`, `result`, and `exitReason`.
158
159 **Example:**
160
161 ```javascript
162 // Sync follow-up: wait for the answer now
163 const result = await messageSubagentAndGetResponse({
164 subagentId: "subagent-happy-tiger",
165 message: "Summarize root cause and include exact changed files.",
166 timeoutSeconds: 180.0
167 });
168 console.log(result.result);
169 ```
170
171 **When to choose which:**
172
173 - Use `messageSubagent` when you want fire-and-forget behavior
174 - Use `messageSubagentAndGetResponse` when you need the response immediately
175
176 ## Best Practices
177
178 1. **Use session plans**: For 2+ tasks, create a .local/session_plan.md and use `fromPlan=True`
179 2. **Launch in parallel**: Independent tasks can run simultaneously with `startAsyncSubagent`
180 3. **Use `subagent()` when you need the result immediately**: For tasks where you need to act on the output, use the synchronous `subagent()` and print the result.
181 4. **Use `startAsyncSubagent()` for independent tasks that can run in the background**: The tasks will be performed in parallel.
182 5. **Use `messageSubagent()` for async follow-ups**: Message running subagents without blocking, then use the `wait_for_background_tasks` tool to collect results
183 6. **Use `messageSubagentAndGetResponse()` for sync follow-ups**: Use this when you need the subagent's output before continuing
184 7. **Trust the results**: Subagent outputs should generally be trusted
185 8. **Pass all implementation skills via relevantSkills**: Include every implementation skill you've read — use the full path from the skills view for each one
186
187 ## Subagent Capabilities
188
189 The subagent has access to:
190
191 - File operations (read, write, edit, glob, grep)
192 - Bash commands
193 - LSP diagnostics
194 - Depending on specialization, additional tools like media generation or canvas tools may be available
195 - Skills (loaded via `relevantSkills` parameter)
196
197 The subagent does **NOT**:
198
199 - Run or restart workflows
200 - Preview/test the app (that's your job as main agent)