opencodekit 0.12.2 → 0.12.3
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/dist/index.js +1 -1
- package/dist/template/.opencode/AGENTS.md +40 -417
- package/dist/template/.opencode/agent/build.md +53 -0
- package/dist/template/.opencode/agent/planner.md +0 -1
- package/dist/template/.opencode/agent/rush.md +38 -0
- package/dist/template/.opencode/command/accessibility-check.md +1 -1
- package/dist/template/.opencode/command/commit.md +1 -1
- package/dist/template/.opencode/command/create.md +68 -441
- package/dist/template/.opencode/command/finish.md +82 -252
- package/dist/template/.opencode/command/fix-ci.md +52 -247
- package/dist/template/.opencode/command/fix-types.md +32 -292
- package/dist/template/.opencode/command/fix-ui.md +49 -234
- package/dist/template/.opencode/command/fix.md +57 -194
- package/dist/template/.opencode/command/handoff.md +66 -243
- package/dist/template/.opencode/command/implement.md +67 -231
- package/dist/template/.opencode/command/issue.md +42 -190
- package/dist/template/.opencode/command/plan.md +86 -442
- package/dist/template/.opencode/command/pr.md +3 -1
- package/dist/template/.opencode/command/research-and-implement.md +69 -370
- package/dist/template/.opencode/command/research.md +72 -197
- package/dist/template/.opencode/command/resume.md +70 -438
- package/dist/template/.opencode/command/status.md +11 -11
- package/dist/template/.opencode/command/triage.md +23 -18
- package/dist/template/.opencode/memory/project/commands.md +139 -7
- package/dist/template/.opencode/memory/project/gotchas.md +85 -0
- package/dist/template/.opencode/plugin/beads.ts +181 -16
- package/dist/template/.opencode/skill/beads/SKILL.md +15 -0
- package/dist/template/.opencode/skill/context-engineering/SKILL.md +94 -0
- package/dist/template/.opencode/skill/memory-system/SKILL.md +107 -0
- package/dist/template/.opencode/skill/session-management/SKILL.md +111 -0
- package/dist/template/.opencode/skill/tool-priority/SKILL.md +115 -0
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
|
|
|
750
750
|
// package.json
|
|
751
751
|
var package_default = {
|
|
752
752
|
name: "opencodekit",
|
|
753
|
-
version: "0.12.
|
|
753
|
+
version: "0.12.3",
|
|
754
754
|
description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
|
|
755
755
|
type: "module",
|
|
756
756
|
repository: {
|
|
@@ -1,64 +1,5 @@
|
|
|
1
1
|
# OpenCode Global Rules
|
|
2
2
|
|
|
3
|
-
## Constraint Awareness
|
|
4
|
-
|
|
5
|
-
OpenCode operates at **Stage 5-6** of AI adoption:
|
|
6
|
-
|
|
7
|
-
- **Stage 5** (Agentic Verification): Agents run tests and iterate autonomously
|
|
8
|
-
- **Stage 6** (Multi-Agent Orchestration): Parallel workstreams with coordination
|
|
9
|
-
|
|
10
|
-
**Current constraint**: Planning and specification quality. Implementation capacity is not the bottleneck—how well you specify requirements is.
|
|
11
|
-
|
|
12
|
-
### Autonomous Duration
|
|
13
|
-
|
|
14
|
-
The key metric: **How long can an agent work before losing the plot?**
|
|
15
|
-
|
|
16
|
-
Extend autonomous duration by:
|
|
17
|
-
|
|
18
|
-
- Binding tighter to intent (clear specs, constraints, invariants)
|
|
19
|
-
- Providing systematic context (AGENTS.md hierarchy, memory files)
|
|
20
|
-
- Verification loops (test → iterate → verify)
|
|
21
|
-
|
|
22
|
-
### Greenfield vs Legacy
|
|
23
|
-
|
|
24
|
-
- **Greenfield**: Simple context, fast prototypes, agents work well immediately
|
|
25
|
-
- **Legacy**: Complex context, hidden invariants, "that one place you must not touch"
|
|
26
|
-
|
|
27
|
-
Codebase complexity is a primary difficulty knob. Context is how you pay it down.
|
|
28
|
-
|
|
29
|
-
### Context Engineering Principles
|
|
30
|
-
|
|
31
|
-
**Three constraints on context:**
|
|
32
|
-
|
|
33
|
-
1. **Blind spots cause hallucinations** - If agent doesn't see specific context, it fills gaps with generic training priors. You only get the behavior you load.
|
|
34
|
-
2. **Everything influences everything** - Noise-to-signal ratio matters. Irrelevant files degrade ALL output quality.
|
|
35
|
-
3. **Window is finite** - Performance degrades BEFORE hitting hard token limits. Curate the smallest, highest-signal slice.
|
|
36
|
-
|
|
37
|
-
**Practical implications:**
|
|
38
|
-
|
|
39
|
-
- Prefer `lsp_lsp_document_symbols` over reading entire files
|
|
40
|
-
- Read specific line ranges, not whole documents
|
|
41
|
-
- Navigate AGENTS.md hierarchy: root → subsystem → details (progressive disclosure)
|
|
42
|
-
- Prune context aggressively; completed work doesn't need to stay loaded
|
|
43
|
-
|
|
44
|
-
### Intent Layer Principles
|
|
45
|
-
|
|
46
|
-
**What belongs in each AGENTS.md (Intent Node):**
|
|
47
|
-
|
|
48
|
-
- **Purpose & Scope** - What this area does. What it explicitly DOESN'T do.
|
|
49
|
-
- **Entry Points & Contracts** - Main APIs, invariants, "all X goes through Y"
|
|
50
|
-
- **Usage Patterns** - Canonical examples: "To add a rule, follow this pattern..."
|
|
51
|
-
- **Anti-patterns** - Negative examples: "Never call X directly; go through Y"
|
|
52
|
-
- **Dependencies & Downlinks** - What it connects to, pointers to child AGENTS.md
|
|
53
|
-
- **Pitfalls** - Things that repeatedly confused agents/humans
|
|
54
|
-
|
|
55
|
-
**Key mechanics:**
|
|
56
|
-
|
|
57
|
-
- **Hierarchical loading** - When a node loads, all ancestors load too (T-shaped view)
|
|
58
|
-
- **Compression, not bloat** - Good nodes compress code; if node is 10k tokens for 20k code, you're adding weight
|
|
59
|
-
- **Least Common Ancestor (LCA)** - Place shared knowledge at shallowest node covering all relevant paths
|
|
60
|
-
- **Downlinks for discovery** - Point to related context without loading everything upfront
|
|
61
|
-
|
|
62
3
|
## Priority Hierarchy
|
|
63
4
|
|
|
64
5
|
1. Security constraints (always first)
|
|
@@ -84,21 +25,10 @@ Codebase complexity is a primary difficulty knob. Context is how you pay it down
|
|
|
84
25
|
|
|
85
26
|
### Research Depth Levels
|
|
86
27
|
|
|
87
|
-
Specify depth when delegating to control tool call budget:
|
|
88
|
-
|
|
89
28
|
- **quick** (~5-10 calls) - Simple lookup, single answer, API syntax
|
|
90
29
|
- **medium** (~20-50 calls) - Moderate exploration, verify across files
|
|
91
30
|
- **thorough** (~100+ calls) - Comprehensive analysis, dependency mapping
|
|
92
31
|
|
|
93
|
-
**Examples**:
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
@explore (quick): Where is the auth middleware?
|
|
97
|
-
@explore (thorough): How does the entire auth system work?
|
|
98
|
-
@scout (quick): Syntax for React useEffect cleanup
|
|
99
|
-
@scout (thorough): How do production apps handle auth refresh tokens?
|
|
100
|
-
```
|
|
101
|
-
|
|
102
32
|
## Anti-Hallucination
|
|
103
33
|
|
|
104
34
|
- **Major features**: Check task exists (`bd show <id>`)
|
|
@@ -109,76 +39,29 @@ Specify depth when delegating to control tool call budget:
|
|
|
109
39
|
|
|
110
40
|
## Interaction Modes
|
|
111
41
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- "Help me think through this..."
|
|
118
|
-
- "Before we write any code..."
|
|
119
|
-
- "What are the tradeoffs of..."
|
|
120
|
-
- "I'm torn between X and Y..."
|
|
121
|
-
- "Play devil's advocate..."
|
|
122
|
-
|
|
123
|
-
**Response**: Ask clarifying questions, surface tradeoffs, explore alternatives. Don't jump to implementation.
|
|
124
|
-
|
|
125
|
-
### Execution Mode (Default)
|
|
126
|
-
|
|
127
|
-
Take action. Produce output. Iterate based on feedback.
|
|
42
|
+
| Mode | Triggers | Response |
|
|
43
|
+
| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
|
|
44
|
+
| **Sounding Board** | "Let's chat...", "Help me think...", "What are the tradeoffs..." | Ask questions, explore alternatives, don't implement |
|
|
45
|
+
| **Execution** (default) | Direct requests | Take action, iterate on feedback |
|
|
46
|
+
| **Uncertainty** | "I'm not sure...", "What am I missing?" | Question assumptions, surface edge cases |
|
|
128
47
|
|
|
129
48
|
**Key insight**: First output is ~70-80% right. Refinement is expected, not failure.
|
|
130
49
|
|
|
131
|
-
### Generic + Specific Pattern
|
|
132
|
-
|
|
133
|
-
For batch operations, combine generic goal with concrete example:
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
"Refactor all database queries to use parameterized statements.
|
|
137
|
-
|
|
138
|
-
For example, this: db.execute(f"SELECT * FROM users WHERE id = {user_id}")
|
|
139
|
-
Becomes: db.execute("SELECT * FROM users WHERE id = ?", [user_id])
|
|
140
|
-
|
|
141
|
-
Find and fix all similar patterns."
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
The generic sets intent; the example sets format. Agent generalizes from example.
|
|
145
|
-
|
|
146
|
-
### Inject Uncertainty
|
|
147
|
-
|
|
148
|
-
When facing design decisions, don't just accept user framing as gospel. Question assumptions:
|
|
149
|
-
|
|
150
|
-
- If user says "use SQLite for cache" → Ask about tradeoffs vs alternatives
|
|
151
|
-
- If user provides a list → Ask if categories make sense, what's missing
|
|
152
|
-
- If plan seems too simple → Surface edge cases they might not have considered
|
|
153
|
-
|
|
154
|
-
Trigger uncertainty mode with phrases like:
|
|
155
|
-
|
|
156
|
-
- "I think this should be... but I'm not sure that's right"
|
|
157
|
-
- "My plan is X, but I'm second-guessing whether..."
|
|
158
|
-
- "What am I missing here?"
|
|
159
|
-
|
|
160
50
|
## Universal Standards
|
|
161
51
|
|
|
162
52
|
### Communication
|
|
163
53
|
|
|
164
54
|
- Under 4 lines for typical responses
|
|
165
55
|
- Brief preamble before big tool calls
|
|
166
|
-
- No explanation summaries unless asked
|
|
167
56
|
- Use `file:line_number` format for code references
|
|
168
57
|
- No emojis unless explicitly requested
|
|
169
|
-
- Keep going until query resolved; don't ask to continue
|
|
170
58
|
|
|
171
59
|
### Execution
|
|
172
60
|
|
|
173
61
|
- Batch independent tool calls (parallel)
|
|
174
62
|
- Verify with tools; don't assume
|
|
175
63
|
- Obey project AGENTS.md files (nested takes precedence)
|
|
176
|
-
- Prioritize technical accuracy; disagree when necessary
|
|
177
|
-
|
|
178
|
-
### Planning
|
|
179
|
-
|
|
180
64
|
- TodoWrite BEFORE work; mark completed immediately
|
|
181
|
-
- Verify assumptions with tools
|
|
182
65
|
|
|
183
66
|
### Security
|
|
184
67
|
|
|
@@ -188,337 +71,77 @@ Trigger uncertainty mode with phrases like:
|
|
|
188
71
|
|
|
189
72
|
## Tool Priority
|
|
190
73
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
1. **LSP tools** - Semantic code intelligence (10 tools)
|
|
194
|
-
2. `ast-grep` - **Code search/replace** (functions, patterns, imports, hooks)
|
|
195
|
-
3. `grep` - **Text search** (logs, config, non-code files, simple strings)
|
|
196
|
-
4. `glob` - File discovery by name pattern
|
|
197
|
-
5. `read`, `edit`, `write` - File operations
|
|
198
|
-
|
|
199
|
-
### Choosing the Right Search Tool
|
|
200
|
-
|
|
201
|
-
Ask yourself: **"Am I looking for code structure or just text?"**
|
|
202
|
-
|
|
203
|
-
**Use `ast-grep` when you need to find:**
|
|
204
|
-
|
|
205
|
-
- How a function is called → `pattern="fetchUser($$$)"`
|
|
206
|
-
- Where a hook is used → `pattern="useState($$$)"`
|
|
207
|
-
- Import statements → `pattern="import { $$ } from '$MOD'"`
|
|
208
|
-
- Class definitions → `pattern="class $NAME { $$$ }"`
|
|
209
|
-
- Try-catch blocks → `pattern="try { $$$ } catch ($E) { $$$ }"`
|
|
210
|
-
|
|
211
|
-
**Use `grep` when you need to find:**
|
|
212
|
-
|
|
213
|
-
- Error messages in logs → `pattern="FATAL|ERROR"`
|
|
214
|
-
- Config values → `pattern="API_KEY"`
|
|
215
|
-
- TODO comments → `pattern="TODO|FIXME"`
|
|
216
|
-
- Text in markdown/docs → `pattern="deprecated"`
|
|
217
|
-
|
|
218
|
-
**Use LSP tools when you need to:**
|
|
219
|
-
|
|
220
|
-
- Understand what a symbol is → `lsp_lsp_hover`
|
|
221
|
-
- Jump to where something is defined → `lsp_lsp_goto_definition`
|
|
222
|
-
- Find all usages before refactoring → `lsp_lsp_find_references`
|
|
223
|
-
- Rename across the entire codebase → `lsp_lsp_rename`
|
|
74
|
+
Load `skill tool-priority` for full LSP, ast-grep, and grep reference.
|
|
224
75
|
|
|
225
|
-
**
|
|
76
|
+
**Quick reference**: LSP tools → ast-grep → grep → glob → read/edit/write
|
|
226
77
|
|
|
227
|
-
|
|
78
|
+
| Need | Tool |
|
|
79
|
+
| ------------------------------------------ | ----------------- |
|
|
80
|
+
| Code structure (functions, hooks, imports) | `ast-grep` |
|
|
81
|
+
| Text search (logs, config, TODOs) | `grep` |
|
|
82
|
+
| Type info, definitions, references | `lsp_lsp_*` tools |
|
|
83
|
+
| File discovery | `glob` |
|
|
228
84
|
|
|
229
|
-
|
|
85
|
+
**Rule**: Always `read` before `edit`.
|
|
230
86
|
|
|
231
|
-
|
|
87
|
+
## Context Engineering
|
|
232
88
|
|
|
233
|
-
|
|
234
|
-
- `lsp_lsp_goto_definition(filePath, line, character)` - Jump to where symbol is defined
|
|
235
|
-
- `lsp_lsp_find_references(filePath, line, character)` - Find all usages of a symbol
|
|
236
|
-
- `lsp_lsp_document_symbols(filePath)` - Get file outline (classes, functions, etc.)
|
|
237
|
-
- `lsp_lsp_workspace_symbols(query, filePath)` - Fuzzy search symbols across workspace
|
|
89
|
+
Load `skill context-engineering` for context management principles.
|
|
238
90
|
|
|
239
|
-
**
|
|
91
|
+
**Quick reference**:
|
|
240
92
|
|
|
241
|
-
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
- `lsp_lsp_rename(filePath, line, character, newName)` - Rename symbol across codebase
|
|
246
|
-
- `lsp_lsp_code_actions(filePath, startLine, startChar, endLine, endChar)` - Get available refactorings
|
|
247
|
-
- `lsp_lsp_code_action_apply(...)` - Apply a specific code action
|
|
248
|
-
- `lsp_lsp_organize_imports(filePath)` - Clean up and sort imports
|
|
249
|
-
|
|
250
|
-
**When to use each tool:**
|
|
251
|
-
|
|
252
|
-
**"What type is this variable?"** → Use `lsp_lsp_hover` to see type signature without reading the entire definition file.
|
|
253
|
-
|
|
254
|
-
**"Where is this function defined?"** → Use `lsp_lsp_goto_definition` to jump directly to source instead of grepping.
|
|
255
|
-
|
|
256
|
-
**"What uses this function?"** → Use `lsp_lsp_find_references` before changing anything to see all call sites.
|
|
257
|
-
|
|
258
|
-
**"What's in this file?"** → Use `lsp_lsp_document_symbols` for a quick outline without reading the entire file.
|
|
259
|
-
|
|
260
|
-
**"Where is UserService defined?"** → Use `lsp_lsp_workspace_symbols` to fuzzy search across all files.
|
|
261
|
-
|
|
262
|
-
**"Are there type errors?"** → Use `lsp_lsp_diagnostics` to check before running tests.
|
|
263
|
-
|
|
264
|
-
**"Rename this function safely"** → Use `lsp_lsp_rename` to update all references automatically.
|
|
265
|
-
|
|
266
|
-
**Caveat**: LSP tools modify files directly. Re-read files before further edits.
|
|
267
|
-
|
|
268
|
-
### AST-Grep Usage
|
|
269
|
-
|
|
270
|
-
Semantic code operations - smarter than regex:
|
|
271
|
-
|
|
272
|
-
```bash
|
|
273
|
-
# Search patterns
|
|
274
|
-
ast-grep pattern="console.log($$$)" # Find all console.log
|
|
275
|
-
ast-grep pattern="async function $NAME($$$) { $$$ }" # Find async functions
|
|
276
|
-
ast-grep pattern="const [$S, $SET] = useState($$$)" # Find React hooks
|
|
277
|
-
|
|
278
|
-
# Replace (dry run by default)
|
|
279
|
-
ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
|
|
280
|
-
ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
|
|
93
|
+
- Prefer `lsp_lsp_document_symbols` over reading entire files
|
|
94
|
+
- Navigate AGENTS.md hierarchy (progressive disclosure)
|
|
95
|
+
- Prune context aggressively; completed work doesn't need to stay loaded
|
|
284
96
|
|
|
285
97
|
## Research Tools
|
|
286
98
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
99
|
+
| Tool | Use When |
|
|
100
|
+
| -------------- | ---------------------------------------- |
|
|
101
|
+
| **context7** | Library docs (try first) |
|
|
102
|
+
| **websearch** | Docs not in Context7, recent releases |
|
|
103
|
+
| **codesearch** | Real implementation patterns from GitHub |
|
|
104
|
+
| **webfetch** | Specific URL user provided |
|
|
291
105
|
|
|
292
106
|
## Error Handling
|
|
293
107
|
|
|
294
108
|
- **Transient** (network, timeout): Retry 2x with backoff
|
|
295
109
|
- **Rate limit**: Stop, report to user
|
|
296
110
|
- **Logic error**: Change strategy, don't repeat
|
|
297
|
-
- **Blocked by hook/CI**: Analyze error
|
|
111
|
+
- **Blocked by hook/CI**: Analyze error, adjust approach, retry once
|
|
298
112
|
|
|
299
113
|
## Memory System
|
|
300
114
|
|
|
301
|
-
|
|
302
|
-
.opencode/memory/
|
|
303
|
-
_templates/ # Task templates (prd, observation, session-summary)
|
|
304
|
-
handoffs/ # Phase transitions
|
|
305
|
-
research/ # Research findings
|
|
306
|
-
observations/ # Structured observations
|
|
307
|
-
project/ # Persistent project knowledge
|
|
308
|
-
commands.md # Build, test, lint, deploy commands
|
|
309
|
-
conventions.md # Code patterns, commit style, PR process
|
|
310
|
-
gotchas.md # Footguns, edge cases, "don't forget this"
|
|
311
|
-
architecture.md # Key modules, directory structure
|
|
312
|
-
user.md # Identity, preferences, communication style
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
### Standard Memory Blocks
|
|
316
|
-
|
|
317
|
-
- **project/commands.md** - Build/test/lint commands. Update when discovering new command.
|
|
318
|
-
- **project/conventions.md** - Code patterns, style. Update when learning team pattern.
|
|
319
|
-
- **project/gotchas.md** - Footguns, warnings. Update when hitting unexpected behavior.
|
|
320
|
-
- **project/architecture.md** - Key modules, structure. Update when mapping new area.
|
|
321
|
-
- **user.md** - Preferences, workflow. Update when learning user preference.
|
|
322
|
-
|
|
323
|
-
### Explicit Memory Updates
|
|
324
|
-
|
|
325
|
-
Don't rely on implicit learning. Explicitly persist:
|
|
326
|
-
|
|
327
|
-
- Non-obvious project behavior → `project/gotchas.md`
|
|
328
|
-
- User preferences discovered → `user.md`
|
|
329
|
-
- New build/test commands → `project/commands.md`
|
|
330
|
-
- Code patterns to follow → `project/conventions.md`
|
|
331
|
-
|
|
332
|
-
### Memory Tools
|
|
333
|
-
|
|
334
|
-
- **memory-read** - Load previous context, templates
|
|
335
|
-
- **memory-update** - Save learnings, handoffs
|
|
336
|
-
- **memory-search** - Search across all memory files
|
|
337
|
-
- **observation** - Create structured observations
|
|
338
|
-
|
|
339
|
-
### Observations
|
|
340
|
-
|
|
341
|
-
Record important findings with structured metadata:
|
|
342
|
-
|
|
343
|
-
```
|
|
344
|
-
observation(
|
|
345
|
-
type: "decision", # decision, bugfix, feature, pattern, discovery, learning, warning
|
|
346
|
-
title: "Use JWT auth",
|
|
347
|
-
content: "Decided to use JWT because...",
|
|
348
|
-
concepts: "auth, security",
|
|
349
|
-
files: "src/auth.ts",
|
|
350
|
-
bead_id: "bd-abc123"
|
|
351
|
-
)
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
**When to create observations:**
|
|
355
|
-
|
|
356
|
-
- Major architectural decisions
|
|
357
|
-
- Bug root causes discovered
|
|
358
|
-
- Patterns worth reusing
|
|
359
|
-
- Gotchas and warnings for future
|
|
360
|
-
|
|
361
|
-
### Memory Search
|
|
362
|
-
|
|
363
|
-
Find past decisions, research, or handoffs:
|
|
364
|
-
|
|
365
|
-
```
|
|
366
|
-
memory-search(query: "authentication")
|
|
367
|
-
memory-search(query: "bugfix", type: "observations")
|
|
368
|
-
memory-search(query: "session", type: "handoffs")
|
|
369
|
-
```
|
|
115
|
+
Load `skill memory-system` for memory tools and update patterns.
|
|
370
116
|
|
|
371
|
-
|
|
117
|
+
**Quick reference**: `memory-read`, `memory-update`, `memory-search`, `observation`
|
|
372
118
|
|
|
373
119
|
## Session Management
|
|
374
120
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
### Context Thresholds
|
|
378
|
-
|
|
379
|
-
The environment monitors context usage and warns at these thresholds:
|
|
380
|
-
|
|
381
|
-
- **70%** - Consolidate work; consider pruning irrelevant tool outputs
|
|
382
|
-
- **85%** - Summarize findings and consider starting a new session
|
|
383
|
-
- **95%** - Critical: prune context immediately or restart session
|
|
121
|
+
Load `skill session-management` for session tools and context thresholds.
|
|
384
122
|
|
|
385
|
-
|
|
123
|
+
**Philosophy**: Short sessions (<150k tokens) beat long bloated ones.
|
|
386
124
|
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
```
|
|
390
|
-
list_sessions(limit=10, project="current") # Current project
|
|
391
|
-
list_sessions(since="today") # Today's sessions
|
|
392
|
-
list_sessions(project="all", since="yesterday") # Cross-project
|
|
393
|
-
```
|
|
394
|
-
|
|
395
|
-
**`read_session`** - Pull context from previous session
|
|
396
|
-
|
|
397
|
-
```
|
|
398
|
-
read_session("last") # Most recent
|
|
399
|
-
read_session("2 ago", project="current") # 2nd most recent
|
|
400
|
-
read_session("today") # Today's first session
|
|
401
|
-
read_session("ses_abc123", focus="file changes") # Specific aspect
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
**`search_session`** - Full-text search across sessions
|
|
405
|
-
|
|
406
|
-
```
|
|
407
|
-
search_session(query="auth bug") # Search all sessions
|
|
408
|
-
search_session(query="OAuth", session_id="ses_abc") # Search specific session
|
|
409
|
-
search_session(query="error", limit=10) # Limit results
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
Use to find past discussions, decisions, or work on a topic before starting new work.
|
|
413
|
-
|
|
414
|
-
**`summarize_session`** - Generate AI summary of a session
|
|
415
|
-
|
|
416
|
-
```
|
|
417
|
-
summarize_session("ses_abc123") # Trigger AI summarization
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
Use before `read_session` to get a quick overview of what happened in a past session without loading full context.
|
|
421
|
-
|
|
422
|
-
### When to Start New Session
|
|
423
|
-
|
|
424
|
-
- Completing distinct task from `bd ready`
|
|
425
|
-
- Token usage approaching 150k
|
|
426
|
-
- Switching phases (implementation → review → testing)
|
|
427
|
-
- After handoff (`/handoff <bead-id>`)
|
|
428
|
-
|
|
429
|
-
### Session Workflow Pattern
|
|
430
|
-
|
|
431
|
-
```
|
|
432
|
-
Session 1: Implement feature X (80k tokens)
|
|
433
|
-
↓ close, update memory
|
|
434
|
-
Session 2: list_sessions() → read_session("last") → Refactor (60k tokens)
|
|
435
|
-
↓
|
|
436
|
-
Session 3: read_session("previous") → Add tests (90k tokens)
|
|
437
|
-
↓
|
|
438
|
-
Session 4: read_session refs → Final review (100k tokens)
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
**Result**: 4 fresh contexts vs 1 degraded 330k context. Better performance, lower cost.
|
|
442
|
-
|
|
443
|
-
### Context Transfer
|
|
444
|
-
|
|
445
|
-
Use all three:
|
|
446
|
-
|
|
447
|
-
1. `read_session("last")` - Previous session work
|
|
448
|
-
2. Git state - `git diff`, `git log` - Code changes
|
|
449
|
-
3. Memory files - `.opencode/memory/*` - Persistent context
|
|
450
|
-
4. Beads - `bd show <id>` - Task specs
|
|
451
|
-
|
|
452
|
-
**Don't**: Carry everything forward. Extract what's needed, discard the rest.
|
|
125
|
+
**Quick reference**: `list_sessions`, `read_session`, `search_session`, `summarize_session`
|
|
453
126
|
|
|
454
127
|
## Beads Usage
|
|
455
128
|
|
|
456
|
-
**
|
|
457
|
-
**
|
|
458
|
-
**Weekly**: `bd_cleanup(days=7)` then `bd_sync()`
|
|
459
|
-
|
|
460
|
-
**Philosophy**: Beads is execution, not planning. Plan elsewhere, track in Beads.
|
|
129
|
+
**Leader agents only**: Only `build` and `rush` use beads tools.
|
|
130
|
+
**Subagents** (explore, scout, planner, review, vision): Do NOT touch beads.
|
|
461
131
|
|
|
462
|
-
|
|
132
|
+
Load `skill beads` for full workflow, tool reference, and patterns.
|
|
463
133
|
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
### When to Use
|
|
467
|
-
|
|
468
|
-
- **Multi-agent work**: Multiple agents on same codebase
|
|
469
|
-
- **File conflict prevention**: Reserve files before editing
|
|
470
|
-
- **Cross-workspace coordination**: FE/BE/Mobile agents communicating
|
|
471
|
-
|
|
472
|
-
### Core Workflow
|
|
134
|
+
**Quick reference**:
|
|
473
135
|
|
|
474
136
|
```
|
|
475
137
|
bd_init() → bd_claim() → bd_reserve(paths) → [work] → bd_done(id, msg) → RESTART
|
|
476
138
|
```
|
|
477
139
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
**Lifecycle Tools**
|
|
481
|
-
|
|
482
|
-
Start every session by calling `bd_init` with your team name and role. This registers you in the workspace and enables role-based task filtering. For example, `bd_init({ team: "project", role: "fe" })` joins as a frontend agent.
|
|
483
|
-
|
|
484
|
-
Call `bd_claim` to get the next ready task assigned to your role. It auto-filters based on task tags matching your role and marks the task as in_progress.
|
|
485
|
-
|
|
486
|
-
When work is complete, call `bd_done` with the task ID and completion message. This closes the task, releases all file reservations, and syncs with git. After `bd_done`, restart your session for fresh context.
|
|
487
|
-
|
|
488
|
-
**Task Management Tools**
|
|
489
|
-
|
|
490
|
-
Use `bd_add` to create new tasks for discovered work. Specify title, optional description, and priority (0=critical through 4=backlog). Use `bd_assign` to assign tasks to specific roles like fe, be, mobile, devops, or qa.
|
|
491
|
-
|
|
492
|
-
Call `bd_ls` to list tasks filtered by status: open, closed, in_progress, ready, or all. Use `bd_show` with a task ID to get full details including description, notes, and history.
|
|
493
|
-
|
|
494
|
-
**File Reservation Tools**
|
|
495
|
-
|
|
496
|
-
Before editing any file, call `bd_reserve` with the file paths you need. This creates locks that prevent other agents from modifying the same files. Locks expire after 600 seconds by default.
|
|
497
|
-
|
|
498
|
-
Call `bd_release` to unlock files early, or let `bd_done` release them automatically. Use `bd_reservations` to see all active locks across the workspace before editing.
|
|
499
|
-
|
|
500
|
-
**Messaging Tools**
|
|
501
|
-
|
|
502
|
-
Send messages with `bd_msg` using a subject and optional body. Set `to: "all"` for broadcast messages visible to all agents. Check incoming messages with `bd_inbox`, optionally filtering to unread only.
|
|
503
|
-
|
|
504
|
-
**Status and Maintenance Tools**
|
|
505
|
-
|
|
506
|
-
Call `bd_status` to get workspace overview including ready task count, in-progress tasks, and active locks. Use `bd_sync` to manually sync with git.
|
|
507
|
-
|
|
508
|
-
Run `bd_cleanup` periodically to remove old closed issues. Use `bd_doctor` to check and repair database health.
|
|
509
|
-
|
|
510
|
-
**Analysis Tools**
|
|
511
|
-
|
|
512
|
-
Use `bd_blocked` to see tasks with unresolved dependencies. Use `bd_dep` with action "tree" to visualize dependency chains.
|
|
513
|
-
|
|
514
|
-
Use `bd_diff` to compare issue changes between git revisions.
|
|
515
|
-
|
|
516
|
-
### Rules
|
|
140
|
+
**Rules**:
|
|
517
141
|
|
|
518
|
-
-
|
|
519
|
-
-
|
|
520
|
-
-
|
|
521
|
-
- **Use `bd_msg(to="all")`** for team-wide announcements
|
|
142
|
+
- Always `bd_init()` first in any session using beads tools
|
|
143
|
+
- Reserve before edit to prevent conflicts
|
|
144
|
+
- One task per session - restart after `bd_done()`
|
|
522
145
|
|
|
523
146
|
## Core Constraints
|
|
524
147
|
|
|
@@ -110,3 +110,56 @@ After delegation completes, VERIFY:
|
|
|
110
110
|
- Evidence provided (not just "done")?
|
|
111
111
|
|
|
112
112
|
Vague prompts = wasted tokens. Be exhaustive.
|
|
113
|
+
|
|
114
|
+
## Beads Task Ownership (Leader Pattern)
|
|
115
|
+
|
|
116
|
+
Build is a **leader agent** - owns the session and coordinates with beads.
|
|
117
|
+
|
|
118
|
+
### Session Workflow
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
bd_init({ role: "build" }) # Join workspace
|
|
122
|
+
bd_claim() # Get next ready task
|
|
123
|
+
bd_reserve([files]) # Lock files before editing
|
|
124
|
+
[... do work, delegate to subagents ...]
|
|
125
|
+
bd_done(id, "reason") # Complete and release locks
|
|
126
|
+
→ RESTART SESSION
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Task Decomposition
|
|
130
|
+
|
|
131
|
+
When claiming an **epic**:
|
|
132
|
+
|
|
133
|
+
1. Delegate to @planner for breakdown
|
|
134
|
+
2. Create sub-tasks in beads with appropriate tags:
|
|
135
|
+
```
|
|
136
|
+
bd_add({ title: "Research X", tags: ["scout"], parent: epicId })
|
|
137
|
+
bd_add({ title: "Design Y", tags: ["planner"], parent: epicId })
|
|
138
|
+
bd_add({ title: "Implement Z", tags: ["build"], parent: epicId })
|
|
139
|
+
```
|
|
140
|
+
3. Execute sub-tasks yourself OR delegate via Task tool
|
|
141
|
+
4. Close epic when all sub-tasks done
|
|
142
|
+
|
|
143
|
+
### Subagent Coordination
|
|
144
|
+
|
|
145
|
+
**Subagents (explore, scout, planner, review, vision) do NOT touch beads.**
|
|
146
|
+
|
|
147
|
+
They are stateless workers. Delegate via Task tool:
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
Task({
|
|
151
|
+
subagent_type: "explore",
|
|
152
|
+
prompt: "Find all auth middleware in src/",
|
|
153
|
+
description: "Find auth middleware"
|
|
154
|
+
})
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Results return to you (leader). You update beads accordingly.
|
|
158
|
+
|
|
159
|
+
### File Locking
|
|
160
|
+
|
|
161
|
+
Only leader agents use `bd_reserve`:
|
|
162
|
+
|
|
163
|
+
- Reserve before editing shared files
|
|
164
|
+
- Auto-released on `bd_done()`
|
|
165
|
+
- Check `bd_reservations()` if conflicts
|
|
@@ -84,3 +84,41 @@ Delegate to specialized agents:
|
|
|
84
84
|
- Code review, debugging → @review
|
|
85
85
|
- Architecture, 3+ phases → @planner
|
|
86
86
|
- UI/UX, mockups, visuals → @vision
|
|
87
|
+
|
|
88
|
+
## Beads Task Ownership (Leader Pattern)
|
|
89
|
+
|
|
90
|
+
Rush is a **leader agent** - can own sessions and coordinate with beads.
|
|
91
|
+
|
|
92
|
+
### When to Use Beads
|
|
93
|
+
|
|
94
|
+
Rush should use beads when:
|
|
95
|
+
|
|
96
|
+
- Task is tracked in beads (`bd show <id>` returns valid task)
|
|
97
|
+
- Need to lock files for editing
|
|
98
|
+
- Multi-step work that may span context limits
|
|
99
|
+
|
|
100
|
+
Rush should **skip beads** when:
|
|
101
|
+
|
|
102
|
+
- Quick one-off task (no tracking needed)
|
|
103
|
+
- User didn't mention a bead/task ID
|
|
104
|
+
- Simple command execution
|
|
105
|
+
|
|
106
|
+
### Minimal Workflow
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
bd_init({ role: "rush" }) # Join workspace
|
|
110
|
+
bd_claim() # Get next ready task (or skip if user gave direct task)
|
|
111
|
+
[... quick work ...]
|
|
112
|
+
bd_done(id, "reason") # Complete
|
|
113
|
+
→ RESTART SESSION
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Delegation Over Decomposition
|
|
117
|
+
|
|
118
|
+
Unlike @build, Rush **delegates complexity** rather than decomposing:
|
|
119
|
+
|
|
120
|
+
- Complex task? → Delegate to @build
|
|
121
|
+
- Research needed? → Delegate to @scout/@explore
|
|
122
|
+
- Architecture decision? → Delegate to @planner
|
|
123
|
+
|
|
124
|
+
Rush stays fast by avoiding multi-step coordination.
|