Skip to content

Commit fd3c1c2

Browse files
darrenhindedarrenhinde
committed
fix: correct context path defaults and add preview gates (Issues #175, #177)
- /add-context now always saves to local .opencode/context/project-intelligence/ with --global flag as opt-in for ~/.config/opencode/ (fixes #175) - Added Stage 0.5 path resolution, full file preview before writes, Replace All backup preview, and navigation.md preview (fixes #177) - Rewrote context-paths.md with resolution order, merging rules, scenarios - Added /context migrate operation for global-to-local migration - Added preview/approval gates to creation, harvest, and extract operations - Updated README, CONTEXT_SYSTEM_GUIDE, platform-compatibility docs - All stale ~/.opencode/ and project-context.md references removed
1 parent 456021f commit fd3c1c2

File tree

13 files changed

+647
-82
lines changed

13 files changed

+647
-82
lines changed

‎.opencode/command/add-context.md‎

Lines changed: 106 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -85,10 +85,11 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
8585
## Usage
8686

8787
```bash
88-
/add-context # Interactive wizard (recommended)
88+
/add-context # Interactive wizard (recommended, saves to project)
8989
/add-context --update # Update existing context
9090
/add-context --tech-stack # Add/update tech stack only
9191
/add-context --patterns # Add/update code patterns only
92+
/add-context --global # Save to global config (~/.config/opencode/) instead of project
9293
```
9394

9495
---
@@ -98,11 +99,13 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
9899
**Run**: `/add-context`
99100

100101
**What happens**:
101-
1. Checks for external context files in `.tmp/` (if found, offers to extract)
102-
2. Checks for existing project intelligence
103-
3. Asks 6 questions (~5 min) OR reviews existing patterns
104-
4. Generates/updates technical-domain.md
105-
5. Agents now use YOUR patterns
102+
1. Saves to `.opencode/context/project-intelligence/` in your project (always local)
103+
2. Checks for external context files in `.tmp/` (if found, offers to extract)
104+
3. Checks for existing project intelligence
105+
4. Asks 6 questions (~5 min) OR reviews existing patterns
106+
5. Shows full preview of files to be created before writing
107+
6. Generates/updates technical-domain.md + navigation.md
108+
7. Agents now use YOUR patterns
106109

107110
**6 Questions** (~5 min):
108111
1. Tech stack?
@@ -124,6 +127,23 @@ Help users add project patterns using Project Intelligence standard. **Easiest w
124127

125128
## Workflow
126129

130+
### Stage 0.5: Resolve Context Location
131+
132+
Determine where project intelligence files should be saved. This runs BEFORE anything else.
133+
134+
**Default behavior**: Always use local `.opencode/context/project-intelligence/`.
135+
**Override**: `--global` flag saves to `~/.config/opencode/context/project-intelligence/` instead.
136+
137+
**Resolution:**
138+
1. If `--global` flag → `$CONTEXT_DIR = ~/.config/opencode/context/project-intelligence/`
139+
2. Otherwise → `$CONTEXT_DIR = .opencode/context/project-intelligence/` (always local)
140+
141+
**If `.opencode/context/` doesn't exist yet**, create it silently — no prompt needed. The directory structure is part of the output shown in Stage 4.
142+
143+
**Variable**: `$CONTEXT_DIR` is set here and used in all subsequent stages.
144+
145+
---
146+
127147
### Stage 0: Check for External Context Files
128148

129149
Check: `.tmp/` directory for external context files (e.g., `.tmp/external-context.md`, `.tmp/context-*.md`)
@@ -180,7 +200,7 @@ Ready to harvest? [y/n]: _
180200

181201
### Stage 1: Detect Existing Context
182202

183-
Check: `~/.opencode/context/project-intelligence/`
203+
Check: `$CONTEXT_DIR` (set in Stage 0.5 — either `.opencode/context/project-intelligence/` or `~/.config/opencode/context/project-intelligence/`)
184204

185205
**If exists**:
186206
```
@@ -206,18 +226,41 @@ Current patterns:
206226
Options:
207227
1. Review and update patterns (show each one)
208228
2. Add new patterns (keep all existing)
209-
3. Replace all patterns (start fresh, backup old)
229+
3. Replace all patterns (start fresh)
210230
4. Cancel
211231
212232
Choose [1/2/3/4]: _
213233
```
214234

235+
**If user chooses 3 (Replace all):**
236+
```
237+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
238+
Replace All: Preview
239+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
240+
241+
Will BACKUP existing files to:
242+
.tmp/backup/project-intelligence-{timestamp}/
243+
← technical-domain.md (Version: 1.2)
244+
← business-domain.md (Version: 1.0)
245+
← navigation.md
246+
247+
Will DELETE and RECREATE:
248+
$CONTEXT_DIR/technical-domain.md (new Version: 1.0)
249+
$CONTEXT_DIR/navigation.md (new Version: 1.0)
250+
251+
Existing files backed up → you can restore from .tmp/backup/ if needed.
252+
253+
Proceed? [y/n]: _
254+
```
255+
215256
**If not exists**:
216257
```
217258
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
218259
No project intelligence found. Let's create it!
219260
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
220261
262+
Saving to: $CONTEXT_DIR
263+
221264
Will create:
222265
- project-intelligence/technical-domain.md (tech stack & patterns)
223266
- project-intelligence/navigation.md (quick overview)
@@ -485,7 +528,7 @@ Preview: technical-domain.md
485528
Size: {line_count} lines (limit: 200 per @mvi_compliance)
486529
Status: ✅ MVI compliant
487530

488-
Save to: ~/.opencode/context/project-intelligence/technical-domain.md
531+
Save to: $CONTEXT_DIR/technical-domain.md
489532

490533
Looks good? [y/n/edit]: _
491534
```
@@ -511,12 +554,35 @@ Running validation...
511554
✅ Version set: 1.0 (@version_tracking)
512555
✅ MVI compliant (<30s scannable)
513556
✅ No duplication
557+
```
558+
559+
**navigation.md preview** (also created/updated):
560+
```
561+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
562+
Preview: navigation.md
563+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
514564

515-
Creating files per @project_intelligence...
516-
✓ technical-domain.md
517-
✓ navigation.md (updated per @navigation_update)
565+
# Project Intelligence
518566

519-
Done!
567+
| File | Description | Priority |
568+
|------|-------------|----------|
569+
| [technical-domain.md](technical-domain.md) | Tech stack & patterns | critical |
570+
571+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
572+
```
573+
574+
**Full creation plan**:
575+
```
576+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
577+
Files to write:
578+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
579+
580+
CREATE $CONTEXT_DIR/technical-domain.md ({line_count} lines)
581+
CREATE $CONTEXT_DIR/navigation.md ({nav_line_count} lines)
582+
583+
Total: 2 files
584+
585+
Proceed? [y/n]: _
520586
```
521587
522588
---
@@ -529,9 +595,10 @@ Done!
529595
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
530596

531597
Files created:
532-
~/.opencode/context/project-intelligence/technical-domain.md
533-
~/.opencode/context/project-intelligence/navigation.md
598+
$CONTEXT_DIR/technical-domain.md
599+
$CONTEXT_DIR/navigation.md
534600

601+
Location: $CONTEXT_DIR
535602
Agents now use YOUR patterns automatically!
536603

537604
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -543,7 +610,7 @@ What's next?
543610
> "Create API endpoint"
544611
(Uses YOUR pattern!)
545612

546-
2. Review: cat ~/.opencode/context/project-intelligence/technical-domain.md
613+
2. Review: cat $CONTEXT_DIR/technical-domain.md
547614

548615
3. Add business context: /add-context --business
549616

@@ -560,6 +627,18 @@ When you:
560627

561628
Agents stay synced!
562629

630+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
631+
💡 Tip: Global patterns
632+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
633+
634+
Want the same patterns across ALL your projects?
635+
/add-context --global
636+
→ Saves to ~/.config/opencode/context/project-intelligence/
637+
→ Acts as fallback for projects without local context
638+
639+
Already have global patterns? Bring them into this project:
640+
/context migrate
641+
563642
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
564643
📚 Learn More
565644
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -593,7 +672,7 @@ Agents stay synced!
593672
### Pattern Detection (Stage 1)
594673
595674
**Process**:
596-
1. Check: `ls ~/.opencode/context/project-intelligence/`
675+
1. Check: `ls $CONTEXT_DIR/` (path determined in Stage 0.5)
597676
2. Read: `cat technical-domain.md` (if exists)
598677
3. Parse existing patterns:
599678
- Frontmatter: version, updated date
@@ -822,16 +901,22 @@ Check code & retry.
822901
A: Check file exists, <200 lines. Run `/context validate`
823902
824903
**Q: See what's in context?**
825-
A: `cat ~/.opencode/context/project-intelligence/technical-domain.md`
904+
A: `cat .opencode/context/project-intelligence/technical-domain.md` (local) or `cat ~/.config/opencode/context/project-intelligence/technical-domain.md` (global)
826905
827906
**Q: Multiple context files?**
828-
A: Yes! Create in `~/.opencode/context/project-intelligence/`. Agents load all.
907+
A: Yes! Create in your project-intelligence directory. Agents load all.
829908
830909
**Q: Remove pattern?**
831-
A: Edit directly: `nano ~/.opencode/context/project-intelligence/technical-domain.md`
910+
A: Edit directly: `nano .opencode/context/project-intelligence/technical-domain.md`
832911
833912
**Q: Share w/ team?**
834-
A: Yes! Commit `~/.opencode/context/project-intelligence/` to repo.
913+
A: Yes! Use local install (`.opencode/context/project-intelligence/`) and commit to repo. Team members get your patterns automatically.
914+
915+
**Q: Local vs global?**
916+
A: Local (`.opencode/`) = project-specific, committed to git, team-shared. Global (`~/.config/opencode/`) = personal defaults across all projects. Local overrides global.
917+
918+
**Q: Installed globally but want project patterns?**
919+
A: Run `/add-context` (defaults to local). Creates `.opencode/context/project-intelligence/` in your project even if OAC was installed globally.
835920
836921
**Q: Have external context files in .tmp/?**
837922
A: Run `/context harvest` to extract and organize them into permanent context

‎.opencode/command/context.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,17 @@ When invoked without arguments: `/context`
127127

128128
---
129129

130+
### Migration
131+
132+
**`/context migrate`**
133+
- Copy project-intelligence from global (`~/.config/opencode/context/`) to local (`.opencode/context/`)
134+
- For users who installed globally but want project-specific, git-committed context
135+
- Shows diff if local files already exist, asks before overwriting
136+
- Optionally cleans up global project-intelligence after migration
137+
- **Reads**: `standards/mvi.md`
138+
139+
---
140+
130141
### Utility Operations
131142

132143
**`/context map [category]`**
@@ -174,6 +185,10 @@ When invoked without arguments: `/context`
174185
<operation name="create">
175186
Read: guides/creation.md, standards/structure.md, standards/templates.md
176187
</operation>
188+
189+
<operation name="migrate">
190+
Read: standards/mvi.md
191+
</operation>
177192
</lazy_load_map>
178193

179194
**All files located in**: `.opencode/context/core/context-system/`
@@ -184,7 +199,7 @@ When invoked without arguments: `/context`
184199

185200
<subagent_routing>
186201
<!-- Delegate operations to specialized subagents -->
187-
<route operations="harvest|extract|organize|update|error|create" to="ContextOrganizer">
202+
<route operations="harvest|extract|organize|update|error|create|migrate" to="ContextOrganizer">
188203
Pass: operation name, arguments, lazy load map
189204
Subagent loads: Required context files from .opencode/context/core/context-system/
190205
Subagent executes: Multi-stage workflow per operation
@@ -261,6 +276,13 @@ When invoked without arguments: `/context`
261276
/context update for React 19 breaking changes
262277
```
263278

279+
### Migrate Global to Local
280+
```bash
281+
/context migrate
282+
# Copies project-intelligence from ~/.config/opencode/context/ to .opencode/context/
283+
# Shows what will be copied, asks for approval before proceeding
284+
```
285+
264286
---
265287

266288
## Success Criteria

‎.opencode/context/core/context-system.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -432,8 +432,17 @@ Data: development/data/nosql-patterns/mongodb.md
432432
## Quick Commands
433433

434434
```bash
435-
/context harvest # Clean up summaries
436-
/context extract {source} # From docs/code
437-
/context organize {category} # Restructure
438-
/context update {what} # When APIs change
435+
/context # Quick scan, suggest actions
436+
/context harvest # Clean up summaries → permanent context
437+
/context extract {source} # From docs/code/URLs
438+
/context organize {category} # Restructure flat files → function folders
439+
/context update {what} # When APIs/frameworks change
440+
/context migrate # Move global project-intelligence → local project
441+
/context create {category} # Create new context category
442+
/context error {error} # Add recurring error to knowledge base
443+
/context compact {file} # Minimize verbose file to MVI format
444+
/context map [category] # View context structure
445+
/context validate # Check integrity, references, sizes
439446
```
447+
448+
**All operations show a preview of what will be created/moved/deleted before asking for approval.**

‎.opencode/context/core/context-system/guides/creation.md‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,15 +55,76 @@
5555
Link to related concepts/, examples/, guides/, errors/
5656
</stage>
5757

58-
<stage id="6" name="Update README">
59-
Add entry to category README.md navigation table
58+
<stage id="6" name="Preview &amp; Approve" enforce="@critical_rules.approval_gate">
59+
MUST show full preview before writing ANY files:
60+
61+
```
62+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
63+
Preview: File Creation Plan
64+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
65+
66+
CREATE file:
67+
{category}/{function}/{filename}.md ({line_count} lines)
68+
69+
Content preview:
70+
┌─────────────────────────────────────────────────────────┐
71+
│ # {Type}: {Name} │
72+
│ │
73+
│ **Purpose**: {1 sentence} │
74+
│ **Last Updated**: {date} │
75+
│ │
76+
│ ## Core Concept │
77+
│ {1-3 sentences} │
78+
│ │
79+
│ ## Key Points │
80+
│ {3-5 bullets} │
81+
│ ... │
82+
└─────────────────────────────────────────────────────────┘
83+
84+
UPDATE navigation:
85+
{category}/navigation.md
86+
+ | [{filename}.md]({function}/{filename}.md) | {desc} | {priority} |
87+
88+
Validation:
89+
✓ {line_count} lines (limit: {max_lines} for {type})
90+
✓ MVI format applied
91+
✓ Correct folder: {function}/
92+
✓ Cross-references: {count} links added
93+
94+
Approve? [y/n/edit]: _
95+
```
96+
97+
If file already exists at target path:
98+
```
99+
⚠️ File already exists: {category}/{function}/{filename}.md
100+
101+
Options:
102+
1. Cancel (keep existing)
103+
2. Show diff (compare existing vs new)
104+
3. Overwrite (replace existing)
105+
4. Rename new file to {filename}-v2.md
106+
107+
Choose [1/2/3/4]: _
108+
```
60109
</stage>
61110

62-
<stage id="7" name="Verify">
111+
<stage id="7" name="Write &amp; Report">
112+
Only after approval:
113+
1. Write file to disk
114+
2. Update navigation.md
115+
3. Show confirmation:
116+
117+
```
118+
✅ Created: {category}/{function}/{filename}.md ({line_count} lines)
119+
✅ Updated: {category}/navigation.md
120+
```
121+
</stage>
122+
123+
<stage id="8" name="Verify">
63124
- [ ] <200 lines?
64125
- [ ] MVI format?
65126
- [ ] Correct folder?
66-
- [ ] README updated?
127+
- [ ] navigation.md updated?
67128
- [ ] Cross-refs added?
68129
</stage>
69130
</workflow>

‎.opencode/context/core/context-system/navigation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ core/context-system/
2828
| **Operations & procedures** | `./operations/` |
2929
| **Implementation guides** | `./guides/` |
3030
| **Standards & templates** | `./standards/navigation.md` |
31+
| **Migrate global → local** | `./operations/migrate.md` |
3132

3233
---
3334

0 commit comments

Comments
 (0)