migrate.md 7.6 KB
Context Migrate Operation
Purpose: Copy context files from global (~/.config/opencode/context/) to local (.opencode/context/) so they're project-specific and git-committed.
Last Updated: 2026-02-06
Core Problem
Users who installed OAC globally have project-intelligence files at ~/.config/opencode/context/project-intelligence/. These files are project-specific patterns but aren't committed to git or shared with the team.
Solution: Migrate project-intelligence from global → local, so patterns are version-controlled and team-shared.
4-Stage Workflow
Stage 1: Detect Sources
Scan for context files in the global config directory:
Scanning global context...
Global location: ~/.config/opencode/context/
Found:
project-intelligence/
technical-domain.md (1.2 KB, Version: 1.3)
navigation.md (800 bytes, Version: 1.0)
business-domain.md (1.5 KB, Version: 1.1)
Local location: .opencode/context/
Status: No local project-intelligence/ found
If no global context found:
No global context found at ~/.config/opencode/context/
Nothing to migrate. Use /add-context to create project intelligence.
→ Exit
If no global project-intelligence found (but other global context exists):
Global context found at ~/.config/opencode/context/ but no project-intelligence/ directory.
Only project-intelligence files are migrated (project-specific patterns).
Core standards stay in global (they're universal, not project-specific).
Nothing to migrate. Use /add-context to create project intelligence.
→ Exit
Stage 2: Check for Conflicts
If local .opencode/context/project-intelligence/ already exists:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Conflict: Local project-intelligence already exists
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Global files: Local files:
technical-domain.md technical-domain.md
Version: 1.3, Updated: 2026-01-15 Version: 1.0, Updated: 2026-02-01
navigation.md navigation.md
Version: 1.0, Updated: 2026-01-10 Version: 1.0, Updated: 2026-02-01
business-domain.md (not present locally)
Version: 1.1, Updated: 2026-01-12
Options:
1. Skip existing — only copy files that don't exist locally
→ Will copy: business-domain.md
→ Will skip: technical-domain.md, navigation.md (local kept)
2. Overwrite all — replace local with global versions
→ Will overwrite: technical-domain.md, navigation.md
→ Will copy: business-domain.md
→ Local backup created first
3. Cancel
Choose [1/2/3]: _
If user chooses 2 (Overwrite), show content diff first:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Diff: technical-domain.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Local (current): Global (incoming):
Version: 1.0 Version: 1.3
Tech Stack: Next.js 14 Tech Stack: Next.js 15 ← different
API: basic validation API: Zod validation ← different
Component: same Component: same
Naming: same Naming: same
Show full diff? [y/n]: _
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Backup local files to .tmp/backup/migrate-{timestamp}/ before overwriting?
[y/n] (default: y): _
If no conflicts → proceed directly to Stage 3.
Stage 3: Approval & Copy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Will copy from: ~/.config/opencode/context/project-intelligence/
Will copy to: .opencode/context/project-intelligence/
Files to copy:
✓ technical-domain.md (1.2 KB)
✓ navigation.md (800 bytes)
✓ business-domain.md (1.5 KB)
After migration:
→ Local files committed to git = team gets your patterns
→ Agents load local (overrides global)
→ Global files remain as fallback for other projects
Proceed? [y/n]: _
Actions on approval:
- Create
.opencode/context/project-intelligence/if it doesn't exist - Copy each file from global → local
- Validate copied files (frontmatter, MVI compliance)
Stage 4: Cleanup & Confirmation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Copied 3 files to .opencode/context/project-intelligence/
✓ technical-domain.md
✓ navigation.md
✓ business-domain.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Clean up global project-intelligence?
The global files are no longer needed for THIS project (local takes priority).
Keeping them means they still apply as fallback to other projects.
1. Keep global files (safe default)
2. Remove global project-intelligence/ (only affects this user)
Choose [1/2] (default: 1): _
If user chooses 2 (Remove):
- Delete
~/.config/opencode/context/project-intelligence/only - Do NOT touch
~/.config/opencode/context/core/or any other global context
What Gets Migrated
| Migrated (project-specific) | NOT Migrated (universal) |
|---|---|
project-intelligence/ |
core/standards/ |
project-intelligence/technical-domain.md |
core/context-system/ |
project-intelligence/business-domain.md |
core/workflows/ |
project-intelligence/navigation.md |
core/guides/ |
project-intelligence/decisions-log.md |
Any other core/ files |
project-intelligence/living-notes.md |
Rationale: Project intelligence is project-specific (YOUR tech stack, YOUR patterns). Core standards are universal (code quality, documentation standards) and should stay global.
Error Handling
Permission denied:
Error: Cannot write to .opencode/context/project-intelligence/
Check directory permissions and try again.
Global path not found:
No global OpenCode config found at ~/.config/opencode/
If you installed to a custom location, set OPENCODE_INSTALL_DIR:
export OPENCODE_INSTALL_DIR=/your/custom/path
/context migrate
Related
/add-context— Create new project intelligence (interactive wizard)/context harvest— Extract knowledge from summaries- Context path resolution:
.opencode/context/core/system/context-paths.md