opencodekit 0.4.0 → 0.5.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/dist/index.js +10 -1
- package/dist/template/.opencode/AGENTS.md +78 -55
- package/dist/template/.opencode/agent/build.md +20 -0
- package/dist/template/.opencode/agent/rush.md +27 -15
- package/dist/template/.opencode/command/init.md +176 -0
- package/dist/template/.opencode/memory/project/README.md +47 -16
- package/dist/template/.opencode/memory/project/architecture.md +26 -0
- package/dist/template/.opencode/memory/project/commands.md +26 -0
- package/dist/template/.opencode/memory/project/conventions.md +26 -0
- package/dist/template/.opencode/memory/project/gotchas.md +26 -0
- package/dist/template/.opencode/memory/user.example.md +21 -0
- package/dist/template/.opencode/memory/user.md +21 -0
- package/dist/template/.opencode/opencode.json +13 -8
- package/dist/template/.opencode/package.json +1 -2
- package/package.json +1 -1
- package/dist/template/.opencode/command/setup-project.md +0 -152
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.
|
|
753
|
+
version: "0.5.0",
|
|
754
754
|
description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
|
|
755
755
|
type: "module",
|
|
756
756
|
repository: {
|
|
@@ -2605,6 +2605,15 @@ async function editMCP(configPath) {
|
|
|
2605
2605
|
await addMCPServer(configPath, config);
|
|
2606
2606
|
return;
|
|
2607
2607
|
}
|
|
2608
|
+
console.log();
|
|
2609
|
+
console.log(import_picocolors7.default.bold(" MCP Servers"));
|
|
2610
|
+
for (const [name, server] of Object.entries(config.mcp)) {
|
|
2611
|
+
const status = server.enabled === false ? import_picocolors7.default.red("off") : import_picocolors7.default.green("on");
|
|
2612
|
+
const type = server.type === "remote" ? import_picocolors7.default.dim("remote") : import_picocolors7.default.dim("local");
|
|
2613
|
+
const endpoint = server.type === "remote" ? import_picocolors7.default.dim(` → ${server.url}`) : import_picocolors7.default.dim(` → ${(server.command || []).join(" ")}`);
|
|
2614
|
+
console.log(` ${status} ${name} ${type}${endpoint}`);
|
|
2615
|
+
}
|
|
2616
|
+
console.log();
|
|
2608
2617
|
const action = await ie({
|
|
2609
2618
|
message: "MCP Servers",
|
|
2610
2619
|
options: [
|
|
@@ -15,22 +15,38 @@
|
|
|
15
15
|
|
|
16
16
|
**Check before any tool call. Delegate if task involves search or research.**
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
| Architecture | @planner | design, architect, plan, structure, phases |
|
|
24
|
-
| UI/UX design | @vision | mockup, UI review, accessibility, aesthetics, visual |
|
|
18
|
+
- **@explore** - Code search: find, where is, search, how does X work, locate
|
|
19
|
+
- **@scout** - External research: research, compare, docs for, API for, best practices
|
|
20
|
+
- **@review** - Code review/debug: review, audit, debug, why broken, root cause
|
|
21
|
+
- **@planner** - Architecture: design, architect, plan, structure, phases
|
|
22
|
+
- **@vision** - UI/UX design: mockup, UI review, accessibility, aesthetics, visual
|
|
25
23
|
|
|
26
24
|
**Execute directly**: Single-file edits, explicit commands, answering from loaded context.
|
|
27
25
|
|
|
26
|
+
### Research Depth Levels
|
|
27
|
+
|
|
28
|
+
Specify depth when delegating to control tool call budget:
|
|
29
|
+
|
|
30
|
+
- **quick** (~5-10 calls) - Simple lookup, single answer, API syntax
|
|
31
|
+
- **medium** (~20-50 calls) - Moderate exploration, verify across files
|
|
32
|
+
- **thorough** (~100+ calls) - Comprehensive analysis, dependency mapping
|
|
33
|
+
|
|
34
|
+
**Examples**:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
@explore (quick): Where is the auth middleware?
|
|
38
|
+
@explore (thorough): How does the entire auth system work?
|
|
39
|
+
@scout (quick): Syntax for React useEffect cleanup
|
|
40
|
+
@scout (thorough): How do production apps handle auth refresh tokens?
|
|
41
|
+
```
|
|
42
|
+
|
|
28
43
|
## Anti-Hallucination
|
|
29
44
|
|
|
30
45
|
- **Major features**: Check task exists (`bd show <id>`)
|
|
31
46
|
- **Bug fixes/edits**: Proceed directly; document clearly
|
|
32
47
|
- **Before commit**: Close task with reason (`bd close <id> --reason "..."`)
|
|
33
48
|
- **Find work**: Use `bd ready` for unblocked tasks
|
|
49
|
+
- **URLs**: Never generate or guess URLs. Only use URLs from user input, tool results, or verified documentation.
|
|
34
50
|
|
|
35
51
|
## Universal Standards
|
|
36
52
|
|
|
@@ -65,14 +81,10 @@
|
|
|
65
81
|
|
|
66
82
|
**GKG tools → AST tools → Built-in tools**
|
|
67
83
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| 1 | `gkg_repo_map` | API-level overview |
|
|
73
|
-
| 2 | `ast-grep` | Semantic code search/replace (AST) |
|
|
74
|
-
| 3 | `grep`, `glob` | Pattern matching, file discovery |
|
|
75
|
-
| 3 | `read`, `edit`, `write` | File operations |
|
|
84
|
+
1. `gkg_search_codebase_definitions`, `gkg_get_references`, `gkg_repo_map` - Find symbols, usages, API overview
|
|
85
|
+
2. `ast-grep` - Semantic code search/replace (AST-based)
|
|
86
|
+
3. `grep`, `glob` - Pattern matching, file discovery
|
|
87
|
+
4. `read`, `edit`, `write` - File operations
|
|
76
88
|
|
|
77
89
|
**Rule**: Always `read` before `edit` to verify content.
|
|
78
90
|
|
|
@@ -95,18 +107,17 @@ ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
|
|
|
95
107
|
|
|
96
108
|
## Research Tools
|
|
97
109
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
| `codesearch` | Real implementation patterns from GitHub | Public repo examples |
|
|
103
|
-
| `webfetch` | Specific URL user provided | Direct URL fetch |
|
|
110
|
+
- **context7** - Library docs (try first). Fast, external APIs.
|
|
111
|
+
- **websearch** - Docs not in Context7, recent releases, troubleshooting.
|
|
112
|
+
- **codesearch** - Real implementation patterns from GitHub.
|
|
113
|
+
- **webfetch** - Specific URL user provided.
|
|
104
114
|
|
|
105
115
|
## Error Handling
|
|
106
116
|
|
|
107
117
|
- **Transient** (network, timeout): Retry 2x with backoff
|
|
108
118
|
- **Rate limit**: Stop, report to user
|
|
109
119
|
- **Logic error**: Change strategy, don't repeat
|
|
120
|
+
- **Blocked by hook/CI**: Analyze error message, adjust approach, retry once. If still blocked, ask user to check hooks/config.
|
|
110
121
|
|
|
111
122
|
## Memory System
|
|
112
123
|
|
|
@@ -116,16 +127,37 @@ ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
|
|
|
116
127
|
handoffs/ # Phase transitions
|
|
117
128
|
research/ # Research findings
|
|
118
129
|
observations/ # Structured observations
|
|
130
|
+
project/ # Persistent project knowledge
|
|
131
|
+
commands.md # Build, test, lint, deploy commands
|
|
132
|
+
conventions.md # Code patterns, commit style, PR process
|
|
133
|
+
gotchas.md # Footguns, edge cases, "don't forget this"
|
|
134
|
+
architecture.md # Key modules, directory structure
|
|
135
|
+
user.md # Identity, preferences, communication style
|
|
119
136
|
```
|
|
120
137
|
|
|
138
|
+
### Standard Memory Blocks
|
|
139
|
+
|
|
140
|
+
- **project/commands.md** - Build/test/lint commands. Update when discovering new command.
|
|
141
|
+
- **project/conventions.md** - Code patterns, style. Update when learning team pattern.
|
|
142
|
+
- **project/gotchas.md** - Footguns, warnings. Update when hitting unexpected behavior.
|
|
143
|
+
- **project/architecture.md** - Key modules, structure. Update when mapping new area.
|
|
144
|
+
- **user.md** - Preferences, workflow. Update when learning user preference.
|
|
145
|
+
|
|
146
|
+
### Explicit Memory Updates
|
|
147
|
+
|
|
148
|
+
Don't rely on implicit learning. Explicitly persist:
|
|
149
|
+
|
|
150
|
+
- Non-obvious project behavior → `project/gotchas.md`
|
|
151
|
+
- User preferences discovered → `user.md`
|
|
152
|
+
- New build/test commands → `project/commands.md`
|
|
153
|
+
- Code patterns to follow → `project/conventions.md`
|
|
154
|
+
|
|
121
155
|
### Memory Tools
|
|
122
156
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| `memory-search` | Search across all memory files |
|
|
128
|
-
| `observation` | Create structured observations |
|
|
157
|
+
- **memory-read** - Load previous context, templates
|
|
158
|
+
- **memory-update** - Save learnings, handoffs
|
|
159
|
+
- **memory-search** - Search across all memory files
|
|
160
|
+
- **observation** - Create structured observations
|
|
129
161
|
|
|
130
162
|
### Observations
|
|
131
163
|
|
|
@@ -165,11 +197,9 @@ memory-search(query: "session", type: "handoffs")
|
|
|
165
197
|
|
|
166
198
|
Plugins run automatically in the background:
|
|
167
199
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
| **compactor** | Warns at 70%, 85%, 95% context usage - prevents rushed work |
|
|
172
|
-
| **truncator** | Dynamic output truncation based on context remaining |
|
|
200
|
+
- **enforcer** - OS notification when session idles with incomplete TODOs
|
|
201
|
+
- **compactor** - Warns at 70%, 85%, 95% context usage - prevents rushed work
|
|
202
|
+
- **truncator** - Dynamic output truncation based on context remaining
|
|
173
203
|
|
|
174
204
|
**Compactor thresholds**:
|
|
175
205
|
|
|
@@ -244,35 +274,28 @@ Use all three:
|
|
|
244
274
|
|
|
245
275
|
Use `find_skills` → `use_skill` when:
|
|
246
276
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
| UI/UX with images | `ui-ux-research` |
|
|
257
|
-
| Large codebase research | `gemini-large-context` |
|
|
277
|
+
- Creating something new → `brainstorming`
|
|
278
|
+
- Bug or unexpected behavior → `systematic-debugging`
|
|
279
|
+
- Implementing feature → `test-driven-development`
|
|
280
|
+
- Before commit/done → `verification-before-completion`
|
|
281
|
+
- Complex multi-step work → `writing-plans` → `executing-plans`
|
|
282
|
+
- Finished implementation → `requesting-code-review`
|
|
283
|
+
- Building UI → `frontend-aesthetics`
|
|
284
|
+
- UI/UX with images → `ui-ux-research`
|
|
285
|
+
- Large codebase research → `gemini-large-context`
|
|
258
286
|
|
|
259
287
|
Skip for simple questions, quick edits, or conversations.
|
|
260
288
|
|
|
261
|
-
|
|
289
|
+
### Progressive Skill Loading
|
|
262
290
|
|
|
263
|
-
|
|
291
|
+
Skills consume context. Manage them actively:
|
|
264
292
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
# Image analysis (interactive)
|
|
270
|
-
gemini
|
|
271
|
-
@mockup.png Analyze this UI design
|
|
272
|
-
```
|
|
293
|
+
1. **Load on-demand**: Only load skills when starting relevant work
|
|
294
|
+
2. **Read linked files lazily**: Don't load all skill references immediately—read only when needed
|
|
295
|
+
3. **Unload after completion**: When task completes, skill context is no longer needed
|
|
296
|
+
4. **One skill at a time**: Avoid loading multiple skills unless task requires it
|
|
273
297
|
|
|
274
|
-
**
|
|
275
|
-
**Fast**: `gemini-2.5-flash` with `-m gemini-2.5-flash`
|
|
298
|
+
**IMPORTANT**: Always unload irrelevant skills to free context space. Loaded skills that aren't actively needed are context debt.
|
|
276
299
|
|
|
277
300
|
## Core Constraints
|
|
278
301
|
|
|
@@ -78,3 +78,23 @@ Before claiming completion:
|
|
|
78
78
|
- Code review/debugging → @review
|
|
79
79
|
- Architecture planning → @planner
|
|
80
80
|
- UI/UX analysis, mockups → @vision
|
|
81
|
+
|
|
82
|
+
### Delegation Prompt Structure
|
|
83
|
+
|
|
84
|
+
When delegating, include ALL 7 sections:
|
|
85
|
+
|
|
86
|
+
1. **TASK**: Atomic, specific goal (one action per delegation)
|
|
87
|
+
2. **EXPECTED OUTCOME**: Concrete deliverables with success criteria
|
|
88
|
+
3. **REQUIRED SKILLS**: Which skill to invoke (if any)
|
|
89
|
+
4. **REQUIRED TOOLS**: Explicit tool whitelist (prevents sprawl)
|
|
90
|
+
5. **MUST DO**: Exhaustive requirements - leave NOTHING implicit
|
|
91
|
+
6. **MUST NOT DO**: Forbidden actions - anticipate rogue behavior
|
|
92
|
+
7. **CONTEXT**: File paths, existing patterns, constraints
|
|
93
|
+
|
|
94
|
+
After delegation completes, VERIFY:
|
|
95
|
+
|
|
96
|
+
- Did result match expected outcome?
|
|
97
|
+
- Were MUST DO / MUST NOT DO followed?
|
|
98
|
+
- Evidence provided (not just "done")?
|
|
99
|
+
|
|
100
|
+
Vague prompts = wasted tokens. Be exhaustive.
|
|
@@ -47,13 +47,9 @@ Fast execute-first agent. Speed over depth. Delegate anything complex.
|
|
|
47
47
|
|
|
48
48
|
**GKG tools FIRST, then AST-Grep, then built-in tools.**
|
|
49
49
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
| `gkg_get_references` | Find all usages |
|
|
54
|
-
| `ast-grep` | Semantic code search/replace |
|
|
55
|
-
| `grep` | Text strings, config values |
|
|
56
|
-
| `glob` | Find files by pattern |
|
|
50
|
+
1. `gkg_search_codebase_definitions`, `gkg_get_references` - Find symbols, usages
|
|
51
|
+
2. `ast-grep` - Semantic code search/replace
|
|
52
|
+
3. `grep`, `glob` - Text search, file patterns
|
|
57
53
|
|
|
58
54
|
## Pre-Action Checks
|
|
59
55
|
|
|
@@ -69,15 +65,31 @@ Before mutations (edit, write, delete):
|
|
|
69
65
|
- **Rate limits**: Stop, report to user
|
|
70
66
|
- **Logic errors**: Change strategy, don't repeat
|
|
71
67
|
|
|
72
|
-
## Delegation
|
|
68
|
+
## Delegation
|
|
73
69
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
70
|
+
- Codebase search → @explore
|
|
71
|
+
- Library docs, patterns → @scout
|
|
72
|
+
- Code review, debugging → @review
|
|
73
|
+
- Architecture, 3+ phases → @planner
|
|
74
|
+
- UI/UX, mockups, visuals → @vision
|
|
75
|
+
|
|
76
|
+
### Delegation Prompt Structure
|
|
77
|
+
|
|
78
|
+
When delegating, include ALL 7 sections:
|
|
79
|
+
|
|
80
|
+
1. **TASK**: Atomic, specific goal (one action per delegation)
|
|
81
|
+
2. **EXPECTED OUTCOME**: Concrete deliverables with success criteria
|
|
82
|
+
3. **REQUIRED SKILLS**: Which skill to invoke (if any)
|
|
83
|
+
4. **REQUIRED TOOLS**: Explicit tool whitelist (prevents sprawl)
|
|
84
|
+
5. **MUST DO**: Exhaustive requirements - leave NOTHING implicit
|
|
85
|
+
6. **MUST NOT DO**: Forbidden actions - anticipate rogue behavior
|
|
86
|
+
7. **CONTEXT**: File paths, existing patterns, constraints
|
|
87
|
+
|
|
88
|
+
After delegation completes, VERIFY:
|
|
89
|
+
|
|
90
|
+
- Did result match expected outcome?
|
|
91
|
+
- Were MUST DO / MUST NOT DO followed?
|
|
92
|
+
- Evidence provided (not just "done")?
|
|
81
93
|
|
|
82
94
|
## Execute Directly
|
|
83
95
|
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Initialize project for AI-assisted development (creates AGENTS.md + memory files)
|
|
3
|
+
argument-hint: "[--deep] [--skip-questions]"
|
|
4
|
+
agent: planner
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Init: $ARGUMENTS
|
|
8
|
+
|
|
9
|
+
One command to onboard a project. Creates project-root AGENTS.md and populates memory files.
|
|
10
|
+
|
|
11
|
+
## Options
|
|
12
|
+
|
|
13
|
+
- `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors.
|
|
14
|
+
- `--skip-questions`: Skip upfront questions, infer from git config.
|
|
15
|
+
|
|
16
|
+
Default: Standard research (~20-50 tool calls).
|
|
17
|
+
|
|
18
|
+
## Phase 1: Upfront Questions
|
|
19
|
+
|
|
20
|
+
Unless `--skip-questions`, ask in one message:
|
|
21
|
+
|
|
22
|
+
1. **Identity**: "Which git contributor are you?" (show top 5 from `git shortlog -sn --all | head -5`)
|
|
23
|
+
2. **Communication**: "Terse or detailed responses?"
|
|
24
|
+
3. **Workflow**: "Auto-commit or ask-first?"
|
|
25
|
+
4. **Rules**: "Any rules I should always follow?"
|
|
26
|
+
|
|
27
|
+
If skipped, infer identity from `git config user.name` and `git config user.email`.
|
|
28
|
+
|
|
29
|
+
## Phase 2: Detect Project
|
|
30
|
+
|
|
31
|
+
### Always Check
|
|
32
|
+
|
|
33
|
+
- `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml` - tech stack
|
|
34
|
+
- `README.md` - project description
|
|
35
|
+
- `.github/workflows/`, `.gitlab-ci.yml` - CI/CD
|
|
36
|
+
- `Makefile`, `justfile` - build commands
|
|
37
|
+
- Existing rules: `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`
|
|
38
|
+
|
|
39
|
+
### With --deep
|
|
40
|
+
|
|
41
|
+
- `git shortlog -sn --all | head -10` - contributors
|
|
42
|
+
- `git log --format="%s" -50` - commit conventions
|
|
43
|
+
- `git branch -a` - branching strategy
|
|
44
|
+
- Source file analysis for patterns
|
|
45
|
+
|
|
46
|
+
## Phase 3: Create Project-Root AGENTS.md
|
|
47
|
+
|
|
48
|
+
Create `./AGENTS.md` (project root, ~20-30 lines):
|
|
49
|
+
|
|
50
|
+
```markdown
|
|
51
|
+
## Build/Lint/Test Commands
|
|
52
|
+
|
|
53
|
+
**Build**: [detected command]
|
|
54
|
+
**Test**: [detected command, include single-test syntax]
|
|
55
|
+
**Lint**: [detected command]
|
|
56
|
+
|
|
57
|
+
## Code Style
|
|
58
|
+
|
|
59
|
+
**Imports**: [detected pattern]
|
|
60
|
+
**Formatting**: [tool used, e.g., prettier, black]
|
|
61
|
+
**Types**: [strict, optional, none]
|
|
62
|
+
**Naming**: [conventions detected]
|
|
63
|
+
**Error Handling**: [pattern detected]
|
|
64
|
+
|
|
65
|
+
## Project-Specific Rules
|
|
66
|
+
|
|
67
|
+
[Include any rules from .cursorrules, copilot-instructions, or user-provided]
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
If AGENTS.md exists, improve it - don't overwrite blindly.
|
|
71
|
+
|
|
72
|
+
## Phase 4: Populate Memory Files
|
|
73
|
+
|
|
74
|
+
### .opencode/memory/user.md
|
|
75
|
+
|
|
76
|
+
```markdown
|
|
77
|
+
---
|
|
78
|
+
purpose: User identity, preferences, communication style
|
|
79
|
+
updated: [today]
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
# User Profile
|
|
83
|
+
|
|
84
|
+
## Identity
|
|
85
|
+
|
|
86
|
+
- Name: [from git/questions]
|
|
87
|
+
- Git contributor: [email/username]
|
|
88
|
+
|
|
89
|
+
## Preferences
|
|
90
|
+
|
|
91
|
+
- Communication: [terse/detailed]
|
|
92
|
+
- Workflow: [auto-commit/ask-first]
|
|
93
|
+
|
|
94
|
+
## Rules
|
|
95
|
+
|
|
96
|
+
[from Phase 1]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### .opencode/memory/project/commands.md
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
---
|
|
103
|
+
purpose: Build, test, lint, deploy commands
|
|
104
|
+
updated: [today]
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
# Commands
|
|
108
|
+
|
|
109
|
+
## Build
|
|
110
|
+
|
|
111
|
+
[detected]
|
|
112
|
+
|
|
113
|
+
## Test
|
|
114
|
+
|
|
115
|
+
[detected, include single-test example]
|
|
116
|
+
|
|
117
|
+
## Lint
|
|
118
|
+
|
|
119
|
+
[detected]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### .opencode/memory/project/architecture.md
|
|
123
|
+
|
|
124
|
+
```markdown
|
|
125
|
+
---
|
|
126
|
+
purpose: Key modules, directory structure
|
|
127
|
+
updated: [today]
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
# Architecture
|
|
131
|
+
|
|
132
|
+
## Structure
|
|
133
|
+
|
|
134
|
+
[detected directory layout]
|
|
135
|
+
|
|
136
|
+
## Key Modules
|
|
137
|
+
|
|
138
|
+
[identified entry points, core modules]
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### With --deep, also create:
|
|
142
|
+
|
|
143
|
+
- `project/conventions.md` - from git log analysis
|
|
144
|
+
- `project/gotchas.md` - from bug-fix patterns in history
|
|
145
|
+
|
|
146
|
+
## Phase 5: Reflection
|
|
147
|
+
|
|
148
|
+
Before finishing:
|
|
149
|
+
|
|
150
|
+
1. Did you create both AGENTS.md AND memory files?
|
|
151
|
+
2. Are commands accurate and tested?
|
|
152
|
+
3. Any typos or unclear descriptions?
|
|
153
|
+
4. Would this help your future self?
|
|
154
|
+
|
|
155
|
+
Fix issues found.
|
|
156
|
+
|
|
157
|
+
## Phase 6: Summary
|
|
158
|
+
|
|
159
|
+
Report:
|
|
160
|
+
|
|
161
|
+
- Files created/updated
|
|
162
|
+
- Tech stack detected
|
|
163
|
+
- Key findings
|
|
164
|
+
- Suggested next steps (e.g., "Run /review-codebase to check conventions")
|
|
165
|
+
|
|
166
|
+
## File Locations
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
./AGENTS.md # Project-specific rules (created)
|
|
170
|
+
.opencode/AGENTS.md # Global rules (untouched)
|
|
171
|
+
.opencode/memory/user.md # User preferences (created)
|
|
172
|
+
.opencode/memory/project/commands.md # Build commands (created)
|
|
173
|
+
.opencode/memory/project/architecture.md # Structure (created)
|
|
174
|
+
.opencode/memory/project/conventions.md # Patterns (--deep only)
|
|
175
|
+
.opencode/memory/project/gotchas.md # Warnings (--deep only)
|
|
176
|
+
```
|
|
@@ -1,28 +1,59 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
purpose: Persistent project knowledge that survives across sessions
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
# Project Memory
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
This directory stores persistent project knowledge that agents use across sessions.
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
| ---------------- | ----------------------------------- |
|
|
9
|
-
| `product.md` | Product vision, users, features |
|
|
10
|
-
| `tech-stack.md` | Languages, frameworks, dependencies |
|
|
11
|
-
| `workflow.md` | Branch strategy, review, deployment |
|
|
12
|
-
| `conventions.md` | Coding standards, patterns |
|
|
10
|
+
## Standard Files
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+
| File | Purpose | Update When |
|
|
13
|
+
| ----------------- | --------------------------------------- | ----------------------- |
|
|
14
|
+
| `commands.md` | Build, test, lint, deploy commands | Discover new command |
|
|
15
|
+
| `conventions.md` | Code patterns, commit style, PR process | Learn team pattern |
|
|
16
|
+
| `gotchas.md` | Footguns, edge cases, warnings | Hit unexpected behavior |
|
|
17
|
+
| `architecture.md` | Key modules, directory structure | Map new area |
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
## File Format
|
|
20
|
+
|
|
21
|
+
Each file uses YAML frontmatter:
|
|
22
|
+
|
|
23
|
+
```yaml
|
|
24
|
+
---
|
|
25
|
+
purpose: How this memory should influence agent behavior
|
|
26
|
+
updated: YYYY-MM-DD
|
|
27
|
+
---
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## How Agents Use This
|
|
31
|
+
|
|
32
|
+
- **Session start**: Agents read relevant memory files for context
|
|
33
|
+
- **During work**: Agents update files when learning new information
|
|
34
|
+
- **Session end**: Critical learnings persisted here survive context reset
|
|
35
|
+
|
|
36
|
+
## Integration
|
|
37
|
+
|
|
38
|
+
### With Commands
|
|
39
|
+
|
|
40
|
+
- `/implement` - Reads conventions for code style
|
|
41
|
+
- `/setup-project` - Populates these files initially
|
|
42
|
+
- `/review-codebase` - Checks against conventions
|
|
43
|
+
|
|
44
|
+
### With Beads
|
|
17
45
|
|
|
18
46
|
```bash
|
|
19
47
|
bd new feature "Add auth" --context .opencode/memory/project/
|
|
20
48
|
```
|
|
21
49
|
|
|
22
|
-
##
|
|
50
|
+
## Philosophy
|
|
51
|
+
|
|
52
|
+
**Don't rely on implicit learning.** When agents discover:
|
|
23
53
|
|
|
24
|
-
|
|
54
|
+
- Non-obvious behavior → Update `gotchas.md`
|
|
55
|
+
- New commands → Update `commands.md`
|
|
56
|
+
- Code patterns → Update `conventions.md`
|
|
57
|
+
- Architecture insights → Update `architecture.md`
|
|
25
58
|
|
|
26
|
-
|
|
27
|
-
- `/plan` - Reads product for feature alignment
|
|
28
|
-
- `/review-codebase` - Reads conventions for compliance
|
|
59
|
+
Explicit memory beats hoping the agent remembers.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: Key modules, directory structure, architectural decisions
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Architecture
|
|
7
|
+
|
|
8
|
+
## Directory Structure
|
|
9
|
+
|
|
10
|
+
<!-- Key directories and their purpose -->
|
|
11
|
+
|
|
12
|
+
## Key Modules
|
|
13
|
+
|
|
14
|
+
<!-- Core files/modules and what they do -->
|
|
15
|
+
|
|
16
|
+
## Data Flow
|
|
17
|
+
|
|
18
|
+
<!-- How data moves through the system -->
|
|
19
|
+
|
|
20
|
+
## External Dependencies
|
|
21
|
+
|
|
22
|
+
<!-- Critical third-party services, APIs -->
|
|
23
|
+
|
|
24
|
+
## Architectural Decisions
|
|
25
|
+
|
|
26
|
+
<!-- Why things are structured this way -->
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: Build, test, lint, deploy commands discovered for this project
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Commands
|
|
7
|
+
|
|
8
|
+
## Build
|
|
9
|
+
|
|
10
|
+
<!-- npm run build, make, cargo build, etc. -->
|
|
11
|
+
|
|
12
|
+
## Test
|
|
13
|
+
|
|
14
|
+
<!-- npm test, pytest, cargo test, etc. -->
|
|
15
|
+
|
|
16
|
+
## Lint
|
|
17
|
+
|
|
18
|
+
<!-- npm run lint, ruff check, etc. -->
|
|
19
|
+
|
|
20
|
+
## Deploy
|
|
21
|
+
|
|
22
|
+
<!-- Deployment commands if applicable -->
|
|
23
|
+
|
|
24
|
+
## Other
|
|
25
|
+
|
|
26
|
+
<!-- Project-specific commands worth remembering -->
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: Code patterns, commit style, PR process, team conventions
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Conventions
|
|
7
|
+
|
|
8
|
+
## Code Style
|
|
9
|
+
|
|
10
|
+
<!-- Naming conventions, formatting rules, import ordering -->
|
|
11
|
+
|
|
12
|
+
## Commit Messages
|
|
13
|
+
|
|
14
|
+
<!-- Conventional commits? Prefix style? -->
|
|
15
|
+
|
|
16
|
+
## PR Process
|
|
17
|
+
|
|
18
|
+
<!-- Review requirements, CI checks, merge strategy -->
|
|
19
|
+
|
|
20
|
+
## Patterns to Follow
|
|
21
|
+
|
|
22
|
+
<!-- Recurring patterns in this codebase -->
|
|
23
|
+
|
|
24
|
+
## Patterns to Avoid
|
|
25
|
+
|
|
26
|
+
<!-- Anti-patterns specific to this project -->
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: Footguns, edge cases, and "don't forget this" warnings
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Gotchas
|
|
7
|
+
|
|
8
|
+
## Code That Looks Right But Breaks
|
|
9
|
+
|
|
10
|
+
<!-- Subtle bugs, misleading APIs -->
|
|
11
|
+
|
|
12
|
+
## Non-Obvious Dependencies
|
|
13
|
+
|
|
14
|
+
<!-- Hidden coupling, initialization order -->
|
|
15
|
+
|
|
16
|
+
## Configuration Quirks
|
|
17
|
+
|
|
18
|
+
<!-- Environment variables, config files that bite -->
|
|
19
|
+
|
|
20
|
+
## Time Wasters
|
|
21
|
+
|
|
22
|
+
<!-- Things that will waste 2+ hours if you forget -->
|
|
23
|
+
|
|
24
|
+
## Platform-Specific Issues
|
|
25
|
+
|
|
26
|
+
<!-- macOS vs Linux, Node versions, etc. -->
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: User identity, preferences, communication style
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# User Profile
|
|
7
|
+
|
|
8
|
+
## Identity
|
|
9
|
+
<!-- Name, role, git contributor identity -->
|
|
10
|
+
|
|
11
|
+
## Communication Preferences
|
|
12
|
+
<!-- Concise vs detailed, tone preferences -->
|
|
13
|
+
|
|
14
|
+
## Workflow Preferences
|
|
15
|
+
<!-- Preferred tools, testing habits, review style -->
|
|
16
|
+
|
|
17
|
+
## Technical Preferences
|
|
18
|
+
<!-- Languages, frameworks, patterns they favor -->
|
|
19
|
+
|
|
20
|
+
## Things to Remember
|
|
21
|
+
<!-- Personal quirks, pet peeves, preferences learned -->
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
purpose: User identity, preferences, communication style
|
|
3
|
+
updated: 2024-12-21
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# User Profile
|
|
7
|
+
|
|
8
|
+
## Identity
|
|
9
|
+
<!-- Name, role, git contributor identity -->
|
|
10
|
+
|
|
11
|
+
## Communication Preferences
|
|
12
|
+
<!-- Concise vs detailed, tone preferences -->
|
|
13
|
+
|
|
14
|
+
## Workflow Preferences
|
|
15
|
+
<!-- Preferred tools, testing habits, review style -->
|
|
16
|
+
|
|
17
|
+
## Technical Preferences
|
|
18
|
+
<!-- Languages, frameworks, patterns they favor -->
|
|
19
|
+
|
|
20
|
+
## Things to Remember
|
|
21
|
+
<!-- Personal quirks, pet peeves, preferences learned -->
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://opencode.ai/config.json",
|
|
3
3
|
"agent": {
|
|
4
|
+
"compaction": {
|
|
5
|
+
"model": "proxypal/gemini-3-flash-preview",
|
|
6
|
+
"prompt": "You are summarizing a coding session for context continuity.\n\n## Output Structure\n\nUse these sections:\n\n### COMPLETED\n- What was done (with file paths)\n- Bead IDs closed and why\n\n### IN PROGRESS\n- Current task and bead ID (if any)\n- Files being modified (exact paths)\n- Current todo state (preserve TodoWrite items)\n\n### NEXT\n- What needs to be done next\n- Blockers or pending decisions\n\n### CONSTRAINTS\n- User preferences that must persist\n- Rules or requirements stated by user\n- Technical decisions and rationale\n\n### PERSIST TO MEMORY\n- Gotchas discovered → suggest for project/gotchas.md\n- Commands learned → suggest for project/commands.md\n- Patterns observed → suggest for project/conventions.md\n\n## Rules\n\n- PRESERVE: Bead IDs, todo items, file paths, line numbers, user constraints\n- DROP: Failed attempts, superseded info, verbose tool outputs, exploration dead-ends\n- Be concise but complete - this summary replaces the full conversation\n- Include enough context that a new session can continue seamlessly"
|
|
7
|
+
},
|
|
4
8
|
"build": {
|
|
5
9
|
"description": "Primary development agent with full codebase access",
|
|
6
10
|
"model": "proxypal/gemini-claude-opus-4-5-thinking"
|
|
@@ -25,7 +29,7 @@
|
|
|
25
29
|
},
|
|
26
30
|
"rush": {
|
|
27
31
|
"description": "Fast primary agent for small, well-defined tasks",
|
|
28
|
-
"model": "
|
|
32
|
+
"model": "proxypal/gemini-3-pro-preview"
|
|
29
33
|
},
|
|
30
34
|
"scout": {
|
|
31
35
|
"description": "External research specialist for library docs and patterns",
|
|
@@ -59,6 +63,7 @@
|
|
|
59
63
|
"extensions": [".html", ".css", ".scss", ".sass", ".md", ".yaml", ".yml"]
|
|
60
64
|
}
|
|
61
65
|
},
|
|
66
|
+
"instructions": [".opencode/memory/user.md", ".opencode/memory/project/*.md"],
|
|
62
67
|
"keybinds": {
|
|
63
68
|
"command_list": ";",
|
|
64
69
|
"leader": "`",
|
|
@@ -201,13 +206,6 @@
|
|
|
201
206
|
},
|
|
202
207
|
"proxypal": {
|
|
203
208
|
"models": {
|
|
204
|
-
"claude-opus-4-5-20251101": {
|
|
205
|
-
"limit": {
|
|
206
|
-
"context": 200000,
|
|
207
|
-
"output": 64000
|
|
208
|
-
},
|
|
209
|
-
"name": "Claude Opus 4 5 20251101"
|
|
210
|
-
},
|
|
211
209
|
"gemini-2.5-computer-use-preview-10-2025": {
|
|
212
210
|
"limit": {
|
|
213
211
|
"context": 1048576,
|
|
@@ -292,6 +290,13 @@
|
|
|
292
290
|
},
|
|
293
291
|
"reasoning": true
|
|
294
292
|
},
|
|
293
|
+
"glm-4.6": {
|
|
294
|
+
"limit": {
|
|
295
|
+
"context": 128000,
|
|
296
|
+
"output": 16384
|
|
297
|
+
},
|
|
298
|
+
"name": "Glm 4 6"
|
|
299
|
+
},
|
|
295
300
|
"gpt-5": {
|
|
296
301
|
"limit": {
|
|
297
302
|
"context": 128000,
|
|
@@ -11,10 +11,9 @@
|
|
|
11
11
|
"author": "",
|
|
12
12
|
"license": "ISC",
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@opencode-ai/plugin": "1.0.
|
|
14
|
+
"@opencode-ai/plugin": "1.0.180"
|
|
15
15
|
},
|
|
16
16
|
"devDependencies": {
|
|
17
|
-
"@types/better-sqlite3": "^7.6.13",
|
|
18
17
|
"@types/node": "^20.19.27",
|
|
19
18
|
"fs": "^0.0.1-security",
|
|
20
19
|
"path": "^0.12.7",
|
package/package.json
CHANGED
|
@@ -1,152 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Initialize project context for AI-assisted development
|
|
3
|
-
argument-hint: "[--full] [--minimal]"
|
|
4
|
-
agent: planner
|
|
5
|
-
model: proxypal/gemini-3-flash-preview
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Setup Project: $ARGUMENTS
|
|
9
|
-
|
|
10
|
-
Initialize project context files that AI agents and beads can reference.
|
|
11
|
-
|
|
12
|
-
## Instructions
|
|
13
|
-
|
|
14
|
-
Parse options from `$ARGUMENTS`:
|
|
15
|
-
|
|
16
|
-
- `--full`: Create all context files with detailed prompts
|
|
17
|
-
- `--minimal`: Create only essential files (default)
|
|
18
|
-
|
|
19
|
-
## Context Files to Create
|
|
20
|
-
|
|
21
|
-
### Essential (always created)
|
|
22
|
-
|
|
23
|
-
**`.opencode/memory/project/product.md`**
|
|
24
|
-
|
|
25
|
-
```markdown
|
|
26
|
-
# Product Context
|
|
27
|
-
|
|
28
|
-
## Vision
|
|
29
|
-
|
|
30
|
-
[What is this product? What problem does it solve?]
|
|
31
|
-
|
|
32
|
-
## Target Users
|
|
33
|
-
|
|
34
|
-
[Who uses this? What are their needs?]
|
|
35
|
-
|
|
36
|
-
## Key Features
|
|
37
|
-
|
|
38
|
-
1. [Feature 1]
|
|
39
|
-
2. [Feature 2]
|
|
40
|
-
|
|
41
|
-
## Success Metrics
|
|
42
|
-
|
|
43
|
-
- [How do we measure success?]
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
**`.opencode/memory/project/tech-stack.md`**
|
|
47
|
-
|
|
48
|
-
```markdown
|
|
49
|
-
# Tech Stack
|
|
50
|
-
|
|
51
|
-
## Languages
|
|
52
|
-
|
|
53
|
-
- [Primary language and version]
|
|
54
|
-
|
|
55
|
-
## Frameworks
|
|
56
|
-
|
|
57
|
-
- [Framework 1]: [Purpose]
|
|
58
|
-
|
|
59
|
-
## Infrastructure
|
|
60
|
-
|
|
61
|
-
- [Hosting, CI/CD, etc.]
|
|
62
|
-
|
|
63
|
-
## Key Dependencies
|
|
64
|
-
|
|
65
|
-
| Package | Version | Purpose |
|
|
66
|
-
| ------- | ------- | ------- |
|
|
67
|
-
| [name] | [ver] | [why] |
|
|
68
|
-
|
|
69
|
-
## Development Setup
|
|
70
|
-
|
|
71
|
-
[How to get started locally]
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Full Setup (with --full)
|
|
75
|
-
|
|
76
|
-
**`.opencode/memory/project/workflow.md`**
|
|
77
|
-
|
|
78
|
-
```markdown
|
|
79
|
-
# Development Workflow
|
|
80
|
-
|
|
81
|
-
## Branch Strategy
|
|
82
|
-
|
|
83
|
-
- main: Production
|
|
84
|
-
- develop: Integration
|
|
85
|
-
- feature/\*: New features
|
|
86
|
-
- fix/\*: Bug fixes
|
|
87
|
-
|
|
88
|
-
## Code Review
|
|
89
|
-
|
|
90
|
-
[Review requirements]
|
|
91
|
-
|
|
92
|
-
## Testing Requirements
|
|
93
|
-
|
|
94
|
-
[What must be tested]
|
|
95
|
-
|
|
96
|
-
## Deployment Process
|
|
97
|
-
|
|
98
|
-
[How code gets to production]
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**`.opencode/memory/project/conventions.md`**
|
|
102
|
-
|
|
103
|
-
```markdown
|
|
104
|
-
# Coding Conventions
|
|
105
|
-
|
|
106
|
-
## Naming
|
|
107
|
-
|
|
108
|
-
- Files: [convention]
|
|
109
|
-
- Components: [convention]
|
|
110
|
-
- Variables: [convention]
|
|
111
|
-
|
|
112
|
-
## Structure
|
|
113
|
-
|
|
114
|
-
- [Directory structure rules]
|
|
115
|
-
|
|
116
|
-
## Patterns
|
|
117
|
-
|
|
118
|
-
- [Design patterns used]
|
|
119
|
-
|
|
120
|
-
## Anti-patterns
|
|
121
|
-
|
|
122
|
-
- [What to avoid]
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
## Process
|
|
126
|
-
|
|
127
|
-
1. Check if context files already exist
|
|
128
|
-
2. If exists, offer to update or skip
|
|
129
|
-
3. Analyze codebase to pre-fill where possible:
|
|
130
|
-
- Detect tech stack from package.json, go.mod, etc.
|
|
131
|
-
- Identify patterns from existing code
|
|
132
|
-
- Extract project info from README
|
|
133
|
-
4. Create files with intelligent defaults
|
|
134
|
-
5. Report what was created
|
|
135
|
-
|
|
136
|
-
## Integration with Beads
|
|
137
|
-
|
|
138
|
-
After setup, beads can reference:
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
bd new feature "Add login" --context .opencode/memory/project/
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
## Output
|
|
145
|
-
|
|
146
|
-
Report:
|
|
147
|
-
|
|
148
|
-
- Files created/updated
|
|
149
|
-
- Detected tech stack
|
|
150
|
-
- Suggested next steps
|
|
151
|
-
|
|
152
|
-
Save to `.opencode/memory/project/`
|